Modifying general DataWindow object properties

This section describes the general DataWindow object properties that
you can modify.

Changing the DataWindow object style

The general style properties for a DataWindow object include:

• The unit of measure used in the DataWindow object
• A timer interval for events in the DataWindow object
• A background color for the DataWindow object

PowerBuilder assigns defaults when it generates the basic DataWindow object. You
can change the defaults.

To change the default style properties:

1. Position the pointer in the background
   of the DataWindow object, display the pop-up menu, and select Properties.

   The Properties view displays with the General page on top.

2. Click the unit of measure you want to use to specify
   distances when working with the DataWindow object:

   • PowerBuilder units (PBUs)
   • Pixels (smallest element on the display monitor)
   • Thousandths of an inch
   • Thousandths of a centimeter

   Choosing the unit of measure If you plan to print the contents of the DataWindow object during execution,
   change the unit of measure to inches or centimeters to make it easier
   to specify the margin measurements.

3. Specify the number of milliseconds you want between
   internal timer events in the DataWindow object.

   This value determines how often PowerBuilder updates the time
   fields in the DataWindow object. (Enter 60,000 milliseconds to specify
   one minute.)

4. Select a background color from the Color drop-down
   list and click OK. The default color is the window background color.

Setting colors in a DataWindow object

You can set different colors for each element of a DataWindow object to enhance
the display of information.

To set the background color in a DataWindow object:

1. Position the mouse on an empty spot in
   the DataWindow object, display the pop-up menu, and select Properties.

2. On the General page in the Properties view for
   the DataWindow object, select a color from the Color drop-down list.

To set the color of a band in a DataWindow object:

1. Position the mouse pointer on the bar that
   represents the band, display the pop-up menu, then select Properties.

2. On the General page in the band’s Properties
   view, select a color from the Color drop-down list.

   The choice you make here overrides the background color for
   the DataWindow object

To set colors in controls in a DataWindow object:

1. Position the mouse pointer on the control,
   display the pop-up menu, then select Properties.

   For controls that use text, you can set colors for background
   and text on the Font page in the Properties view. For drawing controls,
   you can set colors on the General page in the Properties view

Specifying properties of a grid DataWindow object

In grid DataWindow objects you can specify:

• When grid lines are displayed
• How users can interact with the DataWindow object during
  execution

To specify basic grid DataWindow object properties:

1. Position the mouse pointer on the background
   in a grid DataWindow object, display the pop-up menu, and select Properties.

2. Select the options you want in the Grid section
   on the General page in the Properties view as described in Table 18-3.

   Table 18-3: Options for grid DataWindow objects

   Option	Result
   On	Grid lines always display
   Off	Grid lines never display (users cannot resize columns during execution)
   Display Only	Grid lines display only when the DataWindow object displays online
   Print Only	Grid lines display only when the contents of the DataWindow object are printed
   Column Moving	Columns can be moved during execution
   Mouse Selection	Data can be selected during execution (and, for example, copied to the clipboard)
   Row Resize	Rows can be resized during execution

Specifying pointers for a DataWindow object

Just as with colors, you can specify different pointers to
use when the mouse is over a particular area of the DataWindow object. For
example, you might want to change the pointer when the mouse is
over a column whose data cannot be changed.

To change the mouse pointer used during execution:

1. Position the mouse over the element of
   the DataWindow object whose pointer you want to define, display the pop-up
   menu, and select Properties to display the appropriate Properties
   view.

   You can set a pointer for the entire DataWindow object, specific
   bands, and specific controls.

2. Select the Pointer tab.

3. Choose the pointer either from the Stock Pointers
   list or, if you have a file containing pointer definitions (CUR
   files), enter a pointer file name.

   You can use the Browse button to search for the file.

4. Click OK.

Defining print specifications for a DataWindow object

When you are satisfied with the look of the DataWindow object, you
can define the print specifications for the DataWindow object.

To define print specifications for a DataWindow object:

1. In the DataWindow painter, select Properties from
   the DataWindow object’s pop-up menu to display the DataWindow object’s
   Properties view.

2. In the Units box on the General page, select a
   unit of measure.

   It is easier to specify the margins when the unit of measure
   is inches or centimeters.

