/*
 MENUITEM.DOX

 License CC0 PUBLIC DOMAIN

 To the extent possible under law, Mark J. Olesen has waived all copyright
 and related or neighboring rights to FDOSTUI Library. This work is published
 from: United States.
*/

/*! \file menuitem.h
\brief Container for a menu item
*/


/*!
\def MENUITEM_MNEMONIC_NONE
\brief indicator that the menu item does not contain a mnemonic
*/

/*!
\typedef void (*menuitem_signal_t)(
    struct menuitem*                    i_menu,
    void*                               i_user_data)
\brief function prototype to recieve signal
\param[in] i_menu menu item 
\param[in,out] io_user_data use defined
\returns none
*/

/*!
\enum menuitem_flags
\brief flags that determine attributes of the menu item

\var menuitem::MENUITEM_NONE
	no attributes

\var menuitem::MENUITEM_VALUE
	menu item value (0=off, 1=on)

\var menuitem::MENUITEM_DISABLED
	menu item is disabled

\var menuitem::MENUITEM_CHECKBOX
	menu item can be checked

\var menuitem::MENUITEM_SEPERATOR
	menu item has a sperator line

\var menuitem::MENUITEM_SUBMENU
	menu item contains a sub menu
*/

/*!
\struct menuitem
\brief a menu item

\var menuitem::m_label
	menu item label (displayed as entered). The life of the label 
	should outlast the life of the menu item.

\var menuitem::m_mnemonic_offset
	zero based offset of the mnemonic.

\var menuitem::m_accel_label
	accelerator label (displayed as entered). The life of the label
	should outlast the life of the menu item. The label should reflect
	the \a m_accell_scancode.

\var menuitem::m_accel_scancode
	accelerator scan code

\var menuitem::m_flags
	bit mask of ::menuitem_flags

\var menuitem::m_signal
	signal to emit when the user selects an item

\var menuitem::m_user_data
	user defined data to send as a parameter to the signal when emitted
*/

/*!
\struct menuitembar
\brief a menu bar item

\var menuitembar::m_label
	menu item label (displayed as entered). The life of the label 
	should outlast the life of the menu item.

\var menuitembar::m_mnemonic_offset
	zero based offset of the mnemonic.

\var menuitembar::m_accel_scancode
	accelerator scan code

\var menuitembar::m_items
	reference to the popup menu
*/

/*!
\fn void menuitem_count(
    unsigned int*const                  o_rows,
    unsigned int*const                  o_cols,
    struct menuitem *                   i_menu)
\brief count the number of elements in menu
\param[out] o_rows the number of elements in ithe menu
\param[out] o_cols the largest string in the menu
\param[in] i_menu the menu object to count

\a o_rows is the count of a flattened menu. It does not include
sub menus. 
*/

/*!
\fn void menuitem_emit(
    struct menuitem *                   i_menu)
\brief emit the callback signal
\param[in,out] i_menu menu to call signal
\returns none
*/

/*!
\fn struct menuitem* menuitem_next(
    struct menuitem*                    i_menu)
\brief get the next menu item of the same level
\param[in] i_menu menu to step through
\returns 0 end of menu
\returns !0 next menu item
*/

/*!
\fn struct menuitem* menuitem_nth(
    struct menuitem*                    i_menu,
    unsigned int const                  i_nth)
\brief gets the nth (zero based) menu item of the same level
\returns 0 end of menu
\returns !0 nth menu item
*/

/*!
\fn void menuitem_flatten(
    struct array*const                  o_array,
    struct menuitem*                    i_menu)
\brief flattens a menu (creates list of menu items of same level)
\param[out] o_array container to hold menu items
\param[in] i_menu menu to flatten
\returns none
*/

/*!
\fn struct menuitem* menuitem_find_scancode(
    struct menuitem *                   i_menu,
    enum scancodes const                i_scan)
\brief scans menu items for a scancode/accelerator (stops at first match)
\param[in] i_menu menu item to traverse
\param[in] i_scan scancode to search for
\returns !0 menu item containing scancode
\returns 0 item not found
*/

