$windowproperties

Set or return the current window properties of a Form instance.

Set: $windowproperties (InstanceName, PropertyList) = PropertyValuesList

Return: Return = $windowproperties (InstanceName {, PropertyList})

Example: $windowproperties("FORM2", "backimage") = "backimage=@%%LOGO.MYENT%%%.png")

Parameters

Parameters
Parameter Data Type Description
InstanceName String Name of a form instance.
PropertyList String List of window property names, separated by GOLD ; (;); can be a string.
PropertyValuesList String Associative list of Property=PropertyValue pairs (separated by GOLD ; ), where PropertyValue is the value to be assigned to the window property identified by Property.

All parameters can be a string, or a variable, function, or parameter that evaluates to a string, or a field (or indirect reference to a field) containing a string.

The property name is not case-sensitive; you can use uppercase or lowercase letters, or any combination of these, to increase readability. If you specify the property names in PropertyList as literals, a compile check is performed to check that they are correct.

Return Values

Returns an associative list of the specified Property = PropertyValue pairs containing the window properties and their values for the specified form instance.

If the function is used in an assignment, it returns the defined property string. If PropertyList is not specified or is an empty string, all window properties are returned.

If an error occurs, $procerror contains a negative value that identifies the exact error. This function does not affect $status.

Values of $procerror commonly returned by $windowproperties
Value Error constant Meaning
-1105 <UPROCERR_INSTANCE> The instance name provided is not valid. For example, the argument contains incorrect characters.
-1110

<UPROCERR_TOPIC>

Property name not known (in either PropertyList or PropertyValuesList)
-1132 <UPROCERR _UNRESOLVED_TOPIC> Property not specified in PropertyValuesList

-1302

<UPROCERR_SERVICE> The named instance is not a Form.
-1304 <UPROCERR_UNKNOWN_ CONTEXT> Function not allowed, unknown context. The InstanceName argument was omitted and one of the following occurred:
  • There is no current instance, for example in the apStart trigger.
  • The current instance is a form started with run.

Use

Use in Form components. Not applicable in character mode.

Description

$windowproperties returns or sets the window properties for the specified form instance, in terms relative to the position and size of the form's parent window, for example, the Uniface application window.

Size and position properties that are set for contained forms are ignored.

Window Properties

Properties set by $windowproperties
Physical Property Property Description
BackColor Background Color (BackColor) Background color of the window.
ForeColor Foreground Color (ForeColor) Foreground color of the window,
BackImage Background Image (BackImage) Background image of the window.
HAlign Horizontal Alignment (Halign) Horizontal alignment of the background image
VAlign Vertical Alignment (Valign) Vertical alignment of the background image
HScale Horizontal Scaling (Hscale) Horizontal scaling of the background image
VScale Vertical Scaling (Vscale) Vertical scaling of the background image
PreserveAspect Preserve Aspect Ratio (PreserveAspect) Indicates whether the aspect ratio of the image should be preserved.
State1 state The window state.
  • NORMAL (default)
  • MAXIMIZED
  • MINIMIZED
  • CENTERED (can be set but not returned)
XPos123

 

 The left (horizontal) window position, relative to the parent window.
YPos3

 

 The top (vertical) window position, relative to the parent window.
XSize124

 

 The width of the window.
YSize124

 

 The height of the window.
XPosPerc13

 

 The horizontal window position, as a percentage relative to the parent window.
YPosPerc13

 

 The vertical window position, as a percentage relative to the parent window.
XSizePerc14

 

 The horizontal window size, as a percentage relative to the parent window.
YSizePerc14

 

 The vertical window size, as a percentage relative to the parent window.
  1. Not applicable for contained forms
  2. Position and size is set in pixels (for example, 235 or 235px) and returned in pixels.
  3. Must be a positive or negative integer.
  4. Must be a positive integer.

Setting Properties Without PropertyList

All properties specified in the PropertyValuesList are assigned their corresponding value. All other properties are restored to their default value. For example:

  • $windowproperties("MYFORM") = "XPOS=50"

    Result: xpos is set to 50 pixels and all other window properties are restored to their default values. 

  • $windowproperties("MYFORM") = ""

    Result: All properties are restored to their default values.

  • $windowproperties("MYFORM") = "backcolor="

    Result: backcolor, and all other window properties, are restored to their default values.

Setting Properties Using PropertyList

