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". Menu items refers 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

Note: For an overview on the commandbar system, refer to 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 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 message is sent to the object.
Popup - A popup is any control that is used to popup 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 determines how an item is displayed allowing you to show a text, image or both.

The pbControlBeginGroup 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 - 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

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 event is sent to 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 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, pbChecked and pbVisible) 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, IsChecked and IsVisible 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 property is set true, the item will receive the Update message on a idle timed basis (if cCJCommandBarSystem's pbTimerUpdate 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 easily can 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 shows 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 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

This 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 is the object that 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 and therefore the cCJMenuItem object is 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 and CreateFirstProxyControl 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 like to encounter this with the combo control. It is a complex control that will require that you use the COM control's interface to create and access the different combo item values. See cCJCommandBarComboBox 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 for a description of how this class is used within a cCJMenuItem object.

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

1. Create a proxy object for the COM control (using CreateProxyControl or CreateFirstProxyControl)
2. Use the interface that is unique to that control to interact with the control
3. Dispose of the proxy object when you are done.

Most of these direct COM control interactions will occur within events such as OnCreateControl, OnExecute and OnPopupInit.

The Menu Item Creation Process

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

1. It creates the COM action by calling CreateComAction. As part of creating this action, the event OnCreateAction is sent.

2. It creates the COM control by calling CreateComControl. As part of creating the control, the event OnCreateControl is called.

3. If the object peControlType is a popup type. It sends CreateComInstance to all child objects. This recursively builds the popup menu system.

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