skip to main content
OpenEdge Development: ADM Reference
Visual Objects and Their Methods and Properties : Base methods for visual objects
 
Base methods for visual objects
This section describes the base methods for visual objects.
applyLayout
Procedure that applies the Master or an alternate layout for a SmartObject that has multiple layouts.
Location: visual.p
Parameters: None
Notes:  
*applyLayout is invoked from initializeObject to set the correct layout during SmartObject initialization. Runs the Layout procedure to apply the Master layout if it is already current (in order to reset the user interface to its original state), and then runs the Layout procedure (determined by the LayoutVariable property that is storing the LAYOUT–VARIABLE preprocessor value) to apply the new layout.
*applyLayout can be customized when special processing is needed to change layouts.
assignFocusedWidget
Sets focus to the named object. Not supported for SmartDataFields and returns FALSE if attempted for SmartDataFields.
Location: visual.p
Parameters:  
INPUT name AS CHARACTER
The name of a single Progress Dynamics object.
Returns: LOGICAL
Notes: None
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
IF widgetIsModified("name":U) THEN 
  assignFocusedWidget("description":U).
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
if (logic.widgetIsModified(‘orderviewv.name’))
  logic.assignFocusedWidget(‘orderviewv.description’);
assignWidgetValue
Takes the name of one object and a character screen value as input and sets the SCREEN-VALUE of the object. The DataValue is set for a SmartDataField. (This would always be the key field for a lookup even when the display field is different.)
Location: visual.p
Parameters:  
INPUT name AS CHARACTER
The name of a single Progress Dynamics object.
INPUT value AS CHARACTER
A string representing the intended screen value of the widget.
Returns: LOGICAL
Notes:  
*Sets DataModified to make the toolbar enable saving data (it behaves as if the user actually changed the field value manually).
*Sets DataModified to TRUE whether or not the field is enabled.
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
assignWidgetValue("Browse.Status":U, "Shipped":U).
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
logic.assignWidgetValue(‘orderfullo.browse.status’,’Shipped’);
assignWidgetValueList
Takes the name of one or more objects and character screen values and a delimiter as input and sets the SCREEN-VALUE of the objects. The DataValue is set for a SmartDataField (this would always be the key field for a lookup even where the display field is different).
This function sets the DataModified attribute to force the toolbar to enable saving data (it behaves as if the user actually changed the field value manually). The DataModified attribute is set to TRUE whether the field is enabled or not.
Location: visual.p
Parameters:  
INPUT namelist AS CHARACTER
The name of one or more objects, separated by commas.
INPUT valuelist AS CHARACTER
A string representing the intended screen values for one or more widgets separated by the specified or default delimiter.
If the name list contains more than one object, then the value list must be either a single value, which will be applied to each field in the name list, or it must be a list of an equal number of entries to the name list, in which case the values are assigned to the corresponding object names. If there is more than one entry in the value list and the number of entries in the namelist and the number of entries in the value list do not match, nothing is done and FALSE is returned. If any assignments fail because the widget is not found, FALSE is returned but it still processes through the list and assigns those that it can.
INPUT delimiter AS CHARACTER
(Optional) Specifies the delimiter to use for the value list. Specify the Unknown value (?) to use the default delimiter, which is the pipe character (“|”).
Returns: LOGICAL
Note: For the DHTML client, the delimiter is optional as the third parameter. If it is not specified, the function uses the default, which is the pipe symbol (“|”).
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
:
assignWidgetValueList("city,state":U, "Boston|MA":U, ?).
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
lRet=logic.assignWidgetValueList('customerviewv.name,customerviewv.city',
'Reeds Ferry|Nashua');
blankWidget
Blanks the SCREEN-VALUE of the objects in the namelist. The DataValue is blanked for a SmartDataField (this would always be the key field for a lookup even where the display field is different).
Location: visual.p
Parameters:  
INPUT namelist AS CHARACTER
The name of one or more objects, separated by commas.
Returns: LOGICAL
Notes:  
*This function sets the DataModified attribute to force the toolbar to enable saving data (it behaves as if the user actually changed the field value manually).
*This function does nothing to objects that do not support SCREEN-VALUE and to objects where a blank screen value does not make sense, such as toggle boxes. It blanks a combo-box by setting its list items to its list items.
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
IF widgetIsTrue("customerviewv.disableAccount":U) THEN
 blankWidget("Self.accountID":U).
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
if (logic.widgetIsTrue(‘customerviewv.disableAccount’))
  logic.blankWidget(‘myviewv.accountID’); 
