This section describes:
The DataWindow object defines the way data is displayed in a DataWindow control. It contains controls that represent the columns, text labels, computed fields, and images.
The properties of the DataWindow object and its controls store the information that specifies the behavior of the DataWindow object. They are not properties of the DataWindow control, but of the DataWindow object displayed in the control.
Terminology
When you are programming for DataWindows, there are several types of expressions involved.
A DataWindow expression is an expression assigned as a value to a DataWindow property and is evaluated by the DataWindow engine. The expression can refer to column data and can have a different value for each row in the DataWindow.
A DataWindow property expression is an expression in your code that gets or sets the value of a DataWindow property. Its effects are equivalent to what the Describe and Modify methods do.
A DataWindow data expression is an expression in your code that gets or sets data in the DataWindow. Its effects are similar to what the SetItem and several GetItem methods do.
Types of values
Property values can be constants or can be DataWindow expressions. DataWindow expressions allow the property value to be based on other conditions in the DataWindow, including data values. Conditional expressions based on data can give the property a different value for each row.
Getting and setting values
You establish initial values for properties in the DataWindow painter. You can also get and set property values at runtime in code.
There are several techniques for accessing property values. A particular property might be accessible by a subset of those techniques. For example, some properties are read-only at runtime, some can be set only at execution, and some accept only constants (not DataWindow expressions) as values.
For a complete list of properties and the ways you can access each one, see DataWindow Object Properties
Examples: ways of setting the Border property
This table lists the ways you can access a property, using the Border property as an example:
|
What you can do with properties |
How to do it, using the Border property as an example |
What happens |
|---|---|---|
|
Set the initial value of the property in the workspace |
Property sheet, General tab, Border box |
The Border property takes on the value you set unconditionally. In the Preview view and at runtime, the control has the border you indicated in the workspace unless you set the Border property again in some way. |
|
Specify the value of the property at runtime based on an expression defined for the control in the workspace |
Property sheet, General tab, Border box, Expression button |
In Preview and at runtime, the border changes as specified in the expression, which overrides the setting on the property sheet. For example, an expression can give the Salary column value a ShadowBox border when the salary exceeds $70,000. To see the effect in the Preview view, you might need to close Preview and reopen it. |
|
Get the value of the property at runtime in code |
Property expression for the Border property or Describe method |
Both the expression and the Describe method return the value of the Border property for the specified control. |
|
Change the value of the property at runtime in code |
Property expression for the Border property or Modify method |
At runtime, the value of the property changes when the code executes. For example, you could code Modify in the Clicked event and change the border of the control the user clicked. |
|
Set the initial value of the property at runtime in code for a DataWindow being created |
SyntaxFromSQL method |
When SyntaxFromSQL executes, the border value of all columns is set in the generated syntax. PowerBuilder SyntaxFromSQL is a method of the Transaction object and is described in the the section called “SyntaxFromSQL” in PowerScript Reference. |
When you specify values in the Properties view of the DataWindow painter, you are setting properties of the DataWindow object and its controls.
Properties for each control
Each control in the DataWindow (columns, text, drawing controls) has its own property sheets, because there are different sets of properties for each object. To access individual property sheets, display the Properties view and then select a control.
If several controls have the same property and you want them all to have the same value, you can select all the controls so that the property sheet shows the properties they have in common. When you change the property value, it is applied to all selected controls.
DataWindow expressions for properties
For many properties, you can specify a DataWindow expression in the Properties view by clicking the Expression button beside the property. At runtime, the expression is evaluated for each row. When the expression includes row-dependent information in the calculation (such as data), each row can have a different value for the property. In the painter, you can see the results in the Preview view. (You might need to close Preview and reopen it if you are not seeing the settings you have made.)
For information about the components of expressions, see Using DataWindow expression functions and the Users Guide. For examples of expressions, see Using DataWindow expressions as property values.
Two techniques
There are two ways to access property values in a DataWindow object:
-
Methods
The Describe and Modify methods use strings to specify the property names. For example:
dw_1.Describe("empname.Border") dw_1.Modify("empname.Border=1") -
Expressions
DataWindow property expressions use the Object property and dot notation. For example:
dw_1.Object.empname.Border = 1 li_border = Integer(dw_1.Object.empname.Border)
In JavaScript, only the Describe and Modify methods are available.
Which technique to use
The technique you use depends on the type of error checking you want to provide and on whether you know the names of the controls and properties you want to access when the script is compiled.
|
If you want to |
Use |
|---|---|
|
Use column and property names that are known when the script is compiled |
An expression |
|
Avoid extra nested tildes (and you know the column and property names you want to access) |
An expression |
|
Build a string at runtime that names controls and properties |
A method |
|
Use the DWRuntimeError to handle problems with incorrect control or property names |
An expression in a try-catch block |
|
Use the Error event to handle problems with incorrect control or property names |
An expression and a script for the Error event |
|
Avoid using the Error event (or DWRuntimeError) for handling problems with incorrect control or property names |
A method and code that evaluates its return value |
When a DataWindow object property's value can be an expression, you can make the control's appearance or other properties depend on other information in the DataWindow.
A DataWindow expression can include:
-
Operators
-
The names of controls within the DataWindow, especially column and computed field names
-
DataWindow expression functions. Some functions, such as IsRowNew, refer to characteristics of an individual row
-
User-defined functions
Different formats for the expression
When you assign an expression in the painter, you specify just the expression:
DataWindowexpression
When you assign an expression in code, you specify a default value, a tab, and the expression:
defaultvalue [tab] DataWindowexpression
Examples
In the painter
This expression for a column called emp_lname is applied to the Background.Color property. It causes the name's background to be light gray (15790320) if the current row (person) uses the day care benefit. If not, the background color is set to white:
If(bene_day_care = 'Y', 15790320, 1677215)
In code
The expression assigned to the Background.Color property includes a default value. Nested quotes complicate the syntax:
PowerBuilder
dw_1.Object.emp_lname.Background.Color = "16777215 ~t If(bene_day_care = 'Y', 15790320, 16777215)"
JavaScript
dw_1.Modify("emp_lname.Background.Color = \"16777215 \t If(bene_day_care = 'Y', 15790320, 16777215)\");These examples illustrate the difference between the format for a DataWindow expression specified in the DataWindow painter versus in code.
Border property
The expression applied to the Border property of the salary_plus_benefits column displays a border around salaries over $60,000:
If(salary_plus_benefits > 60000, 1, 0)
This statement changes the expression in code:
dw_1.Object.salary_plus_benefits.Border = & "0 ~t If(salary_plus_benefits > 60000, 1, 0)"
Font.Weight property for a column
To make out-of-state (not in Massachusetts) names and numbers bold in a phone list, apply this expression to the name and phone_number columns. The state column must be part of the data source, but it does not have to be displayed:
If(state = 'MA', 400, 700)
This statement changes the expression in code:
dw_1.Object.name.Font.Weight = & "700 ~t If(state = 'MA', 400, 700)" dw_1.Object.phone_number.Font.Weight = & "700 ~t If(state = 'MA', 400, 700)"
Brush.Color property for a rectangle
This expression, applied to a rectangle drawn around all the columns in a tabular report, causes alternate rows to be shaded (a graybar effect). Make sure the columns and computed fields have a transparent background. The expression Mod(GetRow( ), 2) = 1 distinguishes odd rows from even rows:
If(Mod(GetRow(), 2) = 1, 16777215, 15790320)
This statement changes the expression in code:
dw_1.Object.rectangle_1.Brush.Color = & "0 ~t If(Mod(GetRow(), 2) = 1, 16777215, 15790320)"
Brush.Color and Brush.Hatch properties for a rectangle
To highlight employees whose review date is approaching, draw a rectangle behind the row. This expression for the rectangle's Brush.Color property makes the rectangle light gray for employees for whom the month of the start date matches the current month or the next month:
If(month(start_date) = month(today()) or month(start_date) = month(today()) + 1 or (month(today()) = 12 and month(start_date) = 1), 12632256, 16777215)
A similar expression for the Brush.Hatch property makes the fill pattern of the rectangle Bdiagonal (1) for review dates that are approaching. Otherwise, the rectangle is transparent (7) so that it does not show:
If(month(start_date) = month(today()) or month(start_date) = month(today()) + 1 or (month(today()) = 12 and month(start_date) = 1), 1, 7)
You can also set the Pen.Color and Pen.Style properties to affect the outline of the rectangle.
If you wanted to change the Brush.Color property in code instead of setting it in the painter, the code would look like this:
dw_1.Object.rectangle_1.Brush.Color = & "'16777215 ~t " + & "If(month(start_date) = month(today()) " + & "or month(start_date) = month(today()) + 1 " + & "or (month(today()) = 12 " + & "and month(start_date) = 1), 12632256, 16777215)'"
Font.Height property for a rectangle
This expression applied to the Font.Height property of a text control makes the text control in the first row of a DataWindow larger than it appears in other rows. Make sure the borders of the text control are large enough to accommodate the increased size:
If(GetRow() = 1, 500, 200)
This statement changes the expression for the text control t_desc in code:
dw_1.Object.t_desc.Font.Height = & "200 ~t If(GetRow() = 1, 500, 200)"
For more information
For more information about DataWindow expressions, see DataWindow Operators and Expressions
DataWindow property values often involve specifying strings within strings. Embedded quotation marks need special treatment so that the strings are parsed correctly. This treatment varies depending on the programming language you are using.
|
If you are using |
See |
|---|---|
|
PowerScript |
Nested strings and special characters for DataWindow object properties. |
|
JavaScript |
Nested strings and special characters in JavaScript for DataWindow object properties. |
Tilde (~) is the escape character that allows you to nest quoted strings within other quoted strings and to specify special characters such as tabs and carriage returns. For DataWindow object properties, several levels of nested strings can create a complicated expression.
Techniques for quoting nested strings
Both double and single quotes are valid delimiters for strings. You can use this fact to simplify the specification of nested strings.
There are two ways to embed a string within another string. You can:
-
Use the other type of quotation mark for the nested string. If the main string uses double quotes, the nested string can use single quotes.
"If(state='MA',255,0)"
-
Use the escape character to specify that a quote is part of the string instead the closure of a previous quote.
"If(state=~"MA~",255,0)"
If the string includes a third level of nested strings, you need to add another tilde which must be accompanied by its own escape character, a second tilde. This is the reason that tildes are usually specified in odd numbers (1, 3, or 5 tildes).
This Modify expression (entered on a single line in code) shows three levels of nested strings:
dw_1.Modify( "DataWindow.Color = '255 ~t If(state= ~'MA~',255,0)'")
This version of the expression has more tildes because there are no single quotes:
dw_1.Modify("DataWindow.Color = ~"255 ~t If(state= ~~~"MA~~~",255,0)~"")Common special characters
Strings can also include special characters, as shown in the previous example. This table lists the special characters that are most often used in DataWindow expressions.
|
Escape sequence |
Meaning |
|---|---|
|
~t |
Tab |
|
~r |
Carriage return |
|
~n |
Newline or linefeed |
|
~" |
Double quote |
|
~' |
Single quote |
|
~~ |
Tilde |
A line break is a carriage return plus a newline (\r\n).
Special use of tilde
A special case of specifying tildes involves the EditMask.SpinRange property, whose value is two numbers separated by a tilde (not an escape character, simply a tilde). To specify this value in a script, you must use a nested string with four tildes, which is interpreted as a single tilde when parsed:
dw_1.Modify("benefits.EditMask.SpinRange='0~~~~10'")More information
For more information about nested strings and special characters, see PowerScript Reference.
Different processing by language and DataWindow
JavaScript uses different characters from those used within the DataWindow to delimit strings and identify special characters. For DataWindow object properties, several levels of nested strings and two types of delimiter can create a complicated expression.
In JavaScript, strings are delimited by double quotes and the escape character in strings is the backslash (\). The escape character allows you to include double quotes and special characters within a string. The DataWindow can use either double or single quotes to delimit strings and uses tilde (~) as an escape character.
Because some parts of the string are parsed by the language and some by the DataWindow, strings passed to the DataWindow often use both types of escape character. The one to use depends on whether the DataWindow or the external language will evaluate the character. The external language deals with the outer string and converts escape sequences to the corresponding special characters. Nested strings are dealt with by the DataWindow parser.
Guidelines
Observe these guidelines for each type of character:
-
Special characters use the language escape character. Tabs, newlines, and carriage returns are \t, \n, \r
-
Nested double quotes require the language escape character (\) so they won't be interpreted as the closure of the opening double quote. Depending on the level of nesting, they may also require the DataWindow escape character (~).
-
Single quotes for nested strings do not need the language escape character, but depending on the level of nesting they may need the DataWindow escape character.
-
Tildes are specified in odd-numbered groups. They do not interact with the language escape character in counting the number of escape characters used.
Examples
Both of these JavaScript examples are valid ways of nesting a string:
dw_1.Modify("DataWindow.Crosstab.Values=\"empname\"");
dw_1.Modify("DataWindow.Crosstab.Values='empname'");The following three JavaScript statements specify the same string. They show a string with three levels of nesting using different combinations of escape characters and quote types. In the first example, note the escaping of the inner quote with a tilde for the DataWindow and a backslash for the language:
dw_1.Modify("emp_id.Color=\"16777215 \t If (emp_status=~\"A~\",255,16777215)\"");
dw_1.Modify("emp_id.Color=\"16777215 \t If (emp_status='A',255,16777215)\"");
dw_1.Modify("emp_id.Color='16777215 \t If (emp_status=\"A\",255,16777215)'");The corresponding example in PowerBuilder is:
dw_1.Modify("emp_id.Color = ~"16777215 ~t If (emp_status=~~~"A~~~",255,16777215)~"")Special use of tilde
A special case of specifying tildes involves the EditMask.SpinRange property, whose value is two numbers separated by a tilde (not an escape character, simply a tilde). In code, the value is in a nested string and needs a tilde escape character. The two tildes are interpreted as a single tilde when parsed by the DataWindow:
dw_1.modify("benefits.EditMask.SpinRange='0~~10'");