Menu

Funciones

Un Menu es un tipo de control que integra una serie de opciones, también llamadas items o MenuItems. Cada una de ellas consta de un texto corto, opcionalmente un icono y opcionalmente también un atajo de teclado, como por ejemplo el clásico Ctrl+C/Ctrl+V para copiar y pegar. Adicionalmente, un item puede albergar un submenu conformando una jerarquía con diferentes niveles de profundidad. En Products tienes una aplicación que utiliza menús y en ¡Hola Menu dinámico! un ejemplo de como añadir o eliminar items en tiempo de ejecución.

• Utiliza menu_create para crear un menú.
• Utiliza menu_destroy para destruir un menú.
• Utiliza menu_add_item para añadir una opción.

Hay que destruir explícitamente cualquier menú que creemos en la aplicación.

Al destruir un menú se realiza la destrucción de todos sus elementos y submenus de forma recursiva.

1. Barra de menú

• Utiliza osapp_menubar para establecer la barra de menú de la aplicación.
• Utiliza menu_is_menubar para obtener si un menú está actuando como barra de menú.

Una vez credo el menú, podemos establecerlo como la barra de menú principal (Figura 1), que será anclada a la ventana principal, aunque hay sistemas operativos (como macOS) que muestran la barra de menú en la parte superior de la pantalla.

1.1. Particularidades de macOS

macOS trata de forma ligeramente diferente la barra de menú, comparado con Windows o Linux. En aplicaciones multiplataforma, deberás tener en cuenta estas consideraciones para cumplir con las Human Guidelines de Apple.

• macOS reserva el primer elemento de la barra al menú de aplicación y aparecerá siempre, aunque la aplicación carezca de barra de menú. Lo podemos ver junto al icono de Apple (Figura 2). Cualquier contenido asociado al primer elemento del menú, se vinculará automáticamente a este item (Listado 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 no permite iconos en los elementos principales de la barra de menú, por lo que serán deshabilitados. Sin embargo, los iconos sí que serán visibles en los submenús desplegables.
• macOS espera que todos los elementos principales de la barra de menú tengan un submenú asociado, por lo que no emitirá eventos al hacer clic sobre los items principales de la barra de menú. Solo emitirá eventos al hacer clic sobre los elementos de los submenús.

2. Menú emergente

• Utiliza menu_launch para lanzar un menú popup.

Por otro lado, podemos lanzar menús emergentes, o contextuales, en cualquier momento de la ejecución (Figura 3). Se mostrarán como una ventana superpuesta, normalmente cuando se hace clic derecho sobre algún elemento de la interfaz. NAppGUI no hace distinciones entre barra de menú o contextual, es decir, podemos utilizar el mismo objeto para ambos roles (Listado 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, v2df(x, y));

// Destroy the menu
menu_destroy(&menu);

3. Perspectiva histórica

El concepto de menú, al igual que el de ventana, existe desde el origen de las interfaces gráficas. El primer ordenador en incorporarlas fue el Xerox Alto que apareció en 1973 y su sucesor comercial el Xerox Star. Conceptos aún muy vivos a día de hoy como: Menú, Ventana, Icono, Escritorio, o Ratón ya estaban presentes en estos equipos que sirvieron de inspiración a Steve Jobs en la creación del Apple Lisa (Figura 4), precursor del Macintosh e inspirador de Microsoft Windows.

menu_create ()

Crea un nuevo menú.

Menu*
menu_create(void);

Retorna

El menú recién creado.

menu_destroy ()

Destruye un menú y toda su jerarquía.

void
menu_destroy(Menu **menu);

menu_add_item ()

Añade un item al final del menú.

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

menu_ins_item ()

Inserta un item en una posición arbitraria del menú.

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

menu_del_item ()

Elimina un item del menú.

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

Observaciones

El elemento será destruido y no se podrá reutilizar. Si tiene asociado un submenú, también se destruirá recursivamente.

menu_launch ()

Lanza un menú como secundario o PopUp.

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

menu_off_items ()

Establece el estado ekGUI_OFF para todos los items del menú.

void
menu_off_items(Menu *menu);

menu_count ()

Obtiene el número de items.

uint32_t
menu_count(const Menu *menu);

Retorna

Número de items.

menu_get_item ()

Obtiene un item del menú.

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

Retorna

El item.

menu_get_citem ()

Obtiene un item constante del menú.

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

Retorna

El item.

menu_is_menubar ()

Retorna TRUE si el menú actualmente está establecido como barra de menú.

bool_t
menu_is_menubar(const Menu *menu);

Retorna

TRUE si es barra de menú. FALSE si no.

menu_imp ()

Retorna la implementación nativa del menú.

void*
menu_imp(const Menu *menu);

Retorna

Puntero al objeto nativo.