Menus

- hmmmmmm. (It's 6:16 a.m. I'm a little tired. A little ? MUCH ! Well, it's better to go to the bed.)

Fine. In the Seal there are two menu types: Vertical menu, Horizontal menu. We will explain all you need to support menues in Seals applications and libraries. All menus are declared in "menus.h" include file, you must include this before doing operations with menus. All menus operate with menu information you set when creating the menu. Use following functions for storing information into the menu:


new_menu ()
     Description:
       Creates a new section for the menu.

     Syntax:
       p_menu  new_menu ( p_menuitem item ); 

     Parameters:
       item        The first item contained in the menu.

     Returns:
       A pointer to use when initializing the menu functions.



new_menu_line ()
     Description:
       Creates a line in the menu (a divider).

     Syntax:
       p_menuitem  new_menu_line ( p_menuitem next ); 

     Parameters:
       next        The next menu item.

     Returns:
       A pointer to the new t_menuitem structure containing
       information about this item.



new_sub_menu_ex ()
     Description:
       Creates a new submenu.

     Syntax:
       p_menuitem  new_sub_menu_ex ( l_text name, l_bool enable, 
                                     l_text info_text, l_font *font, 
                                     BITMAP *icon, l_font *font_symbol,
                                     l_byte chr, p_menu menu, 
                                     p_menuitem next );

     Parameters:
       name        Name of the item.
       enable      True if item is enabled or false if not.
       info_text   Text to be showed when the mouse cursor is over the
                   item and CTRL+F1 is pressed.
       font        Font to be used for the item.
       icon        A picture to be displayed in the item.
       font_symbol Sometimes you want a symbol to be displayed instead
                   of an icon. This is the name of the font to use.
       chr         This is the character to use for the symbol. If you
                   don't use it, just set it to zero.
       menu        Name of the new submenu that contains other items.
       next        The next item in this hierarchy.

     Returns:
       A pointer to the new t_menuitem structure containing
       information about this item.



new_menu_item_ex ()
     Description:
       Creates a new menuitem.

     Syntax:
       p_menuitem  new_menu_item_ex (l_text name, l_text param, 
                                     l_int hotkey, l_dword message, 
                                     l_bool enable, l_text info_text, 
                                     l_int flags, l_font *font,
                                     BITMAP *icon, 
                                     l_font *font_symbol,l_byte chr,
                                     p_menuitem next );

     Parameters:
       name        Name of the item.
       param       Caption (text) of the item.
       hotkey      Keycode (shortcut) for the item.
       message     The message sent to the application when the user
                   clicks this item.
       enable      True if item is enabled or false if not.
       info_text   Text to be showed when the mouse cursor is over the
                   item and CTRL+F1 is pressed.
       flags       -
       font        Font to be used for the item.
       icon        A picture to be displayed in the item.
       font_symbol Sometimes you want a symbol to be displayed instead
                   of an icon. This is the name of the font to use.
       chr         This is the character to use for the symbol. If you
                   don't use it, just set it to zero.
       next        The next item in this hierarchy.

     Returns:
       A pointer to the new t_menuitem structure containing
       information about this item.



new_sub_menu ()
     Description:
       A short version of the new_sub_menu_ex() function.

     Syntax:
       p_menuitem  new_sub_menu ( l_text name, p_menu menu, 
                                  p_menuitem next);

     Parameters:
       name        Name of the item.
       menu        Name of the new submenu that contains other items.
       next        The next item in this hierarchy.

     Returns:
       A pointer to the new t_menuitem structure containing
       information about this item.



new_menu_item
     Description:
       A short version of the new_menu_item_ex() function.

     Syntax:
       p_menuitem  new_menu_item ( l_text name, l_text param, l_int hotkey,
                                   l_dword message, l_text info_text,
                                   p_menuitem next )

     Parameters:
       name        Name of the item.
       param       Caption (text) of the item.
       hotkey      Keycode (shortcut) for the item.
       message     The message sent to the application when the user
                   clicks this item.
       info_text   Text to be showed when the mouse cursor is over the
                   item and CTRL+F1 is pressed.
       next        The next item in this hierarchy.

     Returns:
       A pointer to the new t_menuitem structure containing
       information about this item.



new_menu_check_item ()
     Description:
       Creates a new menu check item. This is similar to the menuitem
       but when selected it shows a checkmark symbol (as in checkboxes).

     Syntax:
       p_menuitem  new_menu_check_item ( l_text name, l_text param, 
                                         l_bool is_check, l_int hotkey, 
                                         l_dword message, l_text info_text,
                                         p_menuitem next);

     Parameters:
       name        Name of the item.
       param       Caption (text) of the item.
       is_check    True if item is selected (checked). False otherwise.
       hotkey      Keycode (shortcut) for the item.
       message     The message sent to the application when the user
                   clicks this item.
       info_text   Text to be showed when the mouse cursor is over the
                   item and CTRL+F1 is pressed.
       next        The next item in this hierarchy.

     Returns:
       A pointer to the new t_menuitem structure containing
       information about this item.




Getting information about actions

When you get recieve a message from the menu, you can use the following functions to get more information about the action. An action may be differenced by messages, but sometimes you need to distinguish two items that have the same message. The best example is the desktop menu, that contains same messages for file running. You can use these two function to distinguish it:


menu_get_lastitem_called ()
     Description:
       Gets the latest item clicked in a menu.

     Syntax:
       p_menuitem  menu_get_lastitem_called ( p_menu m );

     Parameters:
       m           A pointer to the menu to check.

     Returns:
       A pointer to a new t_menuitem structure containing
       information about the item. NULL is returned if the
       menu was closed without clicking an item.



menu_get_item_flags ()
     Description:
       Gets "flags" from the item defined by a message.

     Syntax:
       l_int  menu_get_item_flags ( p_menu m, l_dword message );

     Parameters:
       m           Pointer to the menu containing the item.
       message     The message to check whos item.

     Returns:
       "flags" from the item.




The t_menuitem structure

Variables

     Name:         p_menuitem next;

     Description:  Pointer to the next item in the hierarchy.



     Name:         l_text  name;

     Description:  Name of the item.



     Name:         l_text  param;

     Description:  Text for the keycode information.



     Name:         l_int  hotkey;

     Description:  Hotkey (shortcut) of the item.



     Name:         l_dword  message;

     Description:  Message sent by the item when clicked.



     Name:         l_bool  enable;

     Description:  True if item is enabled, false if it's disabled.



     Name:         l_bool  lastcall;

     Description:  Is set, when this item was the last to be pushed.



     Name:         l_text  info_text;

     Description:  Info text of the menu, you shown when CTRL+F1 is 
                   pressed and the mouse cursor is over the item.



     Name:         l_int  flags;

     Description:  Flags of the item. May combination of the following:

                      MIF_CHECK    - It is a check-item.
                      MIF_CHECKOK  - It was checked.
                      MIF_SELFICON - Icon has its own memory for the 
                                     BITMAP shown in the item.



     Name:         l_font  *font;

     Description:  Font of the item.



     Name:         l_font  *font_symbol;

     Description:  Font for the symbol.



     Name:         l_byte  char_symbol;

     Description:  The symbol to use.



     Name:         BITMAP  *icon;

     Description:  Icon of the item.



     Name:         l_char  reserved[16];

     Description:  Reserved for future versions.



     Name:         p_menu  submenu;

     Description:  A pointer to a submenu, when item is not a menuitem, 
                   but a submenu.




Vertical menu - MENUVIEW

This is like the menu you get by clicking the right mouse-button in Microsoft Windows 95/98/00 etc.


menuview_init ()
     Description:
       Initializes the new menuview.

     Syntax:
       p_menuview  menuview_init ( p_menuview o, t_rect r, p_menu menu );

     Parameters:
       o           Allocated memory to store the menu in.
       r           Rectangle defining the bounds of the menu. If
                   r.b.x < r.a.x, it automatically sets r.b.x to
                   minimum width of menu. r.b.y is automatically 
                   set to the minimum height.
       menu        The menu that was created with new_menu().

     Returns:
       The new menuview object.




Horizontal menu - HORMENU

This is the horizontal menu mainly used at top of the window (for "File" and "Edit" menus etc.).
     Description:
       Initializes the new horizontal menu.

     Syntax:
       p_menuview  hormenu_init ( p_menuview o, t_rect r, p_menu menu );

     Parameters:
       o           Allocated memory to store the menu in.
       r           Rectangle defining the bounds of the menu. If
                   r.b.x < r.a.x, it automatically sets r.b.x to
                   minimum width of menu. r.b.y is automatically 
                   set to the minimum height.
       menu        The menu that was created with new_menu().

     Returns:
       The new hormenu object.




Example:


     t_rect r = rect_assign(100, 100, 0, 0);

     p_menu p = new_menu(

                     new_menu_item_ex("Hello", NULL, 0, MSG_CLOSE, true,
                                      "Info about Hello", MIF_NONE, 
                                      font_system_bi, NULL, NULL, 0,
                     new_menu_line(
                     new_menu_item_ex("Quit", NULL, 0, MSG_QUIT, true,
                                      "This quit Seal", MIF_NONE,
                                      font_system_bd, NULL, NULL, 0,
                     NULL)))
                     );



     p_object menu = OBJECT(menuview_init(
                                    malloc(sizeof(t_menuview)),
                                    r,
                                    p)
                             );


        /* Show the menu on the desktop. */

     desktop->execute_view(desktop, VIEW(menu));