SAS/AF Software: Class Dictionary

Using the Form Editor Class

Making a Form Editor

By default, the form editor is not displayed in the Components window. To create a form editor, you can:

Add the Form Editor class to the Components window by selecting Add Classes... from the Components window pop-up menu. Select the Form Editor class, and the class appears in the Components window. You can now drag and drop a form editor onto a frame.
Select the Form Editor class (sashelp.fsp.Form_e.class) from the SAS Explorer, then drag and drop it onto the frame.

Using a Form Editor Object

Layouts

In a Form Editor, a layout consists of widgets which allow a user to interact with the data from the attached model. As the developer, you can control how the user enters and views the data by displaying the data using any widget available in a FRAME entry. Layouts can be as simple as a default layout or more complex.

The Form Editor allows the flexibility to create any type of layout that your particular application needs using all of the normal FRAME operations, such as, make, move, and resize.

Creating a New (Default) Layout

You can create a new layout in one of several ways:

Create a new Form Editor or subclass of a Form Editor object and specify a Data Class into the Attribute window. Once the Data Class has been assigned, associate a data source to that Data class in the Data Class Attributes window (under Additional Attributes). For example, if the Data Class was Data Set Data Model, then an appropriate data source would be the table SASUSER.CLASS. At this point you can close the attribute window and a default layout will be created for you using all of the columns from the attached model. By default, input field widgets are used to represent the columns.
Create a new Data Form object and specify a table (data set), such as SASUSER.CLASS. From the Data Form Attribute window, you can select Customize Columns to have more control over which columns will be placed automatically in your new layout and which widgets will be used to represent the columns. After completing the customizations in the attribute screen, end out of the attribute screen and a default layout will be created for you using the customizations you specified.
If you have customized your display but want to return to the default layout, you can start all over again by selecting the Refill Using Attributes pop-up menu item. This creates a whole new Form Editor or Data Form object but uses the current attribute settings from the Attribute Screen.

No matter how you create a new layout, you can add, delete, or modify any of the widgets in the layout at any time to customize the layout to your particular application. When using a Data Form, you can start from a blank layout by hiding all of the columns in the Customize Columns attribute window and then create and arrange the widgets inside the layout as needed. To save your customizations, you must specify a DATAFORM entry.

When creating a new layout, a default set of attributes is used to create the layout. These attributes are controlled using either the Form Editor Options window or by calling methods on the Form Editor. The following is a list of methods that control the appearance of a new (default) layout and are called automatically for you:

_setAttributes _setDataBackgroundColor _setDataClass _setDataColor _setDataFont _setLabelBackgroundColor _setLabelClass _setLabelColor _setLabelFont _setLabelRepresentation

For information about any of these methods, see the specific method description.

Once a default layout has been created, you can execute the frame and the data widgets inside of the Form Editor will display the associated model column values for the current row. The default layout has many uses. For example, you can use the default layout as a starting point for the design of your particular layout and customize it to fit your needs. Another example is to use a Data Form to display different tables in run-mode. Each time a new table is displayed in the Data Form a new default layout could be created to represent the column from the new table.

Widget Representations

When creating a default layout or when dragging a column from the Column Window onto a Form Editor, a model column is represented by a combination of widgets, known as a widget representation. There are four ways a widget representation can be made and each is described below. In the descriptions, the widget that displays the column name or label is referred to as the label widget, and the widget that displays and accepts a value for the column is referred to as the data widget.

Two widgets (the default)

By default, the Pair label/data widgets option in the Form Editor Options window is deselected and the GROUP_WIDGETS attribute of the Form Editor is set to 'N'. This representation contains a label widget and a data widget.

Three widgets

To use this representation, select the

Pair label/data
widgets

option in the Form Editor Options window or call the _setAttributes method setting the GROUP_WIDGETS attribute to 'Y'. Then call the _setLabelRepresentation method passing the argument of 'WIDGET'. This representation contains

a label widget
a data widget
a container box that surrounds both the label and data widgets. This container box enables you to move both widgets together keeping the distance between the two widgets consistent.

One widget with a Region Title

To use this representation, deselect the

Pair label/data
widgets

option in the Form Editor Options window or call the _setAttributes method setting the GROUP_WIDGETS attribute to 'N'. Then call the _setLabelRepresentation method passing an argument of 'REGTITLE'. This representation contains a data widget that displays the linked column's name or label as the region title.

One widget

To use this representation, deselect the

Pair label/data
widgets

option in the Form Editor Options window or call the _setAttributes method setting the GROUP_WIDGETS attribute to 'N'. Then call the _setLabelRepresentation method passing an argument of 'NOLABEL'. This representation contains only a data widget and does not contain the column name or label.

Placement of Widget Representations in a Default Layout

When creating a default layout, placement of the widget representations can be either vertical (the default) or horizontal. This order can be set in the Form Editor attribute window or by calling the _setAttributes method.

Modifying a Layout

