***** !ReadMe file for !MenuEd ****** **Last update 17 Jun 1992 **
Welcome to !MenuEd. !MenuEd is exactly that, an editor for menu structures.
This is pre-release version of !MenuEd that is Shareware (subject to the conditions below).
All of the important bits have been implemented - this is not the sort of pre-release where you can't save! - Only some of the less useful functions are not available on the version, such as font handling and the menu colour selection. One or two other more useful things are also unavailable becauase they haven't yet been implemented. All in all, this version will probably have most of the features that you will need.......If not you can buy the full version.
Originally, when Acorn launched RISCOS II, a template system for windows was implemented. !FormEd was written (or converted?). This allows window layouts to be easily created/edited. This is very convenient and useful for anyone writing any piece of RISC OS software.
Unfortunately a system of templates for menus was completely overlooked. This has meant that you could either write a small routine to create the menu in your program or have the menu in a ready to use form in your code. Either way, this is not easy and can be particularly frustrating to do.
This is where !MenuEd comes in. !MenuEd will allow you to make the most out of the RISCOS menu system, making the fonts and sprites in menus so much easier. You can also play around with different styles, colours etc.
!MenuEd, unlike some systems, uses the menu you are creating to select editing functions, so you get an instant preview of the the menu. This means the usual RISC OS interface and definately NO script or command files!
!MenuEd is designed with practicallity in mind, it is written entirly in assembler to use as little space as possible. It uses only 56K on 1MB computer (64k on a 2Mb & +4MB) even with a small file loaded. This means it can realistically multi-task (unlike !FormEd that sometimes crashes unless it gets 640k).
You can realistically run it alongside !Paint, although memory data transfers (ie. a transfer without a scrapfile) are not available yet. All types of internal memory transfers between files in !MenuEd are supported - not like some applications where they save to a scrapfile and the re-load it!
!MenuEd can handle 35 files simultaniously. Each file can theoretically contain over 33 million templates. Unfortunately nobody will every be able test this!. Each template contains one menu structure. At present I can only reach 8 levels of depth in the tree, but apart from this there is no limit to the size of the menu itself apart from the size of your system.
Now for the documentation......
I presume that anyone reading this and wishing to write RISCOS software will understand the terminology.
Menu structures are described in more detail on pages 1226-1230 of the Programmer's Reference Manuals.
Icons (which is effectively what a menu item is) are descibed on pages 1180-1187 of the PRMs
The window template calls are descibed on pages 1236-1239 of the PRMs. These may be worth looking at as the Winsupport calls for loading templates in is very similar to these.
The !MenuEd icon bar icon
-------------------------
Clicking select or adjust will open a new file
Clicking menu will open the icon bar menu
Dragging a sprite file will cause it to be loaded and merged with any other sprites that have been loaded in.
Dragging in a template file will cause it to be loaded in a new window.
The '!MenuEd' icon bar menu
---------------------------
Info - Normal program info etc.
New File - Open a new file if possible (if there is a shortage of memory in the RMA or next slot this may be a problem).
Minimise - !MenuEd uses my own heap manager that implements a very tidy sliding heap. The heap can shrink itself down as far as possible and return any spare memory (If there is more than your computer's pagesize (1Mb - 8k 2Mb - 16k 4+MB - 32K) to the wimp's free pool for use elsewhere on the system.
Also, !Menued has a draggable (red) memory bar in the task manager. By dragging this you can change !Menued's slot yourself, although you can't reduce it below the minimum size (selectable with the minimise option).
The heapmanager is included with the support module needed to load menu template files.
Quit - Quits !MenuEd. You will be asked if you want to save any edited but unsaved files. Similarly if you select Exit on the task manager menu !MenuEd behave in the same manner.
The menu template file window
-----------------------------
The menu template file window displays a list of the templates in the file.
To select a template use select or adjust.
Clicking select on a selected item will cause an 'Edit Menu' window to open for the first menu in the structure.
Clicking adjust will deselect an item
Clicking menu will open the menu template file menu and if no template is selected will select the template directly under the pointer.
Dragging a menu template file either from the filer or another !MenuEd window into the window will cause it to be merged with the file.
Dragging a sprite file into here will cause it to be loaded into the central sprite area.
The menu template file menu
---------------------------
Info - The Info Sub-window/menu displays the size of the file, date of last modification (or current date if new file) and whether the file is modified or not. Additionally, the total size of all of the menu data in the templates is displayed. This is useful when calculating the size it will use when loaded back into a program. Similarly the amount of indirected data used is also displayed.
Save - This opens onto a submenu:
File - this option allows you to save the whole template file. The save dialog box works in the normal way. A menu template file with no templates is valid but useless!
Selection - This allows you to save the current file selection (providing there is one)
Selection - This opens to a submenu:
Info - This is similar to the info option on the parent menu except that the menu and indirected data size fields are filled in for the current selection (only available when there is one)
All - This selects all of the templates Control-A can also be used when the window has the input focus (the title bar is yellow)
Clear - This clears the template selection. Control-Z does the same.
Copy - this makes a copy of the template with the name specified in the submenu.
Rename - This renames the template with the name specified in the submenu.
Delete - This deletes the current selection. Control-X does the same job. A dialog box will be opened dependant on the setting of the delete action flags (see later in this file)
Colours - Opens the colour selection window. Control-B does the same ***Not available with this version****
Fonts - Opens the font selection window. Control-F has the same action. ***Not available with this version****
Colours - This opens the colour selection window. ***Not available with this version****
Fonts - Opens the font selection window. Control-F has the same action. ***Not available with this version****
View Menu -> Submenu is the menu being created/edited for the selected item. If two or more items are selected, this option will be unavailable. Clicking in the submenu will open the Edit Menu Item window for the item allowing its attributes to be edited
New Template - This adds new template to the file with the name <Untitled> as a template name, menu title text and menu item text. The default menu has one item with the usual flags set.
Edit Menu Window
----------------
This window allows you to alter the characteristics of the menu (ie. size)
Menu Title: This is the title of the menu that appears as the title bar. Up to 12 characters only.
Number of items: Enter number of menu items in icon using the keyboard or use the arrows at either side. This is inteded for quick creation of menu structures. If you decrease the number of items you will be asked if you wish to delete i) Items ii) Submenus (if present). The first items are kept. So if you decrease the number from 10 to 5 the last 5 items will be deleted.
Custom Size/Automatic calculation. These icons select between the automatic calculation of menu sizes and your own custom sizes.
The width is the width of the menu in OS graphics units. Item height is the height of each item in OS graphics units and Space is the gap in between items
in OS graphics units.
If automatic calculation is selected the height defaults to 40 and space to 0. This is the RISC OS norm. The automatic sizing is calculated from the largest item in the menu every time an operation that might upset the sizing is carried out ie. adding an item, deleting an item, changing an items text. If you set a custom width it will be overwritten every time the menu is edited, so this should be done after the menu has been finished. If you pad out a writable icon, the sizing routine will size the menu to the full size of the icon, possibly very big if a large string is used, so a custom size will need to be set here.
Clicking on the cancel icon cancels the whole window including the number of items entered.
Clicking on OK makes the selected changes.
In the window the up/down arrow keys move between writable sections. Pressing return moves onto the next icon and when on the last selectable icon is equivelant to clicking on OK.
Edit Menu Item
--------------
This window allows you to edit the appearance of the menu item, including the use of sprites and text.
Item text: This the text used in the item. Any length may be selected. If more than 11 characters long indirected text must be used. Up to 256 characters can be used when indirection is used.
Indirection Icon: This allows you to select the indirection and enter text into the validation string icon.
Validation Icon: Any number of characters may be used (up to 256).
For information on the use of text and validation strings see the Wimp_Create Icon section in the Programmer's reference Manuals (Vol. 3. Pages 1180-1187).
Chars: This is the size of the indirected text string. It must be at least be as big as the text, as overwise the length of the text will overide it. Mostly it is set automatically but can be changed by the user to reserve space for a large writeble icon.
Menu flags:
Text: This determines how text is used along with the sprite icon.
Sprite: Selects sprite use. See Text above.
Shaded: Shades icon. (makes it unselectable). NB. It is impossible to select the item after this bit is set unless you use the back/forwards an icon on the menu (only where there are more than one icon).
Tick: This item is ticked.
Dotted Line: A dotted line appears after item.
Writable: The item is writable - it gains the caret when the menu is opened.
NB. If the text is indirected, the items text will be altered permanently if it is edited in its menu.
Border: A border is drawn round the item.
1/2 Size Sprite: Sprite is drawn half size (only available when Sprite selected)
Note about sprites: At present, combined text and sprite items do not get displayed correctly. Indirected sprite only icons have their sprite pointers set to the internal sprite pool IF the sprite is available there. Otherwise, it is set to 1, indicating that the wimp pool should be used. If the sprite is not available here, nothing will be displayed.
Horizontal Alignment.
Text and or sprite either centered, right aligned or left aligned. When both text and sprite selected the effect may be different.
Default: Clicking here will reset the option flags to the default values but not the text or indirected text icon.
Cancel: Window closed, nothing set
OK: makes changes selected
Clicking menu opens the menu:
Edit Item menu
--------------
Add - Open onto submenu
Item - add item either before or after currently edited one. (select on submenu)
Submenu - add submenu onto this item
Copy item & submenu *** Not available with this version ***
Cut item & submenu *** Not available with this version ***
Paste item & submenu *** Not available with this version ***
Delete - Opens onto submenu
- Item: (control-X does the same) deletes current item only when there is more than one item.
- Submenu: - only if there is one.
Back Item: Go back an item in the menu (if there is one). Control-Up-Arrow does the same thing.
Next Item: Go Down one item in the menu tree (if there is one). Control-Down-Arrow does the same thing.
Fonts: Font selection window *** Not available with this version ***
Colours: Colour selection window *** Not available with this version ***
Edit Menu: Enter Edit Menu window for this menu.
A Quick way to see how !MenuEd works.
-------------------------------------
Look inside the !MenuEd application directory by shift-double-clicking. Here you should find a file called 'MenuTemps', this is !Menued's own menu template file used for all of the internal menus. Load this by dragging on the !MenuEd icon. This should show you how the menu structure handled when loaded.
Configuration of !MenuEd for expert users.
------------------------------------------
!MenuEd has a system variable describing the actions on destroying data by deleting. The user can either chose to have a warning message displayed to confirm the operation or for it to happen without warning.
This is included to speed up operations, especially using key-stroke combinations. Howether, you may find that if you turn off a message for an option with a key-stroke alternative that it is too easy to accidentally select it with the key-stroke.
A set of flags is passed in a system variable called <MenuEd$MessageOptions> which can be found in the !Run file. The option string contains a number of letters representing different circumstances. A '~' immediately before means cancel the option. If fact !MenuEd defaults to using to maximum warning unless the option is specifically disabled
The following letters have these effects:
T - Warn user when a template or a selection of templates is about to be de -leted.
I - Warn user when a menu item is about to be deleted, either in the edit
menu window or from the edit item menu.
M - Warn user when a (sub)menu is about to be deleted.
S - Warn the user when a submenu is deleted along with an item. I not set
no warning is given about the item (Flag I).
Example of line in !Run file
Set MenuEd$MessageOptions TMS~I
This would select messages for all deletions except for that of menu items.
What !MenuEd will do......
--------------------------
Sprites are supported, dragging them in will cause them to be loaded. Data transfers with other software providing sprites is implemented but only using the scrapfile. Eventually, memory data transfer will be supported, something that will make using !Menued and !Paint together much easier.
!MenuEd now supports all kinds of internal data transfer (ie. saving to itself - when the user drags the icon to the !MenuEd icon on the icon bar or into a file window. All of these options are relatively straight forward.
Font and colour provision is available on the full version which is now available from me at the address below.
Cut/Copy/Paste of parts of menus. These options will be available soon.
By thw time this gets to you, the full version will be finished.
The WinSupport module which !MenuEd uses is well worth looking at. A copy is obviously included with !MenuEd. If you require the documentation directory is cheque/P.O./ made payable to M.J.Olleson for £1.50 / coins stuck on the letter or a disc and return postage and packaging to the address below requesting a copy of it. (I distribute it on disc.)
Loading templates into programs:
--------------------------------
Well, here is the other important bit, what to do with the templates now you have created them.....
Loading the template is done in a similar way to loading a window template. The WinSupport module (which is needed to use !MenuEd) provides a call with very similar arguments to Wimp_LoadTemplate. You will need the WinSupport module loaded to use the call...
SWI "WinSupport_XTemplate" (&43EC5)
Use: Open/Load Template/Close extended template file. Extended Template calls complement the Wimp ones by providing a menu template system.
rc: 0 - Load template file'
1 - Load menu template
2 - Close template
Re-Entrancy: I can't see why you would want to use this in an interrupt routine but anyway, the SWI with reason code 1 should be re-entrant as long as the SWI with rc 0 & 2 is not called from an interrupt routine.
Processor Mode: SVC
SWI "WinSupport_XTemplate" (rc: 0)
On Entry: r0 - Reason code (0)
r1 - Zero terminated filename of menu template file
On Exit: r0-r1 Preserved
Notes: This in fact loads the template file into module workspace to save time when actually loading templates. Only one can be opened at once (Remember to close it when you've finished).
SWI "WinSupport_XTemplate" (rc: 1)
On Entry: r0 - Reason Code (1)
r1 - Buffer for Menu
r2 - Pointer to indirected icon workspace
r3 - Pointer to end of indirected icon workspace
r4 - Pointer to font table (-1 if non are to be used)
r5 - Pointer to template name.
r6 - Index into template list (0 for first call)
r7 - Pointer to private sprite area (current unsupported)
On Exit: r0-r1 & r3-r5 Preserved
r2 - Next Free byte in indirected icon workspace
r6 - Index number for template list
Use: This SWI is used to load a template from the currently open template file. The template name is pointed to by r5. The template name can contain wildcards. A '*' causes automatic match if the strings match up to the point of the wildcard. A '#' is a single character wildcard, substituting the character it replaces.
The wildcards tie in with the Index number. This is used when searching for templates with a wild card, it indicates where to search from when a match has already been found - the SWI is called with the same search name.
For instance, a number of templates can have the same name and all can be pulled out in order.
As with Wimp_LoadTemplate r2 & r3 are the pointer to indirected data and pointer to the end of the data that is never exceeded. Unlike Wimp_LoadTemplate, both !MenuEd and WinSupport round the size of indirected data up to a multiple of four, this may seem wasteful but improves speed overheads and make life easier....
r1 points to a area to copy the menu structure into. There is no check on size and if it is extended this may cause problems. The best way to get it right is to use !MenuEd file info window on the select submenu which will give the size of the menu data for the template (and also for indirected data)
r7 - Contains an address of a private sprite pool used in the menu. Any sprite pointer (only available with indirected sprite-only items) which isn't 1 (wimp sprites) will be substituted with the address provided. If -1 is provided in r7, all such references will be changed to 1 which indicates that the internal (WIMP) sprite pool is to be used instead. It is important that if sprites are used in a menu that r7 contains either -1 or a pointer to a valid sprite pool, otherwise a serious error may occur.
Fonts are treated in the same way as they are in Wimp_LoadTemplate. If the font array pointer is -1 fonts and fonts are found in the template, the references to fonts are turned into references to the system font and an error is returned. Unlike Wimp_LoadTemplate, WinSupport does not claim a font every time a font is found in a menu item, if it did, a menu containing font items could increase the font usage count beyond 255 causing it to loop round to zero. Instead, Winsupport finds the font, and if the font handle's byte is not zero it will then lose it again. This way any font will only be found once. As with Wimp_LoadTemplate, you can use just one 256 byte font array, each byte containing the number of times a font has been found by your program, indexed by the font handle, passing it into the template calls each time.
Due to the recursive nature of the routine used in this SWI, error trapping is handled unusually. An error flag is kept, and if at the end of processing, it is set, the relevant error is returned. Unfortunately, only the first error is returned so other errors may well also have occured.
SWI "WinSupport_XTemplate" (rc: 2)
On Entry: r0 - Reason code (2)
On Exit: r0 Preserved
This call simply discards the template file and releases the RMA space that was claimed. If you don't do it, other software using the call will not be able to load its own templates.
In BASIC a routine to load in a menu template may look like this:
DIM q%256,ind%100 \ reserve memory for templates
SYS "WinSupport_XTemplate",0,"MyMenuTemps" \ open template file
\\ statements to load more templates are put here.
SYS "WinSupport_XTemplate",2 \ close template file.
\ q% is the space reserved for the menu structure
\ ind% is the space for indirected data
\ index% is the index to use for the next call
\ endofinddata points to the end of the indirected data after the call
SWI "XWinSupport_RelocateMenu" (&43EC6)
Provided with old and new addresses, this routine will correct all pointers to absolute addresses in the menu structure which may have become corrupt due to the movement of heap blocks etc.
On Entry:
r2 -Old Menu pointer
r3- Old Indirected data pointer
r4- New Menu Pointer
r5- New Indirected data pointer
r6- New Address of sprites (-1 for no change)
On Exit:
r2-r5 preserved
It should be noted that !MenuEd tells the difference between valid window handles and absolute address found in menus by checking that the address is bigger than &8000. If you use this routine to relocate the menu offset to start from zero (ie. converting to offset form), it will be impossible to convert back again as all submenu pointers will be considered as window handles.
Versions from this point (anything above 1.01) onwards will be not be P.D. and will be sold on a normal sort of basis..ie. paying for it and not copying it. If you would like a copy of the latest version please send a cheque or P.O. made payable to M.J.Olleson for £5 to the address below. Once you have bought a copy, you will be entitled to an upgrade for by sending £1 and the original disc to me.
Licencing agreement for version 1.01 !MenuEd.
---------------------------------------------
All occurences of !MenuEd in this agreement refer to version 1.01 only.
1) If you use !MenuEd for any purpose other than that of approval you must register. If you merely have a copy but make no use of it, there is no need to register and it's fine to pass it around your friends.
If you use !MenuEd as a software developement aid in the creation of software which will be supplied to/used by a third party, full registration is necessary.
The good news is that normal registration is FREE. Full registration costs a miserly £5 and if you send a disc with registration you will recieve a full version of !MenuEd will all of the facilities implemented.
Failing to register correctly will be a breach of this licencing agreement and therefore a breach of copyright which is both a civil liability and a criminal offence, which could lead to legal action and/or prosecuted.
2) !MenuEd must be copied whole with no part ommited or modified.
3) There is to be no commercial gain from the distribution of !MenuEd v.1.01. I do, howether grant Peter Sykes (APDL) permission to distribute it as I can be sure about the honesty of his operation. Any other P.D. libraries are welcome to distribute it as long as they contact me first and a fee of less than £3 is charged for !MenuEd that ONLY covers reasonable expenses incurred in distribution.
4) Use of !MenuEd on one workstation is covered by this agreement. If you are going to be using it on more workstations or on a network, full registration and a site licence will be neccesary. Please contact me if you have any enquiries.
5) Use of !MenuEd in schools/colleges and for training purposes is prohibited unless full registration is obtained. In many such cases a site licence will also be required.
If you wish to use the module for any other purpose the agreement should be obtained and observed. The agreement is obtainable free of charge (provided you provide a disc to put it on and return P&P) from the address below.
7) I reserve the right to terminate agreement whenever I choose and will not be liable for losses resulting from this.
8) This agreement and the fact that only version 1.01 is legally copiable is made clear to anyone who recieves a copy from you.
9) In no event will M.J.Olleson or any supplier(s) be liable for indirect, consequential or incidental damages.
Bugs/Suggestions/critisism: Please send them to me. Every effort has been made to remove bugs from this piece of software but obviously, the occasional bug will occur. In order for bug reports to be useful, I need to know exactly what you were doing when the bug occured. If you can send files you were creating at the time this would be more helpful.
