Clarion Community Help

Creating a Browse Window

In this chapter, you'll create a browse window similar to the one created for you by the Application Wizard. The Application Generator uses the same templates, which generate the same basic code'but doing it this way, you'll have a chance to “do it from scratch.” This shows you just how much the Wizards do for you, and how you can do it all yourself, too. You'll start with the Customer browse window.

Starting Point:

The LCLESSON.APP should be open in the Application Editor (Tree).

Creating the Customer Browse Window

You recall from the Getting Started lessons that the Application Wizard created a window for the Customer table Browse procedure that looked like this:

Now you'll create a similar one using the Browse Procedure template:

Select the procedure type for the BrowseCustomers procedure

1.DOUBLE-CLICK on BrowseCustomers in the Application Tree.

2.Select the Defaults tab and highlight the Browse with Update and Select Procedure template in the Select Procedure Type dialog, then press the Select button.

The Procedure Properties dialog appears.

Make the window resizable

1.In the Procedure Properties dialog, select the Extensions tab.

2.In the Extensions dialog, press the Insert button.

3.Highlight WindowResize in the Select Extension dialog, then press the Select button.

This Extension template generates code to automatically handle resizing and re-positioning all the controls in the window when the user resizes the window, either by resizing the window frame, or by pressing the Maximize/Restore buttons.

4.Press the OK button to close the Window Resize template dialog.

Edit the Browse procedure window

1.In the Procedure Properties dialog, select the Window tab.

2.Press the Designer button to load the Window Designer.

3.CLICK on the window's title bar, and open the Properties Pad (if not already opened). If not opened press the F4 key to open it.

4.In the Properties Pad dialog, type Browse Customers in the Title property:

5.Select Resizable from the FrameType drop list property.

6.Locate the MaximizeBox property and set to TRUE.

These last two steps allow the user to resize the window at runtime.

Populating and Formatting a List Box Control

The List Box Formatter allows you to format the data in the list.

Prepare to format the list box

1.RIGHT-CLICK on the list box in the window, then choose List Box Format… from the popup menu. Press the Add Field button .

The Select Column dialog appears. This provides access to the tables defined in the data dictionary. The Tables list displays all the tables selected for use in this procedure in a hierarchical arrangement (the Table Schematic), which includes the browse list box control.

You can call this dialog at any time by pressing the Add Field button.

Select the table and columns to place in the browse list box control

1.Highlight the <;ToDo> item below the File-Browsing List Box and press the Add button.

2.Highlight the Customer table in the Select dialog, then press the Select button.

This adds the table to the Table Schematic in the Select Column dialog, which now lists the table and its columns.

3.With the Customer table that you just highlighted selected, press the Change button.

4.Highlight KeyCustNumber in the Change Access Key dialog and press the Select button.

This is important, because it sets the display order for the rows in the list. If you don't specify a key, the rows appear in (sort of) whatever order they were added to the table (also called “Row Order”).

5.Highlight COMPANY in the Columns list, then press the Select button.

This brings you into the List Box Formatter with the selected column added to the list. The tabs on the right allow you to format the appearance of the column highlighted in the list on the left.

Apply special formatting to the first column

1.In the Property list in the lower right pane, locate the Right Border and Resizeable properties and set them to TRUE:

This adds a resizable right vertical border to the column at runtime.

2.Set the Header Indent property to 2 to slightly indent the heading text and verify that the DataIndent property is already set at 2.

Populate the second column

1.Press the Add Field button.

2.Highlight FIRSTNAME in the Select Columns list, and press the Select button.

3.In the Property list in the lower right pane, locate the Right Border and Resizeable properties and set them to TRUE if not already set.

The List Box Formatter automatically “carries forward” these formatting options from the last column you added, making it very simple to add multiple columns with similar formatting options. In this case, clearing these check boxes deletes the column divider between this and the next column, which will be the LastName column.

Populate the third column

1.Press the Add Field button.

2.Highlight LASTNAME in the Select Columns list, and press the Select button.