After creating a new layout using one of the techniques mentioned in Creating a New (Default) Layout, you can modify that layout using all of the normal FRAME operations. The only limitation is that widgets cannot be moved or copied into or out of a Form Editor.

In order to make any customizations to a layout, you must specify a DATAFORM entry in the Form Editor's Attribute window. Without a DATAFORM entry, your customizations are not available when you execute the frame and are lost when you end from the frame.

The Form Editor allows you to create a custom layout quickly and easily without requiring an SCL program. Since the Form Editor allows you to represent a model column as a widget, you can take advantage of special features of the widgets. They can perform self-validation of values, allow the user to enter values faster and more reliably, and also enhance the appearance of a layout.

These changes made to the default layout to create the custom layout below were easy to make and improved the look and feel of the frame. Also, this customized layout has multiple pages to help split up the information so that it is not so overwhelming to the user.

Data and Label Widgets

The widgets inside a Form Editor can be divided into three categories:

Unlinked Widgets

Widgets that are not linked to a model column.

Data Widgets

Widgets that are linked to model columns that allow a user to view and modify the column's value. Data widgets can be created at any time during the construction of a layout by creating new widget representations or transforming an unlinked widget into a data widget by linking a model column to it. By default the class used to create this widget is an input field. You can customize this by calling the _setDataClass methods.

Label Widgets

Widgets that display either the name or label of a model column. These widgets are initially linked to a model column and can only be created when a new widget representation is made. When a widget representation is made, an internal association is made between the data and label widgets. When the column name or label of the associated data widget changes, that change is reflected in the label widget. By default, the class used to create the label widget is an input field label. If you are using a data form object, you can customize this by calling the _setLabelClass method or through the data form object's attribute window.

When data and label widgets are internally linked, we will use the text of the column name or column label for the text of the label widget instead of any changes to the text you make at the widget level. This also applies if you display the label text as a region title.

Attributes for the Label and Data Widgets

The process used by the Form Editor to get and set attributes depends on whether a legacy class (that is, a Version 6 class) or an SCOM-enabled class (that is, a class defined using a Nashville release of SAS/AF software) is used to represent a column or label. If a legacy class is used, then the Form Editor calls the following methods to get and set attributes:

_getBackgroundColor _setBackgroundColor _getColor _setColor _getFont _setFont _getFormat _setFormat _getInformat _setInformat _getJustify _setJustify

If a method is not defined for a particular class, then that attribute is neither set (if the set method does not exist) nor retrieved (if the get method does not exist).

If an SCOM-based class is used, then the Form Editor uses the following attributes will be set using the _setAttributeValue method and retrieved using the _getAttributeValue method:

backgroundColor format

textColor (for data controls) informat

labelColor (for label controls) justification

font visible

borderTitleFont (for labels represented as the borderTitle) editable

If the attribute does not exist for a particular SCOM class, then that attribute is neither set nor retrieved.

The attributes that are set for the data and label widgets are controlled by the model attached to the Form Editor. A model can have a set of attribute values that are specific to a particular column. If the column linked to a data or label widget has any attribute values specifically set, then those values take precedence over the default attribute values of the Form Editor. For example, if a model column has a background color specified, then that color is used instead of the default background color of the Form Editor. Otherwise, the Form Editor default background color will be used.

The Form Editor has default attribute values for the Data background and foreground color and font as well as similar settings for the label. The Form Editor does not have default settings for the format, informat, or justification attributes, so these attributes are not set unless the model specifies them. The _get methods listed are used to query the attributes from the data or label widgets that you have set in the widget's attribute window or Properties window.

Note: The Form Editor calls the _setData method to set the widget's value to the value of the linked model column. The Form Editor calls the _getData method to retrieve the widget value modified by the user to be stored in the linked model column. These methods are called on all data widgets and are crucial for every data widget. Without the _setData and _getData methods, the data widgets could not display or retrieve changes made to linked model columns. The widgets supplied by SAS/AF software each have a _setData and _getData method defined.

When using a legacy class, the default action of the _getData and _setData methods is based on type of the linked model column. If the linked model column is a character type, then the _setData and _getData methods will call the _setText and _getText methods, respectively. If the linked model column is a numeric type, then the _setData and _getData methods will call the _setValue and _getValue methods, respectively. If you create your own legacy subclass, then you must define a _getData and _setData method or _getText and _setText and _getValue and _setValue methods for for the class in order to use that subclass in a Form Editor.

When using an SCOM-based class, the default action of the _getData and _setData methods is to process the attribute defined in the object's defaultAttribute attribute. (The defaultAttribute is set to the name of the critical attribute for that class.) The _getData and _setData methods retrieve and set the value of the attribute that is defined by the defaultAttribute attribute. For example, the Text Entry control's defaultAttribute is set to 'text'. So when the _getData and _setData methods are called, they will actually query and set the value of the 'text' attribute. If you create your own SCOM subclass, then you must set the value of the 'defaultAttribute' in order to use that subclass in a Form Editor. [cautionend]

