SAS/AF Software: Class Dictionary

Using the Data Form Class

Widgets can be moved within a page or across pages in a data form. To move a widget within a page, use the pop-up menu or drag and drop operations.

To move a widget across pages in a data form, follow these steps:

Go to the page of the data form 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.

Data Form Layouts

In a Data Form, a layout consists of widgets which allow a user to interact with the data from the specified table. 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 Data Form 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 Data Form and specify a table in the Attribute window, for example, 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 table. 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 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 Customize Form window or by calling methods on the Data Form. 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

Once a default layout has been created, you can execute the frame and the data widgets inside of the Data Form will display the associated 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 Data Form, 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 Customize Form window is deselected and the GROUP_WIDGETS attribute of the Data Form is set to 'N' (through the _setAttributes method). 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 Customize Form 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 Customize Form 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 Customize Form 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 Customize Form window or by calling the _setAttributes method.

Modifying a Layout

After creating a new layout using one of the techniques mentioned above, 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 Data Form.

In order to make any customizations to a layout, you must specify a DATAFORM entry in the Data Form Attributes 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 Data Form allows you to create a custom layout quickly and easily without requiring an SCL program. Since the Data Form 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.

Using the Column Window with Data Forms

The Column Window enables you to create a new widget representation for a model's column, associate a model's column with an existing widget, make a computed column, and disassociate a model's column from an existing widget. The Column Window can be displayed in one of two ways:

setting an attribute

Select the Display Column Window check box in the Customize Form window. If you choose to display the Column Window this way, the Column Window will automatically display each time you re-edit this frame.

selecting a pop-up menu item

Select the

Form
menu item from the build-mode pop-up menu. Then select

Display Column Window
from the new pop-up menu. Displaying the Column Window this way causes the Data Form to display the Column Window immediately but it will not automatically display each time you re-edit this frame.

Only one Column Window is present (displayed) at any one time. If you have multiple instances of a Data Form, a Form Editor, or a subclass of a Form Editor, in the same frame or multiple frames, then the Column Window displays the columns from the active Data Form along with that Data Form's name in the list box title. The column window automatically closes when the last frame that contains a data form, a form editor, or a subclass of the form editor, closes.

The Column Window enables you to perform several actions on a Data Form by using drag and drop between the Column Window and the Data Form. Drag the column from the Column Window onto the Data Form. You will notice as you drag the column across the Data Form or any of it's widgets, the region border changes to the NOTE color, indicating valid drop sites. The drop highlight action and color is controlled from the Customize Form window. Releasing the mouse button while either the Data Form or one of its widget's borders is still the NOTE color, finishes the drag and drop operation and the appropriate action will take place as defined below.

The purpose of the Column Window and the linking of columns to widgets is to allow the execution of labels within the model SCL. Each time a widget that is linked to a column is modified, the new value is sent to the model which executes the label corresponding to the name of the column linked to that widget. Without linking columns to widgets, the user could not view or edit the values of the column, nor could the developer add code to the model SCL to perform an action based on a user-entered column value.

Creating a New Widget Representation

To create a new widget representation, drag the column onto the Data Form and release the mouse button when the Data Form's region is the NOTE color. This creates a default widget representation based on the current Data Form settings at the location of your mouse pointer.

Linking a Column to a Widget Representation

Instead of creating a default widget representation, you can make any widget inside the Data Form (for example, a Radio Box or an Input Field) and then associate a model column to that widget. After you create a widget inside of the Data Form, drag a column and release the mouse button when the region border of a widget inside the Data Form is the NOTE color. By performing this action, the widget is now linked to the model column that was dropped on it. Once linked, the widget displays the current row value of the linked column during run-mode.

Disassociating a Column from a Widget

If you no longer want a model column linked to a widget within the Data Form, drag and drop the Unlink Object item onto the widget in the Data Form. When you release the mouse button, the widget is no longer linked to a model column. In run mode, the widget's value will no longer reflect the current row value of the previously linked model column.

Making a Computed Column Based on an Existing Widget

