IntuiSup Library, Release 1.15 User Manual Coded by Gauthier H. Groult, contributions by Jean-Michel Forgeas ~ ~ ~ A runtime software extension package to the Commodore Amiga's operating system and graphical environment. December 18, 1989 Welcome to IntuiSup This document contains the end-user oriented information for the special objects in the iSup library directly dealing with the user interface. Not all objects are documented. An object is not documented herein if it's use can be intuitively guessed from it's dis- play, i.e. if it does not have special shortcuts or actions that one might not guess at first glance. Undisplayable ob- jects an other low level features of the library not covered in this manual. Please report all bugs and send your comments or suggestions to: Groult Gauthier 33, Blvd Saint Denis 92400 Courbevoie, France, Europe Tel: (1) 47 89 09 54 EMail: groult@germinal.ibp.fr Enjoy. IntuiSup r1.15 Page 2 User Manual Requesters File Requester v1.3 THE FILE REQUESTER The file requester is designed to let you move quickly around your filesystem and select a file as easily as pos- sible. To enhance speed and ease of use, it features inter- nal buffering of the last scanned directory, key selection and keyboard shortcuts, file name completion, visual feed- back and fast display update. It has two different modes: the first one enables file selection, the second allows for directory selection only. In directory mode, the File and Pattern strings gadgets are ghosted. DISPLAY AND DISPLAY GADGETS The display window is made of several lines which are actu- ally gadgets. You can select a name appearing on the display by pointing at it and clicking with the left mouse button, and validate it by double-clicking. If it is a file name, it is copied into the file string gadget, while if it is a directory name, it is scanned, the path string gadget is up- dated and the new list of files is displayed. The display can be scrolled vertically. The gadgets on its left let you position the list to your need: Up and down arrow gadgets These have two functions: if you click once, they will move the display up or down one line. If you keep them selected for a brief delay, the display will scroll quickly in the chosen direction until the gadget is released. The proportional gadget This gadget shows you the amount of information cur- rently visible on the display. You can slide the knob to position the display freely. If you click in the gadget area but outside the knob, you will move up or down one page exactly. The top and bottom of list gadgets These are located over the arrows and under the propor- tional gadget. They reset the display to the beginning or the end of the file list. Nice if you first mean to catch "c:XIcon" and change your mind for "c:Ask" :-) 'do that every day, ah? FUNCTION GADGETS IntuiSup r1.15 Page 3 User Manual Requesters File Requester v1.3 The requester has height function gadgets. Their use is the following: The Path string gadget This is the upper string gadget. It contains the cur- rent path, i.e. the exact and complete reference of the directory listed on the display. Path names always use a "volume:dir/.../dir" pattern, and names of assigned volumes are extended to their full reference. You can enter text in this gadget to jump to a specific direc- tory. Note that entering a full file name in the path gadget is allowed, the file will be recognized and splitted into the file string gadget. This gadget can be activated with the Cursor Up key on the keyboard. The File string gadget This is the lower string gadget. It holds the name of the current selected file, if one. You can enter a name in this gadget to select a file, although you will usu- ally find it easier to click in the display area. Note that pressing Return in this gadget will automatically validate the name and is equivalent to clicking on the Ok gadget, if the buffer is not empty. This gadget can be disabled if the application program asked for a directory only requester. If enabled, it can be activated with the Cursor Down key on the keyboard. The Parent gadget Selecting this gadget causes the last directory reference to be removed from the current path and moves up one level before refreshing the display. It is equivalent to remove by hand the last drawer reference in the Path string gadget. This gadget can be activated with the Cursor Left key on the keyboard. The Wildcard/Pattern string gadget. This gadget is located in the file string gadget's box, right under the Parent gadget. It will usually contain a "*" character. It contains the wildcard pattern ap- plied to the display: each time you press Return in this gadget, the current directory is rescanned and only the files matching the new pattern are displayed. The pattern affects only file names, not directory names. The pattern may contain the normal Unix shell metacharacters for pattern matching. The '*' character matches any string, including the null string. The '?' IntuiSup r1.15 Page 4 User Manual Requesters File Requester v1.3 character matches any single character. A list of characters enclosed in '[' and ']' matches any charac- ter in the list. Within a list, the rules implemented here are: The backslash character may be used to quote any special character, i.e. "\]" and "\-" anywhere in list, or "\!" at start of list. The sequence \nnn becomes the character given by nnn (in octal). Any non-escaped ']' marks the end of list. A list beginning with the special character '!' matches any character NOT in list. The '!' character is only special if it is the first character in the list. A '-' character between two letters will match any characters aphabetically between them: [a-d] matches a, b, c and d. For instance, the file name "hello" will not match the pattern "*.c", but the file name "awyxbawxyc.c" will match the pattern "a*b[!wxy]*.c". As for more useful examples, the pattern "*" displays all the files, "a*" will show only those beginning with "a", and "*.c" only those ending with ".c". "*.[ac]" will show all files ending with ".c" and with ".a" only. Note that an empty pattern will macth no files. This gadget can be disabled if the application program asked for a directory only requester. If enabled, it can be activated with the Cursor Right key. The Scan and Stop gadgets These two gadgets let you interrupt and restart the scanning of a directory. The Scan gadget restarts the building of the list from scratch, and not from where it stopped. Note that you can stop a scan by several other ways than the Stop gadget: a keystroke or a mouse button click for instance. The Scan gadget can also be useful if you need to force display refreshing: if for some reason all of the files couldn't be displayed, or if a nasty virus mangled the display, hit Scan to retry a better listing. When the requester is scanning, the Stop gadget can be simulated by pressing the Right mouse button. The Ok gadget This gadget validates the selected file name and sends it to the application program which called the File Re- IntuiSup r1.15 Page 5 User Manual Requesters File Requester v1.3 quester. Note that it is not required that a file name be present in the File string gadget to use select Ok. This gadget can be activated by pressing the Return key, by pressing return in the File string gadget, through file name completion (see below) or by a double click on the display if these are allowed by the ap- plication. The Cancel gadget This gadget simply aborts the requester. It can be ac- tivated by pressing the Esc key. The Drag gadget If the application program which opened the requester allowed it, you might be able to drag the requester window by grabbing it's title bar. This option may or may not be accessible to you, depending on the applica- tion settings. MOUSE BUTTONS The Left mouse button is used to select a display line or to click on a gadget. The Right mouse button has two functions. If the requester is scanning, it will just stop it. When the requester is not scanning, it will switch to the next displayable list. The file requester manages three lists: the first holds the files and directories for the current path, the second holds the volumes and assigns names, the third contains the devices and assigns names. You switch between them with the Right mouse button. Assign names appear after the volume or device names in the related lists, just like directory names in the first list. Assign names corresponding to a file and not to a directory will be correctly splitted into the File string gadget. KEYBOARD SHORTCUTS The following keys can be used as shortcuts when no string gadget is selected: Cursor Up Moves the current selection to the previous file in the list, if one, and resets the display. Useful in conjuc- tion with key selection. Cursor Down Moves the current selection to the next file, or pick the first file in the list if none was already IntuiSup r1.15 Page 6 User Manual Requesters File Requester v1.3 selected, and resets the display. Shift Cursor Up Activates the Path string gadget. Shift Cursor Down Activates the File string gadget if the requester is not a directory requester. Cursor Right Activates the wildcard string gadget if the requester is not a directory requester. Cursor Left Same effect as clicking the Parent gadget or removing the last directory reference in the Path string gadget: moves up one level in the volume's tree. If you are al- ready in the root, nothing happens. Right Alt with Right Amiga Simulates a Right mouse button event, and thus switches between the file, volume and device lists. Return Validates the current file name, same as clicking on Ok. Also file name completion if key selection was used - see below. Esc Cancels the file requester, same as the Cancel gadget. Backspace Back space one character in the key selection buffer - see below. KEY SELECTION & FILE NAME COMPLETION When no string gadget is selected, every keystroke not recognized as one of the preceding shortcuts is considered for key selection. If, by appending the corresponding character to the selec- tion buffer - which is cleared at every scan, the requester can find a name in the current list whose beginning matches the selection buffer, then this name is selected and parti- ally highlighted. This means that you can key in a name while no string gadget is selected, and that name will high- light accordingly. If you enter a character which is not in the name, it will be ignored. If you enter a character which will make the buffer match another name, the selection will switch to that name. This is a little bit difficult to ex- plain clearly, but actually the file requester will always find the name matching best what you have entered. IntuiSup r1.15 Page 7 User Manual Requesters File Requester v1.3 Moreover, the display is moved if needed during key selec- tion so that the best matching name is printed in the middle of window, if possible. Thus you can at glance check the close names and read what you want to key in next. Key selection is not case sensitive. Entering upper or lower case characters makes no difference. You can back up in your selection by pressing BackSpace. File name completion is achieved simply by pressing return when a name is partially selected. If the name is a direc- tory name, it is scanned. If it is a file, it is stuffed in the File string gadget and validated. NOTES User events have a higher priority than directory scanning: they will always be processed, even when the requester is busy reading a file list. This means that you can use any function at any moment, you never have to wait. The volume list are instantly rebuild when you press the right mouse button. Thus, if you Mount a new drive or Assign a name, it will be displayed the next time you hit the right mouse button. If, when the application first displays the File Requester, the current directory is not mounted, the mounted volumes list is displayed instead of a file list. IntuiSup r1.15 Page 8 User Manual Text Editing Text Areas THE TEXT AREAS Text Areas behave like string gadgets, but enable two-dimen- sional screen oriented text editing instead of single line edition. Applications can open Text Areas on windows, and may eventually open several of them on single window, in which case we will speak of an "edition mask". Text Areas can be recognized when activated - usually by pointing end clicking - by their one pixel vertical blinking cursor. EDITION Text editing whith a text area is very straightforward. Insertion and deletion of characters can happen at any posi- tion in the text. Insertion always overwrites any pre-en- tered character at the same position. The text is formatted into paragraphs wich are re-computed in real time while you key-in, and thus the display is always up to date. Depending on the application settings, the text may be left, right or center justified. You may or may not interactively change these parameters, depending again on the application. In the same way, an auto-fill option - which will not allow words to be cut on the right edge of the area - may or may not be enabled. Last, the area may filter some characters and for instance allow only for numbers to be keyed in. The maximum number of lines in an area can also be set by the application, and can in some cases be unlimited - the actual maximum limit is 65536 lines. If you attempt to enter more text than what is permitted, the screen will flash. A flash will also occur if inserting was made unpossible by lack of memory. In any case, a display beep means that you cannot enter more text without deleting some or freeing some memory first. CURSOR MOVEMENT The following actions control the cursor movement and posi- tion on an activated Text Area: Cursor Right, Cursor Left This will move by one character to the right or the left respectively, scrolling the area if necessary. Cursor Up, Cursor Down This moves the cursor one line up or down respectively, scrolling the area as needed. The horizontal position of the cursor is preserved when possible. When on the top or bottom line of an area, this may move the cursor IntuiSup r1.15 Page 9 User Manual Text Editing Text Areas to the previous or next area of a mask. Exact behaviour in this case is determined by the application's set- tings. Shift-Cursor Right, Shift-Cursor Left This moves the cursor to the end or the beginning of the current line respectively. Shift-Cursor Up, Shift-Cursor Down This moves the display and the cursor one page up or down respectively, without changing the cursor position on the display when possible. When moving up or down one page is not possible - you are already at the top or bottom of the area, nothing happens, and par- ticularely you will not move to the next/previous area in the mask - if any. Because the cursor position doesn't change, you can quickly browse through the text and come back for further editing. Ctrl-Cursor Up, Ctrl-Cursor Down Pressed once: moves the display to the beginning or end of the text without changing the cursor display posi- tion. This allows for a quick look at the opposite end of the text and come back. Pressed twice: moves the cursor to the first or last line of the text respec- tively without changing the horizontal position when possible. Alt-Cursor Up, Alt-Cursor Down These keystroke are useful with mask editing only. They move up and down to the previous or next area, if any. The position of the cursor in every area is remembered. Here again, precise behaviour is determined by the ap- plication's settings. IntuiSup r1.15 Page 10 User Manual