User Tools

Site Tools


lesson_5_exploring_the_menu_frame_procedure.htm
Navigation:  User's Guide and Tutorials > The Application >====== Lesson 5 - Exploring the Menu/Frame Procedure ====== Previous pageReturn to chapter overviewNext page

This topic:

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

purple.jpg 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 BLTTRIA.jpg 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:

1.Global selections with FIRST attribute

2.Local selections with FIRST attribute

3.Global selections without FIRST or LAST attributes

4.Local selections without FIRST or LAST attributes

5.Global selections with LAST attribute

6.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.

TipBox.jpg

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.

TipBox.jpg

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.

MenuEditorAccess.jpg

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.

MenuEditor1.jpg

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.

TipBox.jpg

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.

blk2blue.jpg

Creating Your Application's Menus

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

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

2.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.

3.Press the Add new menu NewMenu.jpg 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.

4.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.

5.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.

6.Press the Add new item NewItem.jpg 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.

7.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.

NoteBox.jpg

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.

8.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.

9.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.

10.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.

TipBox.jpg

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 (~).

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

MenuActions2.jpg

12.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 NewMenu.jpg button. Use the arrow buttons to move it if needed.

13.To finish the menu and return to the Window Designer, Save and Close button SaveClose.jpg 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:

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

EditAsText.jpg

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 (<;,>).

2.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:

ITEM('Cut<;9>Ctrl+X'),USE(?CutText),KEY(CtrlX),STD(STD:Cut)

3.Press the Accept button to save your changes.

TipBox.jpg

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.

STD:PrintSetup Opens Printer Options Dialog
STD:Close Closes active window
STD:Undo Reverses the last editing action
STD:Cut Deletes selection, copies to clipboard
STD:Copy Copies selection to clipboard
STD:Paste Pastes clipboard contents at the insertion point
STD:Clear Deletes selection
STD:TileWindow Arranges child windows edge to edge
STD:TileHorizontal Arranges child windows edge to edge
STD:TileVertical Arranges child windows edge to edge
STD:CascadeWindow Arranges child windows so title bars are visible
STD:ArrangeIcons Arranges iconized child windows
STD:WindowList Select child windows from a MENU
STD:Help Opens .HLP file to the contents page
STD:HelpIndex Opens .HLP file to the index
STD:HelpOnHelp Opens Microsoft's Help system.HLP file
STD:HelpSearch 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:

Normal

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

First

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

Last

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.

Right

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.

Mouse clicks may be used as hot keys; however, mouse clicks cannot be specified by clicking the mouse. For mouse clicks, check the corresponding check box(es). For example, to execute the Open command when the user double-clicks, check the Left Button box and the Double Click box.

The ESC, ENTER, and TAB keys may be used as hot keys, but they cannot be specified by pressing them. For these keys, press the ellipsis (…) button and type “esc,” “enter,” or “tab.”

3. Press the OK button to return to the Menu Editor .

4. To display the hot key combination (or any other text) as right-justified menu text, type the text in the Menu Text field.

For example, if you set the hot key as CTRL+h, type CTRL+h in the Hot Key Menu Text field. Then, each time the end user uses the menu, the right-justified text reminds her that the menu choice can be invoked with the ctrl+h keystrokes.

Other Menu Behavior'Disabling and Toggling

The following two “Flag” properties let you disable a selection, and set up an ITEM as toggle switch.

Disable

To disable a MENU or ITEM (dim the text and make it unavailable to the user), set this property to TRUE. This adds the DISABLE attribute to the MENU or ITEM statement.

TipBox.jpg

The Disable box is handy when you incorporate modality into a program'that is, when one type of child window does not support the same commands another type does. For the type that doesn't support the command, disable the ITEM rather than omitting it. This will avoid confusing the user with menu ITEMs that disappear and reappear depending on which window is active.

Check

To create an on/off toggle for a selected ITEM, set this property to TRUE. The ITEM should have a numeric variable in the Use property. The variable should be declared using one of the data dialogs, or in embedded source. See Creating Your Application's Menu above. The Menu Editor adds the CHECK attribute to this ITEM.

With the CHECK attribute, when the user selects the item for the first time, the item is “on,” the USE variable's value is one (1), and a check mark appears beside the item. When the user selects the item a second time, the item is “off,” the USE variable's value is zero (0) and no check mark is displayed. You should add source code to control the application's behavior depending on the state of the USE variable.

Changing the Appearance of Menus

The General and Color property categories lets you change and set how your menu and menu items look. These property settings give your menus a more professional look and allow you to conform to existing design standards.

MenuAppearance.jpg

Icon

To add an icon to a menu item, either select an icon from the drop list or press the ellipsis button to lookup the file name. This entry is not available when the MENUBAR is selected. You can use any image file Clarion supports, but keep in mind that large images may not give you the desired effect. For best results, choose an image that is 32×32 bits.

TipBox.jpg

When making Web based applications, use GIF images.

Color

Enter a valid color value in any of the following entries to add the COLOR attribute to your MENU declaration.

See ..\LIBSRC\EQUATES.CLW for a list of valid color equates.

TextColor

To apply a specific color to the menu text, type a valid color equate in this entry, or press the ellipsis (…) button to select a color from the Color dialog.

BackColor

To apply a specific color to the background, type a valid color equate in this entry, or press the ellipsis (…) button to select a color from the Color dialog.

SelectedTextColor

To apply a specific color to the menu's selected text, type a valid color equate in this entry, or press the ellipsis (…) button to select a color from the Color dialog.

