PowerBuilder 10 Rich Text Control

Rich Text is a standard way of formatting text for display, print, and exchange with other programs. The format is defined by Microsoft and is generally updated with each release of Microsoft Word. The specification for the format is made publicly available by Microsoft and a large number of vendors have implemented it as an intermediary text document format. As of April of 2004, the latest version of that specification is 1.8. A somewhat similar specification is the Portable Document Format (PDF) maintained by Adobe. The PDF specification is much more complex though, requiring approximately 1,200 pages of documentation as opposed to the roughly 200 pages in the RTF specification.

The PB Rich Text Control is the only control included with PowerBuilder that offers formatting similar to a full word processor. The text can be static, program generated, or entered by user interaction. To have a functional word processor all you need to do is place the control on a window, set some properties, and provide common dialogs, such as open, save, and print. The control is not a replacement for Star Office, Word, or Word Perfect. It's a basic control that supports an early RTF standard. This article attempts to point out some PB10 enhancements and also provide some techniques on how to programmatically edit documents beyond what is available with the included properties/functions.

Changes in PowerBuilder 10
There have been several important changes to the PB 10 Rich Text Control over the PB 9 version of the same control. Visually, it looks more like the other XP controls when running on a PC with themes enabled. The ruler bar, tab bar, and tool bar now follow the desktop color scheme instead of being "button" gray.

The control is now Unicode aware, so all PB strings that are passed to the control or received from the control are now made up of 16-bit characters. For the vast majority of cases this will have no impact on the programmer or the user. Sybase has done an excellent job of making the transition from 8-bit characters to 16-bit characters. The "InsertDocument" function is used to insert Rich Text documents, ASCII 8-bit text documents, and Unicode text documents. "SaveDocument" can be used to generate a Rich Text document or an ASCII 8-bit text document. The ability to generate a Unicode text file is not in the current beta, but hopefully will be included in a later version.

The Rich Text Control is not a new control; it's the same control we've been using for many releases. For the most part we should expect the same "personality" in the control that it has had in previous releases. The base control being the same has a positive aspect: very little recoding will be needed on existing applications. Improvements include the enhanced ability of the control to "quietly ignore" RTF command strings that are not supported, and the functions generally behave in a more "expected" manner with fewer side effects.

For the application that replaces a short text string with a much longer text string, there's good news. In previous versions the control would do some unexpected things in terms of line wrap, margins, and indentation settings. Compare the results in the following three examples. In Figure 1, there's a simple document with two tokens. Figure 2 shows the document after replacing the tokens using the "SelectText" and "ReplaceText" functions under PB 9.0.1.7171. Figure 3 presents the same results using the PB 10 Beta release. The results are much better in terms of the line wrap and margin issues compared to the example in Figure 1. Figure 3 shows how some text attributes are lost when using PB 9 and not lost using PB 10.

Changing the Font Properties
The ability to change the font face, font size, and font color is missing from the functions provided by the PB control in previous versions and the PB10 version. A popular and effective solution for previous releases was provided by Bruce Armstrong in an example program known as rte_font. The sample program is available on the Sybase CodeXchange site (http://powerbuilder.codexchange.sybase.com) and can also be downloaded from www.sys-con.com/pbdj/sourcec.cfm. The technique involves getting the control handle and then sending Windows messages to the control to set and return a color logfont structure. The technique used requires some minor changes due to PB 10 being Unicode based.

You'll need to change the logfont structure to handle the change in the size of a character from 8 bits to 16 bits. Since PB 10 does not have an 8-bit integer data type, combining the eight 1-byte fields into four character fields is an easy solution in this case. Notice also that the llfacename member is now a Unicode string. This is handled by using SendMessageW instead of SendMessageA. Listing 1 shows the necessary declarations.

There are 16 colors supported in the color table. These are defined in the color table that resides near the beginning of every RTF document. The color table can be viewed by opening a document created by this control with Notepad. The color table begins with "{colortbl/red0/green0/blue0;" and continues for a maximum of 16 colors. You can only set colors that match an entry in the color table. For example, the color RGB(128,128,128) will not be accepted where the color RGB(127,127,127) will. The font height is in "logical units," not in point size units. You can find documentation on conversion between the two in Windows Win32 API documentation for CreateFont function and LogFont structure. Unused fields in the logfont structures should be set to 0 prior to each use. This sample application can be found on Sybase CaseXpress.

Inserting a Bitmap
Another common desire is to insert a signature into a document. The "InsertPicture" function will insert a bitmap into the document at the start of the selected text, which is okay in some applications. However, you do not have control over the size of the picture from the program. In many cases after altering the bitmap size and resolution to fit the desired area, the quality is not acceptable. A suggested solution is to insert your signature bitmap into a "work" document, size the signature manually, and save this work document as an .rtf file. You can use MS Word or WordPad to generate this work document. Use the "InsertDocument" from the application to insert the signature and the sizing will be maintained. The .rtf file will probably be larger in size than the bitmap file.

Using CopyRTF/PasteRTF
There is another technique that allows you to edit or create the document exactly as needed. The technique is to export the document to PB strings using "CopyRTF" ? edit the strings as text and then replace the string back into the control using "PasteRTF" to do the formatting for display and printing. This is not nearly as difficult as you might expect. Almost all rich text is made of structures, commands, and text data. The structures and commands are all encoded as standard displayable characters. A complete RTF specification can be found on MSDN (msdn.microsoft.com/office/understanding/word/tools/default.aspx).

Other interesting documents on Rich Text Formats and utilities can also be found on the MSDN site. Remember that the MSDN documents refer to RTF version 1.6 and later and the PB control supports an earlier standard. When entering the control sequences remember that a single blank is required to indicate the end of a control sequence and the start of text data. Line feed and carriage returns are ignored. The "par" command sequence is used to end a paragraph and insert a hard-line return. Listing 2 illustrates the PB script to use to extract the text strings and place them back into the RTE control.

Summary
With a little programming, you can extend the base functions exposed by the PB10 control to obtain professionally formatted documents from your PB projects without the expense of purchasing a third-party control for many applications.

© 2008 SYS-CON Media