Syntax for nested objects in DataWindow property expressions in PowerBuilder

Description

In PowerBuilder, DataWindow property expressions use additional Object keywords to refer to nested objects. Nested objects include composite or related nested reports and child DataWindows associated with DropDownDataWindow columns. Related nested and composite reports can include their own nested objects. You can extend the dot notation to refer to any level of nesting.

Syntax

dwcontrol.Object.nestedcontrolname { [row ] } .Object.dwcontrolname. 
	property { .property } { = value }

Argument

Description

dwcontrol

The name of the DataWindow control or child DataWindow in which you want to get or set properties.

Object

The Object keyword indicates that subsequent elements refer to the DataWindow object within dwcontrol.

nestedcontrolname

The name of a DropDownDataWindow column, nested report, or OLE Object control within the DataWindow object in dwcontrol.

NoteAbout nested reports A nested report can be one of a group of reports in the Composite presentation style or a nested report included in a base report, which is associated with a specific row.

row

When nestedcontrolname is a nested report in a base report, the number of the row the report is associated with

If the report is in a band other than the detail band, it is still associated with a row (see Usage below).

dwcontrolname

The name of a control within the nested DataWindow object. Possible values are DataWindow (for properties that apply to the whole DataWindow) or the name of a Button, Column, Computed field, Graph, GroupBox, Line, Oval, Picture, Rectangle, RoundRectangle, Report, TableBlob, or Text control.

If dwcontrolname is a column with the DropDownDataWindow style, a Report control, or an OLE Object control, you can specify an additional Object keyword and dwcontrolname to refer to properties of controls within the nested DataWindow object. You can specify Object.dwcontrolname as many times as needed to refer to a control in a deeply nested DataWindow object.

property

A property that applies to dwcontrolname. If the property requires additional qualifying properties, list the additional properties, separating them with a dot.

For lists of applicable properties, see the Property tables in Chapter 3, “DataWindow Object Properties”.

value

A string whose value is to be assigned to the property

For more information, see “Basic syntax for DataWindow property expressions in PowerBuilder”.

Datatype

Any. The datatype of the expression is Any, but the actual data is a string.

For more information about the expression’s datatype, see “Datatypes of DataWindow property expressions in PowerBuilder”.

Usage

A nested report within a base report is usually in the detail band, and each instance of the report is associated with a row. The property expression must include a row number to identify which report to access. If the nested report is in a band other than detail, there may be only one or a few instances of the report, but it is still associated with a row. The expression must include a row number that has an instance of the report.

The following table lists the band and the row that is associated with the report:

If the report is in this band

This row is associated with the report

detail

The specified row.

header

The first row on the page. On screen, this is the first row visible in the DataWindow body.

footer

The last row on the page. On screen, this is the last row visible in the DataWindow body.

header.n (group header)

The first row of the group (where n is the group number).

trailer.n (group trailer)

The last row of the group (where n is the group number).

summary

The last row in the report.

Examples

Example 1 Suppose that a DataWindow has the Composite presentation style and includes a report called rpt_employee. The report includes a column emp_id. This expression gets the validation expression for the column:

string ls_valid

ls_valid = dw_composite.Object.rpt_employee.&

		Object.emp_id.Validation

Example 2 In a Composite DataWindow, one of the reports rpt_1 has a graph gr_1. This example turns on grid lines for the category axis of that graph. The example sets an instance variable to a default value of “not found.” If the expression fails and triggers the Error event, the ExceptionSubstituteReturnValue! action causes the text “not found” to be returned so that the second assignment succeeds:

is_dwvalue = "not found"

dw_1.Object.rpt_1.Object.&

		gr_1.Category.MajorGridline = 5

st_status.Text = dw_1.Object.rpt_1.Object.&

		gr_1.Category.MajorGridline

The script for the Error event includes these lines:

action = ExceptionSubstituteReturnValue!

returnvalue = is_dwvalue

Example 3 Suppose that a DataWindow called dw_emp is a base report with employee information. The detail band includes a nested report of salary history called rpt_salary. This means there is a separate report with its own properties in each row.

The script checks whether the employee belongs to management (the value in the rank column in the base report is M). If so, the script assigns a DataWindow expression to the Color property of the salary column in the rpt_salary nested report. The expression highlights salaries that are over $60,000 in red.

Another statement sets the salary column’s Mode property so the color change will be visible:

integer li_row


FOR li_row = 1 to RowCount( )

		IF dw_emp.Object.rank.Primary[li_row] = "M" THEN


		 dw_emp.Object.rpt_salary[li_row].Object.&

			salary.Background.Color = &

			'255 ~t If(salary > 60000, 255, 0)'


		 dw_emp.Object.rpt_salary[li_row].Object.&

			salary.Background.Mode = 0


		END IF

NEXT

Example 4 In this example there is a graph in the summary band of a base report called dw_emp. The graph is a nested report called rpt_graph_salaries. Although the graph is not related to a particular row, you still need to provide the row number associated with the summary band when you refer to its properties. This statement turns on autoscaling for the values axis:

dw_emp.Object.rpt_graph_salaries.Object.&

		gr_1.Values.AutoScale = 1

Example 5 If a column has a DropDownDataWindow edit style, there are properties that affect the column’s appearance. Using nested object syntax, you can also change properties of the child DataWindow for the column. In this example, the DataWindow dw_gift allows a clerk at a nonprofit organization to record donations. The clerk can pick a standard donation amount from a drop-down DataWindow.

This example makes the drop-down DataWindow column called amount a required value and changes the display format for the dollars column in the child DataWindow:

dw_gift.Object.amount.dddw.Required = "Yes"

dw_gift.Object.amount.Object.dollars.Format = "$#,##0"