In this lesson you set up the menus for the application. You:
Menus are separate objects that you create using the Menu painter. After you create a menu, you can attach it to as many windows as you want. You can create menus at any time during the application development process.
How long does it take?
About 30 minutes.
Where you are
Add menu scripts to trigger user events
Attach the new menu and run the application
The frame menu was created automatically by the Template Application wizard. The m_pbtutor_frame menu is the ancestor of all the other menus you work with in the tutorial. Changes you make to this menu are automatically propagated to descendant menus.
In the WYSIWYG (What You See Is What You Get) view of the Menu painter, you see menus as they appear when the application is running. In this tutorial, you use the WYSIWYG view to make changes to the application menus, but you can make the same changes from the Tree Menu view. You use the Properties view to change a toolbar button.
In this exercise you:
Now you modify the File cascading menu of the m_pbtutor_frame menu.
-
Double-click m_pbtutor_frame in the System Tree.
The Menu painter displays the menu associated with the MDI frame window in the application. Because m_pbtutor_sheet inherits from m_pbtutor_frame, changes you make to the frame menu are propagated to the sheet menu.
In the WYSIWIG view, the menu items appear across the top of the view. If a WYSIWYG view is not open, you can select it from the View menu in the Menu painter menu bar.
-
Click the File menu in the WYSIWYG view of m_pbtutor_frame.
When you click a menu item in the WYSIWYG view, its menu items appear just as they would at runtime.
If the File menu does not display its menu items
The File menu is selected when you display the WYSIWYG view. You might need to click one of the other menus (Edit, Window, or Help) and then click again on the File menu to display its menu items.
-
Right-click New under the File menu.
Select Edit Menu Item Text in the pop-up menu.
Click in the New field and replace &New with &Report. Press Enter.
You change the display name of the New menu item to Report. The menu name remains m_new and its purpose (to open new sheet windows) remains the same.
Define accelerator keys with the ampersand character
The character following the ampersand is used as an accelerator key (mnemonic) and appears with an underscore in the WYSIWYG display. In the runtime application, the user can access the File>Report menu by pressing Alt+F+R.
-
Make sure that &Report appears in the Text text box in the Properties view.
Click the Toolbar tab in the Properties view.
The toolbar item text is New, Open New Sheet. There is no selection in the ToolbarItemName box, so no toolbar button appears at runtime for the Report menu item. You do not add a toolbar button here, because you use the Report menu item to access cascading menu items rather than as a command to open a new sheet.
-
Click the Open menu item under the File menu in the WYSIWYG view.
Click the General tab in the Properties view.
Clear the Visible and Enabled check boxes on the General page of the Properties view.
You hide the Open menu item in all runtime menus. When you clear the Visible property, the WYSIWYG view displays the menu item with a dithered (broken) appearance. It is not visible at runtime. When you clear the Enabled property, the WYSIWIG view displays the menu item with a very faint and inverted relief appearance. If it is visible at runtime, the menu item will still be grayed out.
-
Click the Toolbar tab of the Properties view.
Clear the ToolbarItemVisible check box.
This prevents the toolbar button for this menu item from appearing in the frame menu toolbar (a button can be included in a toolbar even if its corresponding menu item is not visible or enabled).
-
Click Exit under the File menu in the WYSIWYG view.
The Toolbar page of the Properties view remains open. The ToolbarItemText and ToolbarItemName values change to show the values for the m_exit menu item.
The Help menu has three items, but only one, Help>About, is enabled. Now you enable the other menu items, using commented-out code that was provided by the Template Application wizard and the pbtutor.chm file in the Tutorial directory.
You call application Help topics with the ShowHelp function, passing it an enumerated value that identifies whether you want the Help contents or index to display, or a specific topic or keyword. ShowHelp can open Windows Help or compiled HTML Help (CHM) files.
-
Click the Help menu in the WYSIWYG view and then double-click the Help Index menu item.
You can double-click the Help Index item even though it is not currently enabled. The full name of the Help Index menu item, m_help.m_helpindex, displays in the Script view. It includes the m_help prefix to indicate that it is in the Help menu.
-
Select Clicked in the second drop-down box if it is not already selected.
-
Position the cursor in the line that contains the ShowHelp function and click the Uncomment button in the PowerBar.
Change myapp.hlp to pbtutor.chm:
ShowHelp ("pbtutor.chm", Index!)This displays the default topic in the Help file.
-
Select the Enabled check box on the General page of the Properties view for the m_helpindex menu item.
-
Repeat the preceding steps for the Search For Help On menu item using the following Show Help function.
ShowHelp ("pbtutor.chm", Keyword!, "")If the third argument contained a string that was a keyword in the Help file, the associated topic would display. Because the argument is an empty string, the Help Search window displays.
-
Select File>Save from the main PowerBuilder menu bar.
Select File>Close from the main PowerBuilder menu bar.
Where you are
Add menu scripts to trigger user events
Attach the new menu and run the application
Now you create a new menu that displays whenever the user opens an MDI sheet to look at customer or product information. The menu you create is a descendant of the m_pbtutor_sheet menu that was generated by the Template Application wizard.
The m_pbtutor_sheet menu inherits in turn from m_pbtutor_frame, but has some additional menu items enabled. In the menu you create, you add menu items that are not present in the ancestor menus.
In this exercise you:
By inheriting from the application sheet menu, you retain the sheet menu characteristics without modifying the ancestor menu. It is good practice to save the new menu immediately, then save it again after you modify it.
-
Click the Inherit button (
) in the PowerBar.
The Inherit From Object dialog box displays.
-
Make sure Menus is selected in the Objects of Type drop-down list box.
Select m_pbtutor_sheet in the Object list box and click OK.
PowerBuilder displays an untitled menu that has all the characteristics of m_pbtutor_sheet.
On the inherited sheet menu, the Window menu items are enabled to allow for tiling and cascading windows, just as they are for the m_pbtutor_sheet menu. These items are disabled on the m_pbtutor_frame menu.
Changes made to the MDI frame menu
If you click the File menu in the WYSIWYG view, you see that the first item is now Report. The Open item is dithered to indicate that it is not visible and is grayed to indicate that it is disabled. These characteristics were propagated through the inheritance chain from m_pbtutor_frame.
-
Select File>Save from the menu bar.
The Save Menu dialog box displays.
-
Type m_my_sheet as the menu name in the Menus box.
Type the following line in the Comments box:
New sheet menu for w_master_detail_ancestor and its descendants.
-
Click OK.
This names the menu. The prefix m_ is standard for menus.
The name you just assigned to the new menu displays in the title bar of the Menu painter workspace and the m_my_sheet menu appears in the system tree.
Next you add items to the Edit menu of the menu you just inherited from m_pbtutor_sheet. You use the WYSIWYG and Properties views.
-
Click the Edit menu in the WYSIWYG view for the new menu.
The list of Edit menu items appears just as it would in a runtime application. All items of the Edit menu are visible but disabled (they appear gray -- but not dithered -- in the WYSIWYG view).
-
Right-click a menu item under the Edit menu in the WYSIWYG view.
Select Insert Menu Item At End from the pop-up menu.
The cursor moves into a blank box that appears at the end of the Edit menu list.
-
Click in the box that appears at the bottom of the menu, and type - (hyphen). Press Enter.
The hyphen changes into a separator line. In the Properties view, the menu item name changes to m_0. Even the separator lines between menu items must have unique names. Other separator lines in the menu have a unique index number preceded by the prefix m_dash.
-
Clear the Enabled check box in the Properties view for the new separator line.
-
Right-click the new separator line in the WYSIWYG view.
-
Select Insert Menu Item At End from the pop-up menu.
-
Type &Insert in the box that appears under the new separator and press Enter.
The menu item name is set automatically to m_insert. If PowerBuilder displays a message that the default name is incorrect, it suggests an alternative name. If this occurs, click OK to accept the suggested name.
Alternative method of inserting menu item names
You can type &Insert in the Text box in the Properties view instead of typing it in the box that appears in the WYSIWYG view. In this case, you do not need to press Enter afterwards. First, however, you have to clear the Lock Name check box if the Name box is grayed (otherwise, the menu name does not reset to m_insert).
-
Type Insert a row in the MicroHelp box in the Properties view.
The new menu item is visible and enabled by default.
The text Insert a row displays in the MicroHelp line at the bottom of the application window whenever the user selects the menu item.
-
Repeat steps 5 and 6 for the following menu items:
You add Edit menu items for updating and deleting database records. Even though it is not enabled, the Undo item already uses the letter U as an accelerator key, so you should not use the same accelerator key for the Update menu item. Instead, you use the letter A for this purpose.
Now you add toolbar buttons for the menu items you just defined and then place them in a second toolbar.
-
Click the new Insert menu item in the WYSIWYG view Edit menu.
-
Click the Toolbar tab in the Properties view.
Type Insert in the ToolbarItemText box.
Type or select Insert! in the ToolbarItemName drop-down list.
This defines a toolbar button for the Insert menu item that uses the stock picture called Insert!. When the Show Text option in the runtime application is enabled for toolbars, the text Insert appears on the button.
-
Type or click to 1 in the ToolbarItemSpace spin control.
Type or click to 1 in the ToolbarItemOrder spin control.
Type or click to 2 in the ToolbarItemBarIndex spin control.
When you start a new toolbar for the added menu items, the Insert button will be the first item in this toolbar.
-
Click the new Update menu item in the WYSIWYG view Edit menu.
Make sure it is also displayed on the title bar in the Properties view.
-
Click the Toolbar tab if the Toolbar page is not already open.
Type Update in the ToolbarItemText box.
Type or select Update! in the ToolbarItemName drop-down list box.
This defines a toolbar button for the Update menu item that uses the stock picture called Update!. The button text is Update.
-
Type or click to 2 in the ToolbarItemOrder spin control.
Type or click to 2 in the ToolbarItemBarIndex spin control.
This will add the Update button after the Insert button in the new toolbar.
-
Click the new Delete menu item in the WYSIWYG view Edit menu.
Make sure it is also displayed on the title bar in the Properties view.
-
Click the Toolbar tab if the Toolbar page is not already open.
Type Delete in the ToolbarItemText box.
Type or select DeleteRow! in the ToolbarItemName drop-down list box.
This defines a toolbar button for the Delete menu item that uses the stock picture called DeleteRow!. The button text is Delete.
-
Type or click to 3 in the ToolbarItemOrder spin control.
Type or click to 2 in the ToolbarItemBarIndex spin control.
You add the Delete button after the Update button in the new toolbar.
-
Select File>Save from the PowerBuilder menu bar.
Where you are
> Add menu scripts to trigger user events
Attach the new menu and run the application
Now you add scripts to trigger user events from the sheet window menu bar. You added these user events in Modifying the Ancestor Window. The Menu painter should still be open for the m_my_sheet menu. If it is not, you can open it using the Open button in the PowerBar.
-
Select m_edit.m_insert in the first list box in the Script view
or
Double-click the Insert menu item in the WYSIWYG view.
The full name of the Insert menu item displays in the first list box of the Script view. It includes the m_edit prefix to indicate that it is in the Edit menu.
-
Select Clicked in the second drop-down box if it is not already selected.
Type these lines for the Clicked event:
w_master_detail_ancestor lw_activesheet lw_activesheet = w_pbtutor_frame.GetActiveSheet() lw_activesheet.EVENT ue_insert()
The first two lines determine which sheet in the MDI frame is currently active. The third line triggers the user event ue_insert for the active sheet.
-
Repeat steps 1 and 2 for the following menu items and scripts:
Menu name
Script for Clicked event
m_edit.m_update
w_master_detail_ancestor lw_activesheet lw_activesheet=w_pbtutor_frame.GetActiveSheet() lw_activesheet.EVENT ue_update()
m_edit.m_delete
w_master_detail_ancestor lw_activesheet lw_activesheet = w_pbtutor_frame.GetActiveSheet() lw_activesheet.EVENT ue_delete()
-
Select File>Save from the PowerBuilder menu bar.
PowerBuilder compiles and saves the menu scripts.
-
Click the Close button in PainterBar1
or
Select File>Close from the PowerBuilder menu bar.
Where you are
Add menu scripts to trigger user events
> Attach the new menu and run the application
Now you attach the new sheet menu and run the application again.
-
Double-click w_master_detail_ancestor in the System Tree.
If you cannot see the Properties view
Select View>Properties from the menu bar.
The menu listed in the MenuName box in the Properties view of the Window painter is still m_pbtutor_sheet.
-
Click the ellipsis button next to the MenuName box.
The Select Object dialog box displays.
-
Select m_my_sheet in the Menus list box and click OK.
This is the sheet menu you modified after inheriting it from m_pbtutor_sheet. It is now listed as the menu name in the Properties view.
-
Click the Save button in PainterBar1.
Click the Run button in the PowerBar.
The application login window displays.
-
Type dba in the User ID box.
Type sql in the Password box and click OK.
The database connection is established, and the MDI frame for the application displays. The File menu now includes a Report cascading menu in place of the New menu item. The Open menu item is no longer visible.
-
Select File>Report>Maintain Customers from the menu bar.
Notice that a second toolbar appears and the Edit and Window cascading menus include enabled menu items.
-
Select the Edit menu.
The Edit menu has the Insert, Update, and Delete options you added. These options do not function yet, because the DataWindow controls in the Customer window do not have DataWindow objects associated with them.
-
Select the Window menu.
Notice that a new menu item has been added for the sheet you just opened.
-
Select File>Report>Maintain Products from the menu bar.
A second MDI sheet opens. This sheet cascades relative to the first sheet. The menu bar does not change. That is because m_my_sheet is the menu for both w_customers and w_products.
-
Select the Edit menu.
Because the w_products window uses the m_my_sheet menu, the Insert, Update, and Delete options are also available when the Product window is open.
-
Select the Window menu.
Another menu item has been added for the second sheet you opened. The checkmark next to this menu item indicates that it is the active sheet.
-
Select File>Exit from the menu bar.
The application terminates and you return to the Window painter workspace.
-
Close the Window painter.
