                     ------------------------------------------
                      Commands of the Scripter-plugin <listbox> 
                         (C) 1997 by Markus Hoffmann @ DU2
                     ------------------------------------------

---------
 Keys:
---------

     - CTRL-C      The current list will be written to the clipboard.
     - CTRL-W      The listbox window participates in global window 
                   cycling.

-----------------------------------------------
 createBox(infoline, dragdrop, editline, keys)
-----------------------------------------------

     Determines the appearance and functions of the listbox; parameter is 
     either 0 or 1.

     - <infoline>  The listbox window is furnished with an info line, 
                   whose text can be set with setInfo(text).

     - <dragdrop>  With held down CTRL-key a D&D-action to other windows 
                   or the desktop is enabled; during this an AV-message 
                   as well as a event()-message will be sent. Data dragged
                   to the listbox window is reported to the script via 
                   event().

     - <editline>  A scrollable edit line where up to 128 characters can 
                   be input appears in the upper part of the window. The 
                   contents can be read out with the function getEditline().

     - <keys>      Key presses are reported via event()-message 'key'.
     
     - Examples:   listbox.createBox(1);     // Info line is installed
                   listbox.createBox(0,1);   // D&D is installed
                   listbox.createBox(1,0,1); // Info line and edit field 
                   						// are installed

-----------------
 openBox(string)
-----------------

     Opens the listbox window and displays it on the screen.

     - <string>    The title of the listbox window. This can be 
                   altered later with setTitle(text).

     - Example:    openBox(" [BACKUP.SIC] Backup ");

---------
 event()
---------

     This function sends dialog even-messages that can be evaluated by 
     the script. This allows more complex but also more flexible dialog
     handling, as the script can react directly to the events that the 
     user executes. The return is an array with three entries that 
     specify the event more closely. The function waits until one of
     the following events occurs:

     - <event>     "selected"  - A listbox entry was single-clicked
                   "key"       - A key was pressed (if switched on 
                                 in createBox())
                   "D&D_in"    - Objects were dragged to the dialog box
                   "D&D_out"   - Objects were dragged from the dialog box
                   "button_1"  - The user-button #1 was clicked on
                   "button_2"  - The user-button #2 was clicked on
                   "button_3"  - The user-button #3 was clicked on
                   "popup_1"   - An entry in popup #1 was clicked on
                   "popup_2"   - An entry in popup #2 was clicked on
                   "popup_3"   - An entry in popup #3 was clicked on
                   "cancel"    - The Cancel button was clicked on
                   "okay"      - A listbox-entry was double-clicked, or 
                                 the OK button was selected

     - <value1>    String
                     -> "selected"
                     -> "D&D_out"
                   String or string array
                     -> "D&D_in"
                   String or empty string
                     -> "popup_1", "popup_2", "popup_3"
                     -> "button_1", "button_2", "button_3"
                     -> "okay"
                   Keycode
                     -> "key"
                   Dummy value (0)
                   	-> "cancel"

     - <value2>    Position of the character clicked on in the listbox or 
                   -1 for selection of an entry from the keyboard
                     -> "selected"
                   msg[4] from AV-message VA_THAT_IZIT (type of object)
                     -> "D&D_out"
                   Number of selected popup entry (start from 1)
                     -> "popup_1", "popup_2" und "popup_3"
                   Modifier-keys status
                     -> "key"
                   Dummy value (0)
                   	-> "cancel"
                     -> "button_1", "button_2", "button_3"
                    
-------------
 handleBox()
-------------

     With this one handles the listbox, until a double-click on an entry
     occurs or 'OK' or 'Cancel' are clicked on. For 'OK' or a double- 
     click the selected string is copied to the specified variable, for 
     'Cancel' cancel-code 2 will be returned. This is the simple variant
     for event(), in case one only wishes to handle a simple dialog box.

     - Example:    result=handleBox();

------------
 closeBox()
------------

     The listbox is removed from the screen, but can be recalled at any 
     time without losing its contents.

     - Example:    closeBox();

------------------
 setTitle(string)
------------------

     The window title of the listbox will be changed. If no window is 
     being displayed as yet then nothing happens.

     - <string>    The title line to be set.

     - Example:    setTitle(" [FILEFIND.SIC] Filefinder ");

-----------------
 setInfo(string)
-----------------

     The contents of the installed info line will be changed. If no 
     info line has been installed then nothing happens.

     - <string>    The info line to be set.

     - Example:    setInfo(" 120 entries present.");

----------------------
 setEditline(string)
