| **Navigation:**  [[welcome to my product .htm|User's Guide and Tutorials]] > Guided Tour of Working in Clarion >====== 8 - Creating an Update Form ====== | [[lc creating a browse.htm|{{btn_prev_n.gif|Previous page}}]][[welcome to my product .htm|{{btn_home_n.gif|Return to chapter overview}}]][[lc copying procedures.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

**Creating an Update Procedure**

In the last chapter, we formatted the Customer Browse procedure's list box and added tab controls to change the sort order. To finish the basic procedure, we name the Update procedure. This is the procedure that handles the action for the Insert, Change, and Delete buttons.

**Starting Point:**

**The LCLESSON.APP file should be open.**

**Add a "ToDo" procedure**

1.Highlight //BrowseCustomers// in the Application Tree dialog, then press the **Properties** {{propbut.jpg|propbut.jpg}} button.

The //Procedure Properties// dialog appears. There are actually three ways to get to this dialog (use the method that suits the way you work):

oHighlight the procedure then press the **Properties** button.

oDOUBLE-CLICK the procedure in the Application Tree dialog.

oRIGHT-CLICK the procedure and select **Properties** from the popup menu.

oClick on the **Actions** button to open the //Browse Customers ' Properties// dialog.

{{browsecustomersprops.jpg|BrowseCustomersProps.jpg}}

2.Type //UpdateCustomer// in the **Update Procedure** entry box at the bottom of the //Procedure Properties// dialog.

This names the procedure to update the rows displayed in the browse. The new procedure appears in the Application Tree as a "ToDo."

3.Press the **OK** button to close the //Browse Customers ' Properties// dialog, and then press the **Save and Close** button to close the //Procedure Properties// dialog.

Notice that you didn't have to start a new execution thread for the update procedure. You want it to run on the same thread as the browse, so that the end user can't open a form window to change a row, then activate the browse window again, and open another form on the same row. In other words, you don't want a user trying to change the same row twice at the same time!

**Creating the Update Form Procedure**

The Update Procedure should use the Form Procedure template to create a procedure that the end user can use to maintain a row. It should provide a prompt and entry control for each column in the row.

__**Select the procedure type for UpdateCustomer.**__

1.DOUBLE-CLICK on //UpdateCustomer// in the Application Tree dialog.

2.Choose the **Defaults** tab, Highlight the //FORM (Add/Edit/Delete)// template, then press the **Select** button.

The //Procedure Properties// Window appears.

3.Press the **Actions** button.

{{updateactions.jpg|UpdateActions.jpg}}

Notice that this dialog looks different than the Splash, Frame, or Browse //Procedure Properties// dialogs, because the prompts vary for each type of Procedure template. The User's Guide and on-line help describe the customization options available on each //Procedure Properties// dialog.

4.Press **OK** to close the //Update Customer ' Properties// dialog.

5.Open the **Data / Tables Pad** to name the table the Form will update. If not already opened, press the F12 key, or select **View** {{blttria.jpg|BLTTRIA.jpg}} **Data / Tables Pad** from the IDE Menu.

6.Highlight the <;ToDo> just under the //Update Record on Disk// entry and press the **Add** button.

{{fsp1.jpg|FSP1.jpg}}

7.The //Select a Table //dialog appears. Highlight the //Customer// table in the //Select// dialog, then press the **Select** button.

__**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 //Allow controls to be resized with window// dialog.

__**Edit the Window Properties**__

1.In the //Procedure Properties// dialog, press the **Window** tab.

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

3.CLICK in the window's title bar, then open the //Properties Pad// (if not already opened ' remember the F4 key?).

4.Select //Resizable// from the **FrameType** property.

{{update2.jpg|Update2.jpg}}

5.Set the **MaximizeBox** property to //TRUE//.

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

**Populating the Columns**

The default window design contains three controls for you already. The "OK" button will close the dialog, accepting the end user's input and writes the Customer table row to disk. The "Cancel" button closes the form without updating. The string control provides an action message to inform the end user what action they are taking on the row.

Placing the columns in a window is called populating it.

1.Choose **Window Designer** {{blttria.jpg|BLTTRIA.jpg}} **Populate **{{blttria.jpg|BLTTRIA.jpg}} **Multiple Columns**.

This displays a dialog containing all the columns from all the tables specified in your procedure's Table Schematic. These columns are all ready to populate onto your window design.

2.First, select the CUSTOMER table, and then DOUBLE-CLICK on //CustNumber// in the //Select Column// dialog then move the cursor over the window design.

The cursor changes to a crosshair and a "little book" which indicates the column comes from the data dictionary.

3.CLICK near the upper left corner of your window design.

This places both the data entry control and its associated prompt. These controls default to whatever you specified in the data dictionary for the column.

4.DOUBLE-CLICK on //Company// in the //Select Column// toolbox, and then move the cursor to where you want your control to appear, and CLICK.

5.DOUBLE-CLICK on //FirstName// in the //Select Column// toolbox, and then move the cursor to where you want your control to appear, and CLICK.

6.DOUBLE-CLICK on //LastName// in the //Select Column// toolbox, and then move the cursor to where you want your control to appear, and CLICK.

7.DOUBLE-CLICK on //Address// in the //Select Column// toolbox, and then move the cursor to where you want your control to appear, and CLICK.

8.DOUBLE-CLICK on //City// in the //Select Column// toolbox, and then move the cursor to where you want your control to appear, and CLICK.

9.DOUBLE-CLICK on //State// in the //Select Column// toolbox, and then move the cursor to where you want your control to appear, and CLICK.

10.DOUBLE-CLICK on //ZipCode// in the //Select Column// toolbox, and then move the cursor to where you want your control to appear, and CLICK.

11.Press **Cancel** in the //Select Column// toolbox to return to the Window Designer.

{{tipbox.jpg|TipBox.jpg}}

The sequence of steps above can also be accomplished directly via the Data / Tables Pad! Simply DRAG a control from the Pad and DROP it on to the window. It's that easy, try it!

**Moving and Aligning Columns**

For a professional look, we need to move these columns around and align the sides and bottoms of all the columns in the screen.

__**Move the columns to their approximate positions.**__

1.CLICK on the //State// entry control.

2.SHIFT+DRAG the //State// entry control to the left, closer to its prompt.

SHIFT+DRAG "constrains" the control's movement to the plane of its first movement (either horizontal or vertical).

3.CTRL+CLICK on the //State// prompt.

When you CTRL+CLICK on a control, the previously selected control's handles turn blue while the newly selected control's handles are red. You now have two controls selected.

4.Move the //State// entry control and prompt (CLICK and DRAG on either of the two selected controls) up and to the right of the //City// controls.

Once multiple controls are selected, you can move them as a group the same way you would move one individual control.

5.CLICK on the //ZipCode// entry box.

6.SHIFT+DRAG the //ZipCode// entry box to the left, closer to its prompt.

7.CTRL+CLICK on the //ZipCode// prompt.

8.Move the //ZipCode// entry box and prompt up and to the right of the //City// and //State// controls.

You may need to make the window a little wider to accomplish this.

9.CLICK on the //LastName// entry box.

10.SHIFT+DRAG the //LastName// entry box to the left, closer to its prompt.

11.CTRL+CLICK on the //LastName// prompt.

12.Move the //LastName// entry box and prompt up and to the right of the //FirstName// controls.

__**Align the columns to their final positions**__

{{aligntoolbar.jpg|AlignToolbar.jpg}}

The Window Designer has an //Alignment// toolbar (shown above) that contains the same set of alignment tools that are also available through the **Window Designer** > **Format** menu.

1.CLICK on the first prompt in the upper left corner.

This should be the //CustNumber// prompt. Its handles should appear when you CLICK it.

2.CTRL+CLICK on the four prompts immediately below the first.

As you CTRL+CLICK on each control in turn, the previously selected controls' handles turn blue while the newest selected control's handles are red. The control with the red handles provides the "base point" for the alignment operation. All the other selected controls are aligned in relation to the control with the red handles.

3.Press the **Align Left** button {{alignleft.jpg|AlignLeft.jpg}} (the top left button) in the //Alignment// toolbar.

The controls all line up along their left edges, based on the position of the last item selected (the one with the red handles).

{{alignlefts.jpg|AlignLefts.jpg}}

{{tipbox.jpg|TipBox.jpg}}

To identify the controls in the Alignment toolbar, simply place the mouse cursor over the control and wait half a second for the tool tip to appear.

4.Press the **Spread Vertically** button {{spreadvertical.jpg|spreadvertical.jpg}} in the floating //Align// toolbox.

The controls all evenly spread themselves between the top and bottom controls selected.

5.CLICK on the first entry control (this should be the //CustNumber// string control).

6.CTRL+CLICK on the entry controls immediately below it to select them all.

7.RIGHT-CLICK and choose **Align Left** from the popup menu that appears.

Here is yet another way to get to the alignment tools. The alignment popup menu appears only when you have multiple controls selected.

8.RIGHT-CLICK and choose **Spread Vertically** from the popup menu that appears.

This should align all the data entry controls with their respective prompts that we already spread vertically.

9.CLICK on the //LastName// entry control.

10.CTRL+CLICK on the three controls to its left (its prompt, the //FirstName// entry control and prompt).

11.Choose **Align MIddles** from either the Alignment toolbar or the RIGHT-CLICK popup alignment menu.

This aligns the controls in a neat row.

There is one more way to select multiple controls in the Window Designer: Lasso them.

12.Place the mouse cursor slightly above and to the left of the first control in the bottom row (this should be the //City// prompt).

13.CTRL+CLICK and drag slightly down and to the right until the box outline surrounds all five controls to the right (the prompts and controls for //City//, //State// and //ZipCode//) then release the mouse button.

The red "handles" appear on the //ZipCode// entry control and the blue "handles" on the other controls. This is the "lasso" technique.

14.Choose **Align Middles** from either the floating Alignment toolbar or the RIGHT-CLICK popup alignment menu.

15.Use the **Align Middles** tool to align the //CustNumber//, //Company//, and //Address// entry boxes with their respective prompts.

The window should now look something like this:

{{lcl8form.jpg|LCL8Form.jpg}}

The form window is almost done. Now we will add a browse list box for the related Phones table rows.

{{blk2blue.jpg|blk2blue.jpg}}

**Adding a BrowseBox Control Template**

Control templates generate all the source code required to create and maintain a specific type of control (or set of controls) on your window. All the entry controls we just placed on this window are simple controls, not Control templates, because they do not need any extra code to perform their normal function. Control templates are only used when a specific control needs extra functionality that the "bare" control itself does not provide. For example, the OK and Cancel buttons are both Control templates'the OK button's Control template saves the row to disk, while the Cancel button's Control template has all the "cleanup" code necessary to cancel the current operation.

Now you will place a //BrowseBox// Control template that displays all the rows from the //Phones// table that are related to the current //Customer// row.

__**Place the Control Template**__

1.If not already opened, select **View** {{blttria.jpg|BLTTRIA.jpg}} **Control Templates **from the IDE Menu.

2.In the //Control Templates// dialog, highlight the //BrowseBox// Control template, then DRAG to the window area.

The cursor changes to a DROP cursor.

3.CLICK just below the City entry box to place the control.

The //Select Column// dialog appears, ready for you to choose the table this BrowseBox will display.

4.Select the //<;ToDo>// item below the //File-Browsing List Box// and press the **Add** button.

5.Highlight the //Phones// table in the //Select a Table// dialog, then press the **Select** button.

6.Highlight the //Phones// table in the //Select Column// dialog, then press the **Change** button.

7.Highlight //Pho:CustNumberKey// in the //Change Access Key// dialog, then press the **Select** button.

{{selectcolumn.jpg|SelectColumn.jpg}}

__**Place the Phones table columns in the List Box Formatter**__

1.Highlight //CustNumber// in the //Select// //Columns// list, then press the **Select** button.

2.Resize the Browse Box to fit between the entry column and OK button as shown here:

{{lcl8form2.jpg|LCL8Form2.jpg}}

3.RIGHT-CLICK on the Browse Box, and select **List Box Format** from the popup menu.

The //List Box Formatter// now appears, ready for you to choose the rest of the columns to display.

4.Select //Center// from the Data property list's **DataJustification** drop list:

{{justify.jpg|Justify.jpg}}

This changes the data justification from the default value (which is Right justification for numeric values).

5.Set the **Right Border** and **Resizable** properties to //TRUE//.

This adds a right border to the column and allows the user to resize the column width at runtime.

6.Press the **Add Field** {{addfieldlbf.jpg|AddFieldLBF.jpg}} button.

7.Highlight //PhoneNumber// in the //Columns// list, then press the **Select** button.

8.Set the **Right Border** and **Resizable** properties to //TRUE//. Set the **Width** property in the **Header** property list to //52//.

9.Press the **Add Field** {{addfieldlbf.jpg|AddFieldLBF.jpg}} button.

10.Highlight //Extension// in the //Columns// list, then press the **Select** button.

11.Set the **Right Border** and **Resizable** properties to //TRUE.// Set the **Width** property in the **Header** property list to //56//.

12.Press the **Add Field** {{addfieldlbf.jpg|AddFieldLBF.jpg}} button.

13.Highlight //PhoneType// in the //Columns// list, then press the **Select** button.

14.Set the **Width** property in the **Header** property list to //56//.

You may also want to give the left align columns an offset of 2, so the data is not touching the left border.

15.Press the **OK **button to close the List Box Formatter.

__**Set up the control template's row range limits**__

1.RIGHT-CLICK the list box you just placed, and select **Actions** from the popup menu.

2.Press the **Browse Box Behavior** button.

3.Press the ellipsis (**...**) button next to the **Range Limit Field**. The //PHO:CustNumber //column is auto-selected, as it is the only component in the list.

4.Choose //File Relationship// from the **Range Limit Type** drop list.

5.Press the ellipsis ( ... ) button next to the **Related file** column then select //Customer// from the //Select Table// dialog.

This identifies the Customer table as the related table. These steps limit the rows displayed in the list box to only those rows related to the currently displayed Customer table row.

{{lcphonerangelimit.jpg|LCPhoneRangeLimit.jpg}}

6.Press **OK** to close the //Browse Box Behavior// dialog. Press **OK** again to close the //Prompts// dialog.

**Adding the BrowseUpdateButtons Control Template**

Next we'll add the standard Insert, Change and Delete buttons for the list box control.

__**Place another type of Control Template**__

1.First, resize your window again to make it a little taller, and make some room between the list box and buttons at the bottom:

{{lcl8form3.jpg|LCL8Form3.jpg}}

2.In the** Control Templates **Pad, highlight the //BrowseUpdateButtons// Control template, then DRAG to the window area.

The cursor changes to a DROP cursor.

3.CLICK below the left corner of the list box.

The **Insert**, **Change**, and **Delete** buttons appear. Remember, these are the buttons that will allow the toolbar buttons to function, so they must be present in the window design. They do not have to be visible to the end-user, so you can hide them if you choose. However, since this BrowseBox is placed on an update Form procedure, for this application we'll leave this set of //BrowseUpdateButtons// visible. This will allow the user to use either set of buttons. The toolbar update buttons will only function for this list when the list box has focus'not when the user is inputting data into any other control'so keeping these buttons visible will ensure that the user can easily maintain the Phones table rows.

You may wish to center these buttons under the list box.

__**Specify Edit in Place for Phones Update**__

1.RIGHT-CLICK on the **Delete** button and choose **Actions** from the popup menu.

2.Check the **Use Edit in place** box.

Setting the Actions for one button sets them for all three buttons in the set, because they all belong to the same Control Template. Since the Phones table is a small table with just a couple of columns, there's no need for a separate Update Procedure.

3.Press the **OK** button.

4.Press the **Save and Close** button to close the Window Designer.

5.Press the **Save and Close** button to close the Window Designer Editor.

6.Choose **File** {{blttria.jpg|BLTTRIA.jpg}} **Save**, or press the **Save** button {{savebutton.jpg|savebutton.jpg}} on the tool bar.

**OK, What Did I Just Do?**

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

| {{blueck.jpg|blueck.jpg}} | You created a new Form Procedure'without using a wizard. |
| {{blueck.jpg|blueck.jpg}} | You learned just how quickly you can populate data entry controls onto a Form by using the Columnbox toolbox. |
| {{blueck.jpg|blueck.jpg}} | You learned to use the Window Designer's tools to move and align controls. |
| {{blueck.jpg|blueck.jpg}} | You used the List Box Formatter again and created a range limited list box. |
| {{blueck.jpg|blueck.jpg}} | You learned how to implement edit-in-place for simple updates which don't require a Form procedure. |

Now you've created all the procedures necessary to maintain both the //Customer// and //Phones// tables. Next, we'll create the procedures that will maintain the //Products// data table.

[[lc copying procedures.htm|Click here to jump to the next lesson]]