The Menu type
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, befor 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).
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.
- 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_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:
- Get the string with the query.
- Make it into a QL string with MKSRTING$.
- Search for the string in the array.
- Use the result of the search as an index into the array and the menu...
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). 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_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')
-
PROGS, Professional & Graphical Software
last edited 1996 June 05 (wl)