3. Select the Print Specifications tab.

   The Print Specifications page uses the units of measure you
   specified on the General page.

4. Specify print specifications for the current DataWindow
   object.

   See Table 18-4 for
   more information.

Table 18-4: Setting print specifications
for DataWindow objects

Setting	Description
Document Name	Specify a name to be used in the print queue to identify the report.
Printer Name	Specify the name of a printer to which this report should be sent. If this box is empty, the report is sent to the default system printer. If the specified printer cannot be found, the report is sent to the default system printer if the Can Use Default Printer check box is selected. If the specified printer cannot be found and the Can Use Default Printer check box is not selected, an error is returned.
Margins	Specify top, bottom, left, and right margins. You can also change margins in the Preview view while you are actually looking at data. If you change margins in the Preview view, the changes are reflected here on the Print Specifications page.
Paper Orientation	Choose one of the following: Default: Uses the default printer setup. Portrait: Prints the contents of the DataWindow object across the width of the paper. Landscape: Prints the contents of the DataWindow object across the length of the paper.
Paper Size	Choose a paper size or leave blank to use the default.
Paper Source	Choose a paper source or leave blank to use the default.
Prompt Before Printing	Select to display the standard Print Setup dialog box each time users make a print request.
Can Use Default Printer	Clear this check box if a printer has been specified in the Printer Name box and you do not want the report to be sent to the default system printer if the specified printer cannot be found. This box is checked by default if a printer name is specified.
Display Buttons – Print Preview	Select to display Button controls in Print Preview. The default is to hide them.
Display Buttons – Print	Select to display Button controls when you print the report. The default is to hide them.
Clip Text	Select to clip static text to the dimensions of a text field when the text field has no visible border setting. The text is always clipped if the text field has visible borders.
Override Print Job	When you print a series of reports using the PrintOpen, PrintDataWindow, and PrintClose functions, all the reports in the print job use the layout, fonts, margins, and other print specifications defined for the computer. Select this check box to override the default print job settings and use the print settings defined for this report.
Collate Copies	Select to collate copies when printing. Collating increases print time because the print operation is repeated to produce collated sets.
Newspaper Columns Across and Width	If you want a multiple-column report where the data fills one column on a page, then the second, and so on, as in a newspaper, select the number and width of the columns in the Newspaper Columns boxes. See “Printing with newspaper-style columns”.

Printing with newspaper-stylecolumns

When you define a DataWindow object, you can specify that it print
in multiple columns across the page, like a newspaper. A typical
use of newspaper-style columns is a phone list, where you want to
have more than one column of names on a printed page.

Use Print Preview to see the printed output Newspaper-style columns are used only when the DataWindow object is printed.
They do not appear when a DataWindow object executes (or in Preview). Therefore,
to see them in PowerBuilder, use Print Preview in the DataWindow painter.

To define newspaper-style columns for a DataWindow object:

1. Build a tabular DataWindow object with the data
   you want.

2. Select Properties from the DataWindow object’s
   pop-up menu.

3. Select the Print Specifications tab.

4. Specify the number of columns across the page
   and the width of columns in the Newspaper Columns Across and Newspaper
   Columns Width properties.

5. For each control in the DataWindow object that you do not want
   to have appear multiple times on the page (such as headers), select
   Properties from the control’s pop-up menu and select the
   HideSnaked check box on the General page in the Properties view.

Example

This example describes how to create a newspaper-style DataWindow object using
the Employee table in the EAS Demo DB.

1. Create a tabular DataWindow object,
   selecting the last name, first name, and phone number columns, and
   add a title, page number, and date.
   The Emp_Fname column and the
   text control holding a comma are defined as Slide Left so they display
   just to the right of the Emp_Lname column.

   

2. On the Print Specifications page of the DataWindow object’s
   Properties view, specify two columns across and a column width of
   3.5 inches in the Newspaper Columns boxes.
3. To view the DataWindow object as it will be printed, place
   the pointer in the Preview view and select File>PrintPreview.
   The DataWindow object displays the result set in two columns. Everything above
   the column headers (which includes page number, title, and date) also
   shows twice because of the 2-column specification. This information should
   appear only once per page.
4. To specify that page number, title, and date appear
   only once on the page, you need to suppress printing after the first
   column. For each of these controls, select Properties from the control’s
   pop-up menu. Then select the HideSnaked check box.

