|SAS/AF Software: Class Dictionary|
|Making a Form Editor|
By default, the form editor is not displayed in the Components window. To create a form editor, you can:
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.
|Using a Form Editor Object|
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.
You can create a new layout in one of several ways:
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.
Customize Columnsto 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
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
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:
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.
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.
Pair label/data widgetsoption 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.
Pair label/data widgetsoption 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
Pair label/data widgetsoption 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.
Pair label/data widgetsoption 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.
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.
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.
The widgets inside a Form Editor can be divided into three categories:
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 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:
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:
|textColor (for data controls)||informat|
|labelColor (for label controls)||justification|
|borderTitleFont (for labels represented as the borderTitle)||editable|
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
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.
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
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.
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,
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
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.
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:
Next Page, and
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.
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:
Cut to form bufferfrom the pop-up menu for the widget.
Paste from form bufferto 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
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.
Top of Page
Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.