skip to main content
OpenEdge Development: ADM and SmartObjects
SmartObjects : SmartDataBrowsers
 
SmartDataBrowsers
A SmartDataBrowser is an ADM browser‑class SmartObject that displays records and allows updates to records in a browse widget. In addition, it coordinates the display and updating of records with other SmartObjects, typically SmartDataViewers and SmartDataObjects. A SmartDataBrowser uses a SmartDataObject as a data source.
Table 2–6 lists the SmartDataBrowser files.
 
Table 2–6: SmartDataBrowser files 
File type
Filename / SmartLinks
Template file and master file
(Because dynamic SmartDataBrowsers are customized at design time or even at run time, a template is not necessary.)
src/adm2/dynbrowser.w
(master for dynamic SmartDataBrowser; no wizard)
src/adm2/template/browser.w
(template for static SmartDataBrowser; includes wizard)
Primary include file
src/adm2/browser.i
ADM/Progress Advisor‑ supported SmartLinks
Data-Source
Data-Target
Navigation-Target
TableIO-Target
Properties dialog box
src/adm2/support/dynbrowserd.w
(source code for dynamic SmartDataBrowser)
gui/adm2/support/dynbrowserd.r
(compiled code for dynamic SmartDataBrowser)
src/adm2/support/visuald.w
(source code for static SmartDataBrowser)
gui/adm2/support/visuald.r
(compiled code for static SmartDataBrowser)
SmartDataBrowser instance properties
As the first row in Table 2–6 indicates, there are two types of SmartDataBrowsers: dynamic and static. Each has a different set of instance properties and, therefore, different instance properties dialog box.
Dynamic SmartDataBrowser instance properties
Figure 2–3 shows the Dynamic SmartDataBrowser Properties dialog box.
Figure 2–3: Dynamic SmartDataBrowser Properties dialog box
You use the instance properties in this dialog box as follows:
*SmartDataObject — This field enables you to choose the SmartDataObject to drive the dynamic SmartDataBrowser.
*Edit Displayed field list — This opens a list box that lists the fields in the SmartDataObject that is the SmartDataBrowser’s Data-Source, from which you can select the fields to be displayed in the dynamic SmartDataBrowser.
*Edit Enabled field list This opens a list box that lists the fields in the SmartDataObject that is the SmartDataBrowser’s Data-Source, from which you can select the fields to be enabled for update.
*Search Field If a field is specified, the first line of the SmartDataBrowser’s frame is allocated to a fill‑in field in which the application user can enter a value for a search field. The SmartDataObject query is re‑sorted automatically by the search field, and on each keystroke entered, the browse is repositioned to the first row in which the specified field has a value greater than or equal to what was typed so far.
*Enable If checked (the default), this enables the dynamic SmartDataBrowser for use.
*Layout — This property is disabled for dynamic SmartDataBrowsers.
*View — If checked (the default), this makes the dynamic SmartDataBrowser visible.
*Down — This determines the number of rows to display in the dynamic SmartDataBrowser.
*If this is 0 (zero, the default), Progress calculates the number of rows displayed in the dynamic SmartDataBrowser based on the size of the browser. This might result in the display of a partial row at the bottom of the browse. (You can adjust the height of the browse manually to compensate.)
*If this is a positive integer, Progress displays exactly this many rows in the browse. You cannot specify a decimal value, so the browse never displays a partial row.
The value of this property is assigned to the browse’s DOWN attribute.
*Calculate Width — This determines the width of the dynamic SmartDataBrowser.
*If this is unchecked (the default), the browse’s EXPANDABLE property is turned on, and Progress sets the width of the browse based on the width of the dynamic SmartDataBrowser. In this case, if the width of the browse columns is less than the width of the browse, the last column is expanded to fit the width of the browser.
*If this is checked, Progress calculates the exact width of the dynamic SmartDataBrowser’s columns, compares the result with the Max Width value, and uses the smaller of the two values as the width of the browse. Checking this box turns off the browse’s EXPANDABLE attribute.
*Max Width — This specifies the maximum width of the browse (the default is 80.00). If you check Calculate Width and the calculated width is greater than Max Width, Max Width is used instead. This field is enabled only when Calculate Width is checked.
*Scroll Remote Results List — If checked, this causes the SmartDataBrowser to try to fill the browse with data when you scroll the browser to the end of a batch of records.
*Fetch Data to Fill Browse on Reposition to End of Batch — When checked, this is similar to Scroll Remote Results List, except it occurs on a reposition of the browse (as opposed to a scrolling of the browse).
Static SmartDataBrowser instance properties
The static SmartDataBrowser uses the Visual SmartObject Properties dialog box, shown in Figure 2–4.
Figure 2–4: SmartDataBrowser Properties dialog box
You use the instance properties in this dialog box as follows:
*Enable — If checked (the default), this enables the static SmartDataBrowser for use.
Note: Do not uncheck (turn off) this property.
*Layout — This property is enabled for static SmartDataBrowsers when a custom layout is defined in the SmartDataBrowser master. This box is disabled if there are no custom layouts defined. Its value is the same as the browser's parent layout by default.
*View — If checked (the default), this makes the static SmartDataBrowser visible.
*Scroll Remote Results List — If checked, this causes the SmartDataBrowser to try to fill the browse with data when you scroll the browser to the end of a batch of records.
*Fetch Data to Fill Browse on Reposition to End of Batch — When checked, this is similar to Scroll Remote Results List, except it occurs on a reposition of the browse (as opposed to a scrolling of the browse).
Dynamic versus static SmartDataBrowsers
The primary difference between a dynamic and a static SmartDataBrowser is that a given dynamic SmartDataBrowser can be configured to display and update the query of any SmartDataObject, while a static SmartDataBrowser is specific to a particular SmartDataObject: The two types of SmartDataBrowsers are described in more detail below:
*The dynamic SmartDataBrowser displays and updates records from a set of fields that are determined at run time. At run time, the ADM assigns the display and update fields based on the current values of the SmartDataBrowser’s DisplayedFields and EnabledFields instance properties and takes the query from the SmartDataObject to which the SmartDataBrowser is linked. This is why you can configure a dynamic SmartDataBrowser to display and update the query of any SmartDataObject.
You can set the DisplayedFields and EnabledFields properties of the dynamic SmartDataBrowser at design time through the Dynamic SmartDataBrowser Properties dialog box. If DisplayedFields and EnabledFields are unset at run time, their values are taken from the associated SmartDataObject’s DataColumns and UpdatableColumns properties. For details, see the “Setting the dynamic SmartDataBrowser field properties” section.
Because a dynamic SmartDataBrowser instance’s display and update fields are not assigned until run time, it appears at design time as a browse widget with no columns.
*The static SmartDataBrowser displays and updates records from a set of fields that are assigned at design time. At design time, the wizard sets the display and update fields, as well as the data source’s query, based on the SmartDataObject to which the SmartDataBrowser is linked. This is why a given static SmartDataBrowser is specific to a particular SmartDataObject.
Because a static SmartDataBrowser instance’s display and update fields are assigned at design time, it appears at design time as a browse widget with one column for each field selected in the wizard.
Another significant difference is that you create masters for static SmartDataBrowsers but not for dynamic SmartDataBrowsers. This is because a dynamic SmartDataBrowser uses the SmartDataObject to which it is linked at run time and, therefore, it does not need a master.
SmartDataBrowser usage notes
This section discusses special programming considerations for using SmartDataBrowsers.
The NO-ASSIGN property
The NO-ASSIGN property in the design window of a SmartDataBrowser master or the property sheet for the browse widget is set to TRUE. This allows the ADM code to handle all record updates.
Caution: Do not set NO-ASSIGN to FALSE, or the SmartDataBrowser will not be able to use the ADM methods to perform record updates.
Default triggers for SmartDataBrowsers
The master procedure file for a SmartDataBrowser defines a variety of triggers for the browse widget that it contains:
*OFF-END ({src/adm2/brsoffnd.i}) — Checks whether there are more rows in the query in the forward direction
*OFF-HOME ({src/adm2/brsoffhm.i}) — Checks whether there are more rows in the query in the backward direction
*END ({src/adm2/brsend.i}) — Performs a fetchLast operation
*HOME ({src/adm2/brshome.i}) — Performs a fetchFirst operation
*CTRL-END — Applies the END trigger, which performs a fetchLast operation, to the browse (does not have an include file of its own)
*CTRL-HOME ({src/adm2/brshome.i}) — Applies the HOME trigger, which performs a fetchFirst operation, to the browse (does not have an include file of its own)
*ROW-ENTRY ({src/adm2/brsentry.i}) — Displays the initial values for newly added or copied rows
*ROW-LEAVE ({src/adm2/brsleave.i}) — If the selected object is not a SmartPanel button (for example, a Cancel or Reset button), saves any changes made to the row, otherwise the button takes the action associated with the button
*VALUE-CHANGED ({src/adm2/brschnge.i}) — Instructs the SmartDataObject linked to the browse to let other objects know that the record has changed
*SCROLL-NOTIFY ({src/adm2/brsscrol.i}) — Checks whether there are more rows in the query in the forward direction
Scrolling past the end of the result set
The SmartDataBrowser’s OFF-END and OFF-HOME triggers produce certain visual anomalies when your users browse the associated SmartDataObject query’s result set and try to scroll past the end of the result set.
When a SmartDataBrowser browses a SmartDataObject query, the associated RowObject temp-table might contain only a subset of the entire database query result set at any given time, so the SmartDataBrowser might browse only that subset. Although the supporting trigger code for the SmartDataBrowser is designed to make this as transparent as possible, the retrieval of multiple batches of rows into the SmartDataObject’s RowObject temp-table has some visible impact on the SmartDataBrowser.
In particular, the OFF-END trigger fires when the browse is scrolled to the bottom of the current result set, which happens when the application user does one of the following:
*Presses the DOWN arrow on the keyboard in an attempt to scroll beyond the last row in the current result set
*Presses the down arrow on the SmartDataBrowser’s vertical scroll bar until the last row is reached, then releases the arrow
When the OFF-END event occurs, the SmartDataBrowser code asks the SmartDataObject whether there are more rows to retrieve from the database. If so, an additional batch of rows is added to the RowObject temp-table, the temp-table’s query is reopened, and the browse is repositioned to the same row as before the event. This causes a delay (normally a brief one) while the records are retrieved and the query is reopened. It also means that the user must release the scroll bar arrow to see more rows.
If the SmartDataObject’s RebuildOnRepos instance property is set to YES, an attempt to scroll past the end of the result set might occur in either a forward or a backward direction. For example, if RebuildOnRepos is YES, and the application user either presses the Last button on a SmartPanel or SmartToolbar or presses CTRL-END on the keyboard to move to the last row in the result set, the RowObject table in the SmartDataObject is rebuilt from the end. Thus, if the user scrolls backwards (upwards) to the first row in the current result set, the OFF-HOME event causes the retrieval of the next batch of rows before the current result set, which causes a similar delay as the user scrolls up through the data. The vertical scroll bar might be similarly inconsistent and not reflect the size of the complete data set.
These visual anomalies are necessary to allow a client without a database connection to browse a potentially large result set without the entire data set being moved to the client at one time. If you do not want them to occur in your application, do one of the following:
*Set the SmartDataObject’s RowsToBatch instance property to retrieve the entire data set at one time.
*Set its RebuildOnRepos instance property to build the result set in a single direction from beginning to end.
Multiple selection
Multiple selection is not supported for SmartDataBrowsers. If you want to use this option, you must add supporting code to communicate the multiple selection to other SmartObjects as needed.
Setting the dynamic SmartDataBrowser field properties
Once you link a dynamic SmartDataBrowser to a SmartDataObject, you can set the SmartDataBrowser’s DisplayedFields and EnabledFields instance properties in its instance properties dialog box. The ADM uses the values at run time to determine the display and update fields for the SmartDataBrowser. Setting only one or neither property has these results:
*If you set DisplayedFields but not EnabledFields, and the SmartDataBrowser has a TableIO-Source (an Update SmartPanel), EnabledFields is set at run time to a list of all specified DisplayedFields in the associated SmartDataObject’s UpdatableColumns property. Otherwise, it is made blank (that is, there are no EnabledFields).
*If you set EnabledFields but not DisplayedFields, and the SmartDataBrowser has a TableIO-Source (an Update SmartPanel), DisplayedFields is set at run time to a list of all fields in the associated SmartDataObject’s DataColumns property.
*If you leave both properties unset, the UpdatableColumns property is set only if there is a TableIO-Source.
The dynamic SmartDataBrowser SearchField property
The dynamic SmartDataBrowser has a property called SearchField that is not available in the static SmartDataBrowser. This property allows you to specify a field on which to search at run time. If you specify a value, the first line of the SmartDataBrowser frame is allocated to a fill‑in field in which the user can enter a search value at run time. The SmartDataObject query is automatically re‑sorted by the SearchField value, and on each keystroke entered, the browse is repositioned to the first row whose search field has a value greater than or equal to the user‑specified search value.
Displaying row markers in the dynamic SmartDataBrowser
Unchecking the NO-ROW-MARKERS property in the property sheet for the dynamic SmartDataBrowser does not display row markers (the expected behavior of this browser). You can get row markers, however, by explicitly setting ROW-MARKERS to YES in dynbrowser.w. Specifically, add the following code to the main block of dynbrowser.w:
 
ASSIGN BROWSE {&BROWSE-NAME}:ROW-MARKERS = YES.