Skip to content

Menu Items

A “menu item” refers to all items used in menubars, toolbars, and context menus. If a menu item is a popup menu item, it will contain nested child menu items. The cCJMenuItem class (or one of its sub-classes) is used interchangeably for all of these types of conditions.

Most of the characteristics associated with a menu item are common to any type of menu item. An item’s text, image, etc., will be the same for any type of menu control (e.g., a button, a checkbox, a combo). These common menu item characteristics are referred to as actions and are managed by the cCJAction class. The cCJMenuItem class is a sub-class of cCJAction.

The most commonly used action properties are:

  • psCaption – displays the caption text
  • psImage – displays a menu or toolbar image
  • psDescription – displays a statusbar description
  • psToolTip – displays tooltip text
  • psShortCut – displays the shortcut key text in a menu item
  • pbEnabled – determines if the item is enabled
  • pbChecked – determines if the item is checked
  • pbVisible – determines if the item is visible

The most commonly used action methods are:

  • IsChecked – returns true if the item should be checked
  • IsEnabled – returns true if the item should be enabled
  • IsVisible – returns true if the item should be visible

The most commonly used action events are:

  • OnExecute – is sent when the menu item is “executed”.
  • OnPopupInit – if the item is a popup, this is sent before the popup menu is displayed.

A menu item’s type of control is determined by the peControlType property. There are two types of control types: “buttons” and “popups”. Buttons include all of the types that make a selection. Examples of button types are buttons, edit forms, combo forms, radios, checkboxes, and labels. Popups are item types that are used to invoke a popup menu. Examples of popup types are popup and split-button popup.

See peControlType for the full list of supported control types.

A menu item control’s appearance is controlled by the peControlStyle property. This allows you to display an image, text, or both. The default style picks the best appearance based on the item’s placement (in a menu or in a toolbar) and its definition (does it have an image).

See peControlStyle for the full list of supported control styles.

When a COM menu item is created, both an action and a control COM object are created and added to the cCJCommandBarSystem’s COM object model.

An action is an object that represents a menu item’s fundamental behaviors. These are the behaviors that can be applied to a menu item of any control type. Examples of fundamental behaviors are an item’s image, text, description, tooltip, and selection behavior. All of these actions are based on the same class, cCJAction. The cCJAction class is a superclass of the cCJMenuItem class. When a COM menu item is created, its COM action is bound to the cCJMenuItem item proxy object. After the menu item is created, its COM action remains bound to the proxy object.

A control is the actual control that is displayed within your menu or toolbar. This could be a button, a popup, a combo, a checkbox, etc. Each control is based on a different COM class. When a COM menu item is created, the COM action is created, and then the COM control is created. The control is connected to the action by an action-ID property (piID). The control will refer to the action to supply all of its fundamental behaviors such as images, text, and selection behavior. Behaviors that are unique to a control, such as the contents of a combo list, must be added directly to the COM control. After a COM control has been created and added to the cCJCommandBarSystem COM object model, it will not be bound to a proxy object. In other words, the cCJMenuItem is an action’s proxy object and not the control’s proxy object.

Most of the time, the split personality of a menu item will be of no concern to you. Most of the properties, methods, and events needed to maintain a menu item are action properties, methods, and events. In some cases, you will need to interact directly with the COM control properties. This may be needed when working with the more complex controls such as combos and edits. See Combos, Edits, and Other Complex Controls for an explanation of how these controls are used.

Codejock’s use of separate actions and controls was implemented to support menu end-user full customization. For example, an end user might customize a toolbar by copying an item from a popup menu. In such a case, the control is copied, but it remains bound to the same action. The original item’s cCJMenuItem object will now control both controls, which is exactly what you want.

See Also