home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
ftp.uni-stuttgart.de/pub/systems/acorn/
/
Acorn.tar
/
Acorn
/
acornet
/
dev
/
basic
/
menuutils.spk
/
SWIs
< prev
Wrap
Text File
|
1993-01-23
|
25KB
|
719 lines
Documentation for the MenuUtils module v.0.10
⌐ Petrov Software 1992
Description of SWIs
SWI chunk prefix for the MenuUtils module is MenuUtil_ and base number
is &45BC0. My thanks to Acorn for the allocation of SWI chunk.
Module MenuUtils provides the following SWIs:
"MenuUtil_Initialise"
"MenuUtil_New"
"MenuUtil_Add"
"MenuUtil_Delete"
"MenuUtil_Decode"
"MenuUtil_Show"
"MenuUtil_ShowSubMenu"
"MenuUtil_Info"
"MenuUtil_Text"
"MenuUtil_Tick"
"MenuUtil_Dots"
"MenuUtil_Fade"
"MenuUtil_Warning"
"MenuUtil_Writable"
"MenuUtil_SubMenu"
"MenuUtil_ColourMenu"
"MenuUtil_Colours"
"MenuUtil_TickOnly"
All calls to MenuUtils module (with the exception of
MenuUtil_Initialise and MenuUtil_New) expect in R0 the handle of the menu
or of the menu item. If the handle is omitted (R0=0) then the current menu
or current menu item is assumed (interpretation depends on particular SWI).
MenuUtil_Initialise (SWI &45BC0)
--------------------------------
To register the task as MenuUtils client
Entry:
R0 last MenuUtils version number known to task * 100
R1 initialisation type (see later)
bit 0
0 - "BASIC"
1 - "machine code" (not supported by current version)
Exit:
R0 version number * 100
R1,R2 preserved
MenuUtil_Initialise should only be called once when the task starts up. It
must be called after Wimp_Initialise has been called and before any
other call to the MenuUtils module is made.
MenuUtils performs all the closedown work automatically when the
task finishes so no special MenuUtil_CloseDown SWI is provided.
Example code:
Register the task with any version of the module
SYS "MenuUtil_Initialise"
MenuUtil_New (SWI &45BC1)
-------------------------
Creates new empty menu.
Entry:
R1 pointer to menu title string
R2 approximate number of items (default 5)
Exit:
R0 handle of created menu
This call creates new empty menu with specified title string. Colours
and dimensions of the menu are in standard RISC OS style. You can
specify number of items you are going to have in this menu. This is
optional but it can speed up the process of menu creation. It
may be important for big menus (for example for oldstyle fonts menu).
As Window Manager doesn't allow you to have menus absolutely without
menu items so each new menu is created together with one special item.
This item is created with the only aim to prevent crashes in case you
will accidentially try to open unfinished menu. The special item will
be removed automatically just after you add your first item to this
menu.
If your program has complex menu structure with submenus then you can
use this call to create not only main menu but also all submenus. And
you have to remember the handles of all submenus in order to link them
later to corresponding menu items in parent menu. If on the other hand
your program have only one menu without submenus then you may ignore
the returned menu handle because it will be anyway used as default in
all future calls to MenuUtils.
After this call the new menu becomes the current menu.
Example code:
Start construction of simple menu like one in Palette Utility
SYS "MenuUtil_New",,"Palette"
If you program has complex menu structure (like Source Editor) then you
have to remember the handles of all submenus
SYS "MenuUtil_New",,"SrcEdit" TO mainMenu%
SYS "MenuUtil_New",,"Display" TO dispMenu%
SYS "MenuUtil_New",,"Fonts",200 TO fontsMenu%
MenuUtil_Add (SWI &45BC2)
-------------------------
Adds new item to existing menu.
Entry:
R0 handle of the menu or of the menu item or zero for current menu
R1 pointer to item text
R2 pointer to item handler
Exit:
R0 handle of menu item
R1,R2 preserved
This call adds one item to the existing menu. If handle is the handle
of menu then new item will be added to the end of this menu. If handle
is the handle of the item then new item will be inserted into menu
just before this item. If R0 is zero on entry then item will be added
to the end of current menu.
During this call the current menu may be moved in memory so if you
keep direct pointers to the menu data structure they may become
invalid. On the other hand if there are any menu items linked with
this menu by means of MenuUtil_Submenu then all pointers will be
recalculated automatically by the module and will remain valid.
MenuUtils makes his own copy of the string pointed to by R1 but
inspite of this you still can easily change it with MenuUtil_Text. If R1
is zero on entry then null string ("") will be used as item text.
If R2 is not zero on entry then interpretation of it contents depends
on the initialisation type specified early during the call to
MenuUtil_Initialise. If initialisation type was specified as "BASIC" then
it is assumed that R2 is a pointer to the ctrl-terminated text string.
In this case the module makes his own copy of the string for later use
in MenuUtil_Decode. If initialisation type was "machine code" (not
supported by current version) then only the contents of R2 is saved by
the module. This feature allows you to attach a handler to the menu
item. In case of "BASIC" you can provide the name of BASIC function.
In case of "machine code" - the address of ARM subroutine. See also
MenuUtil_Decode and for possible use of item handlers.
Example code:
Add item "Info" to the current menu
SYS "MenuUtil_Add",,"Info" TO infoItem%
Add item "Quit" and then insert item "Create" just before it. Let's
the first item will have the handler. The handler is assumed to be
BASIC function FNquit. (See MenuUtil_Decode on how this handler may be
called)
SYS "MenuUtil_Add",,"Quit","quit" TO quitItem%
SYS "MenuUtil_Add",quitItem%,"Create" TO createItem%
Create menu similar to Display submenu in Filer. When items are added
to current menu menu handle (dispMenu%) may be omitted as it will be
used by default.
SYS "MenuUtil_New",,"Display" TO dispMenu%
SYS "MenuUtil_Add",,"Large icons" TO largeItem%
SYS "MenuUtil_Add",,"Small icons" TO smallItem%
SYS "MenuUtil_Add",,"Full info" TO fullItem%
MenuUtil_Delete (SWI &45BC3)
----------------------------
Removes menu or menu item
Entry:
R0 = handle of the menu or of the menu item or zero for current menu
if R1<>0 then recursively delete all submenus
Exit:
R0,R1 preserved
This call allows you to delete the whole menu or the particular menu item.
If you will delete menu item then remained items of this menu which are
positioned bellow it will be automatically shifted in memory to fill the
hole. Despite the fact that memory location and position in menu of some
items may be changed the handles of the items will remain valid.
If you want to delete not only the item but also the whole menu subtree
connected with it then you must set R1<>0 on entry. If R0 contains the
handle of menu then this menu will be deleted alone or together with all
submenus depending on R1.
Use recursive deletion with caution as you may accidentally delete
submenus which are connected with other menu items.
This call is supposed to be used when menus with variable number of items
are needed. It may be for example menu with the list of currently opened
documents or archives.
Example code:
Delete item with handle tmpItem%
SYS "MenuUtil_Delete",tmpItem%
Recursively delete all menus linked with mainMenu%
SYS "MenuUtil_Delete",mainMenu%,TRUE
MenuUtil_Decode (SWI &45BC4)
----------------------------
Decodes menu after user selection.
Entry:
R0 = menu handle or zero if current menu
R1 -> pointer to the list of menu selections
Exit:
R0 -> pointer to item handler or zero
R1 -> pointer to block
Block pointed to by R1 must contain the list of menu selections in the same
format as returned by Wimp_Poll in case of menu selection event.
R1 + 0 item in main menu which was selected (starting from 0)
R1 + 4 item in first submenu which was selected
R1 + 8 item in second submenu which was selected
...
terminated by -1
This call maps the list of menu selections onto menu data structure and
determines corresponding menu items. Various information about last two
items from this list (selected item and parent item from menu one level up
if any) is written into special block. Pointer to this block is returned in
R1. Format of the returned block is as follows:
R1+0 position of selected menu item in menu (starting from 0)
R1+4 pointer to selected item data
R1+8 selected item handle or zero if item was created without MenuUtils
R1+12 pointer to text string of selected item
R1+16 position of parent menu item in menu (starting from 0)
R1+20 pointer to parent item data
R1+24 parent item handle or zero if item was created without MenuUtils
R1+28 pointer to text string of parent item
If the item has been selected from the top-level menu then there will be no
parent item and corresponding part of the block will be filled with zeros.
If during creation of this item you have specified the handler then R0 on
exit will contain the pointer to this handler otherwise R0 will be zero.
Interpretation of item handler is determent by initialisation type (see
MenuUtil_Initialise). If initialisation type was "BASIC" then R0 will point to
ctrl-terminated text string. If initialisation type was "machine code" (not
supported by current version) then R0 will contain the value passed in R2 to
MenuUtil_Add. To invoke BASIC handler you can use EVAL statement.
Example code:
Suppose Wimp_Poll has returned reason code 9 (Menu_Selection) and q%
points to the corresponding block. You can use MenuUtil_Decode to call the
item handler in the following way:
SYS "MenuUtil_Decode",,q% TO handler%
IF handler% THEN
handler$="FN"+$handler%
IF EVAL(handler$)
ENDIF
MenuUtil_Show (SWI &45BC5)
--------------------------
Displays menu on screen
Entry:
R0 = handle of the menu or zero for current menu
R1 -> pointer to block or zero
Exit:
R0,R1 preserved
This call may be used to display menu on screen. Screen position for menu
will be calculated according to rules described in PRM. Block pointed to by
R1 must contain the same information as returned by Wimp_Poll in case of
mouse click event (in fact only mouse coordinates and window handle will be
used) :
R1 + 0 mouse X
R1 + 4 mouse Y
R1 + 8 buttons
R1 +12 window handle (-2 if icon bar)
R1 +16 icon handle
MenuUtils automatically distinguishes iconbar menus from ordinary
window menus. If menu is already on screen and you want to reopen it
after user selection with Adjust button then pointer to the block may be
omitted.
Example code:
Suppose Wimp_Poll has returned reason code 6 (Mouse_Click) and q% points to
the returned block. Display menu on screen if the click is with Menu button.
buttons%=q%!8
IF (buttons% AND2)<>0 THEN SYS "MenuUtil_Show",mainMenu%,q%
Leave menu on screen after selection with Adjust button
SYS "MenuUtil_Show"
MenuUtil_ShowSubMenu (SWI &45BC6)
---------------------------------
Display submenu after receiving Message_MenuWarning
Entry:
R0 = handle of the submenu or zero for current menu
R1 -> pointer to block
Exit:
R0,R1 preserved
This call may be used to display submenu when a message type MenuWarning
(&400C0) is received by an application. This message is sent by the Wimp
when submenu is about to be accessed by the pointer moving over the
right-pointing arrow of the parent menu. (To find out the handle of the
menu item in parent menu you can use MenuUtil_Decode).
R1 on entry must point to message block (in fact only two words at offsets
+24 and +28 will be used).
Note: If you plan to use MenuUtil_Decode then all submenu pointers must be
valid. It means that you have to link submenu pointed to by R0 with
corresponding menu item. This can be done by MenuUtil_SubMenu.
Example code:
Display fonts submenu on screen after receiving MenuWarning:
SYS "MenuUtil_SubMenu",fontsItem%,fontsMenu%
SYS "MenuUtil_ShowSubMenu",fontsMenu%,q%
MenuUtil_Info (SWI &45BC7)
--------------------------
This call returns various information about the whole menu or about the
particular menu item.
Entry:
R0 = handle of the menu or of the menu item or zero for current item
Exit:
R0 -> pointer to block
Returned block contains the following information:
R0 + 0 pointer to menu data structure
R0 + 4 pointer to item data or zero
Menus created with MenuUtils are not static and may be moved in
memory, for example after adding new items. So you must use direct
pointers to this menus with caution until you have completely finished
the menu construction.
MenuUtil_Text (SWI &45BC8)
--------------------------
Changes menu title string or text of menu item
Entry:
R0 = handle of menu item or handle of menu or zero for current item
R1 -> pointer to text string
Exit:
R0,R1 preserved
This call allows you to change title string of menu or text of menu item.
The structure of menu tree remains unchanged but pointer to item text may be
changed. The handle of the menu or menu item must be specified in R0. If R0
is zero on entry then the text of current item will be changed. R1 must
point to the ctrl-terminated text string. If R1 is zero on entry then null
string will be used. Remember that the length of menu title is limited by 12
symbols.
Example code
Set new menu title string:
SYS "MenuUtil_Text",objectMenu%,"Directory"
Let's variable type% contains one of the values 0,1,2 or 3 depending on the
object selected in Filer window and variable name$ contains the name of the
file or directory selected.
CASE type% OF
WHEN 0:i$="File ''"
WHEN 1:i$="File '"+name$+"'":s$="File"
WHEN 2:i$="Dir. '"+name$+"'":s$="Directory"
WHEN 3:i$="Selection":s$=i$
ENDCASE
REM fade the item if nothing is selected
SYS "MenuUtil_Fade",objectItem%,type%=0
REM set new item text
SYS "MenuUtil_Text",,i$
REM set new submenu title
SYS "MenuUtil_Text",toolsMenu%,s$
MenuUtil_Tick (SWI &45BC9)
--------------------------
This call may be used to modify the state of menu flag which controls
the tick displayed on the left of the menu item.
Entry:
R0 handle of menu item or zero for current menu item or handle of menu
R1 defines action
if R1 =0 then clear tick flag
if R1 <>0 then set tick flag
Exit:
R0,R1 preserved
R0 must contain the item handle or zero for the current menu item. R1
defines to set or to clear the flag. If R1 is zero then the flag will
be cleared and if R1 is non zero then the flag will be set.
If R0 instead of item handle contains menu handle then the state of
the flag will be changed in all items of this menu.
It is convenient to pass in R1 the result of logical expression (to
set flag if result is TRUE and to clear it if FALSE).
Example code:
Tick one of the items depending on the value of variable disp%:
SYS "MenuUtil_Tick",largeItem%,(disp%=1)
SYS "MenuUtil_Tick",smallItem,(disp%=2)
SYS "MenuUtil_Tick",fullItem%,(disp%=3)
MenuUtil_Dots (SWI &45BCA)
---------------------------
This call may be used to modify the state of menu flag which controls
the dotted line displayed bellow the menu item.
Entry:
R0 handle of menu item or zero for current menu item or handle of menu
R1 defines action
if R1 =0 then clear dots flag
if R1 <>0 then set dots flag
Exit:
R0,R1 preserved
R0 must contain the item handle or zero for the current menu item. R1
defines to set or to clear the flag. If R1 is zero then the flag will
be cleared and if R1 is non zero then the flag will be set.
If R0 instead of item handle contains menu handle then the state of
the flag will be changed in all items of this menu.
It is convenient to pass in R1 the result of logical expression (to
set flag if result is TRUE and to clear it if FALSE).
Example code:
Display dotted line after the current menu item
SYS "MenuUtil_Dots",,TRUE
MenuUtil_Fade (&45BCB)
----------------------
This call can be used to make menu item non-pickable
Entry:
R0 handle of menu item or zero for current menu item or handle of menu
R1 defines action
if R1 =0 clear shaded menu flag
if R1 <>0 fade this menu item (ie. unpickable)
Exit:
R0,R1 preserved
R0 must contain the item handle or zero for the current menu item. R1
defines to set or to clear the flag which makes menu item unpickable. If R1
is zero then the flag will be cleared and if R1 is non zero then the flag
will be set and the item will be shaded.
If R0 instead of item handle contains menu handle then the state of
the flag will be changed in all items of this menu.
It is convenient to pass in R1 the result of logical expression (to
set flag if result is TRUE and to clear it if FALSE).
Example code:
Fade current menu item:
SYS "MenuUtil_Fade",,TRUE
Fade all items in "Select" submenu with handle selctMenu%
SYS "MenuUtil_Fade",selectMenu%,TRUE
MenuUtil_Warning (SWI &45BCC)
-----------------------------
This call can be used to make menu item generate a message when moving to
the submenu
Entry:
R0 handle of menu item or zero for current menu item or handle of menu
R1 defines action
if R1 =0 clear message menu flag
if R1 <>0 set message flag (ie. message will be generated)
Exit:
R0,R1 preserved
R0 must contain the item handle or zero for the current menu item. R1
defines to set or to clear the flag which changes submenu behaviour. If R1
is not zero, then moving over the right arrow will cause a MenuWarning
message (&400C0) to be generated. The application can respond by calling
MenuUtil_ShowSubMenu to display appropriate object.
If R0 instead of item handle contains menu handle then the state of
the flag will be changed in all items of this menu.
It is convenient to pass in R1 the result of logical expression (to
set flag if result is TRUE and to clear it if FALSE).
Example code:
Generate message when moving to the fonts submenu:
SYS "MenuUtil_Warning",fontsItem%,TRUE
MenuUtil_Writable (SWI &45BCD)
------------------------------
Makes menu item writable.
Entry:
R0 = handle of menu item or zero for current item or handle of the menu
R1 <>0 and
R2 = buffer size
R3 -> pointer to validation string, or
R1 =0 makes item not writable
Exit:
R0-R3 preserved
If R1 is not zero on entry then this call will convert existing menu item
into writable item. R0 must contain the handle of the menu item or zero for
current item. If R0 contains handle of the menu then all the items in this
menu will be converted.
R2 on entry contains the length of the buffer for the input string.
The value in R2 must be not less then the length of the current item
text. In the latter case the buffer will remain unchanged.
If R3<>0 on entry then it points to the ctrl-terminated validation
string. The module makes its own copy of the string. If R3=0 on entry
then no validation string will be used.
If R1 is zero on entry then the item will be converted back into ordinary
menu item. In this case contents of registers R2 and R3 will be ignored.
Example code:
Make current item writable without validation string
SYS "MenuUtil_Writable",,TRUE
Make menu item with handle widthItem% writable, with buffer size 40 and
allow to enter to it only digits.
SYS "MenuUtil_Writable",widthItem%,TRUE,40,"A0-9"
MenuUtil_Submenu (SWI &45BCE)
-----------------------------
Links submenu to menu item
Entry:
R0 handle of the menu item or zero if current menu item
R1 handle of submenu or pointer to submenu or window handle
if R1<&8000 then R1 is window handle
if R1>&8000 then R1 is pointer to menu
if R1<0 then R1 is menu handle
Exit:
R0,R1 preserved
This call is used for constructing multilevel menus. R0 on entry
contains the handle of menu item. This item is linked with submenu or
dialog box depending on contents of R1. To connect submenu R1 may
contain menu handle (as returned by "MenuUtil_New") or absolute pointer to
the menu data structure. To connect dialog box R1 must contain window
handle of dialog box (as returned by "Wimp_CreateWindow").
Example code:
Connect "About this program" window to the item "Info"
SYS "Wimp_CreateWindow",,block% TO infoWindow%
SYS "MenuUtil_Submenu",infoItem%,infoWindow%
Create "Display" item in filer menu
SYS "MenuUtil_New",,"Filer"
SYS "MenuUtil_Add",,"Display"
SYS "MenuUtil_Submenu",,dispMenu%
MenuUtil_ColourMenu (SWI &45BCF)
--------------------------------
Creates a wimp colour setting menu
Entry:
R1 -> menu title string
R2 -> menu handle
Exit:
R0 = handle of the menu
R1 preserved
This call creates standard WIMP colour setting menu. R1 on entry
points to the title string for the menu. If R2<>0 then it points to
the handler common for all 16 items. (See also "MenuUtil_Add" for more
info about item handlers). Despite the fact that the same handler is
invoked with all items it is still possible to distinguish user
selection. MenuUtil_Decode returns not only pointer to the handler but
also the number (position) of selected item in the menu. Actually this
number is equal to the colour number.
Example code:
Create colour setting menu:
SYS "MenuUtil_ColourMenu",,"Colour" TO colourMenu%
MenuUtil_Colours (SWI &45BD0)
-----------------------------
Sets new foreground and background colours of menu item
Entry:
R0 = handle of the menu item or zero for current item
R1 = foreground colour
R2 = background colour
Exit:
R0-R2 preserved
This call allows you to change colours of particular menu item. Colours must
be selected from 16 Wimp colours.
Example code:
Change colours of current item to black on yellow
SYS "MenuUtil_Colours",,7,9
MenuUtil_TickOnly (SWI &45BD1)
------------------------------
Tick only specified menu item
Entry:
R0 = handle of the menu item or zero for current item, or
R0 = handle of the menu
R1 = item position in the menu (starting from zero)
Exit:
R0,R1 preserved
This call ticks specified item and clears tick flags in remaining items in
the menu. If you don't know the handle of the menu then you can specify
handle of the menu in R0 and position of the item in R1.
Example code:
Tick black colour in colour menu
SYS "MenuUtil_TickOnly",colourMenu%,7
----------------------------------------------------------------------
Notes from the author
MenuUtils is freeware software. Everybody is free to use MenuUtils
module, even in commercial code. In case of commercial use I would
like to know this in advance (I could than provide you with the latest
release). You can always contact me if you found some bug, or when
having other suggestions.
To contact the author of MenuUtils, please write to:
RUSSIA
115541
Moscow
Kavkazsky boulevard, 29
Bld. 1, Flat 107
Alex Petrov
E-mail: APetrov@misis.msk.su
APetrov@arm.msk.su
FIDO : 2:5020/104.13
phone: +7 095 322 2098
fax : +7 095 236 8350