Pages

The contents of a Form Editor layout can be split into units called pages. If a model has more columns than will fit on the initial page, other pages are added to display those model columns. You may also decide to add additional pages. Pages allow you to

split your layout into smaller groups to make your application easier to use. The groups could be based on column importance or there could be a logical grouping of columns that naturally would go together on a page.
reduce the need to scroll within one page. If you use multiple pages rather than one long page, you can use navigation features (pop-up menus, earmarks, etc.) to jump to different pages to get to the columns you need. If you use one long page, you must scroll through the page to get to the columns you need.

The Form Editor has no limit on the number of pages it can have, nor is there a limit on the number of widgets per page. You are only limited by the resources available on your system. A model column may be linked to a widget on more than one page. But realistically, you should limit the number of pages and widgets per pages since the more pages and widgets per page you have, the longer it takes for the frame to display.

The scroll bars, when active, allow you to scroll within the current page, not between pages or rows. Because the scroll bars scroll within a page, the page can be as large as you like. During the creation of a default layout, the page size is set to the size of the Form Editor's region size. This size can be changed by scrolling down or to the right and adding widgets. Any page customizations that are done, are stored in the DATAFORM entry. DATAFORM entries can be used interchangeably between Form Editors; so if a new Form Editor is smaller than the original Form Editor, the scroll bars will allow you to view the entire contents of the pages.

During build mode, the scroll bars have no boundary, which enables you to place widgets anywhere within a page. During run mode, scroll bars enable you to scroll only to the lowest and right-most widget on the current page. For example, the vertical scroll bar is maximized because all of the widgets are visible in the Form Editor's region. The horizontal scroll bar allows you to scroll to the right and view the entire contents of the page.

Adding and Deleting Pages

All Form Editor layouts have at least one page. The Form Editor allows you to add pages via the build mode pop-up menu items, Add page after current and Add page before current. After selecting one of these pop-up menu items, you are positioned on the new empty page. After a page is added, all of the pages are renumbered and now are referenced using the new number.

You can delete any page from a layout by selecting the build mode pop-up menu item Delete Page.... You will be prompted with a dialog box to verify that you want to delete this page. When a page is deleted, all widgets that were contained on that page are deleted also. The page that has been deleted cannot be recovered unless it was previously stored in a DATAFORM entry and you cancel out of the frame. By cancelling out of the frame, you also lose other changes that you have made, so be careful when deleting pages. After a page is deleted, all of the remaining pages are renumbered and now are referenced by using the new numbers. You cannot delete the last page remaining in a layout.

Navigating Between Pages

When a Form Editor layout has multiple pages, users can navigate between the pages in order to view and enter the data. There are several ways that this can be done:

Run mode pop-up menu

There are four items on this menu that allow you to navigate between the pages of a layout, First Page,

Previous
Page

, Next Page, and Last Page.

Earmarks

Earmarks make the layout look as though it has a turned down page in either the upper left, the upper right, or both corners. An earmark shown in the upper right corner indicates that there are additional pages. An earmark shown in the upper left corner indicates that there are previous pages. By double clicking on the left earmark, you will be taken to the first page. By double clicking on the right earmark, you will be taken to the last page.

You can control the display of earmarks from the Form Editor Options attributes window or by calling the _setAttributes method and passing an item of EARMARK with a value of 'Y' or 'N'. The color of the earmarks can also be controlled from the attribute screen or by calling _setEarmarkColor or _setEarmarkOutlineColor.

Moving Widget Between Pages in a Form Editor

The Form Editor gives you the ability to move widgets between pages using the build-mode pop-up menu. To move a widget across pages in a form editor, follow these steps:

Go to the page of the Form Editor where the widget is displayed.
Select the widget.
Select Cut to form buffer from the pop-up menu for the widget.
Go to the page where you want to paste the widget.
Select Paste from form buffer to paste the widget on the new page.

You cannot select multiple, individual widgets to move, but you can move a group of widgets by wrapping them in a container box and moving the container box.

Effect of Protecting Columns

You can prevent users from modifying a column or columns by "protecting" the column or columns. Columns can be protected by using the _protectColumn method or by setting the Protected attribute for that column or columns. The effect of protecting a column in a data form, form editor, or subclass of the form editor, is different depending on whether a legacy widget or SCOM-based control is used. If a legacy widget is used, then a user can type in and/or select columns that are protected, but the widgets revert to their previous state when the Enter key is pressed or a mouse button is released. If a SCOM-based control is used, then the control is grayed and no typing or clicking is accepted by the control.

In addition, you cannot tab to or tab out of a protected column and labeled sections for protected columns do not run.

When a form editor is in browse mode, all of the columns are protected.

Chapter Contents
Previous
Next
Top of Page

backgroundColor	format
textColor (for data controls)	informat
labelColor (for label controls)	justification
font	visible
borderTitleFont (for labels represented as the borderTitle)	editable