X11 Work Bench Toolkit  1.0
Menu functions and structures

Data Structures

struct  __WBMenuItem__
 structure for managing menu items More...
 
struct  __WBMenu
 structure for managing menu items More...
 

Typedefs

typedef struct __WBMenuItem__ WBMenuItem
 structure for managing menu items More...
 
typedef struct __WBMenu WBMenu
 structure for managing menu items More...
 

Functions

WBMenuMBCreateMenu (int iID, int iPopup, const char *pszResource, int iReserveSpace)
 Create a WBMenu from a text menu resource. More...
 
void MBDestroyMenu (WBMenu *pMenu)
 Destroy a WBMenu created by MBCreateMenu(), freeing up its resources. More...
 
WBMenuMBCopyMenu (const WBMenu *pMenu, int iReserveSpace)
 Create a copy of a WBMenu from an existing WBMenu. More...
 
int MBIsMenuValid (const WBMenu *pMenu)
 Check whether a 'WBMenu' pointer is valid. More...
 
WBMenuItemMBCreateMenuItem (const char **ppszResource)
 Create a single allocated WBMenuItem structure from a text menu resource, advancing the source text pointer to the next menu item. More...
 
void MBDestroyMenuItem (WBMenuItem *pMenuItem)
 Destroy a WBMenuItem created by MBCreateMenuItem(), freeing up its resources. More...
 
int MBIsMenuItemValid (const WBMenuItem *pMenuItem)
 Check whether a 'WBMenuItem' pointer is valid. More...
 
int MBAddMenuItem (WBMenu *pMenu, const WBMenuItem *pMenuItem, int iPos)
 Add a WBMenuItem menu item to an existing WBMenu. More...
 
void MBRemoveMenuItem (WBMenu *pMenu, int iPos)
 Remove a WBMenuItem from a menu created by MBCreateMenu(), freeing up its resources. More...
 
int MBAddPopupMenu (WBMenu *pMenu, const WBMenu *pPopupMenu)
 Add a WBMenuItem menu item to an existing WBMenu. More...
 
WBMenuMBFindPopupMenu (WBMenu *pMenu, int idPopup)
 Locate a WBMenu 'popup' within a menu created by MBCreateMenu() More...
 
void MBRemovePopupMenu (WBMenu *pMenu, int idPopup)
 Remove a WBMenu 'popup' from a menu created by MBCreateMenu(), freeing up its resources. More...
 
static __inline__ int MBMenuIsPopup (WBMenu *pMenu)
 Indicate whether a 'WBMenu' refers to a popup menu. More...
 
int MBMenuProcessHotKey (WBMenu *pMenu, XKeyEvent *pEvent)
 Event handler for menu hotkeys. More...
 
#define WBMENU_RESERVE_DEFAULT   (256 * sizeof(void *))
 
#define WBMENU_POPUP_HIGH_BIT   0x80000000
 
#define WBMENU_DYNAMIC_HIGH_BIT   0x40000000
 
#define WBMENU_POPUP_MASK   0x3fffffff
 
#define WBMENU_SEPARATOR   -1
 

Detailed Description

Structures and API functions for managing and working with menus and menu items

Macro Definition Documentation

#define WBMENU_DYNAMIC_HIGH_BIT   0x40000000

marks menu item as 'dynamic' for WBMenuItem::iAction (TODO may become platform dependent)

Definition at line 79 of file menu.h.

#define WBMENU_POPUP_HIGH_BIT   0x80000000

popup 'high bit' (TODO may become platform dependent)

Definition at line 78 of file menu.h.

#define WBMENU_POPUP_MASK   0x3fffffff

popup mask (TODO may become platform dependent)

Definition at line 80 of file menu.h.

#define WBMENU_RESERVE_DEFAULT   (256 * sizeof(void *))

default menu 'iReserveSpace' size

Definition at line 76 of file menu.h.

#define WBMENU_SEPARATOR   -1

marks menu item as a 'separator' for WBMenuItem::iAction

Definition at line 81 of file menu.h.

Typedef Documentation

structure for managing menu items

Definition for the structure that defines a menu. A menu is a single-level entity that can contain other "sub menus" that display as 'popup' menus when the menu item is highlighted or selected.

