Using the Editors

Chapter 23. Styles Editor

An essential component of a well-designed application is consistency in presentation and behavior. This consistency helps users learn and use the application more quickly and more reliably. Not surprisingly, the larger and more complicated the project, the greater the need and the difficulty of maintaining this consistency. The styles editor addresses this issue. It allows you to specify globally how an application will appear and behave when it uses the transaction manager commands.

The transaction manager applies a set of default classes and styles to your application screens. The styles editor is used to edit these default settings or to define new styles and classes.

This chapter explains how the default styles and classes are applied as well as how to create a new style or class.

Starting the Styles Editor

Invoke the styles editor by choosing ToolsStyles Editor. On opening the styles editor, Panther looks in all open libraries for the binary file called styles.sty (Figure 23-1 illustrates Panther's default styles file) and opens it. If the file isn't found, a new, untitled styles file opens. The styles.sty is distributed in the client library.

Figure 23-1 The styles editor opens the default styles.sty file.

The styles editor provides a workspace with up to five components:

Styles Editor window: A workspace area is divided into two parts: style definitions and class definitions, one for each transaction mode. Generally, you create new styles first. Then, you create a new class and assign the appropriate style for each transaction mode. You can have more than one working styles file open at once; however, an application can access only one styles file.
Styles Editor menu: Provides options to open and create style files and libraries, save style files in libraries, maintain style files under source control management, edit styles and classes, and view the properties set for the selected style.
Properties window: Displays the properties applicable to a selected style or class.
Widget List: Displays the styles, classes, and the styles associated with each transaction mode of the current styles file.

Transaction Modes

When an application calls a Panther transaction manager command, the transaction manager checks the current transaction mode and either changes the mode or reports an error if the current mode is invalid for the command. Since you can define a different style for each mode, the accessibility or appearance of widgets in your application screen can change as you change transaction modes.

Each transaction mode is represented in the styles.sty file. The transaction manager supports the following modes:

new

Mode where the user can enter new data. Saving new data typically generates SQL INSERT statements.

update

Mode where the application has fetched data to be edited. Update mode distinguishes between two types of data: fetched data and new data. For example, if an application is updating a sales order, it fetches the order information and permits updates to the existing data. It might also allow the user to enter new data, such as adding additional items to the order. The styles editor refers to fetched data as "update occ" data. All other transaction data is considered "update" data.

Before fetching data, Panther applies the update styles to the widgets. After occurrences containing data are fetched to a widget, Panther applies the update_occ style to the widget.

Saving updated data typically generates SQL UPDATE statements for altered data, SQL DELETE statements for deleted data, and SQL INSERT statements for new data.

view

Mode where the application has fetched data and prevents the user from making any changes to it. Styles are applied before data is fetched.

initial

Mode associated with a newly opened screen or a closed transaction.

qbe

Mode reserved for a future release.

How Transaction Manager Commands Affect Modes

The following transaction manager commands change the current transaction mode, thus reflecting the state of the transaction:


Command	Changes mode to:
CLOSE	`initial`
COPY	`new`
NEW	`new`
SELECT	`update`
VIEW	`view`

When an application calls one of these transaction manager commands, by way of a push button, menu item, or function key execution, the transaction manager checks the Class property (set in the screen editor Properties window under Transaction) of every onscreen widget and applies the appropriate style for the mode.

The most common style change is protection edits for data entry type widgets or availability status for menu items and push buttons. For example, if the NEW command is selected, the application needs to permit input in some or all data entry widgets on a screen, make a "save" button active, and gray out (deactivate) the "continue" button. On the other hand, if the VIEW command is selected, the application needs to protect some or all data entry widgets from input and make a "save" button inactive.

Some commands do not change the current transaction manager mode but require a particular current mode:


Command	Requires mode:
CONTINUE	`view` or `update`
SAVE	`new` or `update`

Since the transaction mode does not change for these commands, no style changes are made. Whatever styles were set by the required mode (such as view, update, or new) remain in effect. Therefore, when the NEW transaction manager command is selected, the user can enter data in the unprotected fields and choose the save button. If the save button calls sm_tm_command("SAVE"), the data is saved to the database. Until the application calls one of the commands which changes the transaction mode, the screen's data entry fields permit input and the save button remains active.

Using Styles and Classes

Each widget on your application screen has a Class property setting (under Transaction in the screen editor's Properties window). Each menu item has a TM Class property. This property determines how the widget or menu item behaves in each of the transaction manager modes. A class is a matrix of styles and modes. A style is a set of properties that are imposed on the widget.

For example, if you create the following styles:

view—Foreground Color = Red; Focus Protect = Yes
edit—Foreground Color = Blue; Focus Protect = No; Input Protect = No

You can then create a class and set a style for each mode:


Transaction Class	Initial	New	View	Update Occ	Update
`test`	`edit`	`edit`	`view`	`edit`	`edit`

You can now set a widget's Class property to test. Then, when the screen is in initial, new, and update modes, the widget with a Class property setting of test has a blue foreground and permits focus and keyboard input. In view mode, however, the same widget has a red foreground and does not permit focus.

Using the Default Styles Settings

Panther has a series of predefined styles and classes. Initially, Panther uses its internal styles to define the default classes. The internal styles set protections only. Table 23-1 lists the internal styles and their property settings that are used text widgets.

**Table 23-1 Predefined styles and their associated property settings**
Style	Property settings
`change`	allow focus allow input allow clearing allow validation
`edit`	allow focus allow input allow clearing allow validation
`show`	prevent focus prevent input prevent clearing allow validation
`visit`	allow focus prevent input prevent clearing allow validation

The styles editor also supports the values Default and None. When a style property is set to Default, Panther determines the value at runtime based on the value saved in the screen editor.

Using the Default Transaction Classes

You are not required to define transaction classes for an application; your application can use the default classes supplied by Panther or not use any classes.

When a widget's transaction class is set to Default, Panther determines the widget's class at runtime based on the properties set in the screen editor for the widget and for the widget's table view.

There are three default classes:

non_updatable
primary_key
updatable

If a widget is a member of a non-updatable table view, its default Class property is non_updatable.

If a widget is in an updatable table view and it is part of the table view's primary key, its default Class property is primary_key.

If a widget is in an updatable table view and is not a part of the table view's primary key, its default Class property is updatable.

These default Class properties are assigned the following styles in each of the respective transaction modes:


Transaction manager class	Initial	New	View	Update occ	Update
`non_updatable`	`edit`	`show`	`visit`	`show`	`show`
`primary_key`	`edit`	`edit`	`visit`	`visit`	`edit`
`updatable`	`edit`	`edit`	`visit`	`change`	`edit`

Setting Classes for Menu Items and Push Buttons

There are predefined classes that you can apply to push buttons and menu bar items on your application screens. However, they are not applied when the Class property (for buttons) and TM Class property (for menu items) are set to Default. You must explicitly set the Class property under Transaction in the screen editor for each push button, and the TM Class property in the menu bar editor for each menu item. The following table lists the predefined classes and their active/inactive setting in each mode.


Transaction manager class	Initial	New	View	Update and Update_occ
`clear_button`	`active`	`active`	`active`	`active`
`close_button`	`inactive`	`active`	`active`	`active`
`continue_button`	`inactive`	`inactive`	`active`	`active`
`continue_view_button`	`inactive`	`inactive`	`active`	`inactive`
`copy_button`	`active`	`active`	`active`	`active`
`delete_button`	`inactive`	`inactive`	`inactive`	`active`
`new_button`	`active`	`inactive`	`active`	`inactive`
`save_button`	`inactive`	`active`	`inactive`	`active`
`save_immed_button`	`active`	`active`	`inactive`	`active`
`view_button`	`active`	`inactive`	`active`	`inactive`
`view_once_button`	`active`	`inactive`	`inactive`	`inactive`

The styles for each of these classes make the push button or menu bar active or inactive according to the current mode.

Defining a New Transaction Style

To create a new style, choose CreateStyle. A style widget is created in the styles editor window under the Styles heading. With the widget selected, you can access its style properties in the Properties window.

You can also copy style widgets from other style files that are currently open in workspace. Use the Copy and Paste options on the Edit menu.

Style Widget Properties

The Properties window in the styles editor supports a subset of properties available in the screen editor. In addition to the values available in the screen editor, the styles editor also supports the value Default. When you set a style property to Default, Panther determines the value at runtime based on the value defined and saved with the individual widgets in the screen editor.

Identity Properties

Identity properties include the following:

Name

Any valid Panther identifier. By default, the styles editor assigns a name to each new style in the form style#x, where x is a number. Consider renaming the style with a more descriptive name.

Button/Menu Status

Determines the button or menu status. Select one of the following values:

Active—The button or menu is ungrayed. When the user chooses an active button or menu, the control string associated with the object is executed.
Inactive—The button or menu is grayed. The object cannot get focus, and therefore the associated control string cannot be executed.
Default—The active/inactive status is derived from the setting saved with the screen.

Function

Can be either a JPL or prototyped C function (s,i,i,i), if you want to change widget properties that are not available in the styles editor. The function is called after Panther has applied the other properties defined by the style. The function is passed the following parameters:

Style name.
An integer which identifies the current mode. The possible settings are:

0

initial

1

new

2

view

3

update occ

4

update
Field number where style was applied.
Field occurrence number if the transaction mode is update occ; otherwise, it is set to 0.

For menu options, the function is passed the following parameters (s,i,s,i): style name, transaction mode, menu name, and menu item.

`0`	`initial`
`1`	`new`
`2`	`view`
`3`	`update occ`
`4`	`update`


Initial mode	New mode
Foreground=Blue	Foreground=Cyan
Keystroke Filter=Unfiltered	Keystroke Filter=Default

In initial mode, the order_num widget has a blue foreground and permits any keystrokes. In new mode, order_num has a cyan foreground. Since the Keystroke Filter for new mode is set to Default, Panther restores the original keystroke filter, \A\A-\9\9\9\9.

For descriptions of keystroke filters, refer to "Defining the Input with Keystroke Filters."

Required

Determines if the widget requires data in order to pass validation. Set the property to Yes to force the user to enter data in the widget. Set it to No to allow the widget to remain empty. Set the property to Default to leave the widget's current setting unchanged.

Input Protection

Determines if the widget permits data entry. Set the property to Yes to prevent the user from entering data in the widget. Set it to No to allow the user to enter data. Set the property to Default to leave the widget's current input protection unchanged.

Clearing Protect

Determines if the user can clear the widget's contents by pressing the CLR (clear all) or FERA (clear field) keys. Set the property to Yes to prevent the widget's contents from being cleared. Set it to No to allow clearing. Set the property to Default to leave the widget's current setting unchanged.

Validation Property

This category has the following property:

No Validation: Determines if Panther performs validation on the widget. Specify Yes to prevent validation. Specify No to allow validation. Set the property to Default to have the widget's protection edit unchanged.

Creating a New Transaction Class

To create a new class, choose CreateClass. A new row in the class section of the styles editor window is created.

Select the class widget (first in the row under the Class column) to access its properties.
Assign a name to the class; this can be any valid Panther identifier.
For each of the modes, select the corresponding widget and assign a style name. The setting field in the Properties window will list all of the available styles for the current styles.sty file. If you do not want to assign a style name for a particular mode, set it to None. If you select a group of mode widgets, you can assign them the same style.
Note: QBE mode is reserved for a future release.
If you are defining a class for a menu item or push button, specify the same style for update and update occ modes.