3.In the Property list in the lower right pane, locate the Right Border and Resizeable properties and set them to TRUE.

This once again adds the resizable column divider between this and the next column.

Populate the fourth column

1.Press the Add Field button.

2.Highlight ADDRESS in the Select Columns list, and press the Select button.

3.In the Property list in the lower right pane, locate the Right Border and Resizeable properties and set them to TRUE.

Group some columns

1.Press the Add Group button.

2.Highlight the new group as shown here:

As the list box begins to grow in size, you can resize the List Box Formatter as needed to view additional elements.

By creating a new group, in which you'll place the address information, you can add a group header. This appears above the column headers, and visually links the data in the columns beneath. Notice that, as you add columns and make changes you can see the effects of your changes in the sample list box at the top of the List Box Formatter dialog.

3.Type Address Info in the Text property.

This provides the text for the group header. Any columns appearing to the right of this one will be included in the group, until you define another group.

As you add columns, the List Box Formatter continually updates its sample window (at the top) to show you how your list will appear.

4.Highlight the ADDRESS column:

Populate the fifth column

1.Press the Add Field button.

2.Highlight CITY in the Columns list, and press the Select button.

3.In the Property list in the lower right pane, locate the Right Border and Resizeable properties and set them to TRUE.

Populate the sixth column

1.Press the Add Field button.

2.Highlight STATE in the Columns list, and press the Select button.

3.In the Property list in the lower right pane, locate the Right Border and Resizeable properties and set them to TRUE.

Populate the seventh column, and exit the List Box Formatter

1. Press the Add Field button.

2. Highlight ZIPCODE in the Columns list, and press the Select button.

At this time, feel free to use the WYSIWYG display at the top to resize any of the columns as needed.

3. Press the OK button to close the List Box Formatter.

Adding the Tabs

When the Application Wizard created this procedure it had tab controls that changed the list's sort order depending on which tab was selected. Therefore, we'll add this functionality right now to show how easy it is to accomplish!

Add the Property Sheet and the first tab

1.CLICK on your window's title bar to place the white “handles” on your window design.

2.Place the mouse cursor directly over the handle on the lower edge, and DRAG it down to resize the window.

3.CLICK and drag the LIST and BUTTONS to select all of them, then use your mouse or arrow keys to move all controls down as shown here:

4.If the Controls Toolbox is not already opened, open it now by selecting View Toolbox from the IDE Menu (or simply press CTRL + ALT + X)

5.CLICK and DRAG the SHEET control in the Controls toolbox above and to the left of the List box to place the property sheet and one Tab control.

6.DRAG the “white handle” at the bottom left-hand corner so that it appears just below and to the left of the Insert button.

7.DRAG the “white handle” at the bottom right-hand corner so that it appears just below and to the right of the Close button.

This resizes the property sheet so that it appears as though the list box and buttons are on the tab. In fact, they are not, and we don't want them to be, since we want all these controls to be visible no matter which tab the user selects.

8.The list and button controls appear to be hidden. RIGHT-CLICK on the SHEET control JUST TO THE RIGHT OF THE TAB CONTROL, and select Send To Back from the popup menu.

9.CLICK just below the “Tab1” text for the first tab in the sheet.

10.In the Properties Pad, type by Customer Number in the Text property, and then press the TAB key.

This changes the tab's text. This tab text can be anything, but naming the key also names the sort order it will display.

Add the rest of the tabs

1.With the Properties Pad still opened for the TAB control, locate and click on the Select Sheet link shown below:

2.With the SHEET control selected and active in the Properties Pad, press the Add Tab link.

3.Here's another way to select a control in your active window. In the Properties Pad, select the ?TAB2 control in the drop list as shown here:

4.Type by Company Name in the Text entry of the Property toolbox, then press TAB.

5.With the Property Pad still opened for the ?TAB2 control, locate and click on the Select Sheet link.

6.With the SHEET control selected and active in the Properties Pad, press the Add Tab link.

