skip to main content
OpenEdge Development: ADM Reference
Visual Objects and Their Methods and Properties : Methods for data visualization objects
 
Methods for data visualization objects
The following section describes the data visualization methods for visual objects.
addRecord
Procedure that initiates the creation of a new record. First verifies that there is no update pending. If there is an update pending, notifies the user that current values must be saved or cancelled before the Add operation takes place, then it displays initial values.
Location: datavis.p
Parameters: None
Notes:  
*Publishes updateState Update to signal related objects that the update is in progress.
*Sets the NewRecord property to Add.
*Invokes enableFields. The addRow method in the associated SmartDataObject is invoked at a lower level (from addRecord in viewer.p for a SmartDataViewer or in browse triggers for a SmartDataBrowser).
*Is 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).
cancelObject
Procedure that passes a cancel request to its container.
Location: datavis.p
Parameters: None
Notes:  
*The convention is that the standard routine always passes an cancel, OK, or exit request to its CONTAINER-SOURCE. The container that is actually able to initiate the cancel should override this and not call SUPER.
*Is customized when additional processing is needed in the visual SmartObject 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. If you want to customize the Add operation for the SmartDataObject that manages the table being shown in the visualization, you can override addRow to customize the processing at the time the new row is added to the RowObject temp–table, or override submitRow to customize the saving of the newly added row.
Examples:  
PROCEDURE addRecord:
  /* Code placed here will execute PRIOR to standard behavior. */
  RUN SUPER.
  /* Code placed here will execute AFTER standard behavior. */
 
  iRecTotal = iRecTotal + 1.
  DISPLAY iRecTotal WITH FRAME {&FRAME-NAME}.
