Lesson 5 - Exploring the Menu/Frame Procedure

Top  Previous  Next

This topic:

 Tells you how to use the Menu Editor to create a new MENUBAR structure or edit an existing one.

 Tells you how to use the Window Designer to create a new TOOLBAR structure or edit an existing one.


Menu Editor

A menu is a list of the various actions your application may perform. In Clarion, this list of actions (menu) is declared using the MENUBAR structure, MENU structures, and ITEMs. In this chapter, the word menu generically refers to the list of actions your application may perform. The words MENUBAR, MENU, and ITEM refer to Clarion Language statements that define your application’s menu.

The Menu Editor is a visual design tool—a subset of the Window Designer—that generates Clarion Language statements to define your application’s menu.

This section:


Discusses dynamic menu management for Multiple Document Interface (MDI) applications.


Shows you how to call the Menu Editor and create a menu.


Describes how to automatically implement Standard Windows Behavior (SWB) for commands such as Edit Copy by linking a Clarion Standard ID (STD attribute) to an ITEM or MENU.


Merging MDI Menus

Multiple Document Interface (MDI) applications make special demands upon a program. Often, the program may support a variety of document windows, each of which has a slightly different set of commands from which the user may select.

Normally in an MDI application, the developer writes code to monitor which window is active and to change the menus and toolbars to reflect the options currently available to the user. Clarion does this automatically by merging menus and toolbars according to preferences you specify with the Menu Editor. However, accurate specification requires some understanding and planning by the application developer.


Global Selections

On an APPLICATION frame, the MENUBAR defines the Global menu selections for the program. These Global menu selections are generally available on all MDI "child" windows. However, if the NOMERGE attribute is present on the application’s MENUBAR, then there is no Global menu, and the application’s menu is a Local menu displayed only when no MDI child windows are open.


Local Selections

On an MDI child window, the MENUBAR defines Local menu selections that are automatically merged with the Global menu selections defined on the application’s MENUBAR. Both the Global and the Local menu selections are available while the MDI "child" window has input focus. Once the window loses focus, its Local menu selections are removed from the Global menu selections. If the NOMERGE attribute is specified on an MDI child window’s MENUBAR, the Local menu overwrites and replaces the Global menu.


Non-MDI Windows

On a non-MDI window, the Local menu selections are never merged with the Global menu selections. A MENUBAR on a non-MDI window always appears in the window, and not on any application frame which may have been previously opened.


Merging Order

Normally, when an MDI window’s menu (Local selections) merges into an application’s menu (Global selections), the Global menu selections appear "first", followed by the Local menu selections. First means either toward the left or toward the top, depending on whether the merged selection is displayed on the action bar (horizontal list) or in a menu (vertical list).

The merge process also considers whether any Local MENUs match any Global MENUs. MENUs that have the same name and the same MENUBAR level, match. When there are no matches, the menus merge in the normal order. However, when MENUs match, a single menu (vertical list) results with the Global selections appearing above the Local selections. This new menu has all the attributes of the Global MENU, such as, MSG, FIRST, etc. Within this merged menu, any matching subMENUs are also merged into a single menu. Note that ITEMS are not merged, even when they match.

The normal merging order may be modified by using the Menu Editor’s Position drop-down list (see Menu Positions and Merging Behavior below) to add FIRST or LAST attributes to individual MENUs and ITEMs. The merge position priority is:


Global selections with FIRST attribute


Local selections with FIRST attribute


Global selections without FIRST or LAST attributes


Local selections without FIRST or LAST attributes


Global selections with LAST attribute


Local selections with LAST attribute


Planning and Implementing Menus

To create menus for MDI applications:

1. Create a master menu for the APPLICATION frame window.

Most likely, this will include a File menu and a Help menu, since they contain functions that are available even when no document windows are open.

Clarion’s Application Frame procedure template comes with a predefined menu with many of the most common functions already provided for you.

Use the Window Designer’s Menu Editor to create your menus. Be sure to choose the FIRST attribute for the File MENU, and the LAST attribute for the Help MENU from the Position property drop-down list. This ensures that File and Help will maintain their relative positions when Clarion merges this global menu with local menus.


2. Plan the additional menus for the child windows.

Can they all share the same menu titles? Do they share many of the same commands? Ideally, most of the MENUs and ITEMs can be active in all the child windows. If there are only a few commands specific to certain windows, plan on disabling those MENUs and ITEMs in the windows that don’t support them, and enabling them in those that do.


3. Create the menu for the first child window.

Again, you will use the Window Designer’s Menu Editor to create the menu. Add any window-specific MENUs to the first child window. That is, the window-specific MENUs the application frame lacks-—such as Edit, Insert, etc.

Optionally, add a File MENU to the first child window. This is necessary only if the child window needs an ITEM on the File MENU that is not already included on the application’s File MENU. For example, adding a Close command might be appropriate. If so, add the File MENU to the first child window. Add the Close ITEM to the File MENU.

