skip to main content
OpenEdge Development: ADM Reference
Visual Objects and Their Methods and Properties : Browser methods for visual objects
 
Browser methods for visual objects
This section describes the methods for SmartDataBrowsers. SmartDataBrowsers display multiple virtual records in a simple, tabular row and column format.
addRecord
SmartDataBrowser version of addRecord. This procedure initiates the creation of a new record. Inserts a new row below the current row, if any. The ROW–ENTRY trigger in the SmartDataBrowser (src/adm2/brsentry.i) displays initial values.
Location: browser.p
Parameters: None
Notes:  
*Invokes addRecord version in datavis.p (RUN SUPER).
*Sets the BrowseInitted property to FALSE. This property is used in the ROW–ENTRY trigger where the actual display of initial values takes place to make sure that the initialization logic for add is executed once.
*Invoked when an Add is initiated (typically by choosing the Add button in an Update SmartPanel, or the Add button or Add menu item in a SmartToolbar).
*Customized when additional processing is needed at the start of an Add operation. When an addRecord override is invoked, the new record has not yet been created, and there is no transaction active.
applyCellEntry
Procedure that applies ENTRY to the first enabled column in the browse, or to the column passed as an input parameter.
Location: browser.p
Parameters:  
INPUT pcCellName AS CHARACTER
Either the name of the browse column on which to put focus or a the Unknown value (?) to indicate the first column.
Notes:  
*Used internally to reposition to the correct column, for example, when a validation fails for that column.
*Invoked from applyEntry when the SmartDataBrowser has enabled fields.
applyEntry
SmartDataBrowser version of applyEntry. Procedure that applies ENTRY to the first enabled column in the browse if columns are enabled, or to the first enabled object in the SmartDataBrowser.
Location: browser.p
Parameters:  
INPUT pcField AS CHARACTER
Either the name of the browse column on which to put focus or the name of an object part of the SmartDataBrowser.
Notes:  
*Invoked when the ADM code needs to give focus to a SmartDataBrowser. The applyEntry procedure runs applyCellEntry to do browse-specific repositioning to the proper browse cell.
*Customized when focus is given to a different column or object in the SmartDataBrowser or when special processing is needed. Be aware that repositioning to a specific column after a validation or update fails might alter the behavior of the SmartDataBrowser.
assignMaxGuess
Procedure that sets the argument value of the Browse widget’s MAX-DATA-GUESS attribute.
Location: browser.p
Parameters:  
INPUT piMaxGuess AS INTEGER
The value to add to MAX-DATA-GUESS.
Notes: None
calcWidth
Procedure that calculates the exact width of the Browse in the dynamic SmartDataBrowser based on the columns being displayed by it.
Location: browser.p
Parameters: None
Note: Called by initializeObject.
cancelNew
Procedure that deletes a currently selected NEW row from the Browse’s viewport.
Location: browser.p
Parameters: None
Note: Published from dataSource on cancel of a new row. This works for the case of an SBO where the SDO has no updateSource and the SBO has several. Too much work is involved to have some kind of property to keep track of this. Publish seems to be a more future-proof and dynamic way to do this, as it should also work when supporting multiple/switchable updateSources for SDOs. As the method ensures that this really is new, this should ensure that the query only can have one browse.
cancelRecord
SmartDataBrowser version of cancelRecord. This procedure cancels an Update, Add, or Copy operation. For a cancel of an add or copy, deletes the previously added row from the RowObject temp–table in the associated SmartDataObject, and displays the previously current record again. For a cancel of an update, displays the field values of the previous row again. Sets the value of the NewRecord property back to No.
Location: browser.p
Parameters: None
Notes:  
*Invokes cancelRecord in datavis.p (RUN SUPER).
*Invoked when an update is cancelled, usually by choosing the Cancel button in an Update SmartPanel or the Cancel button or Cancel menu item in a SmartToolbar.
*Customized when additional processing is needed when a record Add, Copy, or Update is cancelled. You might want to do this to restore other related nondatabase fields or other objects to their original values, or to undo some action that was taken when the Add, Copy, or Update was initiated.
colValues
Formats the values in the current row of the SmartDataBrowser query for the specified column list. SmartDataBrowser version of colValues.
Location: browser.p
Parameters:  
INPUT pcViewColList AS CHARACTER
A comma‑separated list of requested columns.
Returns: CHARACTER (Values of the specified columns.)
Notes:  
*Only used when the SmartDataBrowser has its own database query defined.
*Passes back a CHR(1)-delimited list with the RowIdent as the first value in all cases and fields values (in the order they are requested).
copyRecord
Procedure that initiates creation of a new record starting with a copy of the previously displayed record. SmartDataBrowser version of copyRecord.
Location: browser.p
Parameters: None
Notes:  
*Invokes copyRecord in datavis.p (RUN SUPER), which in turn invokes the copyRow function in the associated SmartDataObject to add a new row to the RowObject temp–table.
*For a SmartDataBrowser, a new blank row is inserted below the currently selected one. Values that are copied from copyRecord are not displayed here, they are displayed from the ROW–ENTRY trigger (src/adm2/brsentry.i).
*Sets the BrowseInitted property to FALSE. This property is used in the ROW–ENTRY trigger where the actual display of the copied record takes place to make sure the “initialization logic” for copy is executed once.
*Invoked when a Copy operation is initiated, usually by choosing the Copy button in an Update SmartPanel or in a SmartToolbar.
*Customized when copy needs special processing.
createPopupMenu
This procedure creates the browser’s popup menu.
Location: browser.p
Parameters: None
Notes: None
dataAvailable
SmartDataBrowser version of dataAvailable. This procedure repositions the SmartDataBrowser to a specific row in response to a query reposition in its data source.
Location: browser.p
Parameters:  
INPUT pcRelative AS CHARACTER
Indicates the relative query position in which to reposition. For the current version of dataAvailable, valid values are First, Last, Prev, Next, and Repos. The values Same and Different used by other forms of this procedure are simply passed to the super procedure and do not cause a reposition of the browse.
Notes:  
*You can override the version of dataAvailable in browser.p.
*This routine resides in browser.i rather than browser.p because it must sometimes use query.p, and sometimes datavis.p, as its super procedure, depending on whether the SmartDataBrowser has its own database query.
defaultAction
Procedure that runs persistently from default action.
Location: browser.p
Parameters: None
Note: The trigger is defined in setActionEvent.
deleteComplete
Procedure that deletes the currently selected row from the viewport of the browse when that row has been deleted from the RowObject result set.
Location: browser.p
Parameters: None
Note: Invoked from the SmartDataObject. The SmartDataBrowser is connected to synchronize the viewport with the current contents of the RowObject temp-table being browsed. If the SmartDataBrowser has its own query and is updatable, it is invoked from deleteRecord, which in this case does nothing as the row was already deleted.
deleteRecord
Procedure that deletes the current record. SmartDataBrowser version of deleteRecord. Invoked when the delete button is chosen in an Update SmartPanel or in a SmartToolbar.
Location: browser.p
Parameters: None
Note: Invokes deleteRecord in datavis.p (RUN SUPER), which then runs deleteRow in the associated SmartDataObject to delete the row from the RowObject result set. Makes sure a row is selected in the SmartDataBrowser before deleting the row. Runs deleteComplete when the SmartDataBrowser has its own database query. Typically customized when you want to add a message to confirm the deletion.
destroyObject
SmartDataBrowser version of destroyObject. This procedure invokes the standard behavior in datavis.p and as a result, destroyObject informs the SmartDataObject (and any attached SmartDataBrowser) that it is no longer being browsed.
Location: browser.p
Parameters: None
Note: To ensure that a SmartDataObject can only be browsed by one SmartDataObject at a time, when a SmartDataBrowser is destroyed, destroyObject informs the associated SmartDataObject that it is no longer browsed.
disableFields
Procedure that sets the READ–ONLY attribute of the browse control to TRUE. This is the SmartDataBrowser version of disableFields.
Location: browser.p
Parameters:  
INPUT PcFields AS CHARACTER
Acceptable values: All or Create.
Notes:  
*It is not possible to disable only a subset of columns. The Create option is intended to support disabling fields that are enabled only for an Add or Copy operation; this is not yet supported.
*Sets the FieldsEnabled property to FALSE.
displayFields
Procedure that displays the current row values by moving them to the screen values of the browse. Invokes displayObjects to display the values of any other objects that are in the SmartDataBrowser.
This is the SmartDataBrowser version of displayFields.
Location: browser.p
Parameters:  
INPUT pcColValues AS CHARACTER
CHR(1)‑delimited list of field values. The first entry in the list represents the RowIdent of the row being displayed.
Notes:  
*Ordinarily the columns in each row of a browse are displayed automatically just by the opening of the query with which the browse is associated. Therefore, this procedure is only invoked after changes that have been made to a row are saved or undone, necessitating the displaying the current row again.
*For special display (modifying the value of a column in each row of the browse, for example), use the ROW–DISPLAY trigger of the SmartDataBrowser.
*Runs displayObjects to display any object values that are part of the SmartDataBrowser. These would be additional fields which have been placed into the Frame along with the browse widget.
enableFields
SmartDataBrowser version of enableFields. This procedure enables columns in a SmartDataBrowser by turning off the READ–ONLY attribute for the browse object.
Location: browser.p
Parameters: None
Notes:  
*If no Update target is present, or if no record is available, the columns in the browse are not enabled.
*Customized when you require additional processing when RowObject fields are enabled. You might want to do this to enable or hide other widgets not associated with RowObject fields.
enableObject
This procedure overrides the enableObject method in the Visual class.
Location: browser.p
Parameters: None
Notes: None
fetchDataSet
Procedure that changes or resets the state of a Browse, depending on which action occurs.
Location: browser.p
Parameters:  
INPUT pcState AS CHARACTER
The character value of one of the supported states. Possible values include: BatchStart, BatchEnd, NextStart, NextEnd, PrevStart, PrevEnd.
Note: Used internally to turn on/off the REFRESHABLE attribute of the browse. Used to avoid flashing when batches of records are fetched, or to apply the SET–REPOSITIONED–ROW method to the browse.
filterActive
Procedure that calls updateState in the toolbar to set the filter on or off, depending on the argument.
Location: browser.p
Parameters:  
INPUT plActive AS LOGICAL
TRUE if the filter tick is to be turned on.
Notes: None
hasActiveAudit
If there is a valid DataSource, returns the result of hasActiveAudit.
Location: browser.p
Parameters: None
Returns: LOGICAL
Notes: None
hasActiveComments
If there is a valid DataSource, returns the result of hasActiveComments.
Location: browser.p
Parameters: None
Returns: LOGICAL
Notes: None
initializeColumnSettings
This procedure is called from initializeObject to initialize the column settings and browser properties. It sets the FieldHandles and EnabledHandles properties.
Location: browser.p
Parameters: None
Notes: None
initializeObject
SmartDataBrowser version of initializeObject. Part of the general initialization process, this procedure sets certain property values.
Location: browser.p
Parameters: None
Notes:  
*Invokes initializeObject in datavis.p (RUN SUPER).
*Starting with Version 9.1A, dynamically creates columns of the SmartDataBrowser when the Dynamic SmartDataBrowser is used.
*For a SmartDataBrowser that is connected to a SmartDataObject as its Data source, sets the DataQueryBrowsed property to TRUE indicating the SmartDataObject is being browsed, and preventing it from being browsed by more than one SmartDataBrowser at a time.
*Sets the value of EnabledHandles, CreateHandles and FieldHandles property.
*Might create a Search Field for searching in the SmartDataBrowser if the corresponding SearchField property is set.
launchFolderWindow
Procedure that calls launchContainer in the session manager to start a folder window, if there is not already one available.
Location: browser.p
Parameters:  
INPUT pcContainerMode AS CHARACTER
Notes: None
linkStateHandler
This override of the Smart class method runs a profile sorrt before the SDO initializes.
Location: browser.p
Parameters:  
INPUT pcState AS CHARACTER
INPUT phObject AS HANDLE
INPUT pcLink AS CHARACTER
Notes: None
offEnd
Procedure that fires trigger code for OFF-END trigger of SmartDataBrowse.
Location: browser.p
Parameters: None
Notes: None
offHome
Procedure that fires trigger code for OFF-HOME trigger of SmartDataBrowse.
Location: browser.p
Parameters: None
Notes: None
onEnd
Event procedure for the END event. This procedure uses the QueryPosition property of the dataSource to determine whether the position is already last or whether fetchLast needs to be called in the dataSource.
Location: browser.p
Parameters: None
Note: This event must call fetchLast in the dataSource for the normal case when it is a TRUE user event. However, APPLY END must be used to make the browse respond to a fetchLast in the dataSource. When using APPLY END, QueryPosition is already set in the dataSource and can be used to avoid an extra or endless loops.
onHome
Event procedure for the HOME event. This procedure uses the QueryPosition property of the dataSource to determine whether the position is already first or whether fetchFirst needs to be called in the dataSource.
Location: browser.p
Parameters: None
Notes: None
onValueChanged
Event procedure for the browse VALUE-CHANGED event. Because it fires from the VALUE-CHANGED trigger, it only runs when a user changes the row in the browse (or as a backfire from home and end events). It does not run in all cases where a record is changed.
Location: browser.p
Parameters: None
Notes:  
*The event procedure which fires for value changes in the fields is valueChanged in the Datavis class.
*This event should NOT be overriden as a place to trap change of record. DataAvailable is the event that traps the change of record.
refreshBrowse
Procedure that publishes from dataSource when APPEND display is not enough or not required.
Location: browser.p
Parameters: None
Notes: None
refreshQuery
This procedure refreshs the browse query and repositions it to the currently selected row.
Location: browser.p
Parameters: None
Notes: None
resizeBrowse
Procedure that changes the size of the BROWSER WIDGET-HANDLE IN APPEND SmartDataBrowser.
Location: browser.p
Parameters:  
INPUT pd_height AS DECIMAL
The desired height (in rows).
INPUT pd_width AS DECIMAL
The desired width (in columns).
Notes: None
resizeObject
Procedure that changes the size of the SmartDataBrowser.
Location: browser.p
Parameters:  
INPUT pdHeight AS DECIMAL
A decimal value that represents the new height of the SmartDataBrowser.
INPUT pdWidth AS DECIMAL
A decimal value that represents the new width of the SmartDataBrowser.
Notes:  
*Invoked at design time when the SmartDataBrowser is resized. Can be invoked at run time to change the size of the SmartDataBrowser.
*The presence of the resizeObject procedure causes the AppBuilder to generate a statement in the adm–create–objects procedure for a SmartContainer setting the size of a contained SmartDataBrowser. The presence of resizeObject also signals the AppBuilder to allow the SmartDataBrowser to be resized at design time.
rowDisplay
Event Handle procedure for the ROW-DISPLAY event.
Location: browser.p
Parameters: None
Notes: None
rowEntry
Event Handle procedure for the ROW-ENTRY event. This procedure retrieves and displays initial values for Add or Copy.
Location: browser.p
Parameters: None
Notes: None
rowLeave
Event Handle procedure for the ROW-LEAVE event. If the selected object is not a SmartPanel button, this procedure saves any changes to the row. Otherwise, the appropriate action for the button occurs.
Location: browser.p
Parameters: None
Notes: None
rowVisible
Determines if the records currently visible in the browse are the first or last records in the batch.
Location: browser.p
Parameters:  
INPUT pcRowids AS CHARACTER
Comma-separated list of ROWIDs that are currently visible.
INPUT phQryBuffer AS HANDLE
Returns: CHARACTER
Notes: None
searchTrigger
Procedure that contains the logic to support the SearchField property of the Dynamic SmartDataBrowser. The SmartDataBrowser repositions to the first record that is greater than or equal to the value entered in the SearchField.
Location: browser.p
Parameters: None
Note: In the Data source connected to the SmartDataBrowser, searchTrigger Invokes in the following order the columnDataType, rowidWhere, and fetchRowIdent functions to reposition to a corresponding record.
showSort
This function adds a sort arrow to the browser column reflecting the current sort in the datasource.
Location: browser.p
Parameters: None
Returns: LOGICAL
Note: ABL allows showing multiple sort columns with a sort number. However, this function currently shows only the first column in the sort expression, since there is no default support to manipulate the secondary sort.
startSearch
Procedure that launches the start-search trigger.
Location: browser.p
Parameters:  
INPUT phBrowse AS HANDLE
The browse handle.
Note: Because persistent triggers have early binding, current-column cannot be passed in.
stripCalcs
Strips the expression portion of expression @ variable.
Location: browser.p
Parameters:  
INPUT cClause AS CHARACTER
The clause to be edited.
Returns: CHARACTER
Notes: None
toolbar
Procedure that performs one of several operations depending on the value of the argument passed. Valid values are: comments; export for exporting data to Excel; preview for previewing a report; filter or find to launch a filter window; view, copy, modify, or add to launch the appropriate folder window; delete to delete a record with autocommit; and audit.
Location: browser.p
Parameters:  
INPUT pcValue AS CHARACTER
The type of operation.
Notes: None
updateRecord
SmartDataBrowser version of updateRecord. This procedure initiates the Save process after an add, copy, or update. This version of updateRecord stores the RowIdent property of the current record if it is an add or a copy.
Location: browser.p
Parameters: None
Notes:  
*Invokes updateRecord in datavis.p (RUN SUPER).
*If an error occurs after invoking updateRecord in datavis.p (which means the update failed), updateRecord puts focus back in the SmartDataBrowser if it is not already there.
*If the SmartDataBrowser has its own database query, and if the save operation comes after an add or a copy, the SmartDataBrowser’s query is reopened and repositioned to the last row of the viewport.
updateState
Procedure that receives state messages on updates. Enables or Disables the SmartDataBrowser while updates are made to other objects sharing the same SmartDataObject. SmartDataBrowser version of updateState.
Location: browser.p
Parameters:  
INPUT PcState AS CHARACTER
The update state value to be passed to the SmartDataBrowser. Valid values are UpdateBegin, Update, and UpdateComplete.
Notes:  
*Possible input values are UpdateBegin, Update, and UpdateComplete.
*Returns if the DataModified property equals TRUE (meaning updates are in progress), or if the NewRecord property is not equivalent to No (which means add or copy).
*Used internally.
updateTitle
Procedure for the SmartDataBrowser version of updateTitle.
Location: browser.p
Parameters: None
Note: Setting up a window title for an object controller is different than for a viewer. This code gets the information from the browser’s data-sources.
viewObject
Procedure that overrides run setDown to set the DOWN attribute for the browse when it is being viewed and to fix problems caused by the browse’s implicit visualization behavior.
Location: browser.p
Parameters: None
Notes:  
*setDown must be called from viewObject as opposed to initializeObject to support the object being on a page other than zero, because set down requires a visible browse. This sets DOWN when the object is actually being viewed rather than when it is initialized, which could happen before it is viewed if it is on a page other than zero.
*The browser implicitly sets the buffer to its currently selected row when it is visualized. This might cause problems if the DataSource is being manipulated by another object. An update-target might have called AddRow in the DataSource, which creates a RowObject while the browse still has the old row selected.