home *** CD-ROM | disk | FTP | other *** search
-
- The HASWIN window library.
- ===========================
- Copyright H.A. Shaw 1990.
- ===========================
-
- Menus under the HASWIN system.
- ------------------------------
- The HASWIN menu is a data structure created and maintained by the
- HASWIN routines. A menu has the following user selected features.
-
- 1) An X and Y offset from the mouse position to where the menu
- is to opened if opened automatically by a mouse MENU click.
- 2) Pointers to windows to open in order to provide help
- information for the menu itself, the icon the menu was opened
- from, and the window the icon was in.
- 3) A pointer to a routine to call to create the menu.
- 4) A pointer to a routine to call after a selection is made from
- the menu.
- 5) A pointer to a routine to call if a WIMP Message_MenuWarning
- message arrives while the menu is open. The message is sent
- if the pointer passes over a menu section which has the
- 'generate message' bit set.
-
- The WIMP provides a very complex menu system, with sub-menus,
- windows and sprites within menus which may be in many colours, and with many
- spacings. Since it is not easy for a user program to deal with all the
- possible options, HASWIN provides a set of routines to create, display and
- decode menus into text strings. A menu is made up of icons and is created
- from a text string of the following form...
-
- menu := <t-opts>:<title>.<m-opts>:<item>.[<m-opts>:<item>]
- t-opts := <toption><tsep>[<toption><tsep>]
-
- toption := &NN - title background colour NN.
- | $NN - title foreground colour NN.
- | *NN - work background colour NN.
- | @NN - work foreground colour NN.
- | >NN - maximum width of menu.
- | <NN - minimum width of menu.
- | ^NN - minimum height between lines.
- tsep := space
- title := up to 12 characters out of 'a'-'z', 'A'-'Z', '0'-'9'
- m-opts := - - dotted menu separator above.
- | _ - dotted menu separator below.
- | / - place tick at left.
- | | - generate menuwarning message.
- | # - item in inner menu is a window name.
- | <sp> - separator, ignored.
- | , - separator, ignored.
- | T - Text icon.
- | S - Sprite icon, can be combined with T.
- | < - left adjust text.
- | > - right adjust text.
- | F - filled background.
- | $NN - use antialiased font NN (<sp>, ends).
- | h - display any sprite 1/2 size.
- | +NN - writable item, buffer length NN (<sp>, ends).
- | &NN - background colour (<sp>, ends).
- | @NN - foreground colour (<sp>, ends).
- | {str} - validation string "str".
- | [blk] - sprite area control block "blk".
- | `font`- use antialiased font called "font".
-
- Characters inside '...' quotes are never considered to be options or
- separators. Therefore a title or item can have '.' inside it by
- placing the title or item in '...' quotes. The quote marks are
- removed before the menu is displayed.
-
- If the user clicks with the MENU button on an icon created by HASWIN
- or in a window created by HASWIN then a menu is automatically opened. This
- is done by calling "haswin_createmenu()" with the window and icon clicked
- in, and the X and Y positions of the mouse click. haswin_createmenu()
- searches for a menu to open by performing the following pseudocode:
-
- start
- If there is an icon
- If the icon has a menu
- use it
- otherwise
- create a blank menu
- If the icon is on the icon bar
- If there is an information window
- add "Info" to the menu
- If there are load/save file routines
- add "Load/Save files" to the menu
- If the icon has a window to open
- add "Window, open/close" to the menu
- If the icon has a help window
- add it to the menu
- If the icon has its ICON_CANQUIT flag set
- add "Quit" to the menu
- If there is a window and we have not got any menu from the icon
- If the window has a menu
- use it
- otherwise
- create a blank menu
- If the window has a help window
- add it to the menu
- Add the extra bits to the menu
- Look for a "makemenu()" routine either in a menu we have found, or
- the one passed into the routine.
- If the routine exists
- If it returns HASWIN_TRUE
- create the menu
- otherwise
- create the menu
- finish
-
- This seems most complicated but it allows much flexability. For
- example if an icon has its ICON_CANQUIT flag set then a Quit item will be
- automatically added to the menu for it. HASWIN will respond to the Quit
- selection itself. If the user program defines file load or save routines
- then any icon on the iconbar of the program will automatically have all
- the required items added to it and HASWIN will deal with all menu selections
- itself. The same happens with Help windows that may be associated with
- windows, icons or menus. The routines that deal with menus are described
- below.
-
- menu *haswin_makemenu(menu *mu, char *str,
- int (*makemenu)(struct menu *),
- int (*domenu)(char *, struct menu *),
- int (*message)(buffer *, struct menu *))
- - Make a menu ready for use by HASWIN. If "mu" is 0 a new menu
- block is created from scratch. "str" is the text string used
- to make the menu from, or 0 if there is no such string.
- "makemenu" is the user menu building routine for this menu, or 0
- if there is no routine. "domenu" is the user routine to call when
- a menu selection has been made, or 0 if there is no routine.
- "message" is the user routine to call if the menu causes the
- generation of a MenuWarning message, or 0 if there is no routine.
- - Returns a pointer to the menu routine or 0 on any error.
- Note that this routine does not actually put the menu on the
- screen.
-
- int haswin_createmenu(window *win, icon *ic, char *extra,
- int (*user)(char *, menu *), int x, int y)
- - This routine searches "win" and "ic" for a menu to open. The
- searching rules are described above. The X and Y coordinates of
- the opening place of the top level menu are adjusted by the values
- in "x" and "y" respectivly. If "user" is non-zero then it is
- called instead of the menu's own "makemenu()" routine. If "extra"
- is non-zero then it is a text string defining a menu which is
- added to the top of the menu created. HASWIN_TRUE is returned
- if successful, and HASWIN_FALSE on any error.
-
- int haswin_recreatemenu()
- - This routine takes an existing menu and calls its "makemenu()"
- routine before reopening it. This is used by HASWIN when a menu
- selection is made with the ADJUST button. HASWIN_TRUE is returned
- if successful, and HASWIN_FALSE on any error.
-
-