Class: cCJMenuItem

Properties | Events | Methods | Index of Classes

Used to create menu and toolbar item objects.

Hierarchy

Library: Windows Application Class Library

Package: cCJCommandBarSystem.pkg

Description

The cCJMenuItem class is used to create menu items, which refer to menubar items, toolbar items, popup menu items, and context menu items. cCJMenuItem objects can be used interchangeably for all of these purposes.

Object oFindMenu is a cCJMenuItem
    Set peControlType to xtpControlPopup          
    Set psCaption to "&Find"

    Object oFindFirstTool is a cCJFindFirstMenuItem
    End_Object

    Object oFindPreviousTool is a cCJFindPreviousMenuItem
    End_Object

    Object oFindMenuTool is a cCJFindMenuItem
    End_Object

    Object oFindNextTool is a cCJFindNextMenuItem
    End_Object

    Object oFindLastTool is a cCJFindLastMenuItem
    End_Object

    Object oPromptToolItem is a cCJPromptMenuItem
        Set pbControlBeginGroup to True
    End_Object

End_Object

Using Menus, Toolbars and Statusbars

Typically, a menu item will consist of the control type, display properties, execution events, and functions to maintain an item's enabled, checked, and visible state.

The Control Type and Appearance

The [peControlType](cCJMenuItem-Property-peControlType.md) property determines what type of control will be created for a menu item. There are two main types of controls:

Button: A button is any control that is used for selection, such as a menu button or a toolbar button. When selected, the [OnExecute](cCJAction-Event-OnExecute.md) message is sent to the object.
Popup: A popup is any control that is used to display a new menu. For example, menu items in a menubar will usually be popup items. Selecting any item pops up a new menu.

The [peControlStyle](cCJMenuItem-Property-peControlStyle.md) determines how an item is displayed, allowing you to show text, images, or both.

The [pbControlBeginGroup](cCJMenuItem-Property-pbControlBeginGroup.md) is used to create a "break" before the item (a horizontal or vertical line depending on menu orientation).

The Display Properties

The display properties determine the text and images that are used with a menu item. The main properties are:

[psCaption](cCJAction-Property-psCaption.md): Displays the caption text.
[psImage](cCJAction-Property-psImage.md): Displays a menu or toolbar image.
[psDescription](cCJAction-Property-psDescription.md): Displays a statusbar description.
[psToolTip](cCJAction-Property-psToolTip.md): Displays tooltip text.
[psShortCut](cCJAction-Property-psShortcut.md): Displays the shortcut key text in a menu item.

The Selection Events

A menu item is "executed" by clicking on the menu item or navigating to the item and pressing enter.

If the item is a button type, the [OnExecute](cCJAction-Event-OnExecute.md) event is sent to the object. This event is used to perform whatever action you wish.

If the item is a popup type, the popup menu will be displayed. The [OnPopupInit](cCJAction-Event-OnPopupInit.md) event, which is called before the new menu is displayed, provides a place to customize what will appear in the menu.

Enabled, Checked and Visible

Menu items have three main states: enabled, checked, and visible ([pbEnabled](cCJAction-Property-pbEnabled.md), [pbChecked](cCJAction-Property-pbChecked.md), and [pbVisible](cCJAction-Property-pbVisible.md)) that can be changed during the course of program execution. While you may directly set these properties, the preferred method is to augment three functions: [IsEnabled](cCJAction-Function-IsEnabled.md), [IsChecked](cCJAction-Function-IsChecked.md), and [IsVisible](cCJAction-Function-IsVisible.md) to return an item's desired enabled, checked, and visible state. Once created, the mechanism for keeping these properties up to date is automatic.