typedef struct __WBMenu
{
unsigned int uiTag; // a 'tag' identifying this as a WBMenu
int iMenuID; // menu identifier specified when menu was created (high bit set for popup)
WBMenuItem **ppItems; // An allocated array of menu items
int nItems; // The number of menu item entries in the 'ppItems' array
int nMaxItems; // The maximum number of menu item entries that can be stored in 'ppItems'
struct __WBMenu **ppPopups; // An allocated array of 'popup' menus contained by this menu
int nPopups; // The number of popup menu entries in the 'ppPopups' array
int nMaxPopups; // The maximum number of popup menu entries that can be stored in 'ppPopups'
See Also
WBMenuItem

structure for managing menu items

Definition for the structure that defines a single menu item.

typedef struct __WBMenuItem__
{
unsigned int uiTag; // a 'tag' identifying this as a WBMenuItem
// the following data members are offsets from 'data' for each component of the menu item
// '-1' generically indicates "none"
int iMenuItemText; // offset in 'data' to null-byte terminated strings (-1 if none)
int iUnderscore; // offset of (first) 'underscore' within menu text (-1 if none)
int iTooltipText; // offset in 'data' to null-byte terminated strings (-1 if none)
int iHotKey; // hotkey description (-1 if none)
// the following data members are numeric properties (not offsets)
int iAction; // high bit set for popup; -1 for separator, -2 for dynamic; otherwise, it's a message
// if high bit set, corresponding lower bits are the popup menu ID
int nHotKey; // hotkey character translation (0 if none)
int iTextWidth; // width of menu text (in pixels; assign '-1' to calculate it)
int iPosition; // horizontal/vertical position of menu (in pixels; assign '-1' to calculate it)
int nDataSize; // total size of data
char data[4]; // data follows
See Also
WBMenu

Function Documentation

int MBAddMenuItem ( WBMenu pMenu,
const WBMenuItem pMenuItem,
int  iPos 
)

Add a WBMenuItem menu item to an existing WBMenu.

Parameters
pMenuA pointer to a WBMenu structure, created by MBCreateMenu()
pMenuItemA pointer to a (const) WBMenuItem structure, created by MBCreateMenuItem()
iPosThe position to insert/add the menu item to, or -1 to add it to the end
Returns
the index for the added menu item, or -1 on error.

Use this function to add a WBMenuItem to the WBMenu. This function makes a copy of the specified WBMenuItem and inserts the copy (i.e. does not take ownership of the WBMenuItem).

Header File: menu.h

Definition at line 275 of file menu.c.

int MBAddPopupMenu ( WBMenu pMenu,
const WBMenu pPopupMenu 
)

Add a WBMenuItem menu item to an existing WBMenu.

Parameters
pMenuA pointer to a WBMenu structure, created by MBCreateMenu()
pPopupMenuA pointer to a (const) WBMenu structure, created by MBCreateMenu()
Returns
the index for the added popup menu item, or -1 on error.

Use this function to add a WBMenu 'popup' to the WBMenu. This function makes a copy of the specified WBMenu and inserts the copy (i.e. does not take ownership of the WBMenu). The copy operation is recursive, so that the added WBMenu 'popup' does not share memory with any other.

Header File: menu.h

Definition at line 302 of file menu.c.

WBMenu* MBCopyMenu ( const WBMenu pMenu,
int  iReserveSpace 
)

Create a copy of a WBMenu from an existing WBMenu.

Parameters
pMenuA pointer to a WBMenu structure, created by MBCreateMenu()
iReserveSpaceThe amount of space (in menu items) to reserve for use by MBAddMenuItem() and MBAddPopupMenu(). A negative value will retain the existing WBMenu's reserve space.
Returns
An allocated pointer to a new WBMenu structure, or NULL on error. Use MBDestroyMenu() to de-allocate non-NULL return values.

Use this function to make a copy of an existing WBMenu structure.

Header File: menu.h

Definition at line 345 of file menu.c.

WBMenu* MBCreateMenu ( int  iID,
int  iPopup,
const char *  pszResource,
int  iReserveSpace 
)

Create a WBMenu from a text menu resource.

Parameters
iIDThe menu ID, or '-1' to read it from the resource
iPopupThe 'popup' ID, or '-1' to read it from the resource
pszResourceA pointer to a (const) character string, terminated by a 0 byte, defining the menu structure
iReserveSpaceThe amount of space (in menu items) to reserve for use by MBAddMenuItem() and MBAddPopupMenu()
Returns
An allocated pointer to a WBMenu structure, or NULL on error. Use MBDestroyMenu() to de-allocate non-NULL return values.

Use this function to create a WBMenu structure from a text resource, optionally specifying the menu's ID and/or popup ID.

Header File: menu.h

Definition at line 106 of file menu.c.

WBMenuItem* MBCreateMenuItem ( const char **  ppszResource)

Create a single allocated WBMenuItem structure from a text menu resource, advancing the source text pointer to the next menu item.

Parameters
ppszResourceA pointer to a pointer to a (const) character string, terminated by a 0 byte, which is updated by the function call
Returns
An allocated pointer to a WBMenuItem structure, or NULL on error. Use MBDestroyMenuItem() to de-allocate non-NULL return values

Use this function to create a WBMenuItem structure from a text resource, automatically advancing the source text pointer to the next menu item in the text resource. Repeated calls to this function allow you to parse a text menu resource and create all of the menu items.

Header File: menu.h

See Also
MBCreateMenu()

Definition at line 665 of file menu.c.

void MBDestroyMenu ( WBMenu pMenu)

Destroy a WBMenu created by MBCreateMenu(), freeing up its resources.

Parameters
pMenuA pointer to a WBMenu structure, created by MBCreateMenu()
Returns
void

Use this function to destroy a WBMenu created by MBCreateMenu(), and free up its resources.

Header File: menu.h

Definition at line 189 of file menu.c.

void MBDestroyMenuItem ( WBMenuItem pMenuItem)

Destroy a WBMenuItem created by MBCreateMenuItem(), freeing up its resources.

Parameters
pMenuItemA pointer to a WBMenuItem structure, created by MBCreateMenuItem()
Returns
void

Use this function to destroy a WBMenuItem created by MBCreateMenuItem(), and free up its resources.

Header File: menu.h

Definition at line 264 of file menu.c.

WBMenu* MBFindPopupMenu ( WBMenu pMenu,
int  idPopup 
)

Locate a WBMenu 'popup' within a menu created by MBCreateMenu()

Parameters
pMenuA pointer to a WBMenu structure, created by MBCreateMenu()
idPopupThe 'popup menu' ID for the popup menu (this differs from WBRemoveMenuItem() which uses the index)
Returns
a pointer to the WBMenu corresponding to the popup menu.

Use this function to locate a 'popup' WBMenu within a WBMenu created by MBCreateMenu(), returning a pointer to the WBMenu structure, using the popup menu's ID. The returned WBMenu pointer can then be used in the functions that maintain a WBMenu, so long as the actual pointer value is not modified.
If the pointer must be re-allocated, or a new popup menu is created to replace it, you can delete the popup menu using MBRemovePopupMenu() and then re-add the new one with MBAddPopupMenu()

Header File: menu.h

Definition at line 321 of file menu.c.

int MBIsMenuItemValid ( const WBMenuItem pMenuItem)

Check whether a 'WBMenuItem' pointer is valid.

Parameters
pMenuItemA (const) pointer to a WBMenuItem structure, created by MBCreateMenuItem()
Returns
A non-zero 'True' value if valid; zero if NOT valid

Use this function to validate a 'WBMenuItem' pointer before attempting to use it

Header File: menu.h

Definition at line 241 of file menu.c.

int MBIsMenuValid ( const WBMenu pMenu)

Check whether a 'WBMenu' pointer is valid.

Parameters
pMenuA (const) pointer to a WBMenu structure, created by MBCreateMenu()
Returns
A non-zero 'True' value if valid; zero if NOT valid

Use this function to validate a 'WBMenu' pointer before attempting to use it

Header File: menu.h

Definition at line 218 of file menu.c.

static __inline__ int MBMenuIsPopup ( WBMenu pMenu)
static

Indicate whether a 'WBMenu' refers to a popup menu.

Parameters
pMenuA pointer to a WBMenu structure, created by MBCreateMenuItem()
Returns
a non-zero value if the WBMenu refers to a 'popup' menu, zero otherwise

Use this function to indicate whether a 'WBMenu' refers to a popup menu

Header File: menu.h

Definition at line 396 of file menu.h.

int MBMenuProcessHotKey ( WBMenu pMenu,
XKeyEvent *  pEvent 
)

Event handler for menu hotkeys.

Parameters
pMenuA pointer to a WBMenu structure, created by MBCreateMenuItem()
pEventA pointer to the XKeyEvent being processed
Returns
a non-zero value if the key event was processed as a hot-key, zero otherwise

Use this function to process keyboard 'XKeyEvent' events, determine if they correspond to menu hot-keys, and to notify the menu owner with the hot-key action (if found).

Header File: menu.h

Definition at line 1224 of file menu.c.

void MBRemoveMenuItem ( WBMenu pMenu,
int  iPos 
)

Remove a WBMenuItem from a menu created by MBCreateMenu(), freeing up its resources.

Parameters
pMenuA pointer to a WBMenu structure, created by MBCreateMenu()
iPosA zero-based index for the menu item's position
Returns
void

Use this function to remove a WBMenuItem from a WBMenu created by MBCreateMenu()

Header File: menu.h

Definition at line 292 of file menu.c.

void MBRemovePopupMenu ( WBMenu pMenu,
int  idPopup 
)

Remove a WBMenu 'popup' from a menu created by MBCreateMenu(), freeing up its resources.

Parameters
pMenuA pointer to a WBMenu structure, created by MBCreateMenu()
idPopupThe 'popup menu' ID for the popup menu (this differs from WBRemoveMenuItem() which uses the index)
Returns
void

Use this function to remove a popup WBMenu from a WBMenu created by MBCreateMenu()

Header File: menu.h

Definition at line 334 of file menu.c.