7.In the Property Pad, select the ?TAB3 control in the drop list

8.Type by Zip Code in the Text entry of the Property toolbox, then press TAB.

Hiding the Buttons

The toolbar buttons defined on the Frame procedure actually just tell hidden buttons in the Browse procedure to do what they normally do. Therefore, when you are designing a Browse procedure without using the Wizards, you do need to have the update buttons on the screen, but the user does not have to see them at runtime.

1.RIGHT-CLICK on the Close button in the sample window then choose Properties… from the popup menu.

2.Set the Hide property to TRUE.

This adds the HIDE attribute to the control so you won't see it on screen at runtime. Of course, you can still see it in the Window Designer.

3.RIGHT-CLICK on the Select button then choose Properties….

4.Set the Hide property to TRUE.

5.RIGHT-CLICK on the Delete button then choose Properties….

6.Set the Hide property to TRUE.

7.RIGHT-CLICK on the Change button then choose Properties….

8.Set the Hide property to TRUE.

9.RIGHT-CLICK on the Insert button then choose Properties….

10.Set the Hide property to TRUE.

Alternatively, you can select all of the buttons by pressing CTRL + CLICK, and then you can set the Hide property to TRUE for all selected button controls.

Move the buttons and resize the list

There's no need to waste the space these buttons (which the user won't see) occupy on the window, so we'll move them out of the way.

1.CLICK on the Select button then CTRL+CLICK on the Close, Insert, Change, and Delete buttons to select them all, then CLICK and drag the buttons up into the list box.

DRAGGING multiple controls at once allows you to move the controls while maintaining the relative positions of the controls within the group. Now we'll use the space we just gained to make the list longer.

2.CLICK on the list box then DRAG its bottom-center handle down to make the list longer.

Setting the Sort Orders

Now that the tabs are there, we need to tell the list box what alternate sort orders to use and when.

1.RIGHT-CLICK on the list box then choose Actions… from the popup menu.

2.Click on the Browse Box Behavior button.

The list box is actually a BrowseBox Control template that has been placed in the Browse Procedure template's default window design in the Template Registry. This means that it has associated prompts that tell it how to populate the list and what actions to perform.

The prompts that appear on the Actions tab come directly from the templates (in this case, the BrowseBox Control template). This is how you communicate to the templates exactly what code they need to generate to give you the behavior you ask for (and nothing else). These prompts, their meanings and uses, are all covered in this User's Guide and in the on-line help for each window in which they appear.

3.Select the Conditional Behavior tab.

4.Press the Insert button.

5.Type CHOICE(?Sheet1) = 2 in the Condition entry.

This sets the condition under which the alternate sort order will be used. This expression uses the Clarion language CHOICE function to detect when the user has selected the second tab on the sheet. The generated code will use this expression in a conditional statement that will change the sort order at runtime.

6.Press the ellipsis button (…) next to the Key to Use entry.

7.Highlight CUS:KeyCompany then press the Select button on the Select Key dialog.

Now, when the user selects the second tab, the BrowseBox Control template will generate code to switch to the key on the Company column. It doesn't need to know what to do for the first tab, because that always uses the Access Key we set in the Table Schematic.

8.Press the OK button.

9.Press the Insert button.

10.Type CHOICE(?Sheet1) = 3 in the Condition entry.

11.Press the ellipsis button (…) next to the Key to Use entry.

12.Highlight CUS:KeyZipCode then press the Select button on the Select Key dialog.

13.Press the OK button.

14.Press the OK button to close the ?List Prompts dialog.

Closing the Customer Browse

1.Choose Save and Close on the Window Designer's menu bar, and save your window changes if prompted to do so.

2.Press the Save and Close button in the Window Designer Editor dialog to close it.

3.Choose File Save, or press the Save button on the toolbar to save your work.

OK, What Did I Just Do?

Here's a quick recap of what you just accomplished:

Now that the first Browse procedure is complete, we'll go on and create its associated update Form procedure.

Click here to jump to the next lesson