disableObject
Procedure that disables all enabled objects in a frame, including RowObject fields.
Location: visual.p
Parameters: None
Notes:  
*disableObject invokes disableFields to disable RowObject fields. In addition, it disables objects in the frame that are not mapped to RowObject fields, which the disableFields procedure does not do. This allows applications to distinguish between disabling data-related fields (because no row is available for display or for some other reason) from disabling the entire object and all fields in its frame.
*disableObject can be customized when additional processing is needed when a SmartObject is disabled. You might do this to selectively re-enable selected widgets in the SmartObject based on the application state or to disable other related widgets.
disableRadioButton
Disables the specified radio button of the radio set objects identified in the namelist. Returns FALSE if a widget in the list is not a radio-set, if a widget in the list is not found, or if the button number is invalid.
Location: visual.p
Parameters:  
INPUT namelist AS CHARACTER
The name of one or more radio-set objects, separated by commas.
INPUT buttonNum AS INTEGER
The numerical ID of a radio button in a particular radio set.
Returns: LOGICAL
Note: This API is not supported by the DHTML client.
Example:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
IF widgetIsTrue("shipped":U) THEN
 disableRadioButton("shippingTrans":U, 2).
disableWidget
Disables the object or objects identified in the namelist.
For SmartDataFields, it runs the disableField function. disableField is not a generic SmartDataField function, therefore this API is only supported for SmartDataFields that have disableField defined. If a field in the list is not found, or a SmartDataField without disableField is included in the list, disableWidget returns FALSE.
Location: visual.p
Parameters:  
INPUT namelist AS CHARACTER
The name of one or more objects, separated by commas.
Returns: LOGICAL
Notes:  
*Data fields are removed from the EnabledFields and EnabledHandles properties to ensure that once the field is disabled by the API, it remains disabled.
*Local fields are removed from the EnabledObjFldsToDisable property when the property is set to a field list. When the EnabledObjFldsToDisable property is set to (All), the disableWidget function sets this property to the value of the EnabledObjFlds property without the field being disabled. This action ensures that once a field is disabled by the API, it remains disabled. When the EnabledObjFldsToDisable property is set to (None), it is not changed.
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
:
IF widgetValue("Browse.Terms":U) NE "":U THEN
 disableWidget("Self.Discount":U).
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
if (logic.widgetValue(‘orderfullo.browse.terms’)!=’’)
  logic.disableWidget(‘customerviewv.discount’);
enableObject
Procedure that enables an object. Includes all components except RowObject fields. They are enabled using EnableFields().
Location: visual.p
Parameters: None
Notes:  
*enableObject is invoked from initializeObject to enable a SmartObject (different from when a SmartObject’s RowObject fields are enabled with enableFields).
*You can customize enableObject when a SmartObject is enabled, perhaps for initialization that is needed each time a SmartObject is enabled, or to enable other related SmartObjects.
*enableObject and disableObject are not completely opposite in their effects. disableObject always invokes disableFields because it is not meaningful to have a SmartObject disabled while RowObject fields inside it are enabled. On the other hand, enableObject does not invoke enableFields; this is done separately to allow enabling of a SmartObject’s RowObject fields independently of other basic widgets it contains.
enableRadioButton
Enables the specified radio button of the radio set objects identified in the name list. Returns FALSE if a widget in the list is not a radio-set, if a widget in the list is not found, or if the button number is invalid.
Location: visual.p
Parameters:  
INPUT namelist AS CHARACTER
The name of one or more radio-set objects, separated by commas.
INPUT buttonNum AS INTEGER
The numerical ID of a radio button in a particular radio set.
Returns: LOGICAL
Note: This API is not supported by the DHTML client.
Example:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
IF NOT widgetIsTrue("shipped":U) THEN
 enableRadioButton("shippingTrans":U, 2).
