Data Structures
struct	tagWBMenuItem__
	structure for managing menu items More...

struct	tagWBMenu
	structure for managing menu items More...

Macros
#define	WBMENU_TAG (((const unsigned int )"WBMM"))
	TAG for WBMenu structure.

#define	WBMENUITEM_TAG (((const unsigned int )"WBMI"))
	TAG for WBMenuItem structure.

Typedefs
typedef struct tagWBMenuItem__	WBMenuItem
	structure for managing menu items More...

typedef struct tagWBMenu	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...

Variables
Atom	aMENU_COMMAND
	commands sent by menus via ClientMessage More...

Atom	aMENU_UI_COMMAND
	UI notifications sent by menus to owning Frame windows via ClientMessage using 'WBWindowDispatch'. 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

◆ WBMENU_DYNAMIC_HIGH_BIT

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

◆ WBMENU_POPUP_HIGH_BIT

#define WBMENU_POPUP_HIGH_BIT 0x80000000

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

Definition at line 78 of file menu.h.

◆ WBMENU_POPUP_MASK

#define WBMENU_POPUP_MASK 0x3fffffff

popup mask (TODO may become platform dependent)

Definition at line 80 of file menu.h.

◆ WBMENU_RESERVE_DEFAULT

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

default menu 'iReserveSpace' size

Definition at line 76 of file menu.h.

◆ WBMENU_SEPARATOR

#define WBMENU_SEPARATOR -1

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

Definition at line 81 of file menu.h.

Typedef Documentation

◆ WBMenu

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 tagWBMenu
{
  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 tagWBMenu **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

WBMenuItem

structure for managing menu items

Definition for the structure that defines a single menu item.

typedef struct tagWBMenuItem__
{
  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

◆ MBAddMenuItem()

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 280 of file menu.c.

◆ MBAddPopupMenu()

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 307 of file menu.c.

◆ MBCopyMenu()

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 350 of file menu.c.

◆ MBCreateMenu()

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 107 of file menu.c.

◆ MBCreateMenuItem()

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 670 of file menu.c.

◆ MBDestroyMenu()

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 190 of file menu.c.

◆ MBDestroyMenuItem()

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 267 of file menu.c.

◆ MBFindPopupMenu()

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 326 of file menu.c.

◆ MBIsMenuItemValid()

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 244 of file menu.c.

◆ MBIsMenuValid()

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 221 of file menu.c.

◆ MBMenuIsPopup()

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 402 of file menu.h.

◆ MBMenuProcessHotKey()

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 1228 of file menu.c.

◆ MBRemoveMenuItem()

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 297 of file menu.c.

◆ MBRemovePopupMenu()

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 339 of file menu.c.

Variable Documentation

◆ aMENU_COMMAND

Atom aMENU_COMMAND

commands sent by menus via ClientMessage

MENU_COMMAND message format (relative to XEvent.xclient)

type == ClientMessage
message_type == aMENU_COMMAND
format == 32 (always)
data.l[0] Menu command message ID (aka 'action')
data.l[1] secure hash for WBMenu object pointer - see WBCreatePointerHash()
data.l[2] Window ID of the menu bar

Whenever this message is received, you should NOT call WBDestroyPointerHash() for the WBMenu object pointer. This will be done automatically by the message framework.

Definition at line 166 of file window_helper.c.

◆ aMENU_UI_COMMAND

Atom aMENU_UI_COMMAND

UI notifications sent by menus to owning Frame windows via ClientMessage using 'WBWindowDispatch'.

MENU_COMMAND message format (relative to XEvent.xclient)

type == ClientMessage
message_type == aMENU_UI_COMMAND
format == 32 (always)
data.l[0] Menu command message ID (aka 'action')
data.l[1] secure hash for WBMenu object pointer - see WBCreatePointerHash()
data.l[2] secure hash for WBMenuItem object pointer - see WBCreatePointerHash()
data.l[3] the value '0' (reserved)
data.l[4] the value '0' (reserved)

A Frame Window returns '0' to indicate that the menu should be displayed normally (same as 'not handled')
Other return values alter the display of the menu.

For a popup menu: -1 : disables the menu 1 : enables the menu (default behavior if no UI handler present, but menu handler IS present) 0 : menu item NOT handled (menu item will be greyed)

For a dynamic menu: (preliminary) - popup menu items only (not found in top-level menus) -1 : disabled the menu 0 : 'not handled' or 'error' (no dynamic menu will be added or displayed) >0 : a 'secure internal pointer hash' representing an actual pointer value (preliminary, RESERVED) this pointer will be to a WBAlloc'd block of memory describing the menu items (as text). It will be necessary for the caller to interpret this text to create the dynamic memory items. PRELIMINARY: the text will be 'menu text\tAtom Name' - no hotkeys, no tooltip text. The menu text can include underscores which will only work when the popup is available

Whenever this message is received, you should NOT call WBDestroyPointerHash() for the WBMenu object pointer, nor for the WBMenuItem object pointer. This will be done automatically by the message framework.

Definition at line 204 of file window_helper.c.

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ WBMENU_DYNAMIC_HIGH_BIT

◆ WBMENU_POPUP_HIGH_BIT

◆ WBMENU_POPUP_MASK

◆ WBMENU_RESERVE_DEFAULT

◆ WBMENU_SEPARATOR

Typedef Documentation

◆ WBMenu

◆ WBMenuItem

Function Documentation

◆ MBAddMenuItem()

◆ MBAddPopupMenu()

◆ MBCopyMenu()

◆ MBCreateMenu()

◆ MBCreateMenuItem()

◆ MBDestroyMenu()

◆ MBDestroyMenuItem()

◆ MBFindPopupMenu()

◆ MBIsMenuItemValid()

◆ MBIsMenuValid()

◆ MBMenuIsPopup()

◆ MBMenuProcessHotKey()

◆ MBRemoveMenuItem()

◆ MBRemovePopupMenu()

Variable Documentation

◆ aMENU_COMMAND

◆ aMENU_UI_COMMAND