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
WBMenu *	MBCreateMenu (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...

WBMenu *	MBCopyMenu (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...

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. 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...

WBMenu *	MBFindPopupMenu (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

WBMenu

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'
} WBMenu;

See Also: WBMenuItem

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
} WBMenuItem;

See Also: WBMenu

Function Documentation

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

Add a WBMenuItem menu item to an existing WBMenu.

Parameters

pMenu	A pointer to a WBMenu structure, created by MBCreateMenu()
pMenuItem	A pointer to a (const) WBMenuItem structure, created by MBCreateMenuItem()
iPos	The 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

pMenu	A pointer to a WBMenu structure, created by MBCreateMenu()
pPopupMenu	A 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

pMenu	A pointer to a WBMenu structure, created by MBCreateMenu()
iReserveSpace	The 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

iID	The menu ID, or '-1' to read it from the resource
iPopup	The 'popup' ID, or '-1' to read it from the resource
pszResource	A pointer to a (const) character string, terminated by a 0 byte, defining the menu structure
iReserveSpace	The 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

ppszResource A 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

pMenu A 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

pMenuItem A 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

pMenu	A pointer to a WBMenu structure, created by MBCreateMenu()
idPopup	The '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

pMenuItem A (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

pMenu A (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

pMenu A 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

pMenu	A pointer to a WBMenu structure, created by MBCreateMenuItem()
pEvent	A 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

pMenu	A pointer to a WBMenu structure, created by MBCreateMenu()
iPos	A 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

pMenu	A pointer to a WBMenu structure, created by MBCreateMenu()
idPopup	The '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.

Data Structures

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation