VkMenuItem(3x)

NAME
     VkMenuItem - Abstract base class for all ViewKit menu classes

INHERITS FROM
     VkComponent : VkCallbackObject

HEADER FILE
     #include <Vk/VkMenuItem.h>


PUBLIC PROTOCOL SUMMARY
   Manipulating Menu Items
           void activate();
           void deactivate();
           int remove();
           void show();
           void hide();
           virtual void setLabel(const char * str);
           void setPosition(int pos);



   Access Functions
           virtual const char* className();
           virtual Boolean isContainer();


SUBCLASS PROTOCOL SUMMARY
   Constructor/Destructor
           VkMenuItem( );
           VkMenuItem(const char * itemName);


   Managing entries
           static  void    manageAll();



CLASS DESCRIPTION
     VkMenuItem is an abstract class that defines the basic behavior of all
     menu objects supported by the ViewKit. There are two types of classes
     derived from VkMenuItem. The first serve as containers. These correspond
     to the menu types supported by Motif: popup menus, pulldown menu panes,
     menubars, and option menus. The second type of derived classes can be
     used as individually selectable items in a menu. These include actions,
     toggles, labels, separators, and so on.

     For the most part, the classes derived from VkMenuItem have a direct
     correspondence to a Motif widget. An action (a VkMenuAction object)
     represents an XmPushButton gadget along with an associated callback.
     However, the ViewKit menus offer several advantages over directly using
     Motif widgets. First, all menu items can be manipulated more easily than
     widgets. All items can be displayed, activated, or deactivated with a
     single function call.  Items can also be moved, or replaced by other
     items easily. For example an action item in a menu pane can be replaced
     by a cascading pulldown menu with a single function call.

     The various VkMenuItem classes also hide the somewhat confusing
     organization of Motif cascade and option menus. For example, a menu pane
     is just a type of menu item that can contain other items. The items in a
     menu pane might include actions, toggles, labels, or other menu panes.
     There are not confusing submenu id's to work with.

     Menus are also constructed in the most efficient manner possible. Widgets
     within a menu hierarchy are managed in groups in a completely transparent
     way.

     VkMenuItem is derived from VkComponent, and follows most of the
     conventions associated with component. However, unlike most components,
     all menu items defer the creation of widgets. When constructing menus,
     objects are instantiated and organized into a hierarchy, but no widgets
     are created.  When the menu is to be displayed, applications must call
     the build() member function for the top of the menu hierarchy. This
     creates and manages all widgets at once.

   Deriving Subclasses
     Most common types of menu items are already defined within the ViewKit,
     and it is not recommended that new classes be derived directly from
     VkMenuItem.  Various classes derived from VkMenuItem may be candidates
     for further derivation. See the individual derived classes for more
     information.

FUNCTION DESCRIPTIONS
   show
           void show(Widget parent);
           void show();


          Like most components, all menu items are displayed by calling show()
          at the desired time. For VkMenuItems, show() works slightly
          differently. Because the construction of the widgets associated with
          menu items is delayed, show may take an argument that specifies the
          parent of the menu hierarchy to be built. It is only necessary to
          call show() for the top-most object in a menu hierarchy. All other
          objects will be constructed automatically. The parent argument to
          show() is only effective the first time it is called. Menus cannot
          be reparented after they are constructed.

          When called after the menu has been created or with no arguments,
          show() simply sets the state of an item such that it is, or will be
          visible. By default, all items will be visible when they are first
          constructed. See hide() for more information.

   activate
           void activate();


          Makes an item active so that it accepts input.

   deactivate
           void deactivate();


          Make an item inactive so that it cannot be selected. Any item can be
          active or inactive.

   remove
           int remove();


          Removes the item from the menu hierarchy that contains it. The item
          is not destroyed.

   hide
           void hide();


          Marks an item as not visible Calling hide() on a currently visible
          item unmanages the widget associated with the item. Calling hide()
          for an item before the menu has been constructed marks the item so
          that it will not appear when build() is called. Calling show()
          reverses the effects of hide().

   setLabel
           virtual void setLabel(const char *str);


          It is sometimes necessary to programmatically set the label of an
          item.  (Generally labels are retrieved from the item's
          XmNlabelString resource in the resource database.) This function
          allows labels to be set programmatically, without losing the ability
          to set labels in the resource file. The given string is treated as
          the name of a resource to be retrieved from the resource database.
          If no such resource is found, the string is treated as the actual
          label to be displayed.

   setPosition
           void setPosition(int pos);

     Specify a specific position within a menu pane or menubar at which this
     item should appear.

   className

           virtual const char* className();


          The class name of this class is "VkMenuItem".

   isContainer
           virtual Boolean isContainer();


          This function returns TRUE if an object is one of the container
          types of menu items.

   VkMenuItem
           VkMenuItem();
           VkMenuItem(const char* itemName);


          Initialize the data members of a VkMenuItem object.

   ~VkMenuItem
           ~VkMenuItem();


          Frees all memory associated with a VkMenuItem object. If the object
          is a member of a menu, the object is removed from that menu.

   manageAll
           static  void    manageAll();




INHERITED MEMBER FUNCTIONS
   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
     VkMenuAction, VkMenuConfirmFirstAction, VkMenuActionObject,
     VkMenuActionWidget, VkMenuToggle, VkMenuUndoManager, VkMenuLabel,
     VkMenuSeparator, VkMenu, VkOptionMenu, VkSubMenu, VkHelpPane,
     VkRadioSubMenu, VkMenuBar VkPopupMenu,

CLASSES USED BY THIS CLASS
     VkMenu

KNOWN CLASSES THAT USE THIS CLASS
     VkGraph, VkMenu, VkMenuBar, VkMenuItem, VkMenuUndoManager, VkOptionMenu,
     VkPopupMenu, VkSubMenu, VkWindow

SEE ALSO
     VkComponent, VkGraph, VkMenu, VkMenuBar, VkMenuUndoManager, VkOptionMenu,
     VkPopupMenu, 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