Only those properties that exist in both the PropertyList and the PropertyValuesList are assigned the value specified in the PropertyValuesList. All other properties remain unchanged. For example:

  • $windowproperties("MYFORM","xpos;ypos") = "xpos=5px;ypos=2"

    Result: xpos is set to 5 and ypos to 2.

  • $windowproperties("MYFORM","backcolor") = "backcolor="

    Result: backcolor is restored to its default value

  • $windowproperties("MYFORM�?,"") = "xpos=5px"

    Result: Nothing happens

  • $windowproperties("MYFORM","ypos") = "xpos=5px"

    Result: Nothing happens

  • $windowproperties("MYFORM","ypos�?) = ""

    Result: Nothing happens

Restoring Default Values

When you restore a property to its default value, it reverts to the highest ranking statically-defined value. For example for Background Color, this means:

  1. Color defined in the window property window of the form.
  2. Color defined in the application .ini file for uwindow
  3. Uniface default color for uwindow, which is the Windows default.

Getting Properties Without PropertyList

If PropertyList is omitted, all properties and their values are returned.

vAllPropsValues = $windowproperties("MYFORM")

Getting Properties Using PropertyList

You can use $windowproperties to retrieve the values of specified properties. Only the values of the properties specified in the PropertyList are returned. For example:

  • vHorizontalPos = $windowproperties("MYFORM", "XPOS")

    Result: vHorizontalPos = "XPOS=6"

  • vHorizontalPos = $windowproperties("MYFORM", "")

    Result: vHorizontalPos = ""

Getting Active Values

If you have used $windowproperties to set property values, these cannot be returned by $windowproperties until after a show command. For example:

;Set the XPOS and YPOS values 
$windowproperties("MYFORM",XPOS,YPOS) = "XPOS=-100;YPOS=-100"
show

;Retrieve the values of XPOS and YPOS
vPos = $windowproperties("MYFORM","XPOS;YPOS")
;vPos = "XPOS=-100;YPOS=-100"

Restrictions and Precedence of Properties

Implicit data type conversion is used to convert any non-numeric values to numeric values. Values outside the allowed boundaries of the underlying operating system are corrected by the operating system. For example, if you set XPOS to a value of 1000000, the operating system would change this value to the maximum allowed value for XPOS.

The settings for position and size properties of a form that you specify in the Component Editor are not the same as the absolute position and size that you can set using $windowproperties at run time.

  • The form geometry is expressed in columns and rows, whereas $windowproperties sets and retrieves the value in pixels.
  • The declared form size does not take into account the size of panel and/or menus. The window size that is used by $windowproperties defines the outer boundaries of the form and includes the menu, panel, and border, but not the window frame and title bar.

Some properties are not applicable to contained forms. When a form is of Window TypeContained, the widget that contains the form controls the size and position of the form. When setting these properties they will be ignored.

In case of conflicting values, setting the State property takes precedence over setting position and size properties. Setting the percentage properties for position and size takes precedence over setting the absolute properties for position and size.

Example: Returning the Values of Window Properties

The following example returns the values of window properties:

variables
   string vPos ; a list
   numeric vXpos, vYpos
   string vColor
endvariables

vPos = $windowproperties("MYFORM", "XPOS;YPOS")
vXpos = $item("XPOS", vPos)
vYpos = $item("YPOS", vPos)
vColor = $windowproperties("MYFORM", "BACKCOLOR")

Example: Setting the Values of Window Properties

Each of the following statements sets the color of the form to light blue:

$windowproperties ("MYFORM", "BACKCOLOR") = "BACKCOLOR=lightblue"
$windowproperties ("MYFORM", "BACKCOLOR") = "BACKCOLOR=#ADD8E6"

The following examples set the XPOS property to 6 (pixels) in two different ways (the values are determined using implicit type conversion):

;Setting XPOS
$windowproperties("MYFORM", "XPOS") = "XPOS=6"

;Setting dimensions using a variable
vLayout = "XPOS=6;YPOS=20;XSIZE=600;YSIZE=450"
$windowproperties("MYFORM", "XPOS") = vLayout ; Other properties unchanged

The following examples set the values of the XPOS and YPOS properties:

;Setting XPOS and YPOS
$windowproperties("MYFORM", "XPOS;YPOS") = "XPOS=6;YPOS=20"

;Setting XPOS and YPOS using variable
vLayout = "YSIZE=450;XSIZE=600;YPOS=20;XPOS=6" 
$windowproperties("MYFORM", "XPOS;YPOS") = vLayout
; Result: XPOS = 6 and YPOS = 20, other properties unchanged

Example: Setting the Values of Window Properties for Two Forms

The following example sets the dimensions of FORM2 to the same dimensions as FORM1:

$windowproperties("FORM2", "XSIZE;YSIZE") = $windowproperties("FORM1", "XSIZE;YSIZE")

The following example displays FORM1 and FORM2 beside each :other in the parent window:

vLayout1 = "XPOSPERC=0;XSIZEPERC=50;YPOSPERC=0;YSIZEPERC=100"
vLayout2 = "XPOSPERC=50;XSIZEPERC=50;YPOSPERC=0;YSIZEPERC=100"

$windowproperties("FORM1", "XPOSPERC;YPOSPERC;XSIZEPERC;YSIZEPERC") = vLayout1
$windowproperties("FORM2", "XPOSPERC;YPOSPERC;XSIZEPERC;YSIZEPERC") = vLayout2

Example: Removing a Background Image

It is not possible to remove property values, so if you want a property to be applied only in specific circumstances, ensure that it is not set declaratively in the form definition. You can then set it and clear it as required using $windowproperties.

For example, assume that you want to add a background image in certain conditions. For a Record Form, set a background image in the Read trigger: 

;Read trigger
read
if ($status = 0)
   $windowproperties("FORM2", "backimage") = "backimage=@%%LOGO.MYENT%%%.png")
endif

And remove it in the store trigger: 

$windowproperties("FORM2", "backimage") = "backimage="