|Data Definition||Panel Painting|
The second step in developing your Dialog System application is defining panels for your screenset. Panels are rectangular working areas on the screen in which data fields and keystrokes are displayed. The size of a panel can be up to 80 characters wide and 25 lines long. You can include text anywhere on the panel; however, data fields will overwrite panel text and if you choose to have a border, it will overwrite any text on the border.
You use these panels to display the data fields you previously defined to be used in an application. The following chapters describe how to paint panels and place data fields and groups onto them.
This chapter describes:
To enter the Panels menu, press F3=panels from the Main menu. The Panels menu is displayed, which provides options for defining a new panel or selecting a previously defined panel (see Figure 5-1).
Figure 5-1: Panels Menu
You use this function to mark the area that a panel will occupy when you create a new panel. To mark an area, move the cursor to the position on the screen you wish to place your panel, then press the F2=mark/unmark toggle from the Panels menu. The current cursor position is then marked.
Use the <left-arrow>, <right-arrow>, <up-arrow> and <down-arrow> keys to extend the marked area from the original marked position in a rectangular fashion to the desired size. Panels can be any size from one character by one line up to 80 characters by 25 lines. When you have completed marking the area, press Enter=define-panel. You are then prompted to name the panel. Type in a name of up to eight characters, then press Enter. The Panel Painting menu is displayed, where you can enter text and data (see the chapter Panel Painting for details).
You can alter the size and position of the panel later, so you don't have to get the dimensions correct the first time. To cancel the mark function, press F2 again before completing the panel definition.
Pressing F3=panel-list from the Panels menu displays a popup
list containing the names of panels previously defined for the current
screenset and the Panel List menu as shown in Figure 5-2.
Figure 5-2: Panel List Menu
Pressing Enter from the Panel List menu enables you to work on a selected panel. To select a particular panel to work on, use the <up-arrow> and <down-arrow> keys to position the selection bar on the name of the panel, then press Enter. You can then edit the panel using the other facilities available on the Panel List menu.
Pressing F3=show-panel from the Panel List menu displays the chosen panel on the screen so that you can view it and consider its relationship to other panels.
This function is only for viewing purposes; to edit a panel, you must select as described in the previous section.
Up to 50 panels can be visible on the screen, but only one of these can be active at one time. Because Dialog System itself uses panels, for example to display Dialog System menus, you might find that your practical limit to the number of visible panels is less than 50.
Pressing F4=unshow-panel from the Panel List menu removes the chosen panel from the visible screen. Remember the panel is still in the screenset, just no longer visible on the screen.
This identifies which panel is invoked first at run time. You can select any of the panels to be this first panel. Position the selection bar on the desired panel name and press F5=select-first-panel from the Panel List menu. The selected panel name is marked with > and < symbols.
Pressing F6=copy-panel from the Panel List menu creates a new panel that is a copy of the panel identified by the selection bar, including all of its text, attributes and dialog. When you use this facility, you are prompted for a name for the new panel. Type in the desired name and press Enter. The new panel is automatically copied and its name included on the panel list.
The new panel becomes the current panel and is listed on the status line. The new panel occupies the same space on the screen as the original. If required, you can move it elsewhere, resize it, or change it using the facilities provided on the Panel Maintenance menu described in the chapter Panel Painting.
Pressing F8=delete-panel from the Panel List menu enables you to delete a panel from the screenset. Position the selection bar on the name of the desired panel, and press F8. The following prompt appears:
Delete panel. Are you sure? Y/N
Press "Y" to delete the selected panel or "N" to cancel the delete operation. If the selected panel is referenced in any dialog, you are prevented from deleting it.
The Relocate Panel facility enables you to adjust the order of the panel list by relocating the panels individually in the list. Position the selection bar on the desired panel name, and press F9=relocate-panel from the Panel List menu. The following prompt appears:
Use the <up-arrow> and <down-arrow> keys to position the selection bar where you want to insert the relocated panel, and press Enter. Once you have relocated a panel, the Panel Painting menu is displayed (see the chapter Panel Painting for details on the use of this menu).
Pressing F4=CUA-action-bar-and-pull-downs from the Panels menu enables you to create, generate, and maintain an action bar with associated pulldown menus. An action bar is a single line of menu text where each word defines a subsidiary menu name. A pulldown menu is the subsidiary menu that is displayed when an item on the action bar menu is selected.
Defining an action bar is a quick way to produce a menu that you can use to invoke other panels. To use an action bar menu, you simply place the cursor on the menu name and press Enter, or type the letter of the associated mnemonic. It is easy to create an action bar in Dialog System. You only need the following steps:
The panel associated with the action bar must be selected as the "first" panel (see the section Select First Panel (F5) earlier in this chapter).
To define an action bar, press F4, and the Action Bar Definition menu shown in Figure 5-3 is displayed. Only a limited number of the menu options are initially available; others appear after certain stages of action bar definition.
Figure 5-3: Action Bar Definition Menu
Pressing F2=action-bar from the Action Bar Definition menu either enables you to define a new action bar, or amend an existing action bar. When you define a new action bar, a series of menus are displayed that you can use to specify the position, size and name of the new action bar. When you amend an existing action bar, the Amend Action Bar menu, shown in Figure 5-8 is displayed. For information about amending a action bar, see the section Accept Text (Enter) later in this chapter.
When you define an action bar, it is often useful to have the panel associated with the action bar visible on the screen. This makes it easier to position and size the action bar. Typically, the action bar occupies the entire top line of the screen, and the associated panel occupies the remainder of the screen. You must position the action bar more that eight rows from the bottom of the screen, and define it as at least 14 characters wide to allow space for the automatically generated exit and help entries. Don't worry about getting the positioning perfect initially, because you can reposition the bar later on.
The first menu, shown in Figure 5-4, enables you to specify the position of your action bar.
Figure 5-4: Action Bar Definition - Position
Use the <down-arrow>, <left-arrow>, <up-arrow> and <right-arrow> keys to position the cursor at the desired location on the screen and press Enter. The second menu then appears (Figure 5-5), enabling you to define the width of your action bar.
Figure 5-5: Action Bar Definition - Width
With the cursor position now marked, use the <right-arrow> and <left-arrow> or the <right-arrow>| and |<left-arrow> keys to mark the width of the action bar and press Enter, which displays a third menu as shown in Figure 5-6.
Figure 5-6: Action Bar Definition - Name
At the prompt, type in a name of up to eight letters for the action bar and press Enter. The first four characters of the action bar name are used when the pulldown windows are generated. The generated name is in the format AAAA-nnn where AAAA are the first four characters of the action bar name, and nnn is the pulldown window's generated number.
After you enter a valid name, the action bar is displayed, with the automatically generated exit and help entries. The Action Bar Entry menu and popup panel then appear, as shown in Figure 5-7.
Figure 5-7: Action Bar Entry Menu
This panel contains the following fields:
|Action Bar Text||Where you specify the text of your action bar entry. This text must not contain spaces. You can specify entries until you have filled all available space in the action bar. If there is no free space in the action bar, you can only change or delete existing entries.|
|Mne||Where the mnemonic assigned to the action bar text appears. This identification letter is automatically assigned but you can change it if desired. You must choose a unique mnemonic. "X" and "H" are reserved mnemonic characters.|
This confirms the action bar text. Enter the text in the Action Bar Entry panel and press the Enter key from the Action Bar Entry menu. The menu name appears on the action bar with its mnemonic displayed in reverse video attribute. The action bar text list remains on the screen so you can specify subsequent entries until either there is no more free space, or you insert a blank entry, or you press the Escape key.
To change the mnemonic, press the <right-arrow>| key to move the cursor into the Mne field. Overtype the existing entry and press Enter.
When you have completed all of your text entries, press Enter and the Amend Action Bar menu appears, as shown in Figure 5-8.
Figure 5-8: Amend Action Bar Menu
When you invoke this menu, the action bar is reformatted to position any free space in the area before the help and exit entries. The selection cursor highlights the current entry, or the free space if there are no action bar entries. The exit and help entries are mandatory and you cannot change or reposition them; therefore, you cannot move the selection cursor onto these entries. If there are no entries and no free space exists in the action bar, the selection cursor does not appear.
When you leave this menu, the exit and help entries are reformatted to appear immediately after the last user-defined entry. Any free space is placed at the end of the action bar following the help entry.
To use the facilities on the Amend Action Bar menu, position the cursor over the required action bar entry and press Enter before you select the desired function.
Pressing F2=insert-before-entry from the Amend Action Bar menu prompts you to enter a new action bar entry before the highlighted entry.
Pressing F3=insert-after-entry from the Amend Action Bar menu prompts you to enter a new action bar entry after the highlighted entry. If this is the last entry, you can insert additional entries until all of the free space is filled.
Pressing F4=delete-entry from the Amend Action Bar menu enables you to delete the current entry from the action bar together with its specified pulldown menu. Press "Y" to delete the entry at the following prompt:
Delete entry? Y/N?
After you delete the entry, the action bar is reformatted.
Pressing F5=relocate-entry from the Amend Action Bar menu displays a menu to enable you to relocate the highlighted entry elsewhere in the action bar. Move the selection cursor to the desired location on the action bar and at the prompt select F2=insert-before or F3=insert-after to relocate the entry (see Figure 5-9).
Figure 5-9: Relocate Entry Menu
Pressing F2=insert-before from the Relocate Action Bar Entry menu relocates the selected entry before the highlighted entry.
Pressing F3=insert-after from the Relocate Action Bar Entry menu relocates the selected entry after the highlighted entry.
Pressing F6=position-bar from the Amend Action Bar menu enables you to reposition the action bar elsewhere on the screen. You are prevented from moving the bar to a point where any of its pulldown windows are not completely visible.
Use the <up-arrow>, <down-arrow>, <right-arrow> and <left-arrow> keys to position the action bar in the desired location, and press Enter.
Pressing F7=alter-size from the Amend Action Bar menu enables you to expand or contract the width of the action bar. You cannot contract the bar to a point where text is lost. As you alter the size, the bar is reformatted.
Use the <right-arrow> and <left-arrow> keys to resize the bar, and press Enter.
Pressing F8=action-bar-name from the Amend Action Bar menu enables you to rename the action bar. At the prompt, type over the existing action bar name with the new name and press Enter.
Pressing Enter from the Amend Action Bar menu returns you to the Action Bar Definition menu, where you can amend the text of the current action bar.
Pressing Escape from the Amend Action Bar menu finalizes the definition of the action bar and reformats it to place any free space at the end. Then the action bar pulldown windows for any user-defined entry are generated. Remember that the exit and help pulldown menus are automatically generated because they require specific formats; however, you can amend the entries in these menus. All pulldown menus automatically have the text "Esc=cancel" at the bottom; this is a system requirement that you cannot alter. You return to the Action Bars menu.
Pressing F4=save from the Action Bars menu saves the action bar into the current screenset. Remember you must still save the current screenset.
Pressing F6=generate from the Action Bars menu generates Dialog System panels and associated dialog into the current screenset. Once they are generated, these are just normal panels and you can edit them using the normal panel editing functions.
The generated dialog handles all movement along the action bar and selection from the pulldown menus when that dialog is invoked at run time. However, to use the action bar, you must add dialog to the application panel associated with the action bar, to push the current screen and go to the action bar panel. The action bar must also be shown as part of the associated panel's initialization procedure (P000).
Add the following dialog to the associated application panel (see the chapter Dialog for details on defining dialog):
key: PUSH Pnnn GOP action-bar-name
||is the key that switches from your application panel to the action bar.|
The parameter associated with the PUSH (Pnnn) specifies the procedure to be executed on return from the action bar. The next line, GOP (Go To Panel), goes to the action bar panel. The key used to switch from the application panel to the action bar should be the function key associated with the resume entry in the exit pulldown.
P000: SHP action-bar-name
This SHP (Show Panel) function is contained in the application panel's initialization procedure. This makes the action bar visible when the application panel is visible.
Pnnn: BPR start-procedure
This function causes the system to Branch to the Procedure (BPR) that is to be executed on return from the action bar. Depending on the value returned from the internal register, it should branch to the appropriate procedure, that is the start procedure determining the start of the procedure mapping (see the chapter Dialog for details of this register). For example, if the start procedure is P010 and a value of two is returned, then P011 is executed. If the register contains zero, then no branch takes place. The value returned in the register depends on the value associated with the selected pulldown entry at definition time. If nothing is selected, zero is returned in the register.
The action bar should be painted on the line above the application panel, because when control is passed back to a panel via the POP function, Dialog System refreshes the panel. If the action bar panel were painted on the top line of the application panel, the action bar panel would be hidden.
Pressing F9=initialize from the Action Bars menu enables you to clear the action bar definitions. To delete this action bar, type in "Y" at the prompt. However, to remove the definition from the current screenset, this action bar must saved.
Pressing Enter from the Action Bars menu displays the Amend Pulldown menu (see Figure 5-10), which enables you to specify or change the contents of a pulldown window. A pulldown window must consist of at least one entry (when generated, the entry corresponds to the associated action bar text).
Figure 5-10: Amend Pulldown Menu
Pressing F2=insert-before-entry from the Amend Pulldown menu prompts you to enter a new pulldown entry before the current entry. The pulldown list remains on the screen so you can specify subsequent entries until either the pulldown reaches the bottom of the screen, or you insert a blank entry, or you press the Escape key.
Pressing F3=insert-after-entry from the Amend Pulldown menu prompts you to enter a new pulldown entry after the current entry. The pulldown list remains on the screen so you can specify subsequent entries until either the pulldown reaches the bottom of the screen, or you insert a blank entry, or you press the Escape key.
Pressing F4=delete-entry from the Amend Pulldown menu deletes the current entry from the pulldown, then reformats the menu. The pulldown must contain at least one entry in addition to the "Esc=Cancel" entry.
Pressing F6=pull-down-name from the Amend Pulldown menu enables you to specify the name of the current pulldown. The name entered is used in the generating phase as the generated panel name. Remember that the generated name is in the format AAAA-nnn, where AAAA are the first four characters of the action bar name, and nnn is the pulldown window's generated number. When you amend this name, it is advisable to select a name that does not exist elsewhere in this screenset and avoid any possible conflict during the generation phase. If any conflict does occur, you are prompted to rename the pulldown.
Pressing <left-arrow> from the Amend Pulldown menu moves the cursor to the previous pulldown window or, if the current pulldown is the first on the action bar, to the help pulldown window.
Pressing <right-arrow> from the Amend Pulldown menu moves the cursor to the next pulldown window or, if the current pulldown is the last one on the action bar, to the first pulldown window.
Pressing Enter from the Amend Pulldown menu displays the Pulldown Entry Text menu and panel, which enable you to specify or amend a pulldown menu entry (Figure 5-11).
Figure 5-11: Pulldown Entry Text Menu
This panel contains the following fields:
|Pull down entry text||The text for your pulldown menu. This text can contain spaces.|
|Mne||The mnemonic associated with this pulldown menu. This is generated automatically but you can override it by typing over the existing character.|
|Return||This is the value returned from the internal register to the application panel when this pulldown entry is selected. The return value can be in the range 1 to 999.|
|F.Key||This enables a "quick key" to be associated with the pulldown entry by assigning a function key to it. This function key is active in the action bar as well as the pulldown and is a quick way of selecting the entry, instead of entering the pulldown and selecting the entry. The function key must be unique within the action bar and pulldowns.|
Pressing Enter from the Pulldown Entry Text menu confirms the text of the pulldown entry. When you have entered the text, the mnemonic, and the return value as desired, press Enter. You are returned to the Amend Pulldown menu.
Pressing F10=Key/Key+Mouse from the Action Bars menu toggles to generate additional dialog that allows the mouse to be used to control the menu bar and the drop down menus when the application is run.
You need to use a CALLOUT program, dsactbar.cbl, which is supplied with Dialog System. Amend it to include a special copyfile, created by Dialog System at CUA generation time, called screenset-basename.cua. The source file, dsactbar.cbl, is clearly documented to show where the copyfile is to be inserted. This file can hold as many copyfiles as you want, so that this single program can cater for many screensets with mouse controlled CUA menus.
Generating CUA menus for mouse control does not alter the keyboard control that is normally supported; the two interfaces coexist.
Although the mouse support code and dialog is automatically created for supporting the mouse once the top level CUA menu has been selected, you must add a small piece of code to allow the top level menu itself to be activated by the mouse.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
|Data Definition||Panel Painting|