The finished DataWindow object has one set of page heading information
and two columns of column header and detail information.

Modifying text in a DataWindow object

When PowerBuilder initially generates the basic DataWindow object,
it uses the following attributes and fonts:

• For the text and alignment
  of column headings and labels, PowerBuilder uses the extended column
  attributes made in the Database painter.
• For fonts, PowerBuilder uses the definitions made
  in the Database painter for the table. If you did not specify fonts
  for the table, PowerBuilder uses the defaults set in the Application
  painter.

You can override any of these defaults in a particular DataWindow object.

To change text in a DataWindow object:

1. Select the text.

   The first box in the StyleBar is now active.

2. Type the new text.

   Use ~n~r to embed a newline
   character in the text.

To change the text properties for a text control
in a DataWindow object:

1. Select the text control.

2. Do one of the following:

   • Change the text properties in the StyleBar.
   • Select the Font page in the control’s Properties
     view and change the properties there.

Defining the tab order in a DataWindow object

When PowerBuilder generates the basic DataWindow object, it assigns columns
a default tab order, the default sequence in which focus moves from column
to column when a user presses the Tab key during execution. PowerBuilder assigns
tab values in increments of 10 in left-to-right and top-to-bottom
order.

Tab order is not used in the Design view Tab order is used when a DataWindow object is executed, but it is
not used in the DataWindow painter Design view. In the Design view, the
Tab key moves to the controls in the DataWindow object in the order in
which the controls were placed in the Design view.

If the DataWindow object contains columns from more than
one table

If you are defining a DataWindow object with more than one table, PowerBuilder assigns
each column a tab value of 0, meaning the user cannot tab to the
column. This is because, by default, multitable DataWindow objects are
not updatable–users cannot modify data in them. You can
change the tab values to nonzero values to allow tabbing in these DataWindow objects.

For more about controlling updates in a DataWindow object,
see Chapter 20, “Controlling Updates in DataWindow Objects.”

Tab order changes have no effect in grid DataWindow objects In a grid DataWindow object, the tab sequence is always left to right
(except on right-to-left operating systems). Changing the tab value
to any number other than 0 has no effect.

To change the tab order:

1. Select Format>Tab Order from the
   menu bar or click the Tab Order button on PainterBar2.

   The current tab order displays.

2. Use the mouse or the Tab key to move the pointer
   to the tab value you want to change.

3. Enter a new tab value in the range 0 to 9999.

   0 removes the column from the tab order (the user cannot tab
   to the column). It does not matter exactly what value you use (other
   than 0); all that matters is relative value. For example, if you
   want the user to tab to column B after column A but before column
   C, set the tab value for column B so it is between the value for
   column A and the value for column C.

4. Repeat the procedure until you have the tab order
   you want.

5. Select Format>Tab Order from the menu
   bar or click the Tab Order button again.

   PowerBuilder saves the tab order.

Each time you select Tab Order, PowerBuilder reassigns tab values
to include any columns that have been added to the DataWindow object and
to allow space to insert new columns in the tab order.

Changing tab order during execution To change tab order programmatically in a script, use the SetTabOrder function.

Naming controls in a DataWindow object

You use names to identify columns and other controls in validation
rules, filters, PowerScript functions, and DataWindow expression functions.

The DataWindow painter automatically generates names for all controls
in a DataWindow object. To name columns, labels, and headings, the DataWindow painter uses
database and extended attribute information. To name all other controls,
it uses a system of prefixes. You can control the prefixes used
for automatic name generation and you can specify the name of any
control explicitly.

To specify prefixes for naming controls systematically
in a DataWindow object:

1. Select Design>Options from the
   menu bar and then select the Prefixes tab.

2. Change prefixes as desired and click OK.

To specify a name of a control in a DataWindow object:

1. Select Properties from the control’s
   pop-up menu and then select the General tab in the Properties view.

2. Type the name in the Name box.

Using borders in a DataWindow object

You can place borders around text, columns, graphs, and crosstabs
to enhance their appearance. PowerBuilder provides six types of borders:
Underline, Box, ResizeBorder, ShadowBox, Raised, and Lowered:

Border appearance varies Changing the border style may not have the same effect on
all Windows platforms.

