skip to main content
OpenEdge Development: AppBuilder
Customizing AppBuilder : Creating custom object files
 
Creating custom object files
A custom object file is a text file (normally with a .cst extension) that tells AppBuilder to work with your own custom widgets and SmartObjects. You can use a custom object file to control the appearance and behavior of the Object Palette and some aspects of the New dialog box.
Although you can create a custom object file from scratch, it is much simpler to copy and modify an existing custom object file. OpenEdge supplies default custom object files that you can copy and modify according to your application needs.
OpenEdge supplies different default custom object files depending on your AppBuilder licensing option. Table 17 identifies all the custom files in the current release and the object definitions they contain. The files you have depend on your AppBuilder license.
 
Table 17: Custom object files and their contents 
Filename
Contents
progress.cst 
Basic Objects, SmartPanel, SmartFolder, SmartContainer, SmartWindow, SmartDialog, SmartFrame, Method Library, Structured Include, Structured Procedure
shared.cst 
SmartDataObject
smart.cst 
SmartDataBrowser and SmartDataViewer
activex.cst 
CSSpin, CSComboBox, PSTimer
web.cst 
CGI Wrapper, Frameset, HTML Mapping, Structured Include, Main, Structured Procedure, Report Template, Table, and Method Library
smartv8.cst
Version 8 SmartObject definitions
Note: The ActiveX control definitions that were in the Progress Version 8 cst file are now contained in the activex.cst file.
General coding rules
Here are some general comments on coding custom object files:
*You can put comments (/* ... */) anywhere in a custom object file.
*Custom object files must end with a blank line, otherwise you lose the last line of code.
Entry types
You can add four types of entries to a custom objects file:
*A button to the Object Palette
*A SmartObject to an Object Palette button pop‑up menu
*A template to the New dialog box
*A custom widget to an Object Palette button pop‑up menu
The following sections describe these entries.
Adding a button to the Object Palette
Use this type of entry to define your own object type and place it on the Object Palette:
 
Syntax 
#object-type &Default
UP-IMAGE-FILE bitmap-file [X,Y]
DOWN-IMAGE-FILE bitmap-file [X,Y]
LABEL label-name
{ USE master-file-name
| NEW template-file-name
[ DIRECTORY-LIST list FILTER filter TITLE title ]
| DIRECTORY-LIST list FILTER filter TITLE title
}
[
DB-CONNECT ]
#object-type &Default
Specifies the type of object to add to the Object Palette.
UP-IMAGE-FILE bitmap-file [X,Y]
Specifies the name of the bitmap file for object-type when deselected. To fit properly on the Object Palette, the image must be 28 by 28 pixels, including all shadows and highlights.
DOWN-IMAGE-FILE bitmap-file [X,Y]
Specifies the name of the bitmap file for object-type when selected. To fit properly on the Object Palette, the image must be 28 by 28 pixels, including all shadows and highlights.
LABEL label-name
Specifies the text for the label for object-type. This label appears on the Object Palette and in the Object Palette menu.
USE master-file-name
Specifies the name of the SmartObject master file to instantiate when smartobject-type is selected from the Object Palette. If you specify USE, a Choose Object dialog box does not appear.
NEW template-file-name
Specifies the template file that AppBuilder opens when the user performs a New operation from Object Palette. You cannot use this option with the USE option.
DIRECTORY-LIST list
Specifies the directories that appear in the Choose dialog box for object-type.
FILTER filter
Specifies a comma‑separated list of file search masks that appear in the Choose dialog box for the current directory.
TITLE title
Specifies the title for the Choose dialog box for object-type.
DB-CONNECT
Specifies whether AppBuilder prompts you to connect a database (if one is not connected) when you select the object-type. This is useful for data‑aware objects such as SmartDataViewers, SmartDataObjects, and SmartDataBrowsers.
The sample entry in Figure 70 adds a SmartObject type, specifically a SmartDataBrowser.
Figure 70: Sample entry for SmartObject type
Note: You can also use the adecomm/_chosobj.w procedure in the src/adecomm.pl procedure library to modify the Choose Object dialog box. For more information, see OpenEdge® Development: Basic Development Tools (character only; information for Windows is in online help).
Adding a SmartObject to a palette button pop-up menu
Use this type of entry to add an object to the Object Palette’s pop‑up menu for an object type. The new object you define also appears in the Object Palette’s submenu for the object type. This type of entry also allows you to select an object without first using the Choose dialog box. Before you create this type of entry, make sure that you have created the object type (see the “Adding a button to the Object Palette” section). For example:
 
