Getting Started-2-Tier

The repository provides a development team with a central storage mechanism and access point for commonly used application objects and database-derived widgets. You can easily modify the contents of the repository and propagate changes to all application screens.

In this lesson you learn how to:

• Control user input by defining an edit mask.

• Edit a repository entry and propagate the changes from the repository to screens.

• Create a widget on the screen and copy it to a repository entry for later use.

  ---

1. If necessary:

   • Invoke the editor.

   • Reopen the dstslect.scr screen from client.lib.

   • Reopen the distributors repository entry: choose FileOpenRepositoRy EntRy and select distributors from the Open Repository Entry dialog.

You can apply an input filter to a widget so it conforms to specific data requirements, such as restricting the length of data or allowing only numeric input. Or, in the case of a telephone number, apply an edit mask so users have a visual cue as to what format is expected when entering data.

2. Select the phone single line text widget (next to the Phone label) on the distributors repository entry.
   

3. Under Input, set the Keystroke Filter property to Edit Mask.

   An Edit Mask subproperty appears, where you define the edit mask.

   In an edit mask, a character that is preceded by a backslash allows a data character to be entered in this position. A character that has no leading backslash is treated as a literal. For example, the string (\9\9\9) specifies to display open and close parentheses around three spaces in which the user can only enter digits, such as (415).

4. Define the Edit Mask subproperty as (\9\9\9)\9\9\9-\9\9\9\9.

   The widget displays ( ) - and accepts only numbers as input.

   

More About Input Filters

Panther provides built-in input filters to help guide user input and, at the same time, reduce validation requirements. Some input controls include:

• Digits-only—Allows entry of the digits 0 through 9 only.

• Alphanumeric—Allows entry of any digits, the letters a-z and a-Z, and the space character.

• Yes/No fields—Allows entry of the initial letters of "yes" and "no."

• Case style—Enforces upper-case, lower-case, mixed case conversion.

• Required data—Requires at least one non-blank character for validation to succeed.

• Minimum/maximum value specifications—Specifies a range of values.

• Various protection modes—Protects data from being cleared, or the field from receiving focus, thereby protecting it from data entry.

• Edit masks—Imposes a pattern of symbols or characters that limit the kinds of characters a user can type into a field.

• Regular expressions—Enforces or excludes a specific pattern of letters and/or numbers.

• Table lookups—Verifies input against a list of possible values.

You can set properties to enhance specific widgets—for example, using more descriptive label text or using a different font for data entry widgets. The following steps show how to set a variety of properties on different widgets. By setting these properties once in the repository, you ensure that they affect the entire application.

5. Select the Distrib_name label widget on the distributors repository entry.
   

6. Under Identity, change the Label property to Distributor.
7. Select single line text widget distrib_name.
8. Under Identity, change the Column Title property to Distributor.

   This property controls the label that appears within the grid widget.

9. Select label widget Ldistrib_id (Distrib_id).
10. Under Identity, change the Widget Type property to Dynamic Label.

    Dynamic label widgets have a broader scope of properties; therefore, they are more easily manipulated programmatically (more on this in the next lesson).

11. Under Geometry, set the Size to Contents property to Yes.

    This property lets the widget resize dynamically according to its label content. If the label changes at runtime, the widget size automatically adjusts. This feature is useful for labels that display a name or date whose length is variable.

Changes made to parent widgets in the repository are visible in child widgets on screens that are open in the editor when the repository entry is saved. To propagate changes to child widgets on other screens, open those screens in the editor, or run the utility binherit to propagate changes as a batch process to all the application's screens.

12. While the distributors@[Repository] entry has focus, choose FileSave.

    Notice that the mask you added to the phone widget in the repository entry appears in the phone grid member on the dstslect.scr screen. Also, the label next to the query field is updated, as is the column title in the grid widget.

More About Inheritance

When you import a table from a database, the text widgets in the resulting repository entry represent columns in the table. These widgets inherit database-related properties from the database. Like the screen wizard, you can use these widgets to build application screens by copying them from repository entry to screen. The result is an inheritance hierarchy of database to repository to screen (and service component). Also, the next time you use the screen wizard, these changes are implemented.

If changes in the database occur such as length specifications, the changed table can be reimported to the repository. These changes are automatically propagated to all application objects that are copies of those repository objects. Also, any custom attributes that you apply to repository objects, such as color, font specification, and validation, can also be defined and propagated to the screens that inherit from these widgets.

Importation and inheritance simplify application maintenance and facilitate the enforcement of a consistent look and feel to an application's interface.

13. Choose FileClosedistributors.

    The repository entry closes.