END PROCEDURE.
cancelRecord
Procedure that cancels an Update, Add, or Copy operation. For a cancel of an add or copy, resets the fields in their previous state. If no record was available before the add, the fields are disabled.
Location: datavis.p
Parameters: None
Notes:  
*Invokes the cancelRow() function in the update target of the visualization to delete the row created for add or copy.
*When you choose the Cancel button during:
*Add or Copy — The new record is erased and the previously current record is displayed again.
*Update — The Update is cancelled and the record’s original values are displayed.
*Invoked when an update is cancelled, usually by choosing the Cancel button in an Update SmartPanel or the Cancel button.
*Sets DataModified property FALSE.
*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.
canNavigate
Returns TRUE if the object can allow a navigation.
Location: datavis.p
Parameters: None
Returns: LOGICAL
Notes:  
*An object cannot navigate if there are uncommitted or unsaved changes in the updateTarget or unsaved changes in any of the Datatargets of the updatetarget. - The check is used as rule for enabling of toolbar actions. This includes delete and add / copy as navigation is an implicit result of these actions on the client.
*See details in the data.p canNavigate.
collectChanges
Procedure that collects the screen values and assigns them to the appropriate record. Values are collected as a character value of a list form.
Location: datavis.p
Parameters:  
INPUT-OUTPUT pcChanges AS CHARACTER
A CHR(1)‑delimited list made of changed fields and their corresponding value.
INPUT-OUTPUT pcInfo AS CHARACTER
A comma‑delimited list with three entries per object containing the number of fields changed, the page number of the object, and its handle. This allows the proper page to be viewed and focus applied to the proper field in the event of an error.
Notes:  
*collectChanges is invoked from updateRecord and published to any GroupAssign target.
*The collectChanges procedure is not intended to be run from application code. If validation of modified field values is required, this should generally be done using one of the methods in the SmartDataObject (under submitRow), rather than in the associated visualization.
*Only values of fields that are modified are collected. (The MODIFIED attribute is used to determine if the field is modified or not.)
*Use the ModifyFields property to control from which fields to collect values. See the “ModifyFields” section for more information.
confirmCancel
Procedure that verifies that no data is lost before allowing its container to initiate a destroy operation.
Location: datavis.p
Parameters:  
INPUT-OUTPUT plError AS LOGICAL
If TRUE on output, there is a problem and you should cancel the destroy operation.
Note: The name confirm is used as it is in family with the other confirm methods, but this does not ask any questions.
confirmCommit
Procedure that checks to be sure there are no unsaved changes before allowing the data-source to start a commitTransaction operation.
Location: datavis.p
Parameters:  
INPUT-OUTPUT plCancel AS LOGICAL
Returns TRUE if the transaction can be committed.
Notes: None
confirmContinue
Checks to make sure there are no unsaved or uncommitted data changes before allowing its data-source to start an Apply filter operation.
Location: datavis.p
Parameters: None
Returns: LOGICAL
Notes: None
confirmDelete
Procedure that allows you to force the user to confirm a pending deletion so that it can be aborted if not intended.
Location: datavis.p
Parameters:  
INPUT-OUTPUT plAnswer AS LOGICAL
Notes: None
confirmExit
Data visualization version of confirmExit. This procedure checks the value of the DataModified and RowObjectState properties to make sure there are not unsaved or uncommitted changes before allowing its container to initiate a Destroy operation.
Location: datavis.p
Parameters:  
INPUT plCancel AS LOGICAL
If field values have been modified and not saved, it returns TRUE and the destroyObject is cancelled.
Notes:  
*Invoked from destroyObject and confirmExit itself.
*A SmartContainer publishes this event to all its container targets before initiating destroyObject. If data are modified in one of its container targets, the destroyObject is cancelled.
*The first object where updates are uncommitted displays the message “Unsaved changes. Exit operation cancelled.”
*Used internally. Could be customized to add additional checks before allowing an Exit, or to modify the message displayed.
confirmOk
Procedure that verifies unsaved changes are saved and uncommitted data is committed before allowing its container to carry out a destroy operation.
Location: datavis.p
Parameters: None
Note: The name confirm is used as it is in family with the other confirm methods, but this does not ask any questions.
confirmUndo
Procedure that checks to make sure there are no unsaved changes before allowing its data-source to start an undoTransaction operation.
Location: datavis.p
Parameters:  
INPUT-OUTPUT plCancel AS LOGICAL
Returns TRUE if the transaction can be undone.
Notes: None
copyRecord
Procedure that initiates creation of a new record, starting with a copy of the previously displayed record.
Location: datavis.p
Parameters: None
Notes:  
*copyRow() is invoked in the update target, which creates the new RowObject temp-table record and copies the current row to it.
*Displays the previously displayed record’s values and allows data entry. The new record is not actually created until it is committed in serverCommit. See the addRecord reference entry for additional notes.
*Sets NewRecord property to Copy.
*Invoked when a Copy operation is initiated, usually by choosing the Copy button.
*Customized when copy needs special processing.
dataAvailable
Data visualization version of dataAvailable. Procedure that requests that data columns be displayed in the Data source that the data visualization object is connected to, and displays them.
Location: datavis.p
Parameters:  
INPUT pcRelative AS CHARACTER
A flag that signals whether this is a different row than was previously sent; this version of dataAvailable does not care; it displays the row in any case.
Notes:  
*Invoked whenever the Data source has a new row.
*Invokes colValues( ) in its Data source and displayFields in itself to display the data.
*Parallel to row–available for Version 8 SmartViewers.
deleteRecord
Procedure that initiates the deletion of the current record in the associated SmartDataObject. Invoked when the delete button is chosen in an Update SmartPanel or in a SmartToolbar.
Location: datavis.p
Parameters: None
Note: Invokes deleteRow( ) in the update target the data visualization object is connected to. If the deleteRow( ) fails, error messages are displayed by invoking showDataMessages( ). Typically customized when you want to add a message to confirm the deletion.
Example:  
PROCEDURE deleteRecord:
  /* Purpose:     Super Override*/
 
  /* Code placed here will execute PRIOR to standard behavior. */
  MESSAGE “Are you sure you want to delete this record?”
    VIEW-AS ALERT-BOX QUESTION BUTTONS YES-NO
  UPDATE lAnswer AS LOGICAL.
  IF lAnswer THEN 
    RUN SUPER.
 
  /* Code placed here will execute AFTER standard behavior. */