As mention above, a modified widget inside Data Form does not execute any labeled section in the model SCL unless it is linked to a column, either a real or computed column. The Make Computed Column item allows you to quickly create a computed column which is then automatically linked to the widget it was dropped on.

The name of the computed column will be the name of the widget, unless that name already exists. If the name exists, a number is appended to the name of the widget to create a unique name, for example RADIO1, RADIO2, etc. The name of the computed column now displays in the column window. When the widget associated with the computed column is modified, the labeled section that you have added to the model SCL, and which corresponds to the name of the computed column, executes.

The type of the computed column is the same as the type for the widget.

Using Commands Instead of Drag and Drop

Each of the actions mentioned in the previous sections can be performed without doing drag and drop operations; instead simply issue a command. Click in an empty section of the Data Form to make it the active object. Use the following command and substitute any of the column names appearing in the Column Window for the 'column-name' argument:

   LINK widget-name column-name

To disassociate a column from a widget, issue the following command to the Data Form:

   UNLINK widget-name

Data and Label Widgets

The widgets inside a Data Form 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 or by using the CLASSES window in the Customize Columns Attribute window.

Label Widgets

Widgets that display either the name or label of a model column. These widgets are internally 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. 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.

The Data Form calls the following methods to get and set attributes of both the label and data widgets.

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

If a method is not defined for a particular widget class, then that attribute is neither set nor retrieved. The attributes that are set for the data and label widgets are controlled by the Data Set Data Model. 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 Data Form. For example, if a model column has a background color specified, then that color is used instead of the default background color of the Data Form. Otherwise, the Data Form default attribute value will be used.

The Data Form has default attribute values for the data background and foreground color and font as well as similar settings for the label. The Data Form 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.

Note: The Data Form calls the _setData method to set the widget's value to the value of the linked model column. The Data Form 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, but if you create your own widget subclass, you must define a _getData and a _setData method for it in order to use that widget subclass in a data form. [cautend]

Pages

The contents of a Data Form 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 Data Form 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 Data Form'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 Data Forms; so if a new Data Form is smaller than the original Data Form, 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.

Adding and Deleting Pages

All Data Form layouts have at least one page. The Data Form 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 numbers.

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 Data Form 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 Customize Form 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.

Pop-up Menus for Data Form

Build-mode Pop-up Menu

When you use the pop-up menu button of your mouse to open the standard build-mode widget pop-up menu, the following two items are added to the build-mode pop-up menu for the form. The other items in the build-mode pop-up are described in the Widget Class.

Paste from Form Buffer

Pastes into a layout of a Data Form a copy of the widget that was copied or cut to the Form Buffer. This menu item is grayed until you copy or cut a widget to the form buffer by choosing Copy to Form Buffer or Cut to Form Buffer from a widget within a data form. Widgets can be pasted into any Data Form as well as between pages within any Data Form. Once a widget is cut or copied to the Form Buffer, it remains in the buffer until you either replace the contents of the buffer, by cutting or copying another widget, or end your SAS session.

Form

Displays another pop-up menu that contains items specific to the Data Form. The items in this pop-up are defined as follows:

Display Column Window

opens a separate window with a list box that contains one item for each of the columns currently defined in the model.

Once the Column Window is displayed, it remains displayed until one of the following happens:

You end the Column Window.
You end all currently open frames containing a Form Editor, subclass of the Form Editor, or Data Form.

Edit SCL...

opens a source window containing the model's associated SCL. The item is grayed when there is no associated SCL entry specified in the attributes window.

To compile this SCL, issue the COMPILE command from the EDIT SCL window

Compile SCL

compiles the associated model's SCL entry that is specified in the attributes window. The item is grayed when there is no associated SCL.

Refill using attributes...

deletes all widgets and pages in your layout and then refills the Data Form using the current attribute settings from the Attribute Window. This action is a destructive operation, so you are prompted with a dialog box to allow you to cancel the action. Choosing this pop-up item calls the _refillUsingAttributes method of the Data Form passing an argument of 'Y'. This will cause a dialog to appear and prompt you to accept or deny the refill requested.

The Refill using attributes... pop-up item is used when you want to completely start over as if you were creating a new Data Form from scratch along with a default layout.