SelectedBackgroundColor

To apply a specific color to the background of the menu's selected text, type a valid color equate in this entry, or press the ellipsis (…) button to select a color from the Color dialog.

LeftOffset

Enter a numeric value to make the menu or menu item offset from the far left. By default, there is a small space (for icons) and this setting can be used to remove this space or increase it.

The value is in dialog units (Special fractional measurement units, based on the system font. Windows automatically calculates the horizontal measurement unit in fourths of the average system character width, and the vertical in eighths of character height. The net effect supports a proportional placement of dialog box elements regardless of the resolution Windows is running in).

Width (AT)

To specify the width of your menu or menu item, choose the desired width value. Choose from:

Default

Setting to TRUE instructs Windows to set the width of the menu or menu item to a default value which will depend on the user's system.

Value

To set a specific width, mark the Default property FALSE and specify a value. This sets the width of the window in dialog units.

Height (AT)

To specify the height of your window, choose the desired height value. The choices are the same as for Width.

TextFont

To set a font property for this menu or menu item, press the ellipsis button and select one. If you choose a font on a menu item, then the menu item will appear in the font style you select.

If a menu, then all menu items under it inherit the font. If a MENUBAR, then all menus and menu items inherit the font selected.

TipBox.jpg

Choose a font that could be installed on any machine. Otherwise, you will have to ship the font in your installation procedure.

Managing Your Menus

NewSeparator.jpg

Press this button to add a separator bar after the highlighted MENU or ITEM.

TipBox.jpg

Separator bars can provide the user with a visual cue that a group of ITEMs on the menu perform related functions.

DeleteMenu.jpg

Press this button to delete the highlighted MENU or ITEM. If you delete a MENU, all nested ITEMs and MENUs, and its associated END statement are also deleted.

MoveUpDown.jpg

To move the highlighted MENU or ITEM up or down in the menu list, press the appropriate button. When moving a MENU, all ITEMs and MENUs within it and its associated END statement move also.

blk2blue.jpg

Toolbars

With a simple action in the Window Designer, you can add a toolbar to any window. You can place any controls on a toolbar, but the ones you will probably use the most are command buttons, check boxes, radio buttons, and drop-down listboxes. As with menus, Clarion automatically merges global and local toolbars in certain situations.

Merging Toolbars

Global and Local Toolbars

The TOOLBAR structure declares the tools displayed for an APPLICATION or WINDOW. On an APPLICATION, the TOOLBAR defines the Global tools for the program. Global tools are active and available on all MDI child windows unless the MDI child window's TOOLBAR structure has the NOMERGE attribute.

If you specify the NOMERGE attribute on the APPLICATION's TOOLBAR, there are no global tools; the tools are local and are displayed only when no MDI child windows are open.

NoteBox.jpg

To merge toolbars, the APPLICATION's toolbar AT width must be less than the APPLICATION's frame width. In the Procedure Properties dialog, press the Window's ellipsis (…) button, then set the TOOLBAR's width (third AT attribute) equal to the X position plus the width of the rightmost toolbar control.

MDI Windows

On an MDI window, the TOOLBAR defines tools that are automatically merged with the Global toolbar. Both the Global and the local MDI window's tools are active while the MDI child window has input focus. Once the window loses focus, its specific tools are removed from the Global toolbar. If the NOMERGE attribute is specified on an MDI window's TOOLBAR, the tools overwrite and replace the Global toolbar.

Non-MDI Windows

On a non-MDI WINDOW, the TOOLBAR is never merged with the Global menu. A TOOLBAR on a non-MDI window always appears with the window itself, and not on the parent window.

Merging Order

When an MDI window's TOOLBAR is merged into an application's TOOLBAR, the global tools appear first, followed by the local tools. The toolbars are merged so that the fields in the window's toolbar begin just right of the position specified by the value of the width parameter of the application TOOLBAR's AT attribute. The height of the displayed toolbar is the maximum height of the “tallest” tool, whether global or local. If any part of a control falls below the bottom, the height is increased accordingly.

Toolbar Merging Checklist

Application Properties

1.Set the NOMERGE property of the APPLICATION's toolbar to TRUE.

2.TOOLBAR's width property must be less than APPLICATION's width.

In the Properties Pad dialog for the TOOLBAR control, set the TOOLBAR's Width property (third AT attribute) equal to the X position plus the width of the rightmost toolbar control.

Child Window Properties

1.Set the NOMERGE property of the WINDOW's toolbar control to FALSE.

2.Set the MDI property to TRUE.

Adding Toolbars

The following describes how to add a toolbar to a window, then how to add a control to the toolbar. The starting point is the Window Designer, open to an empty window:

1.In the Controls Toolbox, select the TOOLBAR control entry, and DRAG and DROP to the active window.

The Window Designer places a toolbar at the top of the window (gray rectangle).

2.To place a control on the toolbar, click on a control in the Controls toolbox, then click inside the toolbar in the target window.

This places the control in the toolbar. See Controls and Their Properties for more information on various controls.

TipBox.jpg

Use .ICO files that are 32 x 32 pixels for toolbar buttons. These larger .ICO files contain both the enabled and the disabled icon in the same file, rather than requiring a separate file. When creating a custom .ICO file for a toolbar button, place the image in the center of the icon file. Clarion automatically crops the icon image to fit the button size.

Next: Lesson 6 - Exploring the Browse Procedure

lesson_5_exploring_the_menu_frame_procedure.htm.txt · Last modified: 2021/04/15 15:57 by 127.0.0.1