Step 1: Creating a New Winform

Description of the Application

The application you develop in this tutorial writes to the Car sample data source. If you do not have write access to Car, consult with the database administrator.

You build an application user interface, that is, a Winform, that looks like the following:

The Country and Car fields appear at the top of the screen. Below these two fields, a grid displays multiple rows of the Model, BodyType, Dealer_Cost, and Retail_Cost stack columns.

You can press PF1 and PF2 to scroll through the Country and Car values. Inside the grid, you can use scroll bars or function keys to scroll the data backward (PF7) and forward (PF8).

How to Open the Painter

To open Maintain's Winform Painter, you enter MPAINT at the FOCUS prompt.

You can provide the FOCEXEC name that displays the Winforms you want to paint. The syntax is:

MPAINT procedure_name

For the purposes of this tutorial, do not supply the Maintain procedure name.

Try it now: Enter MPAINT at the FOCUS prompt.

mpaint

The Open Maintain dialog box appears.

If your screen does not display scroll bars similar to the ones in the Open Maintain dialog box shown in Naming the Procedure, or if the check boxes in subsequent screens do not look like the one in the screen shown in System Setup Dialog Box, exit the Winform Painter. Follow the instructions in Adjusting Winform Appearance to specify the desired appearance.

If your screens appear similar to the screen captures, you can skip to The Painter Dialog Boxes.

Adjusting Winform Appearance

Reference:

Different terminals and terminal emulators process screen information in different ways. Some configurations support dashed lines instead of solid Winform borders. For solid borders, SBORDER must be set to ON in your FOCUS session. (See the Developing Applications manual for information about SET commands.)

You can change the Winform Painter's terminal emulator setting to display the options that appear on the screen.

Top of page

Reference: System Setup Dialog Box

Try it now: To change the terminal emulator setting, at the FOCUS command line, enter:

EX MSETUP

or, from the File menu while in the Painter, select Preferences and then Terminal.

FOCUS displays the following System setup dialog box and an Example window:

Five terminal emulations and an option for customized emulation are available. The Example window in the upper right-hand corner of the screen provides examples of the check box and the scroll bar for the currently selected emulation.

Try it now: To select your terminal emulation:

Position the cursor in the appropriate box and press any key.
Press Enter. (To cancel what you have entered, press PF3.)
When you are finished, press PF4.

The box you selected displays an asterisk (*).

If you choose Custom, the Custom character set dialog box opens:

Initially, your cursor is on the input area for the left square bracket. You can type a value or press PF1 to select from a list. When you change the characters, decimal (dec) and hexadecimal (hex) values change automatically.

Try it now: To reset the characters to the original settings:

Check the Reset button.
When you are finished entering your customized characters, press PF4.
To display a screen with mapping information, press PF1.
When the Left square bracket dialog box opens, to select a value from this box, move your cursor to the appropriate character and press Enter.

Top of page

Reference: The Painter Dialog Boxes

To change any of your choices later in the session, you can use the Painter's File and Forms menus.

Dialog boxes request information about a task or supply information. After you specify options, you click a button to carry out an action.

When the dialog box opens, the cursor is on the first option.

To move to another option, press the Tab key to move forward, or press the Shift+Tab keys to move backward.
The PF3 key usually cancels an action or signals No.
The PF4 key usually signals OK or Yes.
When a dialog box offering several options has a default option, pressing Enter always selects the default.

Naming the Procedure

A Maintain procedure that displays Winforms is composed of a pair of files: a Maintain procedure (either FOCEXEC or MAINTAIN) file and a WINFORMS file. Each pair has the same member name: this is the name of the procedure. The Open Maintain dialog box asks you to enter this name. If the Maintain procedure and WINFORMS files do not exist, the Painter creates them.

The Open Maintain dialog box includes a combo box (a combination of the entry field and the list box) and command buttons.

Entry Field. An entry field is a field in which you type information. If a field permits a value longer than the field's width, you can scroll the field to enter more text. PF10 scrolls left and PF11 scrolls right.

List Box. A list box displays a list of choices. To select an item from the list, position the cursor on the desired item and press Enter.

If the list is longer than the box, you can use the scroll bars to move through the list.

To scroll:	Move the cursor to:
One line up or down	The up or down arrow on the vertical scroll bar and press Enter.
One screen up or down	Just above or below the arrow on the vertical scroll bar and press Enter.
One position left or right	The right or left arrow on the horizontal scroll bar and press Enter.
One screen left or right	Just to the right or left of the arrow on the horizontal scroll bar and press Enter.

When you scroll through a list, the scroll box moves up, down, left, or right to indicate where you are in the list.

Combo Box. When an entry field appears together with a list box, the combination is known as a combo box. You can enter a value by selecting it from the list box or by typing it directly into the entry field.

Note: The combo boxes that you create inside the painter (by selecting Combo box from the Objects menu) are different. In these, you cannot type directly into the entry field.

Command Buttons. Click a command button to initiate an immediate action, such as issuing or canceling a command.

You click a button by positioning the cursor on the button and pressing Enter. If the button has a shortcut key, it is faster to press the associated key. (A shortcut key is a function key assigned to a button. When a button has a shortcut key, the key name is usually displayed next to the button name.)

In the Open Maintain dialog box, you can name the procedure you wish to open by either:

Typing the name of the Maintain procedure in the entry field and pressing Enter (or moving the cursor to the OK button and pressing Enter).
Adding FOCEXEC is optional.

Pressing F2 also works if the Maintain procedure does not already exist. If it exists and you press F2, you are asked if you want to use the existing Maintain procedure.
Pressing Tab to position the cursor in the list box, then moving the cursor to the desired procedure and pressing Enter.
If the list of Maintain procedures is too long to fit in the box, you can use search criteria to narrow the list. For example, if you want to see Maintain procedures that start with the letter C, enter C*.

If you do not see the Maintain procedure, you can press PF8 to scroll forward, PF7 to scroll backward, or use the scroll bars. As you scroll through the list, notice that the scroll box indicator moves to show where you are in the list.

If you press PF3 (or click the Cancel button), you exit the Painter.

Try it now: Type CARSPECS in the entry field and press Enter (or move the cursor to the OK button and press Enter) as you will be creating a new procedure named CARSPECS.

Selecting Master Files

After you enter the name of the Maintain procedure, the Select Master Files dialog box appears. This is where you select the data sources you access in this Winform. (This is the same dialog box that appears if you chose Select Master from the File menu.) For the purposes of this tutorial, you entered a name of a Maintain procedure that does not exist. When the Maintain procedure exists, you are not prompted for the data source(s).

When the dialog box first opens, your cursor is positioned so you can type the name of the file. You can either type the name (the word MASTER is optional), or you can select from the list box. After you press Enter, the data source name appears in the box to the right of the list of available Master Files. You may select up to 16 data sources.

The data sources selected determine which fields are displayed in the Field dialog box that is used to add fields to the form.

If you add a data source you do not want, you can remove it by moving the cursor to the data source name and pressing PF9. Note that PF9 does not delete the name from the list. To remove several data sources, you can press PF12 (or click the Reset button) to clear all changes.

If your procedure will not access a data source (for example, a menu), you need not select one. In that case, when the dialog box opens, press PF4 or the OK button. If you press PF3 (or click the Exit button), you return to the Open Maintain dialog box.

When you have finished adding data sources, press PF4 or move the cursor to the OK button and press Enter.

For the purposes of this tutorial, you access the Car sample data source.

Try it now:

Select CAR from the combo box on the left.
Your screen should look similar to the following.
Press PF4 to indicate that you have finished or move the cursor to the OK button and press Enter.