$paintedfieldproperties

Return or set the position and size for a specific instance of a field widget in a Form.

$paintedfieldproperties( Field {,PaintedOccurrence} {,PropertyList} ) { = } PropertyValuesList

PropertyValuesList = $paintedfieldproperties(Field,PaintedOccurrence {,Position | Size} )

Example: $paintedfieldproperties(FIELD1,"1") = "XPos=50;YPos=50"

Parameters

Parameters
Parameter Data Type Description
Field String Field name. It can optionally contain a qualified field name, for example MYFLD.MYENT.
PaintedOccurrence String Number of a painted occurrence or, if there are nested multiple occurrences, a GOLD ; separated list specifying the occurrences starting from the outer occurrence. For example, "3;1" specifies the field in the third occurrence of the inner entity in the first occurrence of an outer entity.
PropertyList String Associative list of one or more of the following property names:
  • xpos—sets the horizontal position
  • ypos—sets the vertical position
  • xsize—sets the horizontal size in characters
  • ysize—sets the vertical size in characters
  • zorder—places the painted field to Top or Bottom of a stack of fields (Z-order)
PropertyValuesList String Associative list of property values specifying the position, size, or Z-order of the GUI object
  • Position—associative list of properties specifying the beginning coordinates of the GUI object, in characters. The value for each coordinate can be from -32768 to 32767. The format is:

    "XPos {+ | -} = Value;YPos {+ | -} = Value"

  • Size—associative list of properties defining the dimensions of the GUI object, in characters. The value of each dimension can be from 0 to 65535. The format is:

    "XSize {+ | -} = Value;YSize {+ | -} = Value"

  • + | - —increment or decrement the current value of the size or position property by the specified value. If increment or decrement is not used, the value specified is absolute.
ZOrder String Place the current field on top or bottom of stack; useful when fields stack or overlap.

"ZOrder = Top|Bottom"

Return Values

  • Associative list of properties for the specified GUI object.
  • Empty string ("") if the object cannot be found.
  • ZOrder has no return value.

Use

Allowed in Form components without split bars. Not allowed for Unifields.

Note: $paintedfieldproperties has no effect on forms with split bars.

Description

Use the $paintedfieldproperties function to move or resize specific field widgets on a form at runtime. Only the single specified widget is affected. The Field and PaintedOccurrence identify the specific field instance to be repositioned.

Properties that are changed by $paintedfieldproperties are reset to the compiled values (that is, the default properties, plus the properties set for the entity declaratively) when the form is restarted.

The position of the widget is not restricted by the position of entities and fields on the form in the Layout Editor. This frees the form layout from the restrictions imposed by drawing the data structure in the Layout Editor as frames within frames.

For example, you can dynamically hide widgets by moving them outside the borders of the form. (It is possible to set the size of a field to 0,0, to hide a field, use the $fieldsyntax function.)

If you use enhanced printing to print a form after using $paintedfieldproperties, the printed output reflects the change, so fields that are located outside of the form boundaries are not printed.

Form scroll bars do not appear when the layout is changed using $paintedfieldproperties. If you move a widget so that it becomes fully or partially drawn outside the visible window border, scroll bars are not added to the form even if the window property No Form Scrollbars is set to FALSE.

When $paintedfieldproperties is used in the exec operation, it must be preceded by a show statement. This ensures that the painted fields are available, which is otherwise not the case when the exec operation is executed.

The following limits apply to position and size coordinates that can be set by $paintedfieldproperties:

  • Xpos, Ypos: -32768 to 32767
  • Xsize, Ysize: 0 to 65535

If you specify values outside these limits, the value outside of the range will be rounded to the nearest possible value, for example Xpos=-40000 is rounded to Xpos=-32768.

Stacked or Overlapping Fields

Caution: Avoid overlapping fields in forms that are used for printing. Uniface print functionality is not designed to handle multiple objects in one place.

The $paintedfieldproperties function enables you to position fields on top of one another, either directly, or so that they overlap. This means that forms may gain a virtual third dimension along a Z axis.

To determine which field is displayed on top (or on the bottom) when fields stack or overlap, you can set the ZOrder property of the field to appear on the top or bottom of the stack.

Normally. the default Z-order is determined by the initial painted position of a field, so the top left field is on top and the bottom right field is at the bottom of the Z-order. Resizing or repositioning the field has no effect on the Z-order.

However, when the position or size of an Edit Box, Output Box, or Rich Text Edit widget is changed, it is put on top of the Z-order stack.

Multiple Occurrences

If a field can be displayed multiple times in a form, you need to specify which instance of the field you want to move or resize. Fields are displayed multiple times if you draw multiple occurrences of the entity. Therefore, you need to specify the painted occurrence containing the field to be moved or resized.

Note:  Painted occurrence refers to the occurrence painted on the form and has nothing to do with the number of occurrences retrieved. For example, as the user scrolls through retrieved data, occurrence 54 may be displayed as the first painted occurrence on the form.

To specify a painted occurrence, provide the occurrence number. For example, If you have painted four occurrences of an entity on a form, and you want to change the size of a field (NAME) in the fourth occurrence, use the following instruction:

$paintedfieldproperties (NAME, 4) = "xsize=3;ysize=25"

However, if you have multiple occurrences nested in multiple occurrences, you need to specify both the inner entity occurrence and the outer entity occurrence. For example, the following form shows the layout and data structure of multiple nested entities. There are three occurrences of the Employee entity, each containing three occurrences of the Employment entity. When run, this form can display the project name field 12 times.

Form with multiple nested occurrences

If you wanted to specify that the third project name of the fourth displayed employee is to be resized, you could use the following instruction: 

$paintedfieldproperties (NAME.PROJECT.MYORG, "1;3;4;1") = "xsize+=2"

In this case:

  • The fully qualified field name is specified because there are multiple fields called NAME.
  • 1—first (and only) painted occurrence of PROJECT.MYORG
  • 3 —third painted occurrence of EMPLOYMENT.MYORG
  • 4 —fourth painted occurrence of EMPLOYEE.MYORG
  • 1—first (and only) occurrence of DEPARTMENT.ORG.

Using $paintedfieldproperties

The following example sets a field widget, named FIELD1 to X, Y position (50, 50). 

; trigger exec
show
$paintedfieldproperties(FIELD1,"1") = "XPos=50;YPos=50"

The following example sets a field widget, named FIELD1 to Z-sort order Top. 

$paintedfieldproperties(FIELD1,"1") = "Zorder=Top"
History

Version

Change

9.1.01

Introduced

Related Topics