enableWidget
Enables the object or objects identified in the name list. For SmartDataFields, it runs the enableField function. Note that enableField is not a generic SmartDataField function, therefore this API is only supported for SmartDataFields that have enableField defined. If a field in the list is not found, or a SmartDataField without enableField is included in the list, enableWidget returns FALSE.
Location: visual.p
Parameters:  
INPUT namelist AS CHARACTER
The name of one or more objects, separated by commas.
Returns: LOGICAL
Notes:  
*Data fields are added to the EnabledFields and EnabledHandles properties to ensure that once the field is enabled by the API, it remains so enabled.
*Local fields are added to the EnabledObjFldsToDisable property when the property is not set to (None) or (All). This action ensures that once a field is enabled by the API, it remains enabled. It could also result in adding a field that was not included in the EnabledObjFldsToDisable property initially to the property by a call to this API. If this behavior is not desired, do not use the enableWidget function or manipulate the EnabledObjFldsToDisable property after using the function to remove the field.
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
IF widgetIsModified("customerviewv.discount":U) THEN
 enableWidget("Self.terms":U).
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
if (logic.widgetIsModified(‘customerviewv.discount’))
  logic.enableWidget(‘orderviewv.terms’);
formattedWidgetValue
Returns the SCREEN-VALUE of the object, or in the case of a browse column when in a ROW-DISPLAY trigger, the STRING-VALUE from the RowObject buffer field. The DataValue is returned for a SmartDataField (this would always be the key field for a lookup even where the display field is different). For example, you could use this function to get the formatted value of a single field to use for comparisons.
Location: visual.p
Parameters:  
INPUT name AS CHARACTER
The name of a single Progress Dynamics object.
Returns: CHARACTER
Notes: None
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
IF formattedWidgetValue("orderviewv.ordernum":U) > cNumber THEN … 
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
if (logic.formattedWidgetValue(‘orderviewv.ordernum’)>cNumber) …
formattedWidgetValueList
Takes the name of one or more objects and returns the SCREEN-VALUE of the object or objects. For example, use this function to retrieve the formatted values of several fields to assign their screen values to other fields.
If the object is a browse column (called from within a ROW-DISPLAY trigger), the STRING-VALUE from the RowObject buffer field is added to the list of returned values.
If the object is a SmartDataField, the DataValue field is returned. The DataValue field is always the key field, even when the display field is different.
If a field in the list is not found or a field has an unknown value, the function returns the Unknown value (?) for its value in the returned character list.
Location: visual.p
Parameters:  
INPUT namelist AS CHARACTER
The name of one or more objects, separated by commas.
INPUT delimiter AS CHARACTER
(Optional) Specifies the delimiter to use for the return value only. Specify the Unknown value (?) to use the default delimiter, which is the pipe character (“|”).
Returns: CHARACTER
Note: Use the pipe (“|”) delimiter in the DHTML client, since manipulating unprintable characters such as CHR(3) is problematic. The delimiter is optional. If not specified it defaults to the pipe delimiter.
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
ASSIGN
 cValues = formattedWidgetValueList("salesrepviewv.region,county,city":U, CHR(3))
 cCounty = ENTRY(2, cValues, CHR(3)).
assignWidgetValue("county":U, cCounty). 
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
cvalues=logic.formattedWidgetValueList(‘salesrepviewv.region, salesrepviewv.city’,’|’);
hideWidget
Hides the object or objects identified in the namelist (and their popup buttons). For SmartDataFields, it invokes the hideObject method.
Location: visual.p
Parameters:  
INPUT namelist AS CHARACTER
The name of one or more objects, separated by commas.
Returns: LOGICAL
Notes: None
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
IF widgetIsTrue("Self.Current":U)THEN
 hideWidget("Browse.Balance":U).
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
if (logic.widgetIsTrue(‘familyviewv.coveredonbenefits’))
  logic.hideWidget(‘customerfullo.browse.balance’);
highlightWidget
Sets the background and foreground colors (FGCOLOR and BGCOLOR widget attributes) of the named object or objects to a standard highlight color, depending on the value of the highlightType argument. For example, you may want to change the background color of a field with an invalid value to red.
Location: visual.p
Parameters:  
INPUT namelist AS CHARACTER
The name of one or more objects, separated by commas.
INPUT highlightType AS CHARACTER
Determines the color values applied to the FGCOLOR and BGCOLOR widget attributes. Table 3–1 shows the valid values of this parameter map to certain attributes of the visual class.
 
Table 3–1: Color values for foreground and background widget attributes  
Valid value
Foreground color
Background color
info or information
colorInfoFG attribute
colorInfoBG attribute
warn or warning
colorWarnFG attribute
colorWarnBG attribute
err or error
colorErrorFG attribute
colorErrorBG attribute
def or default
Windows default
Windows default
The default setting uses the default Windows color values for foreground and background. The visual class attributes use values mapped to the application’s color table. Table 3–2 shows the default values for the visual class attributes.
 
