Putting a DataWindow object into a control

The DataWindow control is a container for DataWindow objects in an application. It provides properties, methods, and events for manipulating the data and appearance of the DataWindow object. The DataWindow control is part of the user interface of your application.

You also use DataWindow objects in the nonvisual DataStore and in child DataWindows, such as drop-down DataWindows and composite presentation styles. For more information about DataStores, see Using DataWindow Objects. For more information about drop-down DataWindows and composite DataWindows, see Working with DataWindows in Users Guide.

To use the DataWindow object in an application, you add a DataWindow control to a window or form, then associate that control with the DataWindow object, as illustrated in the following figure: 

Figure 2-1: Putting a DataWindow object into a DataWindow control

The DataWindow painter contains multiple DataWindow objects. The Form designer contains a form that includes a DataWindow control. An arrow points from one of the DataWindow objects in the painter to the DataWindow control on the form, showing the association that has been established between them.

This section has information about:

Names for DataWindow controls and DataWindow objects

There are two names to be aware of when you are working with a DataWindow:

  • The name of the DataWindow control

  • The name of the DataWindow object associated with the control

The DataWindow control name

When you place a DataWindow control in a window or form, it gets a default name. You should change the name to be something meaningful for your application.

In PowerBuilder, the name of the control has traditionally had a prefix of dw_. This is a useful convention to observe in any development environment. For example, if the DataWindow control lists customers, you might want to name it dw_customer.

Using the name

In code, always refer to a DataWindow by the name of the control (such as dw_customer). Do not refer to the DataWindow object that is in the control.

The DataWindow object name

To avoid confusion, you should use different prefixes for DataWindow objects and DataWindow controls. The prefix d_ is commonly used for DataWindow objects. For example, if the name of the DataWindow control is dw_customer, you might want to name the corresponding DataWindow object d_customer.

Working with the DataWindow control in PowerBuilder

To place a DataWindow control in a window:

  1. Open the window that will contain the DataWindow control.

  2. Select Insert>Control>DataWindow from the menu bar.

  3. Click where you want the control to display.

    PowerBuilder places an empty DataWindow control in the window:

    A field of dots displays as a background grid in an untitled window. A blank rectangle superimposed on the grid represents the DataWindow control. The four corners of the control are small black rectangular handles for resizing the control. (Optional) Resize the DataWindow control by selecting it and dragging one of the handles.
  4. (Optional) Resize the DataWindow control by selecting it and dragging one of the handles.

Specifying a DataWindow object

After placing the DataWindow control, you associate a DataWindow object with the control.

To associate a DataWindow object with the control:

  1. In the DataWindow Properties view, click the Browse button for the DataObject property.

  2. Select the DataWindow object that you want to place in the control and click OK.

    The name of the DataWindow object displays in the DataObject box in the DataWindow Properties view.

  3. (Optional) Change the properties of the DataWindow control as needed.

Allowing users to move DataWindow controls

If you want users to be able to move a DataWindow control during execution, give it a title and select the Title Bar check box. Then users can move the control by dragging the title bar.

Defining reusable DataWindow controls

You might want all the DataWindow controls in your application to have similar appearance and behavior. For example, you might want all of them to do the same error handling.

To be able to define these behaviors once and reuse them in each window, you should create a standard user object based on the DataWindow control: define the user object's properties and write scripts that perform the generic processing you want, such as error handling. Then place the user object (instead of a new DataWindow control) in the window. The DataWindow user object has all the desired functionality predefined. You do not need to respecify it.

For more information about creating and using user objects, see Working with User Objects in Users Guide.

Editing the DataWindow object in the control

Once you have associated a DataWindow object with a DataWindow control in a window, you can go directly to the DataWindow painter to edit the associated DataWindow object.

To edit an associated DataWindow object:

  • Select Modify DataWindow from the DataWindow control's pop-up menu.

    PowerBuilder opens the associated DataWindow object in the DataWindow painter.

Specifying the DataWindow object during execution

Changing the DataWindow object

In PowerBuilder, set the DataObject property to one of the DataWindow objects built into the application.

Setting the transaction object when you change the DataWindow object

When you change the DataWindow object during execution, you might need to call setTrans or setTransObject again.

For more information, see Setting the transaction object for the DataWindow control.

Dynamically creating a DataWindow object

You can also create a new DataWindow object during execution and associate it with a control.

For more information, see Dynamically Changing DataWindow Objects.

Changing the DataWindow in PowerBuilder

When you associate a DataWindow object with a control in the window, you are setting the initial value of the DataWindow control's DataObject property.

During execution, this tells your application to create an instance of the DataWindow object specified in the control's DataObject property and use it in the control.

Setting the DataObject property in code

In addition to specifying the DataWindow object in the Window painter, you can switch the object that displays in the control during execution by changing the value of the DataObject property in code.

For example: to display the DataWindow object d_emp_hist from the library emp.pbl in the DataWindow control dw_emp, you can code:

dw_emp.DataObject = "d_emp_hist"

The DataWindow object d_emp_hist was created in the DataWindow painter and stored in a library on the application search path. The control dw_emp is contained in the window and is saved as part of the window definition.

Preventing redrawing

You can use the SetRedraw method to turn off redrawing in order to avoid flicker and reduce redrawing time when you are making several changes to the properties of an object or control. Dynamically changing the DataWindow object at execution time implicitly turns redrawing on. To turn redrawing off again, call the SetRedraw method every time you change the DataWindow object:

dw_emp.DataObject = "d_emp_hist"
dw_emp.SetRedraw(FALSE)

Using PSR files

To put a PSR file into a DataWindow control at execution time, change the control's DataObject property to specify that PSR file name.