You can modify the behavior established by the screen wizard by writing your own procedure to carry out a particular action. For example, the dstslect.scr screen acts as a search or query screen for finding distributor records, so you might consider using a different screen for adding new distributors to the database. You can change the way the New button behaves through its control string, so it invokes a procedure that opens another screen for adding new records.

More About Control Strings and Control String Syntax

You can attach actions to widgets, menu items, and specific logical keys through control strings. Control strings are a shorthand notation for doing common tasks:

• Execute a function—A caret (^) precedes function names. It tells Panther to search for and execute the named function.

• Display another screen—Supply the screen name to tell Panther to search for and open the named screen, and close all other screens.

• Display another screen as a stacked or child window—An ampersand (&) precedes a screen name. It tells Panther to search for and open the named screen as a stacked window. A stacked window becomes the top window and is the only window that can have focus.

• Display another screen as a sibling window—A double ampersand (&&) precedes a screen name. It tells Panther to search for and open the named screen as a sibling of the calling screen. Users can bring focus to any window that is a sibling of the active window.

• Invoke a system command or program—An exclamation point (!) precedes commands. It tells Panther to invoke the specified operating system command.

14. Select the New button on the dstslect.scr screen.
    

15. Under Validation, change the Control String property from its inherited property value ^do_new to ^send_dst_data("NEW").
    

    When the user chooses the New button with this control string, Panther invokes the send_dst_data procedure and supplies NEW as an argument. Lesson 9 describes this procedure.

    The inheritance link no longer exists for this property, as indicated by the absence of reverse-video display.

More About Flexible Inheritance

You can override inherited values on individual properties. For instance, to enforce application standards, all application widgets can inherit colors and fonts from their parent widgets in the repository, but you can also define a font or validation routine for a child widget that differs from its parent. This breaks the inheritance link for the given property.

To reestablish inheritance for a property, select the property and choose the Inh button on the Properties window.

Create a push button that executes a procedure to send data from this screen to the dstord.scr screen, which you created in Module 2.

You can create widgets with either the Create menu or the Tool box. The next several steps show how to use the Tool Box.

16. If the Tool Box is not open:

    UNIX Choose ViewTool Box

    Windows Choose OptionsConfigure Toolbars. Select Create.

    

17. Choose CreatePush Button or
18. Click near the right side of the screen.

    A default-sized push button appears at the cursor position.

    

19. With the button selected, under Identity, set its Name property to order_pb.
20. Set the Label property to Orders.

    The button now has this label:

    

21. Set the Default/Cancel property to Default.

    A push button defined as the Default button can be activated at runtime by pressing Enter.

22. Resize the Order button to match other buttons on the screen:

    • Ctrl+click on one of the other buttons (such as the View button) whose size you want to match. This adds the button to the selection set as the selection set's dominant widget.

    • With both buttons selected, choose EditSizeAdjust Both.

      The Orders button resizes to the same height and width as the dominant selection.

Attach a control string to the push button so it performs the desired action. At run time, the control string executes when the Order button is clicked—in this case, it calls the send_dst_data procedure and supplies an argument of SELECT.

23. Select the Orders push button.
24. In the Control String property (under Validation), enter ^send_dst_data("SELECT").
25. Choose FileSave.

    The dstslect.scr screen is saved to the client.lib library.

You can copy commonly used objects from a screen to a repository, thereby providing the entire development team with application objects and code and facilitating consistent behavior and appearance across the application. In this case, you copy the Orders push button from the screen to a repository entry. An inheritance link is automatically established between the object and its parent in the repository.

26. Choose FileNewRepository Entry.

    The New Repository Entry dialog box opens.

    

27. Enter buttons as the name of the entry. Choose OK.

    An empty window with the name buttons@[Repository] opens in the workspace.

28. Select the order_pb push button on the dstslect.scr screen and drag it to the buttons repository entry.
    

29. Return to the dstslect.scr screen and select its order_pb push button again. Check the Inherit From property (under Identity). It is now set to inherit its property values from the buttons repository entry (buttons!order_pb).
30. Give the buttons repository entry focus and choose FileSave.

    The buttons repository entry is saved to the open repository.

31. (Optional) Choose FileClosebuttons.

    ---

You applied global and local changes to specific widgets, performing these tasks:

• Set properties on widgets in the repository and then propagated those changes to the widgets that inherit from the repository.

• Selectively changed properties at the screen level to override inherited property values.

• Created a prototype push button and then copied it to a repository entry where it can be used and reused by all members of the development team.

What did you learn?

You learned:

• How to define input filters and control what the user sees and can do in the application interface.

• You can copy application objects to and from repository entries. In either case, the repository objects are the parents, and the child objects on the application screens inherit from them.

• How to write a control string to alter the default behavior of wizard-generated push buttons.