If the [pbActiveUpdate](cCJAction-Property-pbActiveUpdate.md) property is set to true, the item will receive the [Update](cCJAction-Procedure-Update.md) message on an idle timed basis (if cCJCommandBarSystem's [pbTimerUpdate](cCJCommandBarSystem-Property-pbTimerUpdate.md) is true). This can be used to keep toolbar items up to date.

cCJMenuItem Sub Classes

A number of menu item sub-classes have been created that are designed to handle most of the commonly needed menu actions such as finding and saving. These can easily be added to any menu or toolbar and used without adding any extra code. These classes are listed above in the sub-class hierarchy list, and the first sample shown at the top of this section demonstrates how these classes are used.

Samples

This menu item will exit the application. This demonstrates the simplest use of a menu item.

Object oExitMenuItem is a cCJMenuItem
    Set psCaption to "&Exit"
    Set psToolTip to "Exit Application"
    Set psDescription to "Close all work and exit application"
    Set psShortcut to "Alt+F4"

    Procedure OnExecute Variant vCommandBarControl
        Send Exit_Application of Desktop
    End_Procedure

End_Object

The following is an example of a save menu item. It uses IsEnabled to determine if the item should be enabled or not. When selected, it will perform a save. Note that the [cCJSaveMenuItem](cCJSaveMenuItem.md) sub-class already provides this functionality.

Object oSaveMenuItem is a cCJMenuItem
    Set psCaption to "Save"
    Set psToolTip to "Save"
    Set psDescription to "Save current information to database"
    Set psImage to "ActionSaveRecord.ico"
    Set psShortcut to "F2"

    // if used in a toolbar, it will get updated dynamically as needed
    Set pbActiveUpdate to True

    Procedure OnExecute Variant vCommandBarControl
        Send Request_save of (focus(Self))
    End_Procedure

    Function IsEnabled Returns Boolean
        Boolean bIsDEO bHasRecord bChanged bEnabled bHasIndex
        Handle hoServer hoCommandBars
        Get CommandBarSystemObject to hoCommandBars
        Get DEOInformation of hoCommandBars (&hoServer) (&bHasRecord) (&bChanged) (&bHasIndex) to bIsDEO
        Function_Return (bIsDEO and hoServer and bChanged)
    End_Function

End_Object

The following is an example of a checkbox menu item. OnExecute is used to toggle a state within the application. IsChecked is used to determine the visual checked state of the control.

Object oTextBelowMenu is a cCJMenuItem
    Set psCaption to "Text Below &Icons"
    Set psToolTip to "Text Below &Icons"
    Set psDescription to "Show Text below the images in toolbars"

    Procedure OnExecute Variant vCommandBarControl
        Handle hoCommandBars
        Get CommandBarSystemObject to hoCommandBars
        Send ToggleTextBelowIcons of hoCommandBars
    End_Procedure

    Function IsChecked Returns Boolean
        Boolean bOn
        Handle hoCommandBars
        Get CommandBarSystemObject to hoCommandBars
        Get pbShowTextBelowIcons of hoCommandBars to bOn
        Function_Return bOn
    End_Function

End_Object

The following is an example of a popup menu item, which could be used to popup a menu with the above three sample items:

Object oStuffPopup is a cCJMenuItem
    Set peControlType to xtpControlPopup          
    Set psCaption to "&Stuff"

    Object oSaveMenuItem is a cCJMenuItem
        :
    End_Object

    Object oTextBelowMenu is a cCJMenuItem
        :
    End_Object

    Object oExitMenuItem is a cCJMenuItem
        :
    End_Object

End_Object

Actions and Controls

A cCJMenuItem object uses two COM classes. Once created, it is bound to a COM action object (cCJAction), which manages all of the properties and behaviors common to all types of items regardless of their control type. This includes most of the properties, events, and methods listed above. The cCJAction object is the super-class of the cCJMenuItem object, making the cCJMenuItem object the proxy object for the COM action. The binding is static; once the COM action is created, it remains bound to the cCJMenuItem object.

In addition, a COM object is created based on the actual control type (peControlType). Different objects are created for the different controls (e.g., a button, an edit, a combo) and these controls can have different interfaces. This COM object is not bound to any of the static proxy objects. In other words, it is not bound to the cCJMenuItem object. If you need to access the COM control directly, you must create a proxy object of the appropriate class, bind it to the COM control, use it, and then destroy it. The [CreateProxyControl](cCJAction-Function-CreateProxyControl.md) and [CreateFirstProxyControl](cCJAction-Function-CreateFirstProxyControl.md) methods are provided for this purpose.

Combos, Edits and Other Complex Controls

In most cases, you will never need to create proxy objects that interact directly with the COM controls. The interface provided in cCJMenuItem will usually do everything you need. There are some exceptions. Some of the more complex COM controls require direct interaction.

You are most likely to encounter this with the combo control. It is a complex control that will require you to use the COM control's interface to create and access the different combo item values. See [cCJCommandBarComboBox](cCJCommandBarComboBox.md) for a description of how this class is used within a cCJMenuItem object.

The edit control also requires that you send messages to the COM control. See [cCJCommandBarEdit](cCJCommandBarEdit.md) for a description of how this class is used within a cCJMenuItem object.

The technique used here can be applied when working directly with any of the COM controls (e.g., [cCJCommandBarEdit](cCJCommandBarEdit.md), [cCJCommandBarControl](cCJCommandBarControl.md), [cCJCommandBarButton](cCJCommandBarButton.md), `cCJCommandBarPopup ). It requires that you:

Create a proxy object for the COM control (using [CreateProxyControl](cCJAction-Function-CreateProxyControl.md) or [CreateFirstProxyControl](cCJAction-Function-CreateFirstProxyControl.md)).
Use the interface that is unique to that control to interact with the control.
Dispose of the proxy object when you are done.

Most of these direct COM control interactions will occur within events such as [OnCreateControl](cCJMenuItem-Event-OnCreateControl.md), [OnExecute](cCJAction-Event-OnExecute.md), and [OnPopupInit](cCJAction-Event-OnPopupInit.md).

When a menu item's parent COM control is created, it sends the message [CreateComInstance](cCJMenuItem-Procedure-CreateComInstance.md) to all child objects. When received, the cCJMenuItem object does the following:

It creates the COM action by calling [CreateComAction](cCJAction-Procedure-CreateComAction.md). As part of creating this action, the event [OnCreateAction](cCJAction-Event-OnCreateAction.md) is sent.
It creates the COM control by calling [CreateComControl](cCJMenuItem-Function-CreateComControl.md). As part of creating the control, the event [OnCreateControl](cCJMenuItem-Event-OnCreateControl.md) is called.
If the object’s [peControlType](cCJMenuItem-Property-peControlType.md) is a popup type, it sends CreateComInstance to all child objects. This recursively builds the popup menu system.

When complete, all COM objects are created. The COM action object is statically bound to the cCJMenuItem object, while the COM control object is not bound to any proxy object.