VkMenu(3x)VkMenu(3x)NAMEVkMenu - Abstract base class for all ViewKit menu container objects
INHERITS FROM
VkMenuItem : VkComponent : VkCallbackObject
HEADER FILE
#include <Vk/VkMenu.h>
PUBLIC PROTOCOL SUMMARY
Adding Items
VkMenuAction *addAction(const char *name,
XtCallbackProc func,
XtPointer data,
int pos = -1);
VkMenuAction *addAction(const char *name,
XtCallbackProc func,
XtCallbackProc undoCallabck,
XtPointer data,
int pos = -1);
VkMenuActionWidget *addActionWidget(const char *name,
XtCallbackProc func,
XtPointer data,
int pos = -1);
VkMenuActionWidget *addActionWidget(const char *name,
XtCallbackProc func,
XtCallbackProc undoCallback,
XtPointer data,
int pos = -1);
VkMenuConfirmFirstAction
*addConfirmFirstAction(const char *name,
XtCallbackProc func,
XtPointer data,
int pos = -1);
VkMenuSeparator *addSeparator(int pos = -1);
VkMenuLabel *addLabel(const char *name,
int pos = -1);
VkMenuToggle *addToggle(const char *name,
XtCallbackProc func,
XtPointer data,
int state = -1,
int pos = -1);
VkMenuToggle *addToggle(const char *name,
XtCallbackProc func,
XtCallbackProc undoCallback,
Page 1
VkMenu(3x)VkMenu(3x)
XtPointer data,
int state = -1,
int pos = -1);
void add(VkMenuItem *name, int pos = -1);
VkSubMenu *addSubmenu(VkSubMenu *submenu, int pos = -1);
VkSubMenu *addSubmenu(const char *name, int pos = -1);
VkSubMenu *addSubmenu(const char *name,
VkMenuDesc *desc,
XtPointer defaultClientData = NULL);
VkRadioSubMenu *addRadioSubmenu(VkRadioSubMenu *submenu,
int pos = -1);
VkRadioSubMenu *addRadioSubmenu(const char *name, int pos = -1);
VkRadioSubMenu *addRadioSubmenu(const char *name,
VkMenuDesc *desc,
XtPointer defaultClientData = NULL);
Manipulating Items
VkMenuItem *findNamedItem(const char *name,
Boolean caseless = FALSE);
VkMenuItem *removeItem(const char *name);
VkMenuItem *activateItem(const char *name );
VkMenuItem *deactivateItem(const char *name );
VkMenuItem *replace(const char *name , VkMenuItem *item );
Access Functions
virtual VkMenuItemType menuType () = 0;
virtual const char* className();
Boolean isContainer();
int getItemPosition(VkMenuItem* item);
int getItemPosition(char *name);
int getItemPosition(Widget);
VkMenuItem * operator[] (int index) const;
int numItems() const;
Access Functions - ViewKit 2.1 only
VkScreen *getScreen();
Control Functions
Page 2
VkMenu(3x)VkMenu(3x)
static void useOverlayMenus(const Boolean flag);
static void useWorkProcs(Boolean flag);
CLASS DESCRIPTIONVkMenu is an abstract base class that implements the bulk of the
functionality needed for all menus, including menubars (see
VkMenuBar(3X)), pulldowns, (see VkSubMenu(3x)), option menus (see
VkOptionMenu(3X)), and popup menus (see (VkPopupMenu(3X)). Menus can be
built by passing a static description to the constructor of a class
derived from VkMenu or by adding items dynamically. The two approaches
can be mixed; an initial menu structure can be defined statically, and
then additional items can be added dynamically as needed.
Using Static Menu Descriptions
Menus can be described statically using an array of structures of type
VkMenuDesc. This structure is defined as follows:
struct VkMenuDesc {
VkMenuItemType menuType;
char *name;
XtCallbackProc callback;
VkMenuDesc *submenu;
XtPointer clientData;
XtCallbackProc undoCallback;
};
Menu hierarchies can be defined by creating connected arrays of this
structure. The first member of this structure indicates a menu type
using the enumerated VkMenuItemType defined in VkMenuItem.h. The possible
values are:
ACTION
A "normal" menu item, implemented as a VkMenuAction object
CONFIRMFIRSTACTION
An action that will not be executed without user confirmation.
ACTIONWIDGET
A "normal" menu item, implemented as a VkMenuActionWidget object.
(This class uses a widget instead of a gadget.)
SUBMENU
A cascading submenu, implemented as a VkSubMenu object
RADIOSUBMENU
Same as above, but forced to act as a radio-style pane, implemented
as a VkRadioSubMenu object.
Page 3
VkMenu(3x)VkMenu(3x)
SEPARATOR
A separator, implemented as an VkMenuSeparator object
LABEL
A label, implemented as a VkMenuLabel object
TOGGLE
A two-state toggle button gadget, implemented as a VkMenuToggle
object
OPTION
A multi-choice option menu, implemented as a VkOptionMenu object.
This option would rarely be used in a menu description.
POPUP
A popup menu pane, implemented as a VkPopupMenu object.This option
would rarely be used in a menu description.
BAR
A menu bar, implemented as a VkPopupMenu object.This option would
rarely be used in a menu description.
END
All menu descriptions must be terminated by this constant.
For example, assume you want to create a menu that contains two submenus,
each of which contain two selectable actions. This menu could be
described as follows:
VkMenuDesc applicationPane[] = {
{ ACTION, "itemOne", oneCallback},
{ ACTION, "itemTwo", twoCallback},
{ END},
};
VkMenuDesc editPane[] = {
{ ACTION, "cut", cutCallback},
{ ACTION, "paste", pasteCallback},
{ END},
};
VkMenuDesc menu[] = {
{ SUBMENU, "Application", NULL, applicationPane},
{ SUBMENU, "Edit", NULL, editPane},
{ END}
};
Page 4
VkMenu(3x)VkMenu(3x)
All the various objects needed to implement this menu hierarchy could
then be create as follows:
VkMenuBar *menubar = VkMenuBar(menu);
Using Static Descriptions With VkWindow
When using static descriptions with classes derived from VkWindow, it is
recommended that both callbacks and menu structures be declared as
members of the class. For example, the following class creates a menubar
that matches the menu hierarchy described above.
class Sample: public VkWindow {
private:
static void oneCallback( Widget,
XtPointer,
XtPointer);
static void twoCallback( Widget,
XtPointer ,
XtPointer);
static void cutCallback( Widget,
XtPointer,
XtPointer);
static void pasteCallback( Widget,
XtPointer ,
XtPointer);
static VkMenuDesc applicationPane[];
static VkMenuDesc editPane[];
static VkMenuDesc menu[];
protected:
public:
Sample( const char *name) : VkWindow( name)
// Other members
};
The constructor of this class can install this menu in several ways.
This example installs the menu bar using the complete description:
SampleWindow::SampleWindow(char *name) : VkWindow(name)
{
setMenuBar(menu);
Page 5
VkMenu(3x)VkMenu(3x)
// Other actions
}
This example instantiates a menu bar and installs the object:
SampleWindow::SampleWindow(char *name) : VkWindow(name)
{
setMenuBar(new VkMenuBar(menu, (XtPointer) this));
// Other actions
}
Note that the top level description in this case is not strictly
required. A menubar could be added to a VkWindow subclass by adding
each pane individually. For example:
SampleWindow::SampleWindow(char *name) : VkWindow(name)
{
addMenuPane("Application", application);
addMenuPane("Edit", edit);
// Other actions
}
Although the above example shows a menu bar, the same description could
be used to create other types of menus. For example, the following code
segment creates a popup menu in addition to a menu bar, using the same
description:
SampleWindow::SampleWindow(char *name) : VkWindow(name)
{
// Create the menu bar
addMenuPane("Application", application);
addMenuPane("Edit", edit);
// Create a popup that has the same
// contents as the menubar
VkPopupMenu *popup = new VkPopupMenu(menu);
// Other actions
}
Page 6
VkMenu(3x)VkMenu(3x)
Creating Menus Dynamically
Regardless of the menu type, items can be added dynamically using the
protocol defined by VkMenu. For example, the menu bar constructed
statically above can be created dynamically with the following code
segment:
VkMenuBar *menuBar = new VkMenuBar();
VkSubMenu *application =
menuBar->addSubMenu("Application");
VkSubMenu *edit = menuBar->addSubMenu("Edit");
application->addAction("itemOne", oneCallback);
application->addAction("itemTwo", twoCallback);
edit->addAction("cut", cutCallback);
edit->addAction("paste", pasteCallback);
Deriving Subclasses
Specific types of menus are implemented as derived classes of VkMenu.
These include VkOptionMenu, VkPopupMenu, VkMenuBar, VkSubMenu, and
VkRadioSubMenu. The VkMenu class is not necessarily designed to support
other derivations.
FUNCTION DESCRIPTIONS
addAction
VkMenuAction *addAction(const char *name,
XtCallbackProc func,
XtPointer data,
int pos = -1);
VkMenuAction *addAction(const char *name,
XtCallbackProc func,
XtCallbackProc undoCallabck,
XtPointer data,
int pos = -1);
Creates and adds an action object to a menu. The first argument
indicates the name, the second specifies a callback function. The
final two arguments can be used to specify some client data for the
callback, and a position within the menu for this item. In the
second form of this function, it is possible to add a callback to be
called if the menu action is to be undone. If the first form of
this function is used, the action cannot be undone and does not
participate in the undo mechanism. (See VkMenuUndoManager(3X)).
addActionWidget
Page 7
VkMenu(3x)VkMenu(3x)
VkMenuActionWidget *addActionWidget(const char *name,
XtCallbackProc func,
XtPointer data,
int pos = -1);
VkMenuActionWidget *addActionWidget(const char *name,
XtCallbackProc func,
XtCallbackProc undoCallback,
XtPointer data,
int pos = -1);
Functionally equivalent to addAction(), but forces the menu system
to create a widget, as opposed to a gadget. Gadgets are used by
default.
addConfirmFirstAction
VkMenuConfirmFirstAction
*addConfirmFirstAction(const char *,
XtCallbackProc func,
XtPointer data,
int pos = -1);
Some actions are potentially dangerous and/or cannot be reversed.
Quitting an application might be one example. The function
addConfirmFirstAction() adds an action to a menu that automatically
posts a confirming dialog before executing the command. Otherwise,
the function is equivalent to addAction() without the option of an
undo callback.
addSeparator
VkMenuSeparator *addSeparator(int pos = -1);
Adds a separator item to a menu.
addLabel
VkMenuLabel *addLabel(const char *, int pos = -1);
Add a non-selectable label item to a menu.
addToggle
VkMenuToggle *addToggle(const char *,
XtCallbackProc func,
XtPointer data,
int state = -1,
int pos = -1);
VkMenuToggle *addToggle(const char *,
XtCallbackProc func,
XtCallbackProc undoCallback,
Page 8
VkMenu(3x)VkMenu(3x)
XtPointer data,
int state = -1,
int pos = -1);
Adds a toggle item to a menu. All arguments serve the same purpose
as those in addAction(). An additional, optional argument, state,
allows the initial state of the item to be specified.
add
void add(VkMenuItem *, int pos = -1);
This function allows an arbitrary instance of a VkMenuItem subclass
to be added to a menu. This function is intended primarily to
support new derived classes not currently supported by the ViewKit.
addSubmenu
VkSubMenu *addSubmenu(VkSubMenu *submenu, int pos = -1);
VkSubMenu *addSubmenu(const char *name, int pos = -1);
VkSubMenu *addSubmenu(const char *name,
VkMenuDesc*,
XtPointer defaultClientData = NULL);
Installs a VkSubMenu object into a menu. The first form adds an
existing VkSubMenu instance. The second form creates and returns an
instance containing no items, while the third form creates a
VkSubMenu from the given static menu description.
addRadioSubmenu
VkRadioSubMenu *addRadioSubmenu(VkRadioSubMenu *submenu,
int pos = -1);
VkRadioSubMenu *addRadioSubmenu(const char *name,
int pos = -1);
VkRadioSubMenu *addRadioSubmenu(const char *name,
VkMenuDesc*,
XtPointer defaultClientData = NULL);
These functions have the same behavior as addSubMenu(), except that
the new submenu pane is configured as a radio box.
build()
void build(Widget parent);
It is possible to need a menu item to exist, but to not want it to
be visible on the screen. For example, an application might start up
with some menu panes hidden from view, to appear when the
application's state changes. To display a menu hierarchy without
forcing all items to become visible, call build(), with a parent
Page 9
VkMenu(3x)VkMenu(3x)
widget.
findNamedItem
VkMenuItem *findNamedItem(const char *name,
Boolean caseless = FALSE);
Finds and returns a menu item of the specified name starting at the
point in the menu hierarchy represented by the object for which this
function is called. If caseless is TRUE, the search is case-
insensitive. If no object with the given name is found, the function
returns NULL. If multiple instances of the same name exist, the
function returns the first name found in a depth-first search. Note
that it may be necessary to cast the return value if a specific type
of item is needed. For example:
VkMenuToggle * toggle;
toggle = (VkMenuToggle*)
pane->findNamedItem("toggle1");
removeItem
VkMenuItem *removeItem(const char *name);
Removes the named item from this menu. The removed item is returned.
This is functionally equivalent to:
(menu->findNamedItem(name))->remove();
activateItem
VkMenuItem *activateItem(const char * );
Activates and returns the named item. This is functionally
equivalent to:
(menu->findNamedItem(name))->activate();
deactivateItem
VkMenuItem *deactivateItem(const char * );
Deactivates and returns the named item. This is functionally
equivalent to:
Page 10
VkMenu(3x)VkMenu(3x)
(menu->findNamedItem(name))->deactivate();
replace
VkMenuItem *replace(const char *name ,
VkMenuItem * newItem);
Replace the named item with the specified item. This function
returns the replaced item.
menuType
virtual VkMenuItemType menuType() = 0;
Identifies the type of a VkMenu subclass. Possible types are BAR,
POPUP, SUBMENU, OPTION.
className
virtual const char* className();
This function returns 'VkMenu" for this class.
isContainer
Boolean isContainer();
This function returns TRUE for VkMenu and all derived classes
getScreen - ViewKit 2.1 only
VkScreen *getScreen();
Return the VkScreen object associated with this menu.
getItemPosition
int getItemPosition(VkMenuItem*);
int getItemPosition(char *name);
int getItemPosition(Widget);
Returns the position of a given menu item within this menu.
operator[]
VkMenuItem * operator[] (int index) const;
Returns the indexed child of a menu.
numItems
Page 11
VkMenu(3x)VkMenu(3x)
int numItems() const;
Returns the number of items currently in a menu.
useOverlayMenus
static void useOverlayMenus(const Boolean flag);
See MENUS IN THE OVERLAY PLANES in VkSubMenu(3).
Puts all menus in the overlay planes.
useWorkProcs
static void useWorkProcs(Boolean flag);
If TRUE (the default value), application startup time is improved
because menus are built using a workproc. An application might wish
to turn this off if there is a conflict with its own workproc usage.
EXAMPLESINHERITED MEMBER FUNCTIONS
Inherited from VkMenuItem
show(), hide(), manageAll(), setLabel(), setPosition(), activate(),
deactivate(), remove(), show(), _position, _isBuilt, _sensitive,
_parentMenu, _label, _isHidden, _unmanagedWidgets,
_numUnmanagedWidgets,
Inherited from VkComponent
installDestroyHandler(), removeDestroyHandler(), widgetDestroyed(),
setDefaultResources(), getResources(), manage(), unmanage(),
baseWidget(), okToQuit(), _name, _baseWidget, _w, deleteCallback
Inherited from VkCallbackObject
callCallbacks(), addCallback(), removeCallback(),
removeAllCallbacks()KNOWN DERIVED CLASSES
VkOptionMenu, VkSubMenu, VkHelpPane, VkRadioSubMenu, VkMenuBar,
VkPopupMenu,
CLASSES USED BY THIS CLASS
VkMenuAction, VkMenuActionWidget, VkMenuConfirmFirstAction, VkMenuItem,
VkMenuLabel, VkMenuSeparator, VkMenuToggle, VkRadioSubMenu, VkSubMenu
Page 12
VkMenu(3x)VkMenu(3x)KNOWN CLASSES THAT USE THIS CLASS
VkAlignmentGroup, VkGraph, VkHelpPane, VkMenu, VkMenuBar, VkMenuItem,
VkWindow
SEE ALSO
VkMenuItem, VkComponent, VkAlignmentGroup, VkGraph, VkHelpPane,
VkMenuAction, VkMenuActionWidget, VkMenuBar, VkMenuConfirmFirstAction,
VkMenuItem, VkMenuLabel, VkMenuSeparator, VkMenuToggle, VkRadioSubMenu,
VkSubMenu, VkWindow
ViewKit Programmer's Guide
The X Window System, DEC Press, Bob Sheifler and Jim Gettys
The X Window System Toolkit, DEC Press, Paul Asente and Ralph Swick
The OSF/Motif Programmers Reference, Prentice Hall, OSF
Page 13
