Using rich text in an application

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 the text with formatting.

In an application, you may want to:

  • Provide a window for preparing rich text documents

    Although not a full-fledged word processor, the RichTextEdit control allows the user to apply formatting to paragraphs, words, and characters.

  • Create a mail-merge application

    You or the user can set up boilerplate text with input fields associated with database data.

  • Display reports with formatted text

    A RichText DataWindow object is designed for viewing data, rather than entering data. It does not have the edit styles of other DataWindow presentation styles.

  • Store rich text as a string in a database and display it in a RichTextEdit control

Sources of rich text

Any word processor

You can prepare rich text in any word processor that can save or export rich text format.

Input fields in PowerBuilder only

Although many word processors support some kinds of fields, the fields are usually incompatible with other rich text interpreters. If you want to specify input fields for a PowerBuilder application, you will have to insert them using the PowerBuilder RichTextEdit control.

Rich text in the database

Since rich text is represented by ASCII characters, you can also store rich text in a string database column or string variable. You can retrieve rich text from a string database column and use the PasteRTF function to display the text with formatting in a RichTextEdit control.

Language of rich text

English is the currently recommended language for the rich text, as only English is fully tested in 2019. The other languages will be listed here after they are fully tested in the future versions.

Rich text editors

You can select from the three rich text editors supported by Appeon PowerBuilder. The selected rich text editor will be applicable to the RichTextEdit control, the RichText DataWindow object, and the RichText edit style.

  • Built-in TX Text Control

    Starting from PowerBuilder 2019, a special OEM version of TX Text Control ActiveX X15 is added as a built-in rich text editor in PowerBuilder (not in InfoMaker), and it is provided at no cost and is highly recommended to be used for backwards compatibility reasons by all existing PowerBuilder projects that already make use of the RichTextEdit of SAP PowerBuilder version 12.6 or older.

  • Built-in Rich Edit Control (TE Edit Control)

    Starting from PowerBuilder 2017, TE Edit Control is provided as a built-in rich text editor for free use by the PowerBuilder developer and the InfoMaker developer. This editor provides almost the same functions/events/properties as the old one used in PowerBuilder 12.6 and earlier. For the difference, refer to Feature difference.

    Class name difference

    The class name for TE Edit Control is "Ter24Class" in PowerBuilder 2017 and 2017 R2, and "Ter25Class" in PowerBuilder 2017 R3 and 2019. Please make sure to use the corresponding class name in your API calls or the third-party auto-test scripts.

    However, TE Edit Control has the following issues and unsupported features in PowerBuilder:

    • When copying text into the RichTextEdit control, the font used may not be the default font for the RichTextEdit control. PowerBuilder 12.6 has the same issue.

    • It is unsupported to merge the data of two RichTextEdit controls into the third RichTextEdit control. For example, the following code is unsupported:

      ls_1 = rte_1.CopyRTF ( false )
      ls_2 = rte_2.CopyRTF ( false )
      ls_3 = ls_1 + ls_2
      ris = rte_3.PasteRTF (ls_3)
      
    • RichTextEdit control has problems in handling the space width of some fixed width fonts such as Courier and Courier New, which causes text not aligned.

    • In DataWindow preview, content of RichTextEdit controls do not scale like other controls do.

    • In printout of DataWindows, RichTextEdit controls show additional unwanted padding on the top depending on the location on the page.

    • SaveDocument will fail if the specified directory contains non-English characters.

    • SetFont function or setting font via APIs is unsupported.

    • SelectText function supports 98303 as the maximum length. If the length is over 98303, SelectText failed to select any text.

  • TX Text Control ActiveX X14 Professional/Enterprise

    This is the rich text editor used in PowerBuilder 12.6 and earlier versions. If you want to continue using and distributing this editor in PowerBuilder 2017 and later, you will have to purchase it separately from the vendor (http://www.textcontrol.com) and follow the vendor's documentation to package and distribute it to your users.

    Only the Professional or Enterprise edition of TX Text Control ActiveX X14 is supported by PowerBuilder 2017 and later; Standard edition is not supported.

    The 2400 SP1, 2400 SP2, and 2400 SP3 of TX Text Control ActiveX X14 do not support the RichText edit style any more, although it supports the RichTextEdit control and the RichText DataWindow object. You should use TX Text Control ActiveX X14 2400 for supporting all of these three features.

For how to select the rich text editor, see the section called “Specifying a rich text editor” in Users Guide.

Feature difference

TE Edit Control (newly added since PowerBuilder 2017) provides almost the same functions/events/properties as TX Text Control (which has been used since earlier versions of PowerBuilder), except for the following differences and issues (due to the different ways they are designed):

Affected area

Type

Description

Double-byte languages

Unsupported

Double-byte languages such as Korean, Japanese are not supported well in TE Edit Control.

InputFieldBackColor property

Limitation

For TE Edit Control, this property will not take effect until you save the data into a PDF file or print the data; which means, when you preview the UI in the design view or when you run the UI, you will always see the background color is gray, only when you save the data to a PDF file or print the data, you will see the background color is changed to what you set.

Wordwrap property

Limitation

For TE Edit Control, this property is always true (it cannot be set to false).

BackColor property

Difference

For TE Edit Control, if you set a negative value for the BackColor property, the returned value will be 0 and the color will be black.

For TX Text Control, if you set a negative value for the BackColor property, the returned value will be 16777215 and the color will be white.

BottomMargin/RightMargin/LeftMargin/TopMargin properties

Difference

For TE Edit Control, if you set a negative value, the returned value will be 0.

For TX Text Control, if you set a negative value, the returned value will be the negative value.

Find function

Enhancement

For TE Edit Control, the Find function can not only find the text string, but also can find the carriage return characters and some special characters.

GetTextColor/GetTextStyle functions and font settings

Difference

For TE Edit Control, this function will return the settings (text color, font name, text style etc.) of the first character of the selected text if the selected text contains more than one type of settings.

For TX Text Control, this property will return empty if the selected text contains more than one type of settings.

GetAlignment/GetSpacing/GetParagraphSetting functions

Difference

For TE Edit Control, this function will return the alignment (or spacing or paragraph settings) of the paragraph where the insertion point is located if more than one paragraph are selected.

For TX Text Control, this property will return null if more than one paragraph with different alignments (or spacing or paragraph settings) are selected.

GetParagraphSetting function

Difference

The returned value is different between TE Edit Control and TX Text Control due to the different units used.

Visio drawings

New feature

Visio drawings can be pasted or inserted into TE Edit Control.

Preview

New feature

All pages can be previewed (by scrolling) in TE Edit Control; while only the first page can be previewed in TX Text Control.

SelectedPage function

Limitation

For TE Edit Control, the SelectedPage function returns the number of the page which is being viewed (rather than where the insertion point is placed).

ShowHeadFoot function

Difference

When the document is in preview mode, TX Text Control returns 1; while TE Edit Control returns 1 and closes the preview mode, and when the parameter is true, the insertion point is placed to the header band; when the parameter is false, the insertion point is placed to the detail band.

ReplaceText function

Limitation

In TE Edit Control, the text after replaced will take over the settings (such as font name, font size etc.) carried over by the given string.

SaveDocument function

Limitation

In TE Edit Control, when saving to HTML, the image will lose some quality and will be saved as individual files separately from the document and the reference to the image file uses the absolute path,.

CopyRTF function

Difference

TE Edit Control will return a longer string which contains more types of information.

Insertion point

Difference

When the user switches the editor band (e.g. from the header/footer band to the detail band), the insertion point is placed to the last column and last row in TE Edit Control, while the insertion point's last position will be remembered and restored in TX Text Control, if it is the firs time, the insertion point is placed to the first column and first row.

Input field

Difference

TE Edit Control limits the length of the input field data to no more than 2000 characters while TX Text Control has no such limitation.

Font

Difference

In TE Edit Control, if the user uses a non-English input method to input the English characters, the inserted characters appear like using a different font than the other characters, although they actually use the same font.

Image

Difference

In TE Edit Control, when the user tries to manually select an image (only image, no text), the user can only select it by dragging from end to beginning, but cannot select by dragging from beginning to end.

Bullet list alignment

Issue

In TE Edit Control, the bullet symbol is cut off in a rich-text edit style column under the preview mode or print mode because the bullet list is not perfectly aligned with the body text.


Deploying a rich text application

To deploy a rich text application to a server or client machine:

  • If using the built-in text editor, you can use the PowerBuilder Runtime Packager to deploy the required rich text files with your application.

    For more information on the runtime packager, see PowerBuilder Runtime Packager.

  • If using the old editor (TX Text Control ActiveX), you must follow the vendor's documentation to deploy the required files with your application.