Skip to content

Class: PopupMenu

Properties | Events | Methods | Index of Classes

Displayed whenever a choice is made from a menu bar and from certain choices made from an already-displayed popup menu

Hierarchy

cObject > cUIObject > DfBaseObject > DfBaseWindow > DfBaseUIWindow > DfBaseControl > DfBaseList > DfBaseActionBar > DfBasePullDown > PopupMenu

Show full hierarchy and direct subclasses

Library: Windows Application Class Library

Package: Windows.pkg

Mixins: Statushelp_Item_Mixin

Description

This class is obsolete. Menus are now created using class cCJMenuBar.

As of revision 12.1, DataFlex includes full support for Codejock Software's COM Xtreme CommandBars package for creating menus, toolbars and statusbars. See Using Menus, Toolbars and Statusbars for more information.

A PopupMenu object is displayed whenever a choice is made from a menu bar and from certain choices made from an already-displayed popup menu.

Sample

Object MainPanel is a Panel
    :
    Object ActionBar is a MenuBar
        Item_List
            On_Item "&File"  send MenuPopup to (FileMenu(self))
            Set Status_Help to "Display file menu options."
            :
        End_Item_List

        Object FileMenu is a PopupMenu
            Item_List
                On_Item "&Open" Send Open_File
                Set Status_Help to "Open a new File"
                On_Item "&Close Send Close_File
                Set Status_Help to "Close the File"
                On_Item "" Send None // separator
                On_Item "&Exit" Send Exit_Application
                Set Status_Help to "Exit current Application"
            End_Item_List

            Procedure OnInitMenu
                integer Opened
                Delegate get File_Opened to Opened
                Set Shadow_State item 1 to (Opened=0)     
            End_Procedure

        End_Object

    End_Object
    :
End_Object

Syntax

Use windows
:
Object object_name is a PopupMenu
    Item_List
        On_Item MenuText Send message [to dest_object]
        Set Status_Help to StatusHelpText
        On_Item "" send none // separator
        :
    End_Item_List

    Procedure OnInitMenu
        :
    End_Procedure
End_Object

Of Special Note

The PopupMenu class is a subclass of the MenuBar class and inherits its item-based interface. Items in a PopupMenu are normally created using the item_list / end_item_list syntax. Items may also be created, changed, and deleted using the dynamic item-interface messages (delete_data, add_item, Insert_item, delete_item). Items should only be added or deleted when the menu bar is inactive. The dynamic adding of items may be performed within the OnInitMenu event procedure.

Each item in a PopupMenu is defined with the following properties: Value, Message, Aux_Value, Shadow_state, status_help and select_state.

Col 1 Col 2
Value An item's value is the text that will be displayed in the menu item. It is set by the on_item command, the add_item and insert_item messages, and can be directly changed with the set value message.
Message and Aux_Value An item's message specifies the message that will be sent when the item is selected. If aux_value is 0 (and it normally is), the message is sent to the current focus object. If aux_value is non-zero, the message is sent to the object ID in aux_value. If the message is MenuPopup (or 0), the object ID represented in Aux_Value is activated as a child PopupMenu. This is referred to as a cascading popup menu.
Shadow_State If an item's shadow_state is true, the item will appear disabled and users will be unable to select the item.
Status_Help Each item may have status-help text associated with it. When the menu item is selected, this help will appear in the status bar.
Select_State If the popup-menu object's select_mode is set to Multi_Select, users may set the select_state of any menu item. When selected, the item will appear with a check mark in front of it.

Separators

Item separators may be created by creating a blank item. A 3 D line will be drawn to separate the other menu items. Although this item cannot be selected, it does exist.

On_Item "" Send None

Send Add_Item msg_none ""

Character Highlighting

A highlight character may be defined by prefixing the & symbol to the letter that should be highlighted. When the menu is selected, pressing that highlighted letter (actually it will appear underlined) will select the item.

On_Item "&Save" Send SaveIt

Send Add_Item msg_SaveIt "&Save"

The Focus

The menu bar and its popup-menu children never take the focus. When a MenuBar or PopupMenu is selected, the focus does not change and no focus change messages are sent. This is actually a very useful feature. If you wish to know what object was the focus object when the menu bar was selected, simply get the focus property.

PopupMenu Events

Each time a PopupMenu object is selected, the event message onInitMenu is sent to the object. This is a very useful message. This occurs before the object has been displayed. This is a good time for changing menu items or setting shadow states or select states.

Anytime any menu item change occurs within the a PopupMenu, the message change_menu is sent to the MenuBar. This message is passed both an item number and an object number. This allows the message to determine which object caused the event. If augmented, this must be forwarded-it controls the display of status help.

The following example shows how OnInitMenu might be used to set the shadow_state of various items based on a user login level.

Procedure OnInitMenu
    integer Level
    Get UserID_Level to Level
    Set Shadow_State 0  to False
    Set Shadow_State 1  to False
    Set Shadow_State 2  to (Level lt 1)
    Set Shadow_State 3  to (Level lt 2)
    Set Shadow_State 4  to (Level lt 3)
End_Procedure

The following example shows how select_state may be set and changed within an object. This is using the DFCreate_Menu syntax described in the Menu_System section.

DFCreate_Menu "&Display_Options" Display_Options_Menu
    Set select_mode to Multi_Select
    // note: sending to Self will force the message to get sent to the
    //       PopupMenu which will then delegate to the panel object which 
    //       understands these messages.       
    On_Item "&Tool-bar"   send Toggle_ToolBar   To Self
    On_Item "&Status-bar" send Toggle_StatusBar To Self

    Procedure OnInitMenu
        integer bState
        Delegate Get ToolBar_State to bState
        Set Select_State 0 to bState
        if  bState   Set Status_Help 0 To 'Remove the Tool bar'
        Else         Set Status_Help 0 to 'Add the Tool bar'

        Delegate Get Statusbar_State to bState
        Set Select_State Item 1 to bState
        if  bState  Set Status_Help Item 1 To 'Remove the Status bar'
        Else        Set Status_Help Item 1 to 'Add the Status bar'
    End_procedure
End_Menu

The menubar-system package defined in DfMenu.pkg provides a number of macro commands to make it easier to create MenuBar / PopupMenu systems. This is described in the Menu System section.

SubClasses of PopupMenu

Two PopupMenu subclasses are provided to support special popup menus. The ViewPopupMenu redirects messages to the client-area object instead of the focus object. This is used activate views and report views from a menu. The DEOPopupMenu provides a mechanism for the menu to determine if the invoking focus object is a DEO and if it is a DEO control. This is used to properly shadow items (within onInitMenu), which ensures that DEO messages are never sent to non-DEOs.