Release 10.1A: OpenEdge Development:
Progress 4GL Handbook

> ## Common attribute values for visual objects

> There are literally hundreds of different attributes, many of which apply only to a single object type. But several basic ones that you will likely use most often apply to most or all visual objects. This section summarizes a few of these.

> ##### Geometry attributes

> These attributes affect the size and location of the object in the frame or window:

> - `ROW, COLUMN` — These `DECIMAL` attributes are the character positions of the object within its container. For objects in a frame, the values represent the position within the frame and not within the frame’s window. The frame has its own position within its window, and the window has its own position within the display device. When you lay out objects in the AppBuilder, it generates code to position the objects using `ROW` and `COLUMN` coordinates. Alternately, you can use pixel values for positions. Generally, character positions are more portable and flexible if the font or display device changes.

> - `X, Y` — These `INTEGER` attributes are equivalent to `ROW` and `COLUMN` but measured in pixels.

> - `HEIGHT-CHARS, WIDTH-CHARS` — These `DECIMAL` attributes are the height and width of the object in character units.

> - `HEIGHT-PIXELS, WIDTH-PIXELS` — These `INTEGER` attributes are the height and width of the object in pixels.

> ##### Appearance attributes

> These attributes affect the appearance of the object:

> - `HIDDEN` — If this `LOGICAL` attribute is true, then the object is hidden and does not appear even when its container is displayed. If it is false, then the object does appear when its container is displayed. If you set the `HIDDEN` attribute of a container object, such as a window or frame, to true, then the container and all the objects in it are hidden. If you set it to false for a container, then the container and any contained objects that aren’t themselves hidden appear. This is an attribute you can set only at run time. The definition of an object cannot describe it as initially hidden.

> - `VISIBLE` — This `LOGICAL` attribute is not simply the opposite of `HIDDEN`. Its relation to `HIDDEN` can be somewhat confusing to understand. Generally, you use it much less than the `HIDDEN` attribute. Setting the `VISIBLE` attribute of an object to true forces it to be viewed. For example, setting the `VISIBLE` attribute of a field-level object in a window to true forces the window to be displayed even if it was previously hidden. By contrast, setting the `HIDDEN` attribute to false doesn’t force the container to be viewed. You can read all the details of the effects of the `VISIBLE` attribute in the online help.

> - `SENSITIVE` — This `LOGICAL` attribute determines whether an object is enabled for input or not. Its use is parallel to the `ENABLE` verb. That is, executing an `ENABLE` statement for an object is the same as setting its `SENSITIVE` attribute to true. Similarly, executing a `DISABLE` statement for an object is the same as setting its `SENSITIVE` attribute to false. Like the `HIDDEN` attribute, you can set the `SENSITIVE` attribute only at run time. This means that if you check the Enable toggle box or the Display toggle box on or off in the AppBuilder property sheet for an object when you are building a screen, you do not change the `DEFINE` statement the AppBuilder generates for the object. Rather you change the `ENABLE` and `DISPLAY` statements the AppBuilder generates that execute when the window is initialized.

> - `READ-ONLY` — This `LOGICAL` attribute applies to data-representation objects and prevents the user from modifying the field value. Sometimes you might want to combine setting the Enable toggle box in a field’s property sheet with setting the `READ-ONLY` attribute to true. This gives a fill-in field some of the appearance of an enabled field (with its characteristic box outline, which can improve readability), but prevents the user from changing it. The CustOrders window uses this form for its Customer fill-ins.

> - `HELP` — This is the help text to display when the object is selected.

> - `TOOLTIP` — This is the text to display when the user hovers the mouse over the object. For data-representation objects, you can initialize the ToolTip text in the frame definition for the object, such as in this excerpt from the frame definition for the CustOrders window:

>     DEFINE FRAME CustQuery
>          .
>          .
>          .
>        Customer.City AT ROW 7.19 COL 13 COLON-ALIGNED
>               VIEW-AS FILL-IN
>               SIZE 27 BY 1 TOOLTIP "Enter the City"
>          .
>          .
>          .

> For other types of objects, you can specify the ToolTip text as part of the object definition, as in this button definition:

>     DEFINE BUTTON BtnFirst
>          LABEL "First"
>          SIZE 15 BY 1.14 TOOLTIP "Press this to see the first Customer.".

> - `LABEL` — This `CHARACTER` attribute is the label of the field or button.

> - `SELECTABLE` — You can set up most visual objects for direct manipulation. This means that the user can actually select, move, and resize the object at run time just as you can move and resize objects in a design window in the AppBuilder. The AppBuilder uses these attributes to provide you with the behavior you see in a design window, where you can drag objects around to where you want them. The `SELECTABLE` attribute is a `LOGICAL` value which, if true, allows the user to select the object by clicking on it with the mouse. It then sprouts the characteristic resize handles around the object border that let the user size or move it.

> - `RESIZABLE` — You can set this `LOGICAL` attribute to true to let a user change the size of an object at run time. You must also set the `SELECTABLE` attribute to true to provide the resize handles.

