Menu

This page has been automatically translated using the Google Translate API services. We are working on improving texts. Thank you for your understanding and patience.

Functions

A Menu is a type of control that integrates a series of options, also called items or Menuitems. Each of them consists of a short text, optionally an icon and optionally also a keyboard shortcut, such as the classic Ctrl+C/Ctrl+V to copy and paste. Additionally, an item can house a submenu forming a hierarchy with different levels of depth. In Products you have an application that uses menus and in Hello dynamic Menu! an example of adding or eliminating items at runtime.

• Use menu_create to create a menu.
• Use menu_destroy to destroy a menu.
• Use menu_add_item to add an option.

We must explicitly destroy any menu that we create in the application.

When destroying a menu, the destruction of all its elements and submenus is recursively.

1. Menu bar

• Use osapp_menubar to establish the application menu bar.
• Use menu_is_menubar to obtain if a menu is acting as a menu bar.

Once the menu created, we can establish it as the main menu bar (Figure 1), which will be anchored to the main window, although there are operating systems (such as macOS) that show the menu bar at the top of the screen.

1.1. macOS particularities

macOS treats the menu bar slightly differently, compared to Windows or Linux. In multiplatform applications, you must take into account these considerations to comply with the Apple Human Guidelines.

• macOS reserve the first element of the bar to the application menu and will always appear, although the application lacks a menu bar. We can see it next to the Apple icon (Figure 2). Any content associated with the first element of the menu will automatically linked to this item (Listing 1).

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

#if defined(__APPLE__) // Apple app menu Menu *submenu = menu_create(); MenuItem *item0 = menuitem_create(); MenuItem *item1 = menuitem_separator(); MenuItem *item2 = menuitem_create(); MenuItem *item3 = menuitem_separator(); MenuItem *item4 = menuitem_create(); menuitem_text(item0, "About Products"); menuitem_text(item2, "Settings..."); menuitem_text(item4, "Quit Products"); menu_add_item(submenu, item0); menu_add_item(submenu, item1); menu_add_item(submenu, item2); menu_add_item(submenu, item3); menu_add_item(submenu, item4); // Set the Apple app menu as first item MenuItem *item = menuitem_create(); menuitem_text(item, ""); menuitem_submenu(item, &submenu); menu_ins_item(menu, 0, item); #endif



• macOS does not allow icons in the main elements of the menu bar, so they will be disabled. However, the icons will be visible in the drop -down submenus.
• macOS expects all the main elements of the menu bar to have an associated submenu, so it will not launch events when clicking on the main items of the menu bar. It will only launch events by clicking on the submenus elements.

2. PopUp menu

• Use menu_launch to launch a popup menu.

On the other hand, we can launch popup, or contextual menus, at any time of execution (Figure 3). They will be displayed as a overlapped window, usually when right click on some interface element. NAppGUI does not make distinctions between menu bar or popup, that is, we can use the same object for both roles (Listing 2).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

Menu *menu = create_menu_with_options();

// Set as menubar
osapp_menubar(menu, main_window);
...
// Unset menubar
osapp_menubar(NULL, main_window);
...
// Launch as popup
menu_launch(menu, main_window, v2df(x, y));

// Destroy the menu
menu_destroy(&menu);

3. Historical perspective

The menu concept, like the window, exists from the origin of the graphic interfaces. The first computer to incorporate them was the Xerox Alto that appeared in 1973 and its commercial successor the Xerox Star. Concepts still very alive today as: menu, window, icon, desk, or mouse were already present in these teams that served as inspiration to Steve Jobs in the creation of Apple Lisa (Figure 4), precursor of the Macintosh and inspiring Microsoft Windows.

menu_create ()

Create a new menu.

Menu*
menu_create(void);

Return

The newly created menu.

menu_destroy ()

Destroy a menu and all its hierarchy.

void
menu_destroy(Menu **menu);

menu_add_item ()

Add an item at the end of the menu.

void
menu_add_item(Menu *menu,
              MenuItem *item);

menu_ins_item ()

Insert an item in an arbitrary position of the menu.

void
menu_ins_item(Menu *menu,
              const uint32_t pos,
              MenuItem *item);

menu_del_item ()

Remove an item from the menu.

void
menu_del_item(Menu *menu,
              const uint32_t pos);

Remarks

The element will be destroyed and cannot be reused. If has a submenu associated, it will also be destroyed recursively.

menu_launch ()

Launch a menu as a secondary or Popup.

void
menu_launch(Menu *menu,
            Window *window,
            const V2Df position);

menu_off_items ()

Set status ekGUI_OFF for all menu items.

void
menu_off_items(Menu *menu);

menu_count ()

Get the number of items.

uint32_t
menu_count(const Menu *menu);

Return

Number of items.

menu_get_item ()

Get an item from the menu.

MenuItem*
menu_get_item(Menu *menu,
              const uint32_t index);

Return

The item.

menu_get_citem ()

Get a const item from the menu.

const MenuItem*
menu_get_citem(const Menu *menu,
               const uint32_t index);

Return

The item.

menu_is_menubar ()

Returns TRUE if the menu is currently established as a menu bar.

bool_t
menu_is_menubar(const Menu *menu);

Return

TRUE if is menubar. FALSE if not.

menu_imp ()

Returns the native implementation of the menu.

void*
menu_imp(const Menu *menu);

Return

Pointer to the native object.