END PROCEDURE.
disableFields
Procedure that sets the View for ObjectMode.
Location: datavis.p
Parameters: None
Note: Viewer and browser classes have complete override for disabling. The ObjectMode is also set in updateMode, but users might call this directly.
displayObjects
Procedure that displays values for nondatabase-related fields.
Location: datavis.i
Parameters: None
Notes:  
*Invoked from displayFields.
*Displays the values of the fields that are listed in the AppBuilder-maintained preprocessor variable {&DISPLAYED–OBJECTS}. These are fill-ins and other frame fields that are not associated with fields in the associated SmartDataObject.
*This procedure is located in the datavis.i include file rather than the super procedure datavis.p in order to provide access to the DISPLAYED–OBJECTS preprocessor value. Therefore, to override this procedure, it is necessary to define a local version of displayedObjects in an individual visual SmartObject and then define the EXCLUDE–displayedObjects preprocessor, which removes the standard version from the compilation.
displayRecord
Procedure that displays the rows for the current data source.
Location: datavis.p
Parameters: None
Notes: None
enableFields
Procedure that sets ObjectMode to Modify if the value is not Update.
Location: datavis.p
Parameters: None
Note: Viewer and browser classes have complete override for enabling. The ObjectMode is also set in updateMode, but users might call this directly.
fieldModified
This procedure runs whenever a field is modified. It sets DataModified to TRUE unless the ModifyFields property is specifed to ignore the field.
Location: datavis.p
Parameters:  
INPUT phField AS HANDLE
Handle of the field whose value has changed.
Notes:  
*The passed field must be in the EnabledFields or EnabledObjFlds list.
*This procedure is called from valueChanged, SDF's setDataModified, or client APIs that change widget values.
initializeObject
Data visualization version of initializeObject. Procedure that performs initialization appropriate to visual objects that display data values. Part of the general initialization process. Sets certain property values and displays if any nondatabase-related fields.
Location: datavis.p
Parameters: None
Notes:  
*Invokes initializeObject in smart.p (RUN SUPER), first.
*Sets the value of EnabledHandles, CreateHandles, and FieldHandles property.
*Disables any associated Update SmartPanel or SmartToolbar it is connected to if no Update target is present.
*Invokes displayObjects to display nondatabase fields that might be present in the data visualization object.
IsUpdateActive
Procedure that is received from container source to check whether contained objects have unsaved or uncommitted changes, including addMode.
Location: datavis.p
Parameters:  
INPUT-OUTPUT plActive AS LOGICAL
This is published thru the container link and is used for close logic (ok, cancel, exit). It is very similar to canNavigate->isUpdatePending which is published thru the data link. This can be called directly, but canExit() is the intended API. canExit() is used to check an actual container from the toolbar.
Notes: None
linkStateHandler
Procedure that refreshes visual data targets.
Location: datavis.p
Parameters:  
INPUT PARAMETER pcState AS CHARACTER
INPUT PARAMETER phObject AS HANDLE
INPUT PARAMETER pcLink AS CHARACTER
Note: This version of linkStateHandler is different from the version in data.p in that queryPosition must be run in addition to dataAvailable to pass the passed QueryPosition property of the data source.
okObject
Procedure that passes an OK request to its container.
Location: datavis.p
Parameters: None
Note: The convention is that the standard routine always passes an cancel, ok, or exit request to its CONTAINER-SOURCE. The container that is actually able to initiate the OK should override this and NOT call SUPER.
okToContinueProcedure
Procedure that checks whether the visual object has modified screen data or its data-source has uncommitted changes. If either of these conditions is TRUE we issue Yes-No-Cancel questions allowing the user to choose how to proceed. The choices are: save/commit and continue; cancel/undo and continue; not continue.
Location: datavis.p
Parameters:  
INPUT pcAction AS CHARACTER
Used to retrieve the correct message. Valid values are:
*Exit — Exit/close application window.
*‘ ’ (the empty string) — Continue.
*Commit — Commit (yes, no, cancel).
*Undo — Undo (no save option).
*OK — No question: save and commit.
*Cancel — No question: cancel and undo.
OUTPUT plAnswer AS LOGICAL
The user’s response to the question, if any.
Note: confirmExit and confirmOpenQuery call this function. This is copied from okToContinue function in datavis.p for use with Progress Dynamics.
queryPosition
Procedure that captures state events for the associated query in the object’s data source.
Location: datavis.p
Parameters:  
INPUT pcState AS CHARACTER
Possible values are: FirstRecord (first record); NotFirstOrLast (not the first or last record); LastRecord (last record); NoRecordAvailable (no record); OnlyRecord (only one record).
Notes:  
*When any state begins with NoRecordAvail, it means to disable; all others (FirstRecord, NotFirstOrLast, LastRecord, OnlyRecord) mean to enable if in Save mode (SaveSource property is set to yes).
*Sets the RecordState property to NoRecordAvailable when the state is equivalent to that; but for any other state, sets the value to RecordAvilable.
resetRecord
A general code for reset operation. This procedure displays the original field values retrieved from the SmartDataObject by invoking the colValues() function for the fields that are displayed.
Location: datavis.p
Parameters: None
Notes:  
*Invoked when the Reset button is pressed on an Update SmartPanel or a SmartToolbar.
*Publishes resetRecord in the case of a GroupAssign. Sets DataModified property to the Unknown value (?).
showDataMessages
Returns the name of the field (if any) from the first error message. Allows the caller to use it to position the cursor.
Location: datavis.p
Parameters: None
Returns: CHARACTER
Note: Invokes fetchMessages() to retrieve all Data-related messages (normally database update-related error messages), and displays them in an alert-box of type error. This function expects to receive back a single string from fetchMessages with one or more messages delimited by CHR(3), and within each message the message text, Fieldname (or blank) + a Tablename (or blank), delimited by CHR(4), if present.
showDataMessagesProcedure
Procedure that replaces the showDataMessages function. Returns the name of the field (if any) from the first error message, to allow the caller to use it to position the cursor. A Progress Dynamics procedure that uses Progress Dynamics message handling routines.
Location: datavis.p
Parameters:  
OUTPUT pcReturn AS CHARACTER
Notes:  
*Invokes fetchMessages() to retrieve all Data-related messages (normally database update-related error messages), and displays them in a alert-box of type error.
*This function expects to receive back a single string from fetchMessages with one or more messages delimited by CHR(3), and within each message the message text, Fieldname (or blank) + a Tablename (or blank), delimited by CHR(4) if present.
undoChange
This procedure undoes the last change. The precedence for undoing changes is as follows:
1. Undo changes to current screen values.
2. Undo the unsaved new record created by an Add or Copy, if this option is enabled for the current object.
3. Undo any stored changes for the selected record.
Location: datavis.p
Parameters: None
Notes: None
undoRecord
This procedure undoes a saved record. It calls undoRow if the record is modified and deleteRow if the record is newly created.
Location: datavis.p
Parameters: None
Notes: None
updateMode
Procedure that enables or disables fields when the data visualization object is linked to an Update SmartPanel for which the type is Update.
Location: datavis.p
Parameters:  
pcMode AS CHARACTER
Update mode possible values are:
*updateBegin — Signals that the user has pressed the update button.
*updateEnd — Signals that the user has pressed the save button.
Note: UpdateBegin signals that the Update button has been pressed in an Update SmartPanel in Update mode. Enable fields for data entry. updateEnd signals that Save has completed; disable fields. update-begin was a state msg in V8. updateEnd corresponds to the save button dispatching disable-fields in V8.
updateRecord
Procedure that receives a Save message from a TableIO source and sends the changed values back to the SmartDataObject. General code to start the save operation.
Location: datavis.p
Parameters: None
Note: Invoked when the Save button is pressed on an Update SmartPanel or a SmartToolbar. PUBLISHes “collectChanges” to gather changes made eventually in any GroupAssign target. Invokes submitRow() in the Data source that actually applies the changes to the database. If any validations failed or errors occurred during the save operation for a field, it brings up the page where the field is, if necessary, and repositions to it.
updateState
Procedure that receives the updateState event (for example, from a GroupAssign target) and sets its own DataModified property accordingly (which in turn passes on the updateState event).
Location: datavis.p
Parameters:  
INPUT pcState AS CHARACTER
pcState AS CHARACTER update state Possible values are:
*Update — Signals that update is in progress.
*Complete — Signals that update is terminated.
Notes: None
validateFields
Procedure that validates a field in a data-display object.
Location: datavis.p
Parameters:  
INPUT-OUTPUT pcNotValidFields AS CHARACTER
Valid values on output are:
*The empty string, if validation succeeded.
*A comma-separated list of the fieldname, object handle and page, if validation failed.
The updateRecord routine uses this output value to set focus.
Notes:  
*Called from updateRecord to ensure that data can be saved.
*Field validation on leave cannot be trusted because save can be triggered by accelerators and no-focus buttons (toolbar).
*Currently, only one error is handled. Validate() on hidden objects does not give any message.
*Validation always checks unmodifed fields. This is useful for add/copy but not otherwise, as those fields are not saved.
valueChanged
This procedure captures the VALUE-CHANGED event of all field changes in the object's frame and passes the handle on to the fieldModified procedure.
Location: datavis.p
Parameters: None
Notes: None
You can extend the base visual object to filter what it displays. The following section lists the functions and procedures for SmartFilter objects.