VkMenu(3x)
VkMenu - Abstract base class for all ViewKit menu container objects
As shipped in IRIX 6.5.22. Last changed in IRIX 6.5.5.
NAME VkMenu - 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, 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 static void useOverlayMenus(const Boolean flag); static void useWorkProcs(Boolean flag); CLASS DESCRIPTION VkMenu 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. 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} }; 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); // 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 } 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 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, 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 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: (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 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. EXAMPLES INHERITED 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 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