Add the Window MENU to the first child window. Window MENUs are standard for most windows programs. A typical Window MENU includes the following ITEMs: Arrange Icons, Tile, Cascade, plus a document (windows) list that displays all open child windows and allows the user to switch between them. In many cases this entire MENU, including the document list, can be implemented with standard ID’s (StdID’s). See Creating Your Application's Menu below.

4. Exit the Menu Editor and save the menu.

5. Test the interaction of these first two menus.

Do they merge the way you planned? Are the correct selections available for the window with focus? Make any adjustments with the Menu Editor.

6. Repeat steps 3. through 5. for other child windows.


Calling the Menu Editor

To create a menu for your application, use the Menu Editor. You access the Menu Editor through the Window Designer.

You can also create a toolbar for your application using the Window Designer. See Toolbars for more information.

This section provides detailed examples of using the Menu Editor to create menus. From the Window Designer, DRAG the MENUBAR control in the Controls Toolbox to the active window to create a new menu, or right-click on the MENU and choose Edit Menu from the popup menu to edit an existing menu. You can also select the Window and click on the Edit Menu smart link in the Properties Pad.

The Menu Editor dialog visually represents a Clarion MENUBAR data structure. The menu tree (on the left hand side of the dialog) appears as simplified Clarion language syntax, containing these Clarion keywords:


A MENUBAR keyword at the top.


A MENU statement followed by the corresponding Use property, and a menu name (Text).


An ITEM statement followed by the corresponding Use property, followed by an item name (Text).


A SEPARATOR followed by the corresponding Use property.



Menu Editor command buttons allow you to add and delete MENUs and ITEMs. You may also move MENUs and ITEMs within the MENUBAR structure with navigation buttons.

The right hand side of the dialog lets you specify the properties of your MENUs and ITEMs.

For a more detailed look at the Menu Editor and its options, click here.

When using the Application Generator, each ITEM you place on a MENU or MENUBAR automatically adds an embed point to the control event handling tree in the Embedded Source dialog. This lets you easily attach functionality to your ITEMs.

The following section provides a step-by-step procedure for creating a menu. Following that are sections detailing the Menu Editor commands and options, and a discussion of considerations to keep in mind when creating MDI application menus.



Creating Your Application’s Menus

Here are the steps for creating a menu starting from an empty window within the Window Designer.


Open the Controls Toolbox (View  Toolbox) and DRAG the MENUBAR control to the active window.


RIGHT-CLICK on the MENUBAR control just populated, and select Edit Menu from the popup menu.

The Menu Editor dialog appears. Only the MENUBAR statement is present.


Press the Add new menu  button.

This adds the first MENU statement, its name, and its corresponding USE attribute.

The ampersand within the MENU name signifies that the character following the ampersand is the accelerator key. That is, the character is underlined (for example: Menu1), and, when the user presses ALT+accelerator key, the menu displays.


In the Menu Text property on the right side of the Menu Editor, type the text to display for this MENU.

For example, type &File, so the end user sees File.


In the Use property, type a Field Equate Label.

A Field Equate Label has a leading question mark (?), and you should make it descriptive. For example ?File shows this menu is to manipulate a file. You can refer to the MENU in your source code by its Field Equate Label.


Press the Add new item  button.

This inserts an ITEM just after the MENU statement. Note that ITEMs are used to execute commands or procedures, whereas MENUs are used to display a selection of other MENUs or ITEMs.


In the Text property field, type the text to display for this menu ITEM.

For example, type &Open, so the end user sees Open. The ampersand within the ITEM name signifies the character following the ampersand is the accelerator key. That is, the character is underlined, and, when the user presses the accelerator key, the action associated with the ITEM executes.

A MENU accelerator key requires the alt key to take effect, whereas an ITEM accelerator key does not require the alt key, but does require that the ITEM is currently displayed. See Adding a Hot Key below for another method of invoking your MENUs and ITEMs.


In the Use property, type a Field Equate Label.

A Field Equate Label has a leading question mark (?), and you should make it descriptive. For example, ?FileOpen shows at a glance the intended purpose of this ITEM: to open a file.

You refer to an ITEM within source code by its Field Equate Label.


In the Message property, type the MSG attribute contents.

This message text displays in the status bar (if enabled) when the user highlights this MENU or ITEM.


In the HelpID property, type either a help keyword or a context string present in a .HLP file.

If you fill in the HelpID for a MENU or an ITEM, when the user highlights the MENU or ITEM and presses F1, the help file opens to the referenced topic. If more than one topic matches a keyword, the search dialog appears.

The HelpID property (HLP attribute) takes a string constant specifying the key for accessing a specific topic in a Windows Help file. This may be either a Help keyword or a context string.

A Help keyword is a word or phrase indexed so that the user may search for it in the Help Search dialog.

When authoring a Windows Help file, you indicate a keyword with the ‘K’ footnote. A Help context string is the arbitrary string which uniquely identifies each topic page for the Windows Help Compiler. When creating the Help file, the ‘#’ footnote marks a context string. Many help authoring tools do all these tasks for you.

When referencing a context string in the Help ID field, you must identify it with a leading tilde (~).


RIGHT-CLICK on the ITEM just added, and select Actions from the popup menu.




