The Menu type

Purpose

A Menu is a special purpose application window (explained later). It provides a scrollable list of items which can be indicated by the user. The contents of each item is a string.

A menu is always vertically scrollable. The number of visible lines and the minimum width can be chosen by the designer of the window (the minimum width can be the maximum width of an item in the menu).

When a menu is displayed, the items are all displayed in rows. Each row contains as many items as can be completely visualised (i.e. the width of the menu is divided by the itemwidth to get the number of items on each row). The menu is only scrollable vertically. In SBasic, a menu is not sorted unless you sort the items first, before adding them to the menu.

A menu can either have no selectable items, at most one selected item, or all items can be selected and deselected at will. The programmer can also query all selected, all available or just all items (returning a pointer to the string, or the number of the item). Also, the status of each item can be changed at will (normally an item is just available when it is selected).

Please note that in the Basic interface, for various reasons, the object returned with PWcreate is not the correct menu object. To get at the correct menu object, you should query the object returned with the PW('MENU_BASIC_TRUEMENU') tag.

The Type Word

When creating this type of object, the type parameter is:

PW('TYPE_MENU')

The tags

Here are the tags for this object. As usual, with one exception, change tags are also used when creating the object, but query tags are only used for queries.
A create tag (use during creation only)
PW('MENU_KEYPRESSES')
Set the keypresses which should be used to allow the user to scroll the menu without indicating the scroll items. This tag needs four parameters, first the keypresses for scrolling a line up and down, then the keypresses for scrolling a page up and down. The keypresses are passed as numbers. You can, if course, use the CODE function. If this tag is not passed, then the standard keypresses for scrolling are defined as follows: <ALT up/down> will scroll one line, <ALT SHIFT up/down>will scroll one page.
The change (and creation) tags
PW('MENU_ADD')
Add an item inside the menu. The item will be added at the end. The parameter should be a string, it cannot be a direct string. The current item, as last returned with one of the queries, is reset when adding something to the menu.
PW('MENU_ADD_COPY')
Add an item inside the menu. Same as above, but the string is copied to a safe place.
PW('MENU_ADD_ARRAY')
Add all strings from an array of string to the menu. If the menu is not sorted, then the items are added at the end, in the same order as in the array. This tag requires three parameters, the number of elements in the array, the maximum length of each string, and the array itself (see the section on strings for more explanations on this subject). The items in the menu will just point to the position in the array, so the array should persist (i.e. no local arrays, unless the window is removed before the procedure is left). The current item, as last returned with one of the queries, is reset when adding something to the menu.

It is suggested that this is the best way to handle menus from SBasic. Whilst it is possible to add elements to the menu with the MENU_ADD and MENU_ADD_COPY tags, this is not really practical from SBasic, as finding out later which item in the menu was selected or not will not be easy. Even adding strings later should be done in this way. If you have a menu that corresponds to an array, and wish to add a string to the menu, you should add it to the array first, clear the menu (with MENU_CLEAR), and add the entire array to the menu again. Alternatively, you can make sure that your array has some elements left at the end, put the new string there and add it to the menu.

PW('MENU_ITEMWIDTH')
Specify the width of each item in the menu. The parameter is a PROforma number.
PW('MENU_ITEMWIDTH_PIX')
Specify the width of each item in the menu. The parameter is a number, the width in pixels.
PW('MENU_ITEMWIDTH_FS')
Specify the width of each item in the menu. The parameter is a PROforma number, which is interpreted as a factor, the base unit being the fontsize used. However, since PROforme uses proportional fonts, this does not mean that a determined number of characters will fit inside the window.
PW('MENU_ITEMWIDTH_MAX')
Specify that the itemwidth which should be used inside the menu should be the maximum width of all the items in the menu (this is the default). This tag requires no parameters. An attempt is made to prevent that the size of all objects in the window are redetermined when the itemwidth changes because a larger item appears. This can influence the appearance of the window (compared with the other case) if items are added while the window is visible !
PW('MENU_ACTION_SELECT')
Specify a routine which should be called each time an item is selected. The parameter should be an action routine, preferably DO_ROUTINE. The add_info parameter to the PWactivate call contains the address of the string selected, which you can then make into an SBasic string with MKSTRING$.
PW('MENU_ACTION_DESELECT')
Specify a routine which should be called each time an item is deselected. The parameter should be an action routine, preferably HIT_ROUTINE . The add_info parameter to the PWactivate call contains the address of the string deselected, which you can then make into an SBasic string with MKSTRING$.
PW('MENU_UNIQUE')
Tell the menu that only one item can be selected at any instant: if ou select another item, the first one be automatically be deselected. This tag needs no parameters. When this tag is given, all selected items in the menu will be deselected!
PW('MENU_SORT_COMPARE')
This is not available in SBasic.
PW('MENU_VISIBLE_LINES')
Specify the minimum number of lines which should be visible in the menu. Each line could (if the menu is wide enough) contain more than one item. The parameter is a number.
PW('MENU_CLEAR')
Clear the menu. All the items will be removed from the menu. The current itemwidth is reduced to zero if the maximum width is the current option. This tags does not need a parameter. The current item, as last returned with one of the queries, is reset when adding something to the menu.

In SBasic, this is an easy way to prepare the menu to accept a new array.