Syntax 
*smartobject-type    name
{ USE master-file
| DIRECTORY-LIST list FILTER filter TITLE title
}
*smartobject-type
Specifies the name of an existing object type.
name
Specifies the name of the object as it appears on the Object Palette’s menus.
USE master-file
Specifies the name of the SmartObject master file to instantiate when name is selected from the Object Palette.
DIRECTORY-LIST list
Specifies the directories that appear in the Choose dialog box for smartobject-type.
FILTER filter
Specifies a comma‑separated list of file search masks that appears in the Choose dialog box for the current directory.
TITLE title
Specifies the title for the Choose dialog box for smartobject-type.
The sample entries in Figure 71 add SmartObject masters from src/template/smart.cst.
Figure 71: Sample entries for adding a SmartObject master
Adding a new template
The following type of entry allows you to define your own template, whose name appears in the New dialog box:
 
Syntax 
{     *NEW-CONTAINER
| *NEW-SMARTOBJECT TYPE name
| *NEW-PROCEDURE
} template-name
NEW-TEMPLATE template-file
*NEW-CONTAINER
Specifies that the template appears in the New dialog box when the Containers toggle box is selected. A container is a either a window, a dialog box, or a SmartContainer.
*NEW-SMARTOBJECT
Specifies that the template appears in the New dialog box when the SmartObjects toggle box is selected.
TYPE name
Specifies the type of SmartObject. AppBuilder uses this value to determine whether to connect a database when the particular type of SmartObject is created.
*NEW-PROCEDURE
Specifies that the template appears in the New dialog box when the Procedures toggle box is selected. A procedure can be either a structured procedure file, a structured include file, or a method library.
template-name
Specifies the name of the template as it appears in the New dialog box.
NEW-TEMPLATE template-file
Specifies the pathname of the template file that AppBuilder opens when you select the template from the New dialog box.
The sample entries in Figure 72 define New templates.
Figure 72: Sample entries for new templates
Adding a widget to a palette button pop-up menu
You create and define custom widgets in a custom object file. The following is the syntax for adding custom widgets:
 
Syntax 
*widget-type name
[ DESCRIPTION [ description-text-string ] ]
{
[ attribute value ] ...
[ INHERIT name-of-entry ] ...
[ trigger-block ] ...
}
...
RUN file-name
*widget-type
Specifies the type of custom widget to create. It must be one of the following: BROWSE, BUTTON, COMBO-BOX, EDITOR, FILL-IN, FRAME, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, TEXT, and TOGGLE-BOX.
name
Specifies the display name of the custom widget as it appears on the Palette submenu (or pop‑up menu on the Palette). After you choose a widget, AppBuilder displays display-name, followed by widget-type, in the status bar of AppBuilder main window.
DESCRIPTION [ description-text-string ]
Specifies the description of the widget. The description helps another developer to read and understand the intent of each custom widget.
attribute
Specifies an attribute to set for the widget. You can specify any attribute that you can also set from the widget’s property sheet. See Table 18, later in this appendix, for a list of the attributes that you can specify and the widgets to which they can apply.
value
Specifies the value for attribute (based on the data type of the attribute).
INHERIT name-of-entry
Specifies the display name of another widget in the custom widgets file. The current widget inherits all of the attribute settings specified for the other widget. If attribute settings conflict, the latter setting applies.
trigger-block
Specifies a trigger for the custom widget, as shown:
 
Syntax 
TRIGGER event
  DO [ trigger-code ] END.