> - `MOVABLE` — You can set this `LOGICAL` attribute to true to let a user move an object at run time. You do not need to set the `SELECTABLE` attribute to make an object movable. The user can move the object without using its resize handles. However, it is considered a more standard user provision to set `SELECTABLE` along with `MOVABLE`.

> ##### Data management attributes

> These attributes affect how to manage data associated with the object:

> - `SCREEN-VALUE` — There is a special screen buffer that holds the displayed values of all data-representation objects in a frame. This buffer is separate from the underlying database record buffer for database fields and from the buffer where variable values are held. If a user enters a value into a field on the screen, that value is not assigned to the underlying record buffer until you execute an `ASSIGN` statement for the field. In the meantime, the input value is held only in the screen buffer. You can retrieve a value from the screen buffer using the `SCREEN-VALUE` attribute, which is a `CHARACTER` value representing the value as it appears on the screen, or as it would appear on the screen in a fill-in field. You can also set the `SCREEN-VALUE` attribute of an object to display a value without setting the underlying record value. It is important to remember that the value of the `SCREEN-VALUE` attribute is always the formatted value as it appears in the user interface. If this contains special format mask characters (such as commas and decimal points in a decimal value, for example), then any comparisons you do against this string must include those format characters. If this presents problems, you must assign the screen value to its underlying record buffer and reference the `BUFFER-VALUE` of the field to access it in its native data type and without format characters.

> - `INITIAL` — This attribute holds the initial value of a data-representation object. You can set it only in the `DEFINE` statement.

> ##### Relationship attributes

> These attributes affect how the object interacts with other objects:

> - `FRAME-NAME` — This `CHARACTER` attribute holds the name of the container frame the object is in.

> - `FRAME` — This `HANDLE` attribute holds the object handle of the container frame the object is in. In later chapters, you learn how to traverse from one handle to another to locate an object or to locate all objects that are in a container.

> - `WINDOW` — This `HANDLE` attribute holds the object handle of the container window the object is in.

> ##### Identifying attributes

> These attributes identify characteristics of the object:

> - `NAME` — This `CHARACTER` attribute holds the name of the object.

> - `PRIVATE-DATA` — This `CHARACTER` attribute lets you associate any free-form text with an object, which can help program logic that determinse how to identify or treat the object at run time.

> You can see most of the object attributes that you can set for an object type in the AppBuilder property sheet for the object, such as the one shown in Figure 8–1 for the Customer.Name fill-in field in the CustOrders window.

> Figure 8–1: Property sheet for a fill-in field

> The Advanced button takes you to the dialog box shown in Figure 8–2. These are attributes that you might use less often, some of which are mentioned in this chapter.

> Figure 8–2: Advanced Properties dialog box

> Certain property sheet settings, such as Display and Enable, affect AppBuilder-generated executable statements and preprocessor values rather than the `DEFINE` statement for the object itself. You’ve seen the effect of the Display and Enable settings already in the code for the AppBuilder-generated `enable_UI` procedure:

>     IF AVAILABLE Customer THEN
>          DISPLAY Customer.CustNum Customer.Name Customer.Address Customer.City
>               Customer.State
>            WITH FRAME CustQuery IN WINDOW CustWin.
>        ENABLE BtnFirst BtnNext BtnPrev BtnLast Customer.CustNum Customer.Name
>             Customer.Address Customer.City Customer.State OrderBrowse dTotalPrice
>             dTotalExt dAvgDisc cWorstWH cBestWH
>            WITH FRAME CustQuery IN WINDOW CustWin.

> The AppBuilder also keeps the list of displayed and enabled objects in preprocessor values:

>     &Scoped-define FIELDS-IN-QUERY-CustQuery Customer.CustNum Customer.Name ~
>     Customer.Address Customer.City Customer.State
>     &Scoped-define ENABLED-FIELDS-IN-QUERY-CustQuery Customer.CustNum ~
>     Customer.Name Customer.Address Customer.City Customer.State

> Other property sheet settings for attributes that you cannot set as part of the object definition are set in a series of `ASSIGN` statements the AppBuilder generates, such as these for the `READ-ONLY`, `PRIVATE-DATA`, `SELECTABLE`, `MOVABLE`, and `RESIZABLE` attributes in this example:

>     ASSIGN
>          BtnFirst:PRIVATE-DATA IN FRAME CustQuery     =
>                    "Private data for the first button.".
>     ASSIGN
>          cBestWH:READ-ONLY IN FRAME CustQuery         = TRUE.
>     ASSIGN
>          cWorstWH:SELECTABLE IN FRAME CustQuery       = TRUE
>          cWorstWH:MOVABLE IN FRAME CustQuery          = TRUE
>          cWorstWH:READ-ONLY IN FRAME CustQuery        = TRUE
>          cWorstWH:RESIZABLE IN FRAME CustQuery        = TRUE.

> As you develop your own applications, you need to keep in mind which attributes you can define in a `DEFINE` statement, which in a frame definition, and which only in executable statements at run time.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095