PW('MENU_WINDOW_DO')
The parameter is either 1 (=TRUE) or 0 (=FALSE). By default it is FALSE. When the window do status is TRUE, then the keypress is also handled by the system (thus a keypress object can react to it).
PW('MENU_NONE_SELECTED')
This tag is similar to the PW('MENU_UNIQUE') tag, except that in this case, a menu item will never be displayed as selected. However, when a menu item is indicated, the menu Select routine will still be called. This tag does not need a parameter.
PW('MENU_STATUS')
Change the status of an item in the menu. This tag needs two parameters, the new status and the item. The new status should be one of PW('STATUS_AVAILABLE'), PW('STATUS_UNAVAILABLE') or PW('STATUS_SELECTED'). The item is passed as a string which is the string contained in the item (i.e. if you want to set, say, the first item of an array a$, pass a$(0)). It is important that the string thus passed is the same variable as that uses when making the array: do not copy that string into another string and then pass that other string: the string will not be found, and no status will be changed. When changing the status of an item, the Select or Deselect routines are not called, except when it causes an item to be deselected (because of PW('MENU_UNIQUE')). When the PW('MENU_NONE_SELECTED') tag has been used, this tag can only be used to make an item available or unavailable.
PW('MENU_STATUS_ALL')
Set the statusses of all items in the menu. This tag needs one parameter, the new status which should be one of PW('STATUS_AVAILABLE'), PW('STATUS_UNAVAILABLE') or PW('STATUS_SELECTED').
PW('MENU_STATUS_CURRENT')
Change the status of the current item, being the last one which was returned by one of the queries. This tag requires only one parameter, the new status, either PW('STATUS_AVAILABLE'), PW('STATUS_UNAVAILABLE') or PW('STATUS_SELECTED'). When changing the status of an item, the Select or Deselect routines are not called, except when it causes another item to be deselected (because of the PW('MENU_UNIQUE') tag). When the PW('MENU_NONE_SELECTED') tag has been used, this tag can only be used to make an item available or unavailable.
The query tags
PW('MENU_BASIC_TRUEMENU')
This returns the true menu object to Sbasic. It it this true object which you should use when selecting on the different objects, as this is the object parameter returned through the PWactivate keyword. The only moment you might conceivably use the object returned by the PWcreate command when creating a menu is if you want to remove the menu specifically. Since objects are removed when their parent (the outline) is removed, this should not be necessary.
PW('MENU_FIRST')
Get the first item in the menu. This query should be used to initialise cycling over all items in the menu. The first item will become the current item. The parameter returned is the address of the string of this item. You should use MKSTRING$ to make this into a normal SBasic string.
PW('MENU_NEXT')
Get the next item in the menu. This query should only be used if the current item was initialised using a PW('MENU_FIRST') query. The returned item will become the current. The parameter returned is the address of the string of this item. You should use MKSTRING$ to make this into a normal SBasic string. If all items in the menu have been returned, then this address will be 0 and the current item is undefined (can be anything).
PW('MENU_AVAILABLE_FIRST')
Get the first available item in the menu. This query should be used to initialise cycling over all available items in the menu. The returned item will become the current item. The parameter returned is the address of the string of this item. You should use MKSTRING$ to make this into a normal SBasic string.
PW('MENU_AVAILABLE_NEXT')
Get the next available item in the menu. This query should only be used if the current item was initialised using a PW('MENU_AVAILABLE_FIRST') query. The returned item will become the current item. You should use MKSTRING$ to make this into a normal SBasic string. If all items in the menu have been returned, then this address will be 0 and the current item is undefined (can be anything).
PW('MENU_SELECTED_FIRST')
Get the first selected item in the menu. This query should be used to initialise cycling over all selected items in the menu. The returned item will become the current item. The parameter returned is the address of the string of this item. You should use MKSTRING$ to make this into a normal SBasic string.
PW('MENU_SELECTED_NEXT')
Get the next selected item in the menu. This query should only be used if the current item was initialised using a PW('MENU_SELECTED_FIRST') query. The returned item will become the current item. The parameter returned is the address of the string of this item. You should use MKSTRING$ to make this into a normal SBasic string. If all items in the menu have been returned, then this address will be 0 and the current item is undefined (can be anything).

The above queries are not too much use for an SBasic programmer, since, to find to what item this corresponds in your array you will have to:

So another form of the above query tags exists. They have the same name, with "_NUMBER" added at the end, and return the number of the item concerned, starting at 0 (i.e. PW('MENU_FIRST_NUMBER') will always be 0):

PW('MENU_FIRST_NUMBER')
PW('MENU_NEXT_NUMBER')
PW('MENU_SELECTED_FIRST_NUMBER')
PW('MENU_SELECTED_NEXT_NUMBER')
PW('MENU_AVAILABLE_FIRST_NUMBER')
PW('MENU_AVAILABLE_NEXT_NUMBER')

Thus, if the menu corresponds to an array, you will get the number of the elements in the array. If there is no NEXT element any more, the queries return -1.

PW('MENU_SELECTED_NUMBER')
PW('MENU_AVAILABLE_NUMBER')
PW('MENU_UNAVAILABLE_NUMBER')
These three tags respectively return the number of selected, available and unavailable items in the menu, or 0 if none.

PROGS, Professional & Graphical Software
last edited 28.01.1997 (wl)