Table 3–2: Default color values for visual class attributes
Attribute
Default color value
colorInfoFG
Unknown value (?)
colorInfoBG
10 (green)
colorWarnFG
Unknown value (?)
colorWarnBG
14 (yellow)
colorErrorFG
Unknown value (?)
colorErrorBG
12 (red)
Returns: LOGICAL
Notes:  
*To remove highlighting from a widget, call the function with the highlight type set to default.
*If code in one object, attempts to highlight a widget in another object, the color values come from the attribute the widget resides in.
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
IF widgetIsBlank("phone":U) THEN highlightWidget("phone":U, "warn":U).
The following illustrates the use of this method in DHTML code for use with a Web browser:
:
logic.highlightWidget(‘customerviewv.phone,customerviewv.fax’,’warn’);
initializeObject
Procedure that initializes code specific to visualizations.
Location: visual.p
Parameters: None
Notes:  
*Invoked with RUN SUPER from containr.p’s version of initializeObject.
*Reads through the list of enabled objects (which does not include RowObject fields) and gets their handles to store in EnabledObjHdls property.
*Invokes enableObject and viewObject depending on the values of DisableOnInit and HideOnInit property settings.
*Invokes applyLayout to change the object to the correct layout if there are multiple layouts.
resetWidgetValue
Resets the SCREEN-VALUE of the object or objects identified in the name list back to its original value from its data source. If a field in the list is not found or there is no data source for a field in the list, FALSE is returned and it will process all others in the list.
Location: visual.p
Parameters:  
INPUT namelist AS CHARACTER
The name of one or more objects, separated by commas.
Returns: LOGICAL
Notes: None
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
IF widgetIsModified("itemId":U) THEN resetWidgetValue("discount":U).
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
if (logic.widgetIsModified(‘orderlineviewv.itemnum’))
  logic.resetWidgetValue(‘customerviewv.discount’);
toggleWidget
Reverses the value of one or more objects of type LOGICAL in the name list. The format of the widget is used to reverse its SCREEN-VALUE. For example, a logical with a format of credit/debit would change a “credit” screen-value to “debit.” A null value is not changed and FALSE is returned.
Location: visual.p
Parameters:  
INPUT namelist AS CHARACTER
The name of one or more objects, separated by commas.
Returns: LOGICAL
Notes:  
*Sets the DataModified attribute to force the toolbar to enable saving data (it behaves as if the user actually changed the field value manually).
*The DHTML client supports logical text fill-ins (HTML input) and toggle boxes (HTML check box).
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
IF widgetValue("status":U) = "Shipped":U THEN 
 toggleWidget("transType":U).
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
if (logic.widgetValue(‘orderviewv.shipped’)==’Shipped’)
  logic.toggleWidget(‘myviewv.transtype’);
viewWidget
Views the object or objects identified in the namelist (and their popup buttons). For SmartDataFields, it invokes the viewObject method.
Location: visual.p
Parameters:  
INPUT namelist AS CHARACTER
The name of one or more objects, separated by commas.
Returns: LOGICAL
Notes: None
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
IF widgetIsTrue("Shipped":U) THEN
  viewWidget("ShipDate":U).
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
if (logic.widgetIsTrue(‘myviewv.shipped’))
  logic.viewWidget(‘orderviewv.shipdate’);
widgetHandle
Returns the handle of the requested object. For a basic object it returns the widget-handle, for a SmartDataField it returns the procedure handle.
Caution: While this is not a low-level API, future versions of Progress Dynamics might not automatically migrate calls to this API. Try to avoid using this function. If you do use it, keep track of its use so that you can quickly locate potential migration issues later.
Location: visual.p
Parameters:  
INPUT name AS CHARACTER
The name of a single Progress Dynamics object.
Returns: HANDLE
Notes: None
widgetIsBlank
Returns TRUE if the widget is blank, otherwise FALSE. If the namelist contains more than one object, then the function returns TRUE if all of them are blank, otherwise FALSE.
Location: visual.p
Parameters:  
INPUT namelist AS CHARACTER
The name of one or more objects, separated by commas.
Returns: LOGICAL
Notes: None
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
IF widgetIsBlank("terms":U) THEN 
  disableWidget("discount":U).
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
if (logic.widgetIsBlank(‘orderviewv.terms’))
  logic.disableWidget(‘customerviewv.discount’);
widgetIsFocused
Returns TRUE if the widget has focus. This is not supported for SmartDataFields. This returns unknown if the field is not found or if the widget is a SmartDataField.
Location: visual.p
Parameters:  
INPUT name AS CHARACTER
The name of a single Progress Dynamics object.
Returns: LOGICAL
Note: This API is not supported by the DHTML client.
Example:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
IF widgetIsFocused("shipped":U) AND widgetIsTrue("shipped":U) THEN   assignFocusedWidget("comments":U). 
widgetIsModified
Returns TRUE if the MODIFIED attribute or its equivalent is set for the object, otherwise FALSE. If the name list contains more than one object, then the function returns TRUE if any of them have changed, otherwise FALSE. If any field in the name list is not found, unknown is returned.
For example, use this function to check if any of multiple values involved in a calculation or expression have been modified.
Location: visual.p
Parameters:  
INPUT namelist AS CHARACTER
The name of one or more objects, separated by commas.
Returns: LOGICAL
Notes: None
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
IF widgetIsModified("deposit":U) THEN 
  assignWidgetValue("status":U, "current":U). 
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
if (logic.widgetIsModified(‘customerviewv.name’))
  logic.assignWidgetValue(‘orderviewv.orderstatus’,’current’);
widgetIsTrue
Returns TRUE if the value of a LOGICAL object is TRUE, otherwise FALSE. This function does not support SmartDataFields. This function returns unknown if the field is not found, if the value of the LOGICAL is unknown, if the widget is not a LOGICAL field, or if the widget is a SmartDataField. Contrast with the widgetValue function which returns a CHARACTER value.
Location: visual.p
Parameters:  
INPUT name AS CHARACTER
The name of a single Progress Dynamics object.
Returns: LOGICAL
Notes: None
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
IF widgetIsTrue("writeToConfig":U) THEN 
  RUN genConfig.
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
if (logic.widgetIsTrue(‘myviewv.writeToConfig’))
  getConfig();
widgetValue
For most objects, returns the INPUT-VALUE of the object.
For a browse column within a ROW-DISPLAY trigger, the function returns the BUFFER-VALUE from the RowObject buffer field. If INPUT-VALUE returns an ABL error because the value is actually blank, widgetIsBlank will be invoked and blank will be returned. For SmartDataFields, which do not have a standard function for returning an unformatted value, this function does nothing and returns unknown.
Location: visual.p
Parameters:  
INPUT namelist AS CHARACTER
The name of one or more objects, separated by commas.
Returns: CHARACTER
Note: The DHTML client supports for DATE, DECIMAL, and INTEGER data types. CHARACTER and LOGICAL data types are not supported.
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
IF widgetValue("custID":U) = cID THEN …
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
if (logic.widgetValue(‘customerviewv.custnum’) == cID) …
widgetValueList
Takes the name of one or more objects and a delimiter and returns the INPUT-VALUE of the object. In the case of a browse column reference from within a ROW-DISPLAY event, it returns the BUFFER-VALUE from the RowObject buffer field. SmartDataFields do not have a standard function for returning an unformatted value so this function does nothing for SmartDataFields and returns unknown.
If a field in the list is not found or a field has an unknown value, the function returns the Unknown value (?) for its value in the returned character list.
Location: visual.p
Parameters:  
INPUT namelist AS CHARACTER
The name of one or more objects, separated by commas.
INPUT delimiter AS CHARACTER
(Optional) Specifies the delimiter to use for the return value only. Specify the Unknown value (?) to use the default delimiter, which is the pipe character (“|”).
Returns: CHARACTER
Notes:  
*The DHTML client supports DATE, DECIMAL, and INTEGER data types. CHARACTER and LOGICAL data types are not supported.
*For the DHTML client, the delimiter is optional. If it is not specified, it uses the default delimiter, which is the pipe symbol (“|”).
Examples:  
The following illustrates the use of this method in ABL code for use with a graphical user interface:
 
ASSIGN
  cValues   = widgetValueList("Self.discount,balance":U, ?)
  iDiscount = INTEGER(ENTRY(1, cValues, "|":U))
  dBalance  = DECIMAL(ENTRY(2, cValues, "|":U)).
The following illustrates the use of this method in DHTML code for use with a Web browser:
 
cValues = logic.widgetValueList
  (‘customerviewv.discount,customerviewv.balance’);