$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
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.
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:
|
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
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.
|
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. |
|
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:
- Color defined in the window property window of the form.
- Color defined in the application
.ini file for
uwindow
- 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="