About this chapter
This chapter explains how to create DataWindow objects using the RichText presentation style and how to use the RichTextEdit control.
Rich text format (RTF) is a standard for specifying formatting instructions and document content in a single ASCII document. An editor that supports rich text format interprets the formatting instructions and displays formatted content. If you look at rich text in a plain ASCII editor, you see complex instructions that are not very readable. The actual text of the document is obscured by the formatting instructions:
{\par}\pard\ql{\f2\fs18\cf0\up0\dn0 A RichText piece of text}The same sample displayed without the commands looks like this:
A RichText piece of text
Elements of rich text
Rich text in PowerBuilder can have:
-
Margins and tab settings for each paragraph
-
Character formatting such as italic, bold, underline, or superscripts for each character
-
Named input fields associated with database columns or other data
-
Bitmaps
-
A header and footer for the document
The user can use toolbars, editing keys, and a pop-up menu to specify formatting. A print preview lets users view a reduced image of the document to see how it fits on the page.
Rich text support in PowerBuilder
In PowerBuilder you can use rich text as a DataWindow presentation style. You can also add a RichTextEdit control to a window or visual user object.
What is not supported
PowerBuilder supports version 1.6 of the RTF standard, except for the following features:
-
Formatted tables
-
Drawing objects
The RichText presentation style allows you to combine input fields that represent database columns with formatted text. This presentation style is useful for display-only reports, especially mail-merge documents. However, if you want to use the RichText DataWindow object for data entry, you can specify validation rules and display formats for the input fields.
In the Design view, you see the text along with placeholders called input fields:
{FNAME} {LNAME}
{COMPANY_NAME}
{ADDRESS}
{CITY}, {STATE} {ZIP}
Dear {FNAME}:
...In the Preview view, the text is the same, but PowerBuilder replaces the input fields with values from the database:
Beth Reiser AMF Corp. 1033 Whippany Road New York, NY 10154 Dear Beth: ...
Document template
The formatted text acts like a document template. There is only one copy of the text. As the user scrolls from row to row, the data for the current row is inserted in the input fields and the user sees the document with the current data. If the user edits the text, the changes show up in every row of data.
Input fields
In the RichText presentation style, an input field is associated with a column or computed field. It gets its value from the retrieved data or from the computed field's expression.
If an input field is not a computed field and its name does not match a column, there is no way to specify data for the input field.
There can be more than one copy of an input field in the rich text. In the sample above, there are two instances of the field FNAME. Each instance of the field displays the same data.
Unavailable settings
Not all the settings available in other DataWindow styles are available. You cannot apply code tables and edit styles, such as a DropDownDataWindow or EditMask, to input fields. You cannot use slide left and slide up settings to reposition input fields automatically. However, you can set the LineRemove property at runtime to achieve a similar effect.
To create a RichText DataWindow object
-
In the New dialog box, select RichText from the DataWindow tab and click OK.
-
Select data for the DataWindow object as you do for any DataWindow object.
-
If you want data to be retrieved into the Preview view automatically, select the Retrieve on Preview check box. For more information, see Building a DataWindow object.
-
Specify settings for the DataWindow object on the Specify RichText Settings screen, click Next, and then click Finish.
Available settings
The following table describes the types of settings you can make for the RichText DataWindow object in the wizard.
|
You can specify |
With these settings |
|---|---|
|
Tools available to the user |
Rich text bars: Tool, Status, Ruler, and PopUp Menu |
|
Whether there will be a header and footer for the printed DataWindow object |
Header/Footer |
|
Whether users are prevented from editing input fields and text |
Display Only |
|
Colors for the whole background and the background of input fields |
Background Color: General and Input Field |
Editing the content
After you click Finish in the wizard, you see input fields with their labels in the detail band in the Design view:
You can:
-
Begin editing text in the detail, header, or footer bands, building a report around the input fields. You can delete, move, copy, and paste text and input fields as needed.
-
Include a rich text file you have already prepared. If you include a rich text file created in PowerBuilder that contains input fields, those names should match the columns selected in the DataWindow object.
For information about creating rich text files, see the section called “Implementing Rich Text” in Application Techniques.
-
Add computed fields that will appear as input fields in the report and whose values come from the computed field expression.
This sample shows how you might rearrange the input fields in a sales letter:
Editing text
You can add text by typing directly in the Design view. You do not have to create text objects as you do for other DataWindow object styles. The DataWindow painter's StyleBar lets you apply formatting to selected text. The RichText toolbars are not available in the painter.
Preview mode and editing text
You cannot edit text in the Preview view, but you can edit it when you preview the DataWindow object by selecting File>Run/Preview from the menu bar. It may seem convenient to edit text in Preview mode because the toolbars are available. However, any changes you make to the text when previewing are temporary. They are discarded as soon as you return to the Design view.
Inserting a file
If you have a rich text file, you can include it in the DataWindow object. In the Design view, you can insert text from a file into the detail, header, or footer band.
To insert a file
Click in the text in any band to set the insertion point for the file.
-
Right-click in the Design view and select Insert File from the pop-up menu.
-
In the file selection dialog box, select the file you want to insert.
Only the body of the file is used. If the file has a header or footer, it is ignored.
Headers and footers
You decide whether your RichText DataWindow object has a header and footer by checking Header/Footer in the wizard or Rich Text Object dialog box (described in Formatting for RichText objects within the DataWindow object).The decision to include a header and footer must be made at design time; it cannot be changed at runtime.
To display a page number or a date in the header or footer, you can insert the predefined computed fields Page n of n or Today(). You do not need to write scripts to set the values of these fields for each page, as you do for the RichTextEdit control.
Each type of object in a RichText DataWindow object has its own dialog box. When you select Properties from the pop-up menu, the dialog box you get depends on what is selected.
Properties and Control List views
The Properties and Control List views are not available for RichText DataWindow objects. The painter uses the same property sheets as are available to users when they run the DataWindow object, and controls in RichText DataWindow objects cannot be manipulated in the same way as in other DataWindow objects.
Most of the objects in a RichText DataWindow object correspond to familiar objects like bitmaps, columns, and computed fields. You can also specify formatting for a temporary selected text object. In a RichText DataWindow object, the objects are:
-
The whole document
-
Selected text and paragraphs
-
Input fields (associated with columns or computed fields)
-
Pictures
This section describes how to select each type of object and access its dialog box. The user can access the property sheets too if you enable the Popup Menu option on the Rich Text Object's General dialog box.
Settings for the whole RichText DataWindow object include the values you specified in the wizard, as well as:
-
Whether pictures are displayed or represented by empty frames
-
Whether newly entered text will wrap within the display
-
Whether various nonprinting characters, such as tabs, returns, and spaces, are visible
-
Standard DataWindow object settings such as units of measurement and the pointer
-
Print specifications
Use the following procedure to change settings:
You can specify detailed font formatting for selected text. The selected text can be one character or many paragraphs.
If an input field is part of the selection, the font settings apply to it, too. A picture that is part of the selection ignores settings for the selected text object.
To specify formatting for selected text
-
Select the text you want to format.
-
Right-click in the Design view and select Properties from the pop-up menu.
The Selected Text Object dialog box displays. You can set:
-
Paragraph alignment
The alignment setting on the Selected Text page applies to all paragraphs in the selection.
-
Font formatting
Settings on the Font page apply to text in the selection, including input fields.
-
Paragraphs
There are also settings for selected paragraphs. You can display the Paragraph dialog box by pressing Ctrl+Shift+S. The user can double-click the ruler bar or press the key combination to display the same dialog box.
Default font
The user can change the default font by double-clicking on the toolbar or pressing Ctrl+Shift+D. You cannot change the default font in the painter.
An input field can be either a column or a computed field. Before you retrieve data, its value is shown as two question marks (??).
The text can include many copies of a named input field. The same data will appear in each instance of the input field.
Column input fields
The columns you select for the DataWindow object become input fields in the rich text. Because the input field's name matches the column name, PowerBuilder displays the column's data in the input field.
If an input field exists in the text, you can copy and paste it to create another copy. If you need to recreate a column input field that you deleted, use this procedure.
To insert a column input field in the text
-
Select Insert>Control>Column from the menu bar.
-
Click in the text where you want the column input field to appear.
PowerBuilder displays a list of the columns selected for the DataWindow object.
-
Select a column for the input field.
Properties for input fields
You select an input field by clicking inside it. A computed input field is selected when the whole field is highlighted.
To set properties for an input field
-
Click in the input field in Design view.
-
Display the pop-up menu and select Properties.
-
On the Font page, specify text formatting.
-
On the Format page, specify a display format.
-
On the Validation page, specify a validation rule for the column.
If there are multiple copies of an input field, the validation and format settings apply to all the copies. Background color on the Font page applies to all input fields. Other settings on the Font page apply to individual instances.
The user cannot change the format or validation rule. At runtime, these pages are not available in the dialog box.
Computed field input fields. When you display the dialog box for a computed field, the settings are a little different. You can specify the input field name and its expression on the Compute page and there is no validation.
Data Value in preview. For both columns and computed fields, you see a value in the Data Value box when you preview the DataWindow object. The user sees a value in the Data Value box when the current row has a value. For columns, users can change the value.
Computed fields
Computed fields have an expression that specifies the value of the computed field. In rich text, they are represented as input fields, too. You specify a name and an expression. The data value comes from evaluating the expression and cannot be edited.
To define a computed field:
-
Select Insert>Control>Computed Field.
Predefined computed fields
You can also select one of the predefined computed fields at the bottom of the menu. PowerBuilder provides several predefined computed fields, but in a RichText DataWindow object, only the page number (Page n of n) and today's date (Today()) are available.
-
Click in the text where you want the computed field to appear.
If you do not select a predefined computed field, PowerBuilder displays the dialog box for the computed field:
-
On the Compute page, name the computed field and specify its expression.
-
(Optional) On the Font page, specify text formatting.
-
(Optional) On the Format page, specify a display format.
If there are multiple copies of a computed field input field, the expression and format settings apply to all the copies. Font settings apply to individual instances. For more about computed field expressions and display formats, see Enhancing DataWindow Objects.
Inserting a picture
You can include bitmaps (BMP, GIF, JPG, RLE, or WMF files) in a RichText DataWindow.
To insert a picture in the rich text
-
Select Insert>Control>Picture from the menu bar.
-
Click in the text where you want the picture to appear.
PowerBuilder displays the Select Picture dialog box.
-
Select the file containing the picture.
Specifying picture size
A picture is selected when you can see a dashed outline in Design or Preview view. When the picture is part of a text selection, it displays with inverted colors.
You can change the size of a picture as a percentage of the original picture size. The allowable range for a size percent change is between 10 and 250 percent.
To specify size settings for the picture
-
Click on the picture in the Design or Preview view so you see its dashed-outline frame.
-
Right-click in the Design or Preview view and select Properties from the pop-up menu.
The Rich Text - Picture Object dialog box displays.
-
Change the percent of the original picture size in the Width and Height text boxes.
The picture expands or contracts according to the size percentage you selected.
To see what the RichText DataWindow object looks like with data, you can preview it in the Preview view or in preview mode.
To preview the DataWindow object in preview mode
-
Select File>Run/Preview from the menu bar, or click the Run/Preview button on the PowerBar.
-
Select Rows>Retrieve from the menu bar.
Retrieve on Preview
If the RichText definition specifies Retrieve on Preview, data is retrieved automatically when you open the Preview view or preview the DataWindow object in preview mode.
Changes in preview
Datax. While previewing the DataWindow object in preview mode, or when focus is in the Preview view, you can use the scroll buttons in the Preview toolbar to move from row to row, and you can change data in the input fields. If you choose the Save Changes button on the toolbar, you will update the data in the database.
Text. Any changes you make to the rich text in the Preview view will not be reflected in the Design view. Any changes that you want to keep must be made in the Design view, not in preview.
If the Display Only setting is checked, you cannot change text or data in the Preview view.
Print Preview
Print Preview displays a reduced view of one row of data as it would appear when printed.
To see the DataWindow object in Print Preview:
-
Click in the Preview view to make it the current view.
-
Select File>Print Preview.
In Print Preview, you can test different margin settings and scroll through the pages of the document.
You cannot scroll to view other rows of data.
Any changes you make to settings in Print Preview are discarded when you return to the Design view.
Setting margins
To specify permanent margin settings for the RichText DataWindow object, use the Print Specifications page of the Rich Text Object dialog box.
You can add a RichTextEdit control to a window to enhance your application with word processing capabilities.
Users can enter text in a RichTextEdit control, format it, save it to a file, and print it. You can also enable a pop-up menu from which users can control the appearance of the control and import documents.
To add a RichTextEdit control to a window:
-
In the Window painter, select Insert>Control>RichTextEdit and click the window.
Controlling the appearance of a RichTextEdit control
You modify the appearance of a RichTextEdit control by setting its properties. Some of the properties you can set are:
-
The toolbars that appear in the control
-
The visibility of nonprinting characters and graphics
To control the appearance of a RichTextEdit control:
-
Select the control, then select the Document tab in the Properties view.
-
Choose the appropriate properties to display toolbars.
-
Choose the appropriate properties if you want to display nonprinting characters such as tabs, spaces, and returns.
For information about other options on the Document properties page, select Help from the property page's pop-up menu.
Making a RichTextEdit control read-only
There are times when you might want to import a file into the RichTextEdit control and not give the user the opportunity to alter it. You can make a control read-only by setting the Enabled and Popup Menu properties.
To make a RichTextEdit control read-only:
-
Select the control, then select the General tab in the Properties view.
-
Make sure the Enabled check box is cleared.
-
Select the Document tab.
-
Make sure the PopMenu check box is cleared.
Enabling the pop-up menu
If you enable the pop-up menu property, users can customize the appearance of the RichTextEdit control.
From the pop-up menu, users can:
-
Perform editing tasks (cut, copy, paste, and clear)
-
Insert a file into the RichTextEdit control
-
Display and modify the Rich Text Object dialog box
The General property page on the user's Rich Text Object dialog box presents many of the same options as the Document property page in the development environment.
For more information about the RichTextEdit control, see the section called “Implementing Rich Text” in Application Techniques.
When the toolbar is visible, you can use its buttons to format text. The changes you make in preview are temporary.
The keystrokes listed in the following tables also assign formatting to selected text.
Keyboard shortcuts do not work in the painter
These keystrokes work only when you are running the DataWindow object or the window containing the RichTextEdit control. In PowerBuilder, only keyboard shortcuts defined for menu items in the painter can be used.
|
Category |
Action |
Key |
|---|---|---|
|
Using the clipboard |
Cut |
Ctrl+X |
|
Paste |
Ctrl+V, Shift+Insert |
|
|
Copy |
Ctrl+C |
|
|
Undo |
Ctrl+Z |
|
|
Assigning font attributes |
Bold |
Ctrl+B |
|
Italic |
Ctrl+I |
|
|
Underline |
Ctrl+U |
|
|
Subscript |
Ctrl+= |
|
|
Superscript |
Ctrl+Shift+= |
|
|
Strikeout |
Ctrl+U |
|
|
Change font |
Ctrl+Shift+U |
|
|
Setting line spacing |
Single space |
Ctrl+1 |
|
Double space |
Ctrl+2 |
|
|
One and a half space |
Ctrl+5 |
|
|
Aligning text |
Justify |
Ctrl+J |
|
Center |
Ctrl+E |
|
|
Left |
Ctrl+L |
|
|
Right |
Ctrl+R |
|
|
Set paragraph formatting |
Ctrl+Shift+S |
|
|
Editing |
Insert a new paragraph |
Enter |
|
Insert an empty line |
Ctrl+N |
|
|
Delete character to right of insertion point |
Delete |
|
|
Delete character to left of insertion point |
Backspace |
|
|
Input fields |
Select the input field at the insertion point |
Enter |
|
Activate the input field at the insertion point |
Space |
|
|
When input field is active, accept data and exit field |
Enter |
|
|
When input field is active, exit field without changing data |
Esc |
|
|
Move to next input field |
Ctrl+Tab |
|
|
Move to previous input field |
Shift+Ctrl+Tab |
|
|
Miscellaneous |
Select All |
Ctrl+A |
|
|
Ctrl+P |
|
|
Undo |
Ctrl+Z |
|
|
Toggle display of nonprinting characters |
Ctrl+* |
|
|
Toggle preview mode |
Ctrl+F2 |
Navigating and selecting text
|
Move or select |
Navigating key |
Selection key |
|---|---|---|
|
A character to the right or left |
Right Arrow or Left Arrow |
Shift+Right Arrow or Shift+Left Arrow |
|
A word to the right or left |
Ctrl+Right Arrow or Ctrl+Left Arrow |
Ctrl+Shift+Right Arrow or Ctrl+Shift+Left Arrow |
|
A line up or down |
Up Arrow or Down Arrow |
Shift+Up Arrow or Shift+Down Arrow |
|
To start of line |
Home |
Shift+Home |
|
To end of line |
End |
Shift+End |
|
To start of document |
Ctrl+Home |
Ctrl+Shift+Home |
|
To end of document |
Ctrl+End |
Ctrl+Shift+End |
|
To next input field |
Ctrl+Tab |
|
|
To previous input field |
Shift+Ctrl+Tab |