----------------------

     The text <string> is copied to the edit line. If no edit line has 
     been installed, then nothing happens.

     - <string>    The edit line to be set.

     - Example:    setEditline("");          // Clear edit line

----------------
 getEditline()
----------------

     With this function the current contents of the edit line is obtained.
     If no edit line has been installed then nothing happens.

     - Example:    entry=getEditline();    // Get edit line

---------------------------------------------
 installButton(number, string, [entry, ...])
---------------------------------------------

     Up to three self-defined buttons or popups can be installed. A 
     click on them is reported to the script with event() and can be   
     evaluated by it.

     - <number>    Number of the button to be installed (1 to 3).

     - <string>    A string, up to 10 characters long, that appears in 
     		    the button. If no text is specified then the button 
                   will be removed from the listbox again. With a repeated 
                   installation only the text will be altered.

     - <entry>     Following <string> there can be up to twelve further 
                   strings that will form entries in the popup that will 
                   be installed in that case. The strings may have a 
                   maximum length of 10 characters; longer strings will 
                   be truncated.

     - Examples:   installButton(1,"Edit");     // Installs button 1
                   installButton(2,"Delete");   // Installs button 2
                   installButton(2);            // Removes button 2
                   installButton(1,"Set");      // Sets a new text
                   installButton(3,"Options","Insert","Delete");
                                                // Installs a popup

---------------------------------------
 checkPopupEntry(number, entry, value)
---------------------------------------

     With this the entries in the popups can be furnished with a tick. 

     - <number>    Number of the popup (1 to 3).

     - <entry>     Number of entries in the popup (1-12).

     - <value>     0 or 1, depending on whether the tick is to be set or 
                   removed.

     - Examples:   checkPopupEntry(1,1,1);  // Ticks entry 1 in popup #1 
                   checkPopupEntry(1,1,0);  // Removes the tick once more

--------------------------------
 insertItem(mode, string1, ...)
--------------------------------

     Insert an entry in the list of the listbox. If the listbox is being 
     displayed then its window will be updated automatically.
     Note: If you are after maximum speed, then the listbox should not be 
     displayed beforehand, as each redraw of the list takes time.

     - <mode>      A parameter that specifies how the entry is to be 
                   inserted:

                   "-t" - The entry is inserted at the top of the list
                   "-b" - The entry is inserted at the bottom of the list
                   "-s" - The entry is inserted sorted in the list

     - <string>    The entry to be inserted as single string, string list 
                   or array.

     - Examples:   insertItem("-b","1st entry","2nd entry","3rd entry");
                   insertItem("-t","3rd entry","2nd entry","1st entry");
                   insertItem("-s","2nd entry","1st entry","3rd entry");
                   insertItem("-s",array);

--------------------------
 deleteItem(string1, ...)
--------------------------

     Deletes an entry from the list of the listbox. If the listbox is 
     being displayed then its window will be updated automatically.

     - <string>    The entry  to be deleted as single string, string list 
                   or array. If it is not found in the list, then 
                   nothing happens.

     - Examples:   deleteItem("3rd entry");
                   deleteItem("1st entry","3rd entry");
                   deleteItem(array);

-------------
 freeItems()
-------------

     Removes the whole list of the listbox and frees the memory it 
     occupied.  If the listbox is being displayed then its window will be 
     updated automatically.

     - Example:    freeItems();

--------------
 countItems()
--------------

     Returns the number of entries in the listbox.

     - Example:    entries=countItems();

--------------------
 getFirstItem(mode)
--------------------

     Returns the first entry of the listbox according to <mode>. If no 
     string is present then error-code 2 will be returned.

     - <mode>      A parameter that specifies which entry is to be 
                   returned:

                   "-s" - The first selected entry
                   "-d" - The first non-selected entry
                   "-a" - The first entry, no matter whether selected 
                          or not

     - Example:    entry=getFirstItem("-a");

-------------------
 getNextItem(mode)
-------------------

     Returns the next entry of the listbox according to <mode>. If no 
     further string is present or if no getFirstItem() has been called 
     yet, then error-code 2 willbe returned.


     - <mode>      A parameter that specifies which entry is to be 
                   returned:

                   "-s" - The first selected entry
                   "-d" - The first non-selected entry
                   "-a" - The first entry, no matter whether selected 
                          or not

     - Example:    /* Deletes all non-selected entries */
                   entry=getFirstItem("-s");

                   while(!errno)
                   {
                      deleteItem(entry);
                      entry=getNextItem("-d");
                   }