Choose Call a Procedure from the When Pressed drop-down list.

The procedure you specify executes when the user selects this ITEM. You may specify parameters to pass and standard file actions (insert, change, delete, or select) if applicable (Clarion’s Procedure templates understand and carry out the requested file actions). Or you may initiate a new thread. The procedure appears as a "ToDo" item in your Application Tree (unless you named a procedure that already exists).

When you START a procedure on its own thread, the procedure and its window operate independently of other threads in the same program; that is, the end user can switch focus between each execution thread at will. These are "modeless" windows.

If you don’t initiate a new thread, the program behavior depends on whether the procedure’s window has the MDI attribute. A non-MDI child window on the same thread as its parent, blocks access to all other threads in the program. This is an "application modal" window. When the application modal window closes, the other execution threads are available again. An MDI child window on the same thread as its parent, blocks access only to its parent window. When the MDI child window closes, its parent window regains focus.

This is one way to add functionality to your ITEM. You may also add functionality by choosing Run a Program from the drop-down list, by embedding source code, or by typing an STD ID in the STD ID field. STD IDs give your application Standard Windows Behavior (SWB) for common actions such as File/Open and Edit/Cut, Copy, and Paste. See Implementing Standard Windows Behavior.

After following these steps, you have a single MENU called File, with a single ITEM called Open. To add other ITEMS to the MENU, repeat steps 6 through 12. To add a second MENU, press the button. Use the arrow buttons to move it if needed.


To finish the menu and return to the Window Designer, Save and Close button to exit the Menu Editor.


Adding Special Characters to your Menu

You can embed tabs and other special characters within your menu text. To embed special characters (such as the tab character) in your menu text:


Press the Save and Close button again to exit the Window Designer.. In the Window Designer Editor dialog, press the Edit as Text button.



This opens the Text Editor to the WINDOW declaration for this procedure. When you embed special ASCII characters in your WINDOW declaration, you must edit the source code directly, because the Window Designer doesn’t recognize the ASCII delimiter characters (<,>).


In your ITEM text, type <n> where you want the character to appear.

Where n is the ASCII code for the character. The brackets (<,>) tell the Clarion compiler to insert the ASCII characters specified within. For example:



Press the Accept button to save your changes.

You can embed special characters within POPUP menu text and MESSAGE text by using the ASCII delimiters (<,>).


Implementing Standard Windows Behavior

There are some menus and commands that you see in almost every windows program. For example, Cut, Copy, and Paste. Clarion provides an easy method for implementing these standard actions in your application menus—with the Std ID field on the Menu Editor dialog.

To specify a standard action for your menu ITEM, enter one of the equates listed below in the Std ID field. Clarion automatically implements the command using standard windows behavior; you do not need any other support for it in your code. The standard equate labels and their associated actions are also contained in the \LIBSRC\EQUATES.CLW file.



Opens Printer Options Dialog


Closes active window


Reverses the last editing action


Deletes selection, copies to clipboard


Copies selection to clipboard


Pastes clipboard contents at the insertion point


Deletes selection


Arranges child windows edge to edge


Arranges child windows edge to edge


Arranges child windows edge to edge


Arranges child windows so title bars are visible


Arranges iconized child windows


Select child windows from a MENU


Opens .HLP file to the contents page


Opens .HLP file to the index


Opens Microsoft’s Help system.HLP file


Opens Microsoft’s Help Search .HLP file.


Menu Positions and Merging Behavior

The Position drop-down list lets you specify MENU and ITEM order priority when Clarion merges menus. Choose from:


Set normal merging order. In normal merging, Global selections precede Local selections.


Force the selected MENU or ITEM to the first position when merging menus. This adds the FIRST attribute to the MENU or ITEM statement.


Force the selected MENU or ITEM to the last position when merging menus. This adds the LAST attribute to the MENU or ITEM statement.


The following two property Flags let you specify whether or not your menu can be merged, and right justification of selections displayed on the action bar:

Do Not Merge

To never merge this MENUBAR with other MENUBARs, check this box. This is available only for the MENUBAR. See NOMERGE in the Language Reference for more information.


To right justify the selected MENU, check this box. This is available only for MENUs on the action bar. Nested MENUs (subMENUs) cannot be right justified. Checking this box displays the selected MENU, and all MENUs after the selected MENU, at the far right of the action bar.


Adding Hot Keys

A hot key is very similar to an accelerator key. A hot key or hot key combination allows the end user to immediately display a MENU, or execute the action associated with an ITEM, without mouse clicking, and without displaying the menu that contains the ITEM. Customarily, hot keys take the form of CTRL + character, or CTRL + SHIFT + character. To add a hot key:


1. Press the Key property ellipsis (...) button to select the hot key combination.

This opens the Input Key dialog. Use this dialog to add the KEY attribute to your MENU or ITEM. The KEY attribute specifies a "hot" key or key combination.

2. From the Input Key dialog, specify the hot key or key combination by pressing the desired key or keys.

The keys you press appear in the Key field, and are supplied as the parameter to the KEY attribute for this menu item.