skip to main content
OpenEdge Development: AppBuilder
Data-Display/Capture Objects : SmartDataViewers
 
SmartDataViewers
While the SDB is useful for rapidly scanning many records, it is less easy to focus on the fields of a single record. This is particularly true when there are a large number of fields involved. The SDB can only display data in tabular format; no more subtle arrangement is possible.
The SmartDataViewer displays fields from a single record at a time. By default, each field is represented by a fill-in widget, and the fields are stacked in a single left‑aligned column. In contrast to the SDB, you can completely rearrange the fields of a SmartDataViewer master to suit your layout, and can even replace individual fill-ins with special‑purpose SmartDataFields that you create.
The SmartDataViewer instances you use in your applications are each based on a master object that you design. SmartDataViewer masters are static objects; you design each one to display records supplied by a particular SDO. Once you design a SmartDataViewer master, you can reuse it repeatedly in your applications.
Creating a SmartDataViewer master
The first step in defining a new SmartDataViewer master is always to identify the source of the data stream. Because of this dependency, you must first create your SDO, then create the SmartDataViewer. See the “Creating a SmartDataObject master” section for information about that process.
AppBuilder supplies a wizard to help with creating SmartDataViewer masters. The wizard has four pages, only two of which involve significant work:
1. Introduction.
2. Identifying the data source.
3. Selecting the fields to display from the data stream.
4. Congratulations.
To create a SmartDataViewer master:
1. Start the SmartDataViewer Wizard by clicking on the SmartDataViewer in the Object Palette.
2. When the Choose dialog box opens, click New.
3. The SmartDataViewer Wizard starts up and displays its first page. When you have finished reading the introductory text, click Next. The Page 2 dialog box appears:
4. Click Browse and select the appropriate SDO master. Alternately, you can create an SDB against a SmartBusinessObject (SBO) or a temp-table’s definition in an include file.
5. Click Next. The Page 3 dialog box appears:
6. Click Add Fields. The Multi‑Field Selector dialog box appears.
7. The fields available for display appear in the left‑hand list. Select those you wish the SmartDataViewer to display and click the Add button to move them to the Selected list in the right-hand window. If you make a mistake, click the Remove button.
When you have finished selecting fields, you can reorder them using the Move Up and Move Down buttons. When they are in the order you want them displayed, click OK. The Selector dialog box closes and the list of selected fields appears in the Available Fields section of the wizard, as shown:
8. Click Next to advance to the wizard’s final page. If you have successfully defined a data source and selected the fields to display, you will see “Congratulations!”. If you do not see that page, click Back and make necessary changes.
9. Click Finish to dismiss the wizard and reveal the new SmartDataViewer master, if it was not already visible. For example:
10. Fields in a SmartDataViewer are read‑only unless you connect them to the appropriate TableIO source, such as an Update SmartPanel. If you do connect them to Update controls, then all fields become updatable unless you explicitly make them read‑only.
To make any of the individual fields read-only, double‑click on it to open its property sheet. When the Property Sheet dialog box opens, set the Read-only check box and click OK.
Note the difference in how fields display at run time, depending on their state.
In the first case, there is no Update SmartPanel, and so all fields are read-only. The fill-ins display their content without displaying themselves—the fields are not outlined or modelled in any way; they are invisible. All text looks static. This is the same effect you will get if you set the fields to be not‑updatable in the SDO:
In the second case, there is an Update SmartPanel, and so all fields are updatable if they are updatable in the SDO. The fill-ins display their content in the ordinary way, as shown:
In the third case, there is an Update SmartPanel, but the Name field has its Read‑only property set. Here, the Name field is clearly in a different state to the others, and the experienced user will recognize that it is not editable. However, this style of presentation only applies where the field is updatable in the SDO, but set read-only in the fill-in. If it is not updatable in the SDO, it appears as in the first example:
11. Choose FileSave and give the new master a descriptive filename. Note that SmartDataViewer filenames conventionally begin with v. The new master object is now available for your use.
If you plan to replace one or more of the simple fields with SmartDataFields, do it now. See the “Placing and configuring a SmartDataField instance” section for information about that process.
Note: Although SmartDataViewers can be members of the class SmartContainer, they are not organizer objects, so placing SmartObjects in them other than SmartDataFields is not supported. The only exception is that, if you replace one or more of the fields with SmartSelect objects, you can also include an equal number of SDOs to feed them.
Adding and removing SmartDataViewer fields
If you modify the data stream being supplied to a SmartDataViewer master, you might have to add and/or remove fields.
Removing SmartDataViewer fields
Removing fields is very easy: just select and delete them. AppBuilder handles the situation gracefully, without leaving residue behind.
Adding SmartDataViewer fields
Adding additional fields for display is also easy, once you know how.
To add additional fields for display:
1. Choose FileOpen and open the master object. Drag the edges of its workspace, if necessary, to add space for the new fields.
2. Click on DB-Fields in the Objects Palette.
3. Click on an empty spot in the master object’s workspace, not the main workspace. The Multi‑Field Selector dialog box appears:
4. Move the desired fields from the Available Fields list to the Selected Fields list. Click OK.
5. Position, size, and configure the newly added fields in the master workspace. Save your work.
Configuring SmartDataViewer properties
SmartDataViewers have properties associated both with their fill-in components and with their nature as a procedure‑based object. You can make a number of changes to those settings, if the default values do not meet your needs.
To open the property sheet associated with a fill-in component:
1. Choose FileOpen, select the master you wish to configure, and click OK. The SmartDataViewer master object appears in its own workspace:
2. Click on the fill-in to select it, and choose ToolsProperty Sheet. The Property Sheet dialog box appears:
Minimal configuration
Although you can accept many of the default settings, you might wish to make three changes:
*Add a Tooltip string. Under MS‑Windows, Tooltips display whenever the user allows the mouse cursor to hover for a few seconds over an object for which a Tooltip is defined.
*Add a unique integer as the identifier for context‑sensitive help, if you plan to provide such help as part of your application.
*Set the Read‑Only check box (in the Other Settings area) to prevent the user from modifying the data in the field.
Rearranging the layout
The way a viewer’s fields are laid out is also a property that can be changed, though only at the level of the master. All instances created from a given master share the same physical layout. To have different layouts for different applications, you must either create extra copies of the master and lay out each one differently—effectively creating separate masters—or use the alternate‑layouts feature. See Appendix B, “Multiple Layouts” for information about that feature.
To create a custom layout:
1. Open the master object by choosing FileOpen. The object opens in a design window workspace:
2. Save the master under the name you will use for the new arrangement. Do this before you actually make any changes, so that you will not risk getting confused later and overwriting the original arrangement.
3. Resize the workspace appropriately, drag the individual fill-ins into the new arrangement, and save again:
Note that you should make the workspace no larger than needed, since the amount of space taken up by an instance is always the same as the master’s workspace.
Other property changes
By default, AppBuilder predefines certain properties of each fill-in that is used by a SmartDataViewer, and makes some of the properties read‑only:
*Object identifier
*Label
*Allowed field format and size
*Help string
AppBuilder creates and assigns a unique identifier, and sets the other properties to conform to the field definition from the data stream. You cannot assign a different identifier or change the basic data type, but you can make changes to the label, field specifications, or help string.
To make changes to the label, field specifications, or help string:
1. Click the Database Field button, and when the dialog box opens, clear the check boxes for the properties you wish to set by hand. Click OK to dismiss the dialog box. If you clear all three, the properties dialog box appears as shown:
2. You can now enter new values for the label and the format specification. If you wish to pick the format specifier from a list, click Format. The Format dialog box appears:
You can more directly change other properties:
*No-Label — Normally cleared. Setting this check box turns off display of any label. Setting this check box does not clear the actual label text; the label string remains visible in the property sheet. The only other effect of setting or clearing this box is to alter the values in the Geometry section so that the fill-in stays at the same XY location within the enclosing frame.
*Geometry — Reflects the XY origin and size, in character units, of the fill-in. By default, the fill-in is colon‑aligned. You can change that to left‑ or right‑alignment, though the only noticeable effect that will have is to change the X origin value.
*Auto‑Resize — Normally cleared. Setting this box causes the object to automatically change its displayed size to agree with the current type size.
*Auto‑Return — Normally cleared. Setting this box causes focus to move to the next object in the traversal list once this fill-in has accepted as many characters as it can.
*Blank — Normally cleared. Setting this box prevents the fill-in from echoing input back to the display. Useful for password fields and similar applications.
*Deblank — Normally cleared. Setting this box causes the fill-in to automatically discard any leading blanks from input.
*Disable-Auto‑Zap — Normally cleared. Setting this box prevents the fill-in from automatically clearing its input field whenever it gets the focus.
*Display — Normally set. Clearing this box prevents the SmartDataViewer from automatically populating this fill-in during initialization.
*Drop-Target — Normally cleared. Setting this box causes this object to experience an event whenever the user drags another object onto this one. You must write the appropriate event‑handling code.
*Enable — Normally set. Clearing this box makes the fill-in decline input focus when offered.
*Hidden — Normally cleared. Setting this box prevents the fill-in from responding to implicit requests to display itself. It will only honor explicit requests.
*Native — Normally cleared. Setting this box causes the fill-in to vary its behavior according to the underlying platform (MS‑Windows, for example) rather than behaving in the same way regardless of platform.
*No-Tab-Stop — Normally cleared. Setting this box removes this fill-in from the enclosing frame’s traversal list. Normally, pressing the key causes focus to move to the next object in the list. When this box is set, the fill-in can neither lose nor gain focus when the user presses the TAB key. If the widget has the focus, it will ignore the key, and if it does not, focus will cycle through the other members of the traversal list while ignoring this widget.
Caution: Making this fill-in Movable or Resizable (Advanced Properties) prevents this fill-in from gaining input focus using the mouse. So if you also set this property, you effectively prevent the widget from ever gaining input focus.
*No-Undo — Cleared. Cannot be set. The ABL Virtual Machine (AVM) will always journal changes to the data in this fill-in.
*Read‑Only — Normally cleared. Setting this box prevents the user from changing the content of the fill-in.
*Remove from Layout — Cleared. Cannot be set unless defining an alternate layout.
*Shared — Cleared. Cannot be set. This fill-in will always be local to the SmartDataViewer within which it is defined.
*View-as-Text — Normally cleared. Setting this box causes this fill-in to display the contents of its field as though it were static text: read‑only, and without any border or 3D effect.
Advanced properties
A fill-in has only the minimum advanced properties, but you can change those that do not meet your needs.
*Initial value — You cannot set this for a fill-in that is part of a SmartDataViewer.
*Help — Unless this fill-in inherits the help string defined in the data dictionary, the text you enter here will display in the parent window’s status bar whenever this fill-in has input focus. No text will display if the window has no status bar.
*Private data — AppBuilder assigns the contents of this field as the value of the PRIVATE-DATA property. You can write code to manipulate this data in any way you desire.
*Layout units — You can choose character or pixels. This setting affects source code generation only.
*Custom lists — You can add this fill-in to any or all of the six lists (macros) maintained by the enclosing frame.
*Geometry — Shows the same information as in the base property sheet, but in pixel units.
*Manual highlight — Normally cleared. Setting this box allows you to write code to define a custom highlight effect. Your custom effect will be applied whenever this fill-in has input focus.
*Movable — Normally cleared. Setting this box makes it impossible for the user to give this fill-in input focus by clicking with the mouse. Instead, the user can use the mouse to drag the fill-in field—but not the label, which remains where it was—to a different position within the bounds of the enclosing frame.
*Resizable — Normally cleared. Setting this box makes it impossible for the user to give this fill-in input focus by clicking with the mouse. Instead, if the Selectable box is also set, clicking with the mouse causes handles to appear so that the user can resize the object.
*Selectable — Normally cleared. Setting this box allows the user to select this object.
Caution: If you make this fill-in Movable or Resizable, and you also set the No Tab Stop option in the base property sheet, you effectively prevent this object from ever gaining input focus.