APDL Public Domain 1

home *** CD-ROM | disk | FTP | other *** search

/ APDL Public Domain 1 / APDL_PD1A.iso / program / menus / !Menus / !Help next >

Wrap

Text File | 1992-05-01 | 14.3 KB | 362 lines

ARMageddon Software presents -----!Menus and MenuMod----- ------------------ WARNING!! --------- This document expects you know how to program the WIMP and basically how it works. If you don't then refer to either the RISC-OS Programmers Reference Manual (volume 3) or the hundreds of magazine articles that have been published on the subject. The programs ------------ These two programs provide an easy and effective way to produce and manipulate standard WIMP menus in your own WIMP programs. The menu structures can be easily designed using the multi-tasking application, !Menus. In much the same way that !FormEd produces 'Templates' !Menus produces files that contain all relevant information for the menus, these include indirect data and validation strings. MenuMod is a relocatable module which contains several SWI's, these allow the programmer to control the menus and change their state. This includes shading items, ticking items, changing the item's colours, changing the items text, etc. Also included with the programs are two BASIC freebies called !ListMenus and !ListTemp. All four programs will be explained after this short commercial break.... These programs are not public domain. If you find a use for any part of this software you should register your copy with me at the address at the end of this file. The registration fee is £3 if you use this software for non-commercial applications. If you will charge for your programs the registration fee is doubled at £6 You must admit these prices are not high and if enough people register it will:- a) Earn me a bit of money. b) Give me the incentive to write more CHEAP software and to improve these programs. c) Allow you to distribute the MenuMod module with your software (providing you payed the right fee of course) It will also allow you to moan about the software with some hope of me acting on it. Please report any bugs that can be repeated to me stating how and when the bug occurred. Also if there are any features you would like to see added to these programs then tell me. I can be contacted at the addresses at the end of this file. You are free to pass copies of this software, with ALL accompanying files, among your friends and enemies, but they should register their copies as well. ARMageddon software (ie. moi!) retain copyright on all these files. NO part of this software, or its files, should be altered (ie. no sneakily changing the authors name and address!) MenuMod - Technical details --------------------------- -Data MenuMod actually uses data tables identical to those used by SWI "Wimp_CreateMenu" so no extra conversion is needed you simply pass the address of the menu structure to the WIMP. As menu files contain more than one menu finding the address is a bit difficult so SWI's have been incorporated to calculate them. -Accessing menu items Menu items can be accessed in two ways :- -Menu strings These consist of a series of zero terminated strings. The entire string is similar to that returned by SWI "Wimp_DecodeMenu" ie. "Display.Small icons" for a typical filer menu selection. The only differences are that the initial menu title is placed before the selection string ie. the above example would become "Filer.Display.Small icons" also the dots are replaced with zero bytes. After all the selection strings an extra zero byte is added signifying the end. -Menu lists These are standard lists of menu selections as returned by SWI "Wimp_Poll" ie. a series of words signifying the selection path terminated by a -1. Again though the menu number (with 0 being the first in the file) is placed before the list so the above selection would become 0,0,1,-1 each number would be a word long and the 'Filer' menu would have to be the first in the file. -MenuMod SWI's All but one of the SWI's are entered with R0 pointing to the base of the menu file, this is the address where the file is loaded. On exit, all registers, unless otherwise specified, are preserved. When you are told R1 should point to a menu list/string you can use either, MenuMod detects which one you are using (It does so by checking the first word in the string/list, if its less than 256 then it's a list otherwise its a string. Incidentally strings don't have to be word aligned) SWI "Menu_Calculate" This is used to recalculate and reallocate all indirect and validation strings. It also calculates submenu addresses. It is usually called immediately after loading the menu file. SWI "Menu_Validate" This is called when sub-window handles have been calculated and stored with SWI "Menu_SetSubHandle". It checks to ensure that all sub-window handles have been defined. SWI "Menu_ListToAddress" Entry R1=Menu list Exit R2=Address of the item This call returns the address of the menu item specified in the menu list given. If the list contains only a menu number (ie. only the first word contains data) the call returns the address of the entire menu structure. This can then be used by SWI "Wimp_CreateMenu" to open that menu. SWI "Menu_StringToAddress" Entry R1=Menu string Exit R2=Address of menu item This is similar to the previous SWI except it uses menu strings. Again if only one string is passed (ie. a menu title) it returns the address of that menu SWI "Menu_Read" Entry R1=Menu string/list R2=offset to read from Exit R3=Value read This allows you to read the data at an item or menu directly. The offset is not checked so you must know where you want to load from. The base address is calculated from the data at R1, so it could point to an item or a menu. SWI "Menu_Write" Entry R1=Menu string/list R2=Offset to write to R3=Value to write This is used for writing data to items or menus. You must know where you are storing the data as it could corrupt the menu data. The following calls do not check if you are accessing a menu or an item though they should only be used on items SWI "Menu_Tick" Entry R1=Menu string/list R2=State This call allows you to change the state of an items tick icon. The state is 0 for no tick and non-0 for a tick. SWI "Menu_Shade" Entry R1=Menu string/list R2=State This sets the shade flag. The state is 0 for no shade and non-0 to shade an item. SWI "Menu_GetIndirect" Entry R1=Menu string/list R2=Item to read from Exit R3-R5=Indirect data (3 words) This call finds the addresses of the indirect data. As the commonest use of this call is for finding the address of a writable item, it uses a slightly different method of access items. Most writable items will be blank when the menu is defined and you can't use a blank in the menu string (a blank string would be classed as a double zero byte, or the end). To get around this you only specify the menu where the item is in the menu string/list, so if you were accessing the input mode number option from the palette you would pass either 'Mode' or the menu number in the buffer at R1. You then specify the item you want to read from in R2, in this example this would be 3 (item 4 counted from 0). This value could be replaced with -1, the SWI will recognises -1 as meaning 'the last item in the menu'. On exit R3 is the pointer to the indirect string, R4 is the pointer to the validation string (-1 for none), and R5 is the length of the indirect string. These are standard pointers. R3 is probably the most useful as it would point to the data of a writable item. Though it could be used to store items like the "File 'xxxxxxx'" item in the Filer menu. SWI "Menu_SetSubHandle" Entry R1=Menu string/list R2=Sub window handle This call sets up sub window (or dialog box) handles. It returns an error if the item wasn't defined as a sub window. The last call is used internally though I thought it might be useful for other things. SWI "Menu_StringCompare" Entry R0=First string R1=Second string R2=Terminating character R3=Maximum number of characters to compare before returning 'equals' Exit R0 & R1 Are updated. They will point to after the terminators or after the first difference, depending on the outcome. Z=1 for 'equals',Z=0 for 'not equals' This compares the two strings specified. The comparison is case sensitive. If R2 is zero on entry then the the call will accept any control code as a terminator. The call sets the flags so that NE/EQ suffixes can be used in machine code (BASIC programmers can ignore that last bit!) -Menus. If you didn't understand the last bit I don't blame you. Have a look at the BASIC file $.!Menus.!RunImage to get a better idea of how to use the calls. In the program there's a function FNms(m$) this call can be used for generating menu strings, an example could be (in BASIC) SYS "Menu_Tick",Menus%,FNms("Filer:Display.Small icons"),1 The ':' and '.' are treated identically but I thought it would be make it look better. To load and setup a menu file you usually do some code similar to the following pseudo-basic:- DEF PROCmenus x%=(size of menu file) DIM Menus% x% OSCLI("Load <Appl$Dir>.Menus "+STR$~(Menus%)) SYS "Menu_Calculate",Menus% sub window handles are then stored for example SYS "Menu_SetSubHandle",Menus%,FNms("Application:Save"),SaveWindowHandle% SYS "Menu_Validate",Menus% ENDPROC The !Menus Application ---------------------- This program creates the menu tables used by MenuMod. -The !Menus icon Clicking select over this icon will, if possible, create a new menu. Clicking menu over the icon will bring up a menu with Save,Quit, and Info which are standard options. It will also duplicate the New Menu option provided by select. -The Menus So that complex menus can be viewed easily the menus created are displayed with a 'back' icon on their title bars. This also shows you which are menu definitions and which are actual WIMP menus. Menus gain a vertical scroll bar when they reach a certain height (about 900 OS units). Otherwise the menus look identical to normal WIMP menus. These menus will be referred to as emulated menus. -What next? Clicking menu on a emulated menu item will bring up a menu with the following options -Title This allows you to change the menu title. You must give menus titles. The program will generate an error if you don't. -Width This allows you to change the width of the menu items. -Item style This leads to a submenu which control the item where the menu button was originally pressed. It give the following options -Indirect Selecting on this icon will toggle the indirect flag. When the flag is set the item has a submenu which lead to a writable icon where you specify the length of the data. -Validation This item is shaded when the indirect flag is clear. Otherwise it leads to a writable icon where you specify the validation string. -Data This submenu will allow you to change the text used by the item. The input is restricted to the conditions of the validation string. -Foreground & -Background These are used to change the colour of the item. The other options provide pretty obvious functions (ie. Tick) the items current settings are signified by ticks next to the appropriate option. Selecting 'Messages' will make submenu selection from that menu item generate the 'Message_MenuWarning' message. If you don't understand that don't bother and don't use it! Selecting "Sub window" will set the submenu pointer ready to accept a window handle. See SWI "Menu_SetSubHandle" for more details. -Insert after & -Insert before These will insert a new menu item after/before the selected menu item. -Delete item Deletes the selected item. -Link menu This leads to a subwindow. If you drag (with select) the icon to a menu item it will link the current menu to that item. The item then gains the submenu arrow. You can't link a menu to its self. -Delete link Will delete a link made by the last option. -Delete menu This will ask for confirmation of the delete. If you respond with OK the program will check all other menus deleting any links it finds to the selected menu. It will then delete it. Clicking select on an emulated item will :- a) If the item has no sub window/handle the program will beep. b) If the item links to a sub window then the program will tell you so. c) If the item has a submenu then this is moved to just right of the sub arrow. -Filing operations The program loads and saves in the proper RISC-OS way, and I've acquisitioned file type &321 for menu files. Other files can be merged with the current one by dragging them to the !Menus icon. The directory 'Menus' contains a few default menus such as a 'Colours' menu. !ListTemp & !ListMenu --------------------- These two programs can be used to yield information on Templates and Menu files respectively. The output can be sent to a printer which makes the programs very handy for remembering template names and menu selections. Both programs ask for a filename if the last character is a '.' it is treated as being an application directory and the name is suffixed with either 'Templates' or 'Menus'. ie. entering '!Menus.' will make it load the file '!Menus.Templates' or '!Menus.Menus' Right, now where to send your money ----------------------------------- You can send your money £3 or £6, along with your name and address, to me at David Andrews 3 Penzance Street Moor Row Cumbria (The North!!) CA24 3JH Within two weeks you will receive confirmation of your registration. If you use BBS it might help if you give a contact point. You can also ask for extra help or information on the following BBS's Username :- Elwood Blues (Alias David Andrews) The World of Cryton 0749 79794 Noah BBS 0272 572322 Archive BBS 0603 745932 Arcade BBS 081 6542212