Turn Column Describe On/Off

displays the name of the column associated with the current data widget. Each time you click a widget associated with a column, the following message displays on the message line:

NOTE: The object 'object-name' is linked to column 'column-name'.

If you click a widget that is not linked to a column, you see the following message displayed on the message line:

NOTE: The object 'object-name' is not linked to any column.

First Page, Previous Page, Next Page, and Last Page

navigate between the currently defined pages. Each of the commands is appropriately grayed, depending on the current page. The page navigation menu items call the _hscroll method with the appropriate parameters for the requested command.

Add Page Before Current and Add Page After Current

insert a blank page before or after the current page. After the page is added, you are positioned on the newly added page.

Delete Page...

removes the current page along with any widgets that are on that page. Before the page is deleted, you are prompted to confirm the requested deletion.

Build-mode Pop-up Menu for Widgets within Data Forms

When you use the pop-up menu button of your mouse to display the build-mode pop-up menu for any widgets inside the Data Form, the following three items are added to the build-mode pop-up menu for the widget.

Copy to Form Buffer: Copies the widget from which the pop-up menu was displayed into the Form Buffer and leaves the original widget intact. Once placed in the buffer, the widget can be pasted any number of times to any Data Form and to any page within a Data Form. If there is a widget already in the Form Buffer, it is replaced with this widget being copied. You cannot select multiple, individual objects to copy, but you can copy a group of objects by wrapping them in a container box and copying the container box.
Cut to Form Buffer: Copies the widget from which the pop-up menu was displayed into the Form Buffer and REMOVES the original widget. Once placed in the buffer, the widget can be pasted any number of times to any Data Form and to any page within a Data Form. If there is a widget already in the Form Buffer, it is replaced with this widget being cut. You cannot select multiple, individual objects to cut, but you can cut a group of objects by wrapping them in a container box and cutting the container box.
Paste from Form Buffer: Described earlier in Data Form's build-mode pop-up menu.

Run-mode Pop-up Menu

You can use your mouse to display a pop-up menu in run mode. To turn off the run-mode pop-up menu, select Command Processing from the Form Editor Attributes window. Then, select Honor General Attribute from the Popmenu Processing list box.

The menu items specific to the Data Form class are defined as follows.

First Row, Previous Row, Next Row, and Last Row

navigate between rows. The First Row and Previous Row menu items are grayed when the data form displays the model's first row. However, the Next and Last Row menu items are never grayed since the model's last row can change dynamically. This enables you to access any new rows that may have been added by an outside source. For example, the data set used by the data form may be on a SHARE server. If the data set is located on a SHARE server, several people may be adding rows; so the Next Row and Last Row items allow you to access these newly added rows.

The row navigation menu items call the _vscroll method with the appropriate parameters for the requested command.

First Page, Previous Page, Next Page, and Last Page

navigate between the currently defined pages. Each of the commands are appropriately grayed depending on the current page. The page navigation menu items call the _hscroll method with the appropriate parameters for the requested command.

Add Row

runs the _addRow method to add a pending row.

Browse/Edit

runs the _setOpenmode method to alternate between BROWSE mode and EDIT mode.

Cancel Row Edits

runs the _reread method to reread the current row from the table. If you have added or copied a row, this item cancels the add or copy without saving the pending row on the table. Otherwise, this item cancels any edits that you have made on the locked row.

Commit New Row

runs the _commitNewRow method to add the pending row to the table if you have added or copied a row.

Copy Row

runs the _copyRow method to make a pending copy of the locked row in the table.

Delete Row

runs the _deleteRow method to delete the locked row from the table.

Help

runs the _columnHelpText method to obtain column help from the model.

Override

runs the _override method to override required and error fields. This item enables you to override a column that is in error if option settings allow.

Record/Member

runs the _setOpenMode method to change alternate between RECORD level locking and MEMBER level locking.

Where

runs the _setWhere method to open the interactive WHERE window to specify a WHERE clause for the data.

Where Clear

runs the _setWhere method to clear a WHERE clause for the data.

Chapter Contents
Previous
Next
Top of Page