To add a border to a control in a DataWindow object:

1. Select one or more controls.

2. Select the border you want from the Border drop-down
   toolbar in the PainterBar.

   PowerBuilder places the border around the selected controls.

You can also specify a border for one or more controls in
the Properties view on the General page.

Specifying variable-height detail bands in a DataWindow object

Sometimes DataWindow objects contain columns whose data is of variable length.
For example, a Memo column in a table might be a character column that
can take up to several thousand characters. Reserving space for
that much information for the column in the detail band would make
the detail band’s height very large, meaning the users could
see few rows at a time.

The detail band can resize based on the data in the Memo column.
If the Memo column has only one line of text, the detail band should
be one line. If the Memo column has 20 lines of text, the detail
band should be 20 lines high.

To provide a detail band that resizes as needed, specify that
the variable-length columns and the band have Autosize
Height.

To create a resizable detail band in a DataWindow object:

1. Select Properties from the pop-up menu
   of a column that should resize based on the amount of data.

2. Select the Autosize Height check box on the Position
   page.

3. Clear the Auto Horz Scroll check box on the Edit
   page.

   PowerBuilder wraps text in the Preview view instead of displaying
   text on one scrollable line.

4. Repeat steps 1 to 3 for any other columns that
   should resize.

5. Select Properties from the detail band’s
   pop-up menu.

6. Select the Autosize Height check box on the General
   page.

   In the Preview view, the detail band resizes based on the
   contents of the columns you defined as having Autosize Height.

Clipping columns You can have Autosize Height columns without an Autosize Height
detail band. If such a column expands beyond the size of the detail
band in the Preview view, it is clipped.

Modifying the data source of a DataWindow object

When modifying a DataWindow object, you might realize that you have
not included all the columns you need, or you might need to define
retrieval arguments. You can modify the data source from the DataWindow painter. How
you do it depends on the data source.

Modifying SQL SELECT statements

If the data source is SQL (such
as Quick Select, SQL Select,
or Query), you can graphically modify the SQL SELECT statement.

To modify a SQL data
source:

1. Select Design>Data Source from
   the menu bar.

   PowerBuilder returns you to the Select painter. (If you used
   Quick Select to define the data source, this might be the first
   time you have seen the Select painter.)

2. Modify the SELECT statement
   graphically using the same techniques as when creating it.

   For more information, see “Using SQL Select”.

   Modifying the statement syntactically Select Design>Convert to Syntax from the menu bar
   to modify the SELECT statement syntactically.

3. Click the Return button to return to the painter.

Some changes you make (such as adding or removing columns)
require PowerBuilder to modify the update capabilities of the DataWindow object.

For more information about controlling updates
in a DataWindow object, see Chapter 20, “Controlling Updates in DataWindow Objects.”

Changing the table If you change the table referenced in the SELECT statement, PowerBuilder maintains
the columns in the Design view (now from a different table) only
if they match the data types and order of the columns in the original
table.

Modifying the retrieval arguments

You can add, modify, or delete retrieval arguments when modifying
your data source.

To modify the retrieval arguments:

1. In the Select painter, select Design>Retrieval
   Arguments from the menu bar.

   The Specify Retrieval Arguments dialog box displays listing
   the existing arguments.

2. Add, modify, or delete the arguments.

3. Click OK.

   You return to the Select painter, or to the text window displaying
   the SELECT statement if you are modifying the SQL syntactically.

4. Reference any new arguments in the WHERE or HAVING clause
   of the SELECT statement.

For more information about retrieval arguments,
see Chapter 17, “Defining DataWindow Objects “.

Modifying the result set

If the data source is External or Stored Procedure, you can
modify the result set description.

To modify a result set:

1. If the Column Specification view is not open,
   select View>Column Specifications from the menu bar.

2. Review the specifications and make any necessary changes.

If the data source is a stored procedure

If you are modifying the result set for a DataWindow object whose
data source is a stored procedure, the pop-up menu for the Column
Specification view contains the menu item Stored Procedure.

Select Stored Procedure from the Column Specification view’s
pop-up menu to edit the Execute statement, select another stored
procedure, or add retrieval arguments. For more information about
editing the Execute statement, see “Using Stored Procedure”.

---