home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / clib / progs / haswinlib / info / menus < prev    next >
Encoding:
Text File  |  1991-02-04  |  7.7 KB  |  153 lines
  1.  
  2.                       The HASWIN window library.
  3.                      ===========================
  4.                       Copyright H.A. Shaw 1990.
  5.                      ===========================
  6.  
  7. Menus under the HASWIN system.
  8. ------------------------------
  9.         The HASWIN menu is a data structure created and maintained by the
  10. HASWIN routines.  A menu has the following user selected features.
  11.  
  12.         1)      An X and Y offset from the mouse position to where the menu
  13.                 is to opened if opened automatically by a mouse MENU click.
  14.         2)      Pointers to windows to open in order to provide help
  15.                 information for the menu itself, the icon the menu was opened
  16.                 from, and the window the icon was in.
  17.         3)      A pointer to a routine to call to create the menu.
  18.         4)      A pointer to a routine to call after a selection is made from
  19.                 the menu.
  20.         5)      A pointer to a routine to call if a WIMP Message_MenuWarning
  21.                 message arrives while the menu is open.  The message is sent
  22.                 if the pointer passes over a menu section which has the
  23.                 'generate message' bit set.
  24.  
  25.         The WIMP provides a very complex menu system, with sub-menus,
  26. windows and sprites within menus which may be in many colours, and with many
  27. spacings.  Since it is not easy for a user program to deal with all the
  28. possible options, HASWIN provides a set of routines to create, display and
  29. decode menus into text strings.  A menu is made up of icons and is created
  30. from a text string of the following form...
  31.  
  32.         menu    := <t-opts>:<title>.<m-opts>:<item>.[<m-opts>:<item>]
  33.         t-opts  := <toption><tsep>[<toption><tsep>]
  34.  
  35.         toption := &NN     - title background colour NN.
  36.                 |  $NN     - title foreground colour NN.
  37.                 |  *NN     - work background colour NN.
  38.                 |  @NN     - work foreground colour NN.
  39.                 |  >NN     - maximum width of menu.
  40.                 |  <NN     - minimum width of menu.
  41.                 |  ^NN     - minimum height between lines.
  42.         tsep    := space
  43.         title   := up to 12 characters out of 'a'-'z', 'A'-'Z', '0'-'9'
  44.         m-opts  :=  -     - dotted menu separator above.
  45.                 |   _     - dotted menu separator below.
  46.                 |   /     - place tick at left.
  47.                 |   |     - generate menuwarning message.
  48.                 |   #     - item in inner menu is a window name.
  49.                 |   <sp>  - separator, ignored.
  50.                 |   ,     - separator, ignored.
  51.                 |   T     - Text icon.
  52.                 |   S     - Sprite icon, can be combined with T.
  53.                 |   <     - left adjust text.
  54.                 |   >     - right adjust text.
  55.                 |   F     - filled background.
  56.                 |   $NN   - use antialiased font NN (<sp>, ends).
  57.                 |   h     - display any sprite 1/2 size.
  58.                 |   +NN   - writable item, buffer length NN (<sp>, ends).
  59.                 |   &NN   - background colour (<sp>, ends).
  60.                 |   @NN   - foreground colour (<sp>, ends).
  61.                 |   {str} - validation string "str".
  62.                 |   [blk] - sprite area control block "blk".
  63.                 |   `font`- use antialiased font called "font".
  64.  
  65.         Characters inside '...' quotes are never considered to be options or
  66.         separators.  Therefore a title or item can have '.' inside it by
  67.         placing the title or item in '...' quotes.  The quote marks are
  68.         removed before the menu is displayed.
  69.  
  70.         If the user clicks with the MENU button on an icon created by HASWIN
  71. or in a window created by HASWIN then a menu is automatically opened.  This
  72. is done by calling "haswin_createmenu()" with the window and icon clicked
  73. in, and the X and Y positions of the mouse click.  haswin_createmenu()
  74. searches for a menu to open by performing the following pseudocode:
  75.  
  76. start
  77.         If there is an icon
  78.                 If the icon has a menu
  79.                         use it
  80.                 otherwise
  81.                         create a blank menu
  82.                 If the icon is on the icon bar
  83.                         If there is an information window
  84.                                 add "Info" to the menu
  85.                         If there are load/save file routines
  86.                                 add "Load/Save files" to the menu
  87.                 If the icon has a window to open
  88.                         add "Window, open/close" to the menu
  89.                 If the icon has a help window
  90.                         add it to the menu
  91.                 If the icon has its ICON_CANQUIT flag set
  92.                         add "Quit" to the menu
  93.         If there is a window and we have not got any menu from the icon
  94.                 If the window has a menu
  95.                         use it
  96.                 otherwise
  97.                         create a blank menu
  98.                 If the window has a help window
  99.                         add it to the menu
  100.         Add the extra bits to the menu
  101.         Look for a "makemenu()" routine either in a menu we have found, or
  102.         the one passed into the routine.
  103.         If the routine exists
  104.                 If it returns HASWIN_TRUE
  105.                         create the menu
  106.         otherwise
  107.                 create the menu
  108. finish
  109.  
  110.         This seems most complicated but it allows much flexability.  For
  111. example if an icon has its ICON_CANQUIT flag set then a Quit item will be
  112. automatically added to the menu for it.  HASWIN will respond to the Quit
  113. selection itself.  If the user program defines file load or save routines
  114. then any icon on the iconbar of the program will automatically have all
  115. the required items added to it and HASWIN will deal with all menu selections
  116. itself.  The same happens with Help windows that may be associated with
  117. windows, icons or menus.  The routines that deal with menus are described
  118. below.
  119.  
  120. menu *haswin_makemenu(menu *mu, char *str,
  121.                       int (*makemenu)(struct menu *),
  122.                       int (*domenu)(char *, struct menu *),
  123.                       int (*message)(buffer *, struct menu *))
  124.         - Make a menu ready for use by HASWIN.  If "mu" is 0 a new menu
  125.           block is created from scratch.  "str" is the text string used
  126.           to make the menu from, or 0 if there is no such string.
  127.           "makemenu" is the user menu building routine for this menu, or 0
  128.           if there is no routine.  "domenu" is the user routine to call when
  129.           a menu selection has been made, or 0 if there is no routine.
  130.           "message" is the user routine to call if the menu causes the
  131.           generation of a MenuWarning message, or 0 if there is no routine.
  132.         - Returns a pointer to the menu routine or 0 on any error.
  133.           Note that this routine does not actually put the menu on the
  134.           screen.
  135.  
  136. int haswin_createmenu(window *win, icon *ic, char *extra,
  137.                         int (*user)(char *, menu *), int x, int y)
  138.         - This routine searches "win" and "ic" for a menu to open.  The
  139.           searching rules are described above.  The X and Y coordinates of
  140.           the opening place of the top level menu are adjusted by the values
  141.           in "x" and "y" respectivly.  If "user" is non-zero then it is
  142.           called instead of the menu's own "makemenu()" routine.  If "extra"
  143.           is non-zero then it is a text string defining a menu which is
  144.           added to the top of the menu created.  HASWIN_TRUE is returned
  145.           if successful, and HASWIN_FALSE on any error.
  146.  
  147. int haswin_recreatemenu()
  148.         - This routine takes an existing menu and calls its "makemenu()"
  149.           routine before reopening it.  This is used by HASWIN when a menu
  150.           selection is made with the ADJUST button.  HASWIN_TRUE is returned
  151.           if successful, and HASWIN_FALSE on any error.
  152.  
  153.