About DataWindow objects, controls, and components

DataWindow technology is implemented in two parts:

  • A DataWindow object

    The DataWindow object defines the data source and presentation style for the data.

  • A DataWindow control or component

    The control or component is a container for the DataWindow object in the application. You write code that calls methods of the container to manipulate the DataWindow object.

DataWindow controls and components

The DataWindow was invented for use in PowerBuilder to provide powerful data retrieval, manipulation, and update capabilities for client/server applications.

You can also use DataStore objects as containers for a DataWindow object. DataStores provide DataWindow functionality for retrieving and manipulating data without the on-screen display. Uses for DataStores include specifying layouts for printing and managing data in the server component of a distributed application.

What DataWindow objects are

A DataWindow object is an object that you use to retrieve, present, and manipulate data from a relational database or other data source (such as an Excel worksheet or dBASE file). You can specify whether the DataWindow object supports updating of data.

DataWindow objects have knowledge about the data they are retrieving. You can specify display formats, presentation styles, and other data properties to make the data meaningful to users.

In the DataWindow painter, you can also make Powersoft report (PSR) files, which you can use in DataWindow controls or components. A PSR file contains a report definition -- essentially a nonupdatable DataWindow object -- as well as the data contained in the report when the PSR file was created. It does not retrieve data.

Where to define DataWindow objects

You define DataWindow objects in the PowerBuilder DataWindow painter. You can also define nonupdatable DataWindow objects in the InfoMaker Report painter.

Presentation styles and data sources

When you define a DataWindow object, you choose a presentation style and a data source.

Presentation styles

A presentation style defines a typical style of report and handles how rows are grouped on the page. You can customize the way the data is displayed in each presentation style. The presentation styles include:

Presentation style

Description

Tabular

Data columns across the page and headers above each column. Several rows are viewable at once.

Freeform

Data columns going down the page with labels next to each column. One row displayed at a time.

Grid

Row-and-column format like a spreadsheet with grid lines. Users can move borders and columns.

Label

Several labels per page with one row for each label. Used for mailing and other labels.

N-Up

Two or more rows of data next to each other across the page. Useful for periodic data, such as data for each day of the week or each month in the quarter.

Group

A tabular style with rows grouped under headings. Each group can have summary fields with computed statistics.

TreeView

A tabular style that groups data hierarchically and displays the data in a way that is collapsible and expandable.

Composite

Several DataWindow objects grouped into a single presentation.

Graph

Graphical presentation of data.

Crosstab

Data summary in a row-and-column format.

RichText

Paragraphs of text with embedded data columns.

OLE

An OLE object linked or embedded in the DataWindow and associated with the retrieved data.


For examples of the presentation styles, see the section called “Choosing a presentation style” in Users Guide.

Data sources

The data source specifies where the data in the DataWindow comes from and what data items are displayed. Data can come from tables in a database, a Web service, a file with data that you can import, or code that specifies the data. For databases, the data specification is saved in a SQL statement. In all cases, the DataWindow object saves the names of the data items to display, as well as their datatypes.

Data source

Description

Quick Select

The data is coming from one or more tables in a SQL database. The tables must be related through a foreign key. You need to choose only columns, selection criteria, and sorting.

SQL Select

You want more control over the select statement that is generated for the data source. You can specify grouping, computed columns, and so on.

Query

The data has already been selected and the SQL statement is saved in a query object that you have defined in the Query painter. When you define the DataWindow object, the query object is incorporated into the DataWindow and does not need to be present when you run the application.

External

The data is not stored in a database, but is imported from a file (such as a tab-separated or dBASE file) or populated from code.

Stored Procedure

The data is defined in a database stored procedure.

Web Service

The data is defined in a Web service. Support for a Web service data source is not available for the Composite, RichText, and OLE presentation styles.


Basic process

Using a DataWindow involves two main steps:

  1. Use the DataWindow painter to create or edit a DataWindow object.

    In the painter, you define the data source, presentation style, and all other properties of the object, such as display formats, validation rules, sorting and filtering criteria, and graphs.

  2. In your development environment, put a DataWindow control in a window, visual user object, or form or a DataWindow container in a Web page and associate a DataWindow object with the control or container.

    It is through the control or container that your application communicates with the DataWindow object you created in the DataWindow painter. You write code to manipulate the DataWindow control or container and the DataWindow object it contains. Typically, your code retrieves and updates data, changes the appearance of the data, handles errors, and shares data between DataWindow controls.