END TRIGGER
In this syntax, event specifies an event to pair with the custom widget and trigger-code specifies the code statements to execute for the widget/event pair.
RUN file-name
Specifies a procedure to run immediately before the object is created. The procedure file can take two parameters:
*INPUT p_id AS INTEGER NO-UNDO - The context ID of the object being created.
*OUTPUT p_sct AS CHAR NO-UNDO - A list of new custom object entries to process.
You can have multiple RUN statements for a single custom object file; they are run sequentially. Do not end a RUN statement line with a trailing period (.).
Table 18 describes the attributes you can set in the custom objects file and the widgets to which they apply.
 
Table 18: Settable attributes for custom widgets
Attribute
Data type
Allowed widgets
AUTO-COMPLETION
Logical
COMBO BOX
AUTO-END-KEY
Logical
BUTTON
AUTO-GO
Logical
BUTTON
AUTO-INDENT
Logical
BUTTON, EDITOR, FILL-IN, SELECTION-LIST, TOGGLE-BOX
AUTO-RESIZE
Logical
BUTTON, EDITOR, FILL-IN, SELECTION-LIST, SLIDER, TOGGLE-BOX
AUTO-RETURN
Logical
FILL-IN
BGCOLOR
Integer
BROWSER, BUTTON, COMBO-BOX, EDITOR, FILL-IN, FRAME, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, SLIDER, TEXT, TOGGLE-BOX
BLANK
Logical
COMBO-BOX, FILL-IN
BOX-SELECTABLE
Logical
FRAME
CANCEL-BUTTON
Logical
BUTTON
COLUMN-SCROLLING
Logical
BROWSER
DATA-TYPE
Character
COMBO-BOX, FILL-IN, RADIO-SET
DEBLANK
Logical
COMBO-BOX, FILL-IN
DEFAULT-BUTTON
Logical
BUTTON
DEFAULT-STYLE
Logical
BUTTON
DISPLAY
Logical
COMBO-BOX, EDITOR, FILL-IN, RADIO-SET, SELECTION-LIST, SLIDER, TOGGLE-BOX
DOWN
Logical
FRAME
DRAG-ENABLED
Logical
SELECTION-LIST
EDGE-PIXELS
Integer
RECTANGLE
ENABLE
Logical
BROWSER, BUTTON, COMBO-BOX, EDITOR, FILL-IN, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, SLIDER, TOGGLE-BOX
EXPAND
Logical
RADIO-SET
FGCOLOR
Integer
BROWSER, BUTTON, COMBO-BOX, EDITOR, FILL-IN, FRAME, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, SLIDER, TEXT, TOGGLE-BOX
FILLED
Logical
RECTANGLE
FONT
Integer
BROWSER, BUTTON, COMBO-BOX, EDITOR, FILL-IN, FRAME, RADIO-SET, SELECTION-LIST, SLIDER, TEXT, TOGGLE-BOX
FORMAT
Character
COMBO-BOX, FILL-IN
GRAPHIC-EDGE
Logical
RECTANGLE
HEIGHT
Integer
BROWSER, BUTTON, COMBO-BOX, EDITOR, FILL-IN, FRAME, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, SLIDER, TEXT, TOGGLE-BOX
HEIGHT-PIXELS
Integer
BROWSER, BUTTON, COMBO-BOX, EDITOR, FILL-IN, FRAME, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, SLIDER, TEXT, TOGGLE-BOX
HELP
Character
BUTTON, COMBO-BOX, EDITOR, FILL-IN, RADIO-SET, SELECTION-LIST, SLIDER, TOGGLE-BOX
HIDDEN
Logical
BROWSER, BUTTON, COMBO-BOX, EDITOR, FILL-IN, FRAME, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, SLIDER, TEXT, TOGGLE-BOX
HORIZONTAL
Logical
RADIO-SET, SLIDER
IMAGE-DOWN
Character
BUTTON
IMAGE-FILE
Character
BUTTON, IMAGE
IMAGE-INSENSITIVE
Character
BUTTON
INITIAL-VALUE
Character
COMBO-BOX, EDITOR, FILL-IN, RADIO-SET, SELECTION-LIST, SLIDER, TOGGLE-BOX
INNER-LINES
Integer
COMBO-BOX
KEEP-TAB-ORDER
Logical
FRAME
LABEL
Character
BROWSER, BUTTON, COMBO-BOX, FILL-IN, FRAME, TOGGLE-BOX
LARGE
Logical
EDITOR
LAYOUT-UNIT
Character or P
BROWSER, BUTTON, COMBO-BOX, EDITOR, FILL-IN, FRAME, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, SLIDER, TEXT, TOGGLE-BOX
LIST-ITEMS
Character
COMBO-BOX, RADIO-SET, SELECTION-LIST
LOCK-COLUMNS
Integer
BROWSER
MANUAL-HIGHLIGHT
Logical
BUTTON, COMBO-BOX, EDITOR, FILL-IN, FRAME, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, SLIDER, TEXT, TOGGLE-BOX
MAX CHARS
Integer
EDITOR
MAX-DATA-GUESS
Integer
BROWSER
MAX-VALUE
Integer
SLIDER
MIN-VALUE
Integer
SLIDER
MOVABLE
Logical
BUTTON, COMBO-BOX, EDITOR, FILL-IN, FRAME, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, SLIDER, TEXT, TOGGLE-BOX
MULTIPLE
Logical
BROWSER, SELECTION-LIST
NAME
Character
BROWSER, BUTTON, COMBO-BOX, EDITOR, FILL-IN, FRAME, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, SLIDER, TOGGLE-BOX
NATIVE
Logical
FILL-IN
NO-BOX
Logical
BROWSER, FRAME
NO-HIDE
Logical
FRAME
NO-LABEL
Logical
COMBO-BOX, FILL-IN
NO-LABELS
Logical
BROWSER, FRAME
NO-UNDERLINE
Logical
FRAME
NO-UNDO
Logical
COMBO-BOX, EDITOR, FILL-IN, RADIO-SET, SELECTION-LIST, SLIDER, TOGGLE-BOX
NO-VALIDATE
Logical
FRAME
OPEN-QUERY
Logical
BROWSER, FRAME
OVERLAY
Logical
FRAME
PAGE-BOTTOM
Logical
FRAME
PAGE-TOP
Logical
FRAME
PRIVATE-DATA
Character
BROWSER, BUTTON, COMBO-BOX, EDITOR, FILL-IN, FRAME, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, SLIDER, TEXT, TOGGLE-BOX
RADIO-BUTTONS1
Character
RADIO-SET
READ-ONLY
Logical
EDITOR
RESIZABLE
Logical
BUTTON, COMBO-BOX, EDITOR, FILL-IN, FRAME, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, SLIDER, TEXT, TOGGLE-BOX
RETAIN
Integer
FRAME
RETURN-INSERTED
Logical
EDITOR
SCROLLABLE
Logical
FRAME
SCROLLBAR-HORIZONTAL
Logical
EDITOR, SELECTION-LIST
SCROLLBAR-VERTICAL
Logical
EDITOR, SELECTION-LIST
SELECTABLE
Logical
BUTTON, COMBO-BOX, EDITOR, FILL-IN, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, SLIDER, TOGGLE-BOX
SENSITIVE
Logical
FRAME
SEPARATORS
Logical
BROWSER
SHARED
Logical
BROWSER, COMBO-BOX, EDITOR, FILL-IN, FRAME, RADIO-SET, SELECTION-LIST, SLIDER, TOGGLE-BOX
SIDE-LABELS
Logical
FRAME
SORT
Logical
COMBO-BOX, SELECTION-LIST
TITLE
Logical
BROWSER, FRAME
TITLE-BAR
Logical
BROWSER, FRAME
TITLE-BGCOLOR
Integer
FRAME
TITLE-FGCOLOR
Integer
FRAME
TOP-ONLY
Logical
FRAME
UNIQUE-MATCH
Logical
COMBO BOX
VIEW
Logical
BROWSER, BUTTON, COMBO-BOX, EDITOR, FILL-IN, FRAME, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, SLIDER, TEXT, TOGGLE-BOX
VIEW-AS-TEXT
Logical
FILL-IN
VIRTUAL-HEIGHT
Integer
FRAME
VIRTUAL-HEIGHT-PIXELS
Integer
FRAME
VIRTUAL-WIDTH
Integer
FRAME
VIRTUAL-WIDTH-PIXELS
Integer
FRAME
WIDTH
Integer
BROWSER, BUTTON, COMBO-BOX, EDITOR, FILL-IN, FRAME, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, SLIDER, TEXT, TOGGLE-BOX
WIDTH-PIXELS
Integer
BROWSER, BUTTON, COMBO-BOX, EDITOR, FILL-IN, FRAME, IMAGE, RADIO-SET, RECTANGLE, SELECTION-LIST, SLIDER, TEXT, TOGGLE-BOX
WORD-WRAP
Logical
EDITOR

1 The RADIO-BUTTONS attribute represents the labels and values for the individual buttons in a set, arranged in a comma-separated list.The following example identifies this format: label, value, label, value, label, value, and so forth. One label/value pair is defined for each button identified in a set.

Sample widget entry
The following sample entry is in the src/template/progress.cst file:
 
*BUTTON         Ne&xt 
DESCRIPTION     Simple Navigation Button
INHERIT         C&ustom Size/Color
LABEL           &Next
NAME            Btn_Next
TRIGGER CHOOSE
DO:
  &IF "{&PROCEDURE-TYPE}" EQ "SmartPanel" &THEN
    &IF "{&ADM-VERSION}" EQ "ADM1.1" &THEN
      RUN notify IN THIS-PROCEDURE ("get-next") NO-ERROR.
    &ELSE
      PUBLISH "fetchNext":U.
    &ENDIF
  &ELSEIF "{&TABLES-IN-QUERY-{&FRAME-NAME}}" NE "" &THEN
/*
**  This is a simple NEXT RECORD navigation button, useful for building
**  test screens quickly. NOTE: if there are no tables in the query,
**  then this code will not compile’ so use the preprocessor to skip it.
*/
    GET NEXT {&FRAME-NAME}.
    IF NOT AVAILABLE {&FIRST-TABLE-IN-QUERY-{&FRAME-NAME}}
      THEN GET LAST {&FRAME-NAME}.
    IF AVAILABLE {&FIRST-TABLE-IN-QUERY-{&FRAME-NAME}} THEN DO:
      DISPLAY {&FIELDS-IN-QUERY-{&FRAME-NAME}} WITH FRAME {&FRAME-NAME}.
      {&OPEN-BROWSERS-IN-QUERY-{&FRAME-NAME}}
    END.
  &ENDIF
END TRIGGER
If you analyze this sample entry one section at a time, you can see how to write your own custom widget entry. In this example:
*The first line specifies the widget type BUTTON and the display name for the widget:
 
*BUTTON Ne&xt 
AppBuilder displays this name in the appropriate Object Palette menus. The ampersand (&) specifies that the “x” is the mnemonic on the Object Palette menu.
*The second line describes the button’s functionality:
 
DESCRIPTION Simple Navigation Button
AppBuilder does nothing with this description. The description is meant as a summary for someone reading the custom object file.
*The third line names another custom widget (Custom Size/Color) in the progress.cst file by using the widget’s display name:
 
INHERIT C&ustom Size/Color
The current widget (Next) inherits all of the attribute settings for the Custom Size/Color button. Where you place the INHERIT keyword affects how attributes are set. Later definitions override earlier definitions.
*The fourth line specifies the label of the button:
 
LABEL &Next
The ampersand (&) specifies that “N” is the mnemonic for the button.
*The fifth line specifies the widget name that AppBuilder uses internally to refer to the button:
 
NAME Btn_Next