RichTextEdit control

A RichTextEdit control contains a document that it displays as formatted text. It can include input fields that are linked to a DataWindow control. When a DataWindow's data is shared with the RichTextEdit control, there is one instance of the document in the control that can be displayed multiple times with different occurrences of row data. Input fields whose names match columns in the DataWindow are filled with data from the current row.

New RichTextEdit control in PowerBuilder 2017 and later

Staring from PowerBuilder 2017, a new RichTextEdit control is implemented. The properties/functions/events are exactly the same for the new control and the old control, except for those specified in the following tables.

By default the new control is used. The new control is applicable to the RichTextEdit control, RichText DataWindow Object, and the RichText edit style column. You can switch the control in the application's Additional Properties window.

Using with animation features

RichTextEdit controls may not paint correctly when you use animation features.

Properties

RichTextEdit property

Datatype

Description

Accelerator

Integer

Specifies the ASCII value of the accelerator key you want to assign as the accelerator for the control.

AccessibleDescription

String

A description of the control and/or its purpose for use by accessibility tools such as readers for visually impaired users.

AccessibleName

String

A label that briefly describes the control, such as the text in a button or the name of a menu item.

AccessibleRole

AccessibleRole (enumerated)

Describes what kind of user interface element the control is.

BackColor

Long

Specifies the numeric value of the background color of the text editing area of the RichTextEdit. Values are -2 to 16,777,215. For more information about color, see the section called “RGB” in PowerScript Reference.

Difference between the new control and the old control: For the new control, if you set a negative value for the BackColor property, the returned value will be 0 and the color will be black.

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

Border

Boolean

Specifies whether the control has a border. Values are:

TRUE -- Has a border.

FALSE -- Does not have a border.

BorderStyle

BorderStyle (enumerated)

Specifies the style of the border of the control. Values are:

StyleBox!

StyleLowered!

StyleRaised!

StyleShadowBox!

BottomMargin

Long

Specifies the width of the bottom margin on the printed page.

Difference between the new control and the old control: For the new control, if you set a negative value, the returned value will be 0.

For the old control, if you set a negative value, the returned value will be the negative value.

This difference also exists in the other margin properties, such as TopMargin, LeftMargin, and RightMargin.

BringToTop

Boolean

Specifies whether PowerBuilder moves the control to the top of the front-to-back order in the window. Values are:

TRUE -- Moves it to the top.

FALSE -- Does not move it to the top.

ClassDefinition

PowerObject

An object of type PowerObject containing information about the class definition of the object or control.

ControlCharsVisible

Boolean

Specifies whether control characters (carriage returns, spaces, and tabs) are visible. Values are:

TRUE -- Control characters are visible.

FALSE -- Control characters are hidden.

DisplayOnly

Boolean

Specifies whether users can make changes to the content. Values are:

TRUE  -- The content, including text and input files, is protected (the user cannot edit it).

FALSE -- The user can edit the content.

DocumentName

String

Specifies the name that displays in the print queue when the user prints the contents of the control.

DragAuto

Boolean

(Obsolete) This property is no longer supported by the RichTextEdit control since PowerBuilder 12.6.

Specifies whether PowerBuilder puts the control automatically into Drag mode. Values are:

TRUE  -- When the control is clicked, the control is automatically in Drag mode.

FALSE  -- When the control is clicked, the control is not automatically in Drag mode. You have to manually put the control into Drag mode by using the Drag function.

DragIcon

String

Specifies the name of the stock icon or the file containing the icon you want to display when the user drags the control (the ICO file). The default icon is a box the size of the control.

When the user drags the control, the icon displays when the control is over an area in which the control can be dropped (a valid drop area). When the control is over an area that is not a valid drop area, the No-Drop icon displays.

Enabled

Boolean

Specifies whether the control is enabled (can be selected). Values are:

TRUE -- Can be selected.

FALSE -- Cannot be selected.

FaceName

String

Specifies the typeface used for text in the control.

FontCharSet

FontCharSet (enumerated)

Specifies the character set for text in the control.

FontFamily

FontFamily (enumerated)

Specifies the font family for text in the control.

FontPitch

FontPitch (enumerated)

Specifies the spacing of the font used for text in the control.

HeaderFooter

Boolean

Specifies whether the RichTextEdit control has a header/footer section. This property must be set in the painter and cannot be changed during execution. Values are:

TRUE -- The control has a header/footer section.

FALSE -- The control does not have a header/footer section.

If a document has a header or footer and is opened in a control that does not support a header/footer section, then header/footer information in the document is ignored. If the document is then saved in the same file, the header/footer information is lost.

Height

Integer

Specifies the height of the control, in PowerBuilder units.

HScrollBar

Boolean

Specifies whether the RichTextEdit control has a horizontal scroll bar. Values are:

TRUE -- A scroll bar displays.

FALSE -- A scroll bar does not display.

ImeMode

Integer

Specifies the input method editor mode. This property is relevant only to applications running on a Japanese version of PowerBuilder.

InputFieldBackColor

Long

Specifies default background color for all input fields: -2 to 16,777,215. For more information about color, see the section called “RGB” in PowerScript Reference.

Limitation with the new control: For the new 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 run the UI and save the data to a PDF file or print the data, you will see the background color is changed to what you set.

InputFieldNamesVisible

Boolean

Specifies whether input field names are displayed in input fields, rather than the input field values. Values are:

TRUE -- Input fields display their names.

FALSE -- Input fields display their data.

InputFieldsVisible

Boolean

Specifies whether input fields are visible. Values are:

TRUE -- Input fields are visible.

FALSE -- Input fields are hidden.

Italic

Boolean

Specifies default text formatting. Values are:

TRUE -- Text displays in italic format.

FALSE -- Text displays in standard format.

Maintained for forward compatibility with PowerBuilder .NET. In PowerBuilder applications, use the check box on the Font tab of the Properties view to set this property at initialization.

LeftMargin

Long

Specifies the width of the left margin on the printed page.

Modified

Boolean

Specifies whether the document has been modified since it was opened or last saved. Modified is the control's "dirty" flag, indicating that the document is in an unsaved state. Values are:

TRUE -- The document has been modified.

FALSE -- The document has not been modified.

When the first change is made to a newly opened or saved document, PowerBuilder sets the Modified attribute and triggers the Modified event.

PaperHeight

Long

Specifies the value for the display height of pages in the control.

PaperOrientation

PaperOrientation(enumerated)

Specifies the page orientation in the control.

PaperWidth

Long

Specifies the value for the display width of pages in the control.

PicturesAsFrame

Boolean

(Obsolete) This property is no longer supported by the RichTextEdit control since PowerBuilder 12.6.

When the value is true, graphics (bitmaps) are displayed as frames.

Pointer

String

Specifies the name of the stock pointer of the file containing the pointer that is used for the control.

PopMenu

Boolean

Specifies whether the user has access to a pop-up menu by clicking the right mouse button on the control. The menu allows the user to cut and paste, insert a file, and select formatting options. Values are:

TRUE -- Pop-up menu is enabled.

FALSE -- Pop-up menu is disabled.

Resizable

Boolean

Specifies whether the user can resize the control. Values are:

TRUE -- Control is resizable.

FALSE -- Control is not resizable.

RightMargin

Long

Specifies the width of the right margin on the printed page.

RulerBar

Boolean

Specifies whether a ruler bar is visible above the editing area. If visible, the user can use it to see measurements while setting tabs and margins on the tab bar (see the TabBar (obsolete) property). Values are:

TRUE -- Ruler bar is visible.

FALSE -- Ruler bar is hidden.

If the RichTextEdit pop-up menu is enabled, the user can use it to turn ruler bar display on and off (see the PopMenu property).

SelectedStartPos

Long

Specifies the starting position in a selected text string. Typically, you use this property to set the starting position of a selected text string to the first letter of a word flagged by a supported ActiveX spell checker control.

SelectedTextLength

Long

Specifies the length of text you want to highlight in a selected text string. Typically you use this property to obtain the length of a misspelled word that is flagged after passing the selected text string to a supported ActiveX spell checker control.

StatusBar

Boolean

Specifies whether a status bar is visible below the editing area. Values are:

TRUE -- Status bar is visible.

FALSE -- Status bar is hidden.

If the pop-up menu is enabled, the user can use it to turn the status bar display on and off (see the PopMenu property).

TabOrder

Integer

Specifies the tab value of the control within the window (0 means the user cannot tab to the control).

Note that because a RichTextEdit allows tabs within its content, the user cannot tab away from the control.

Tag

String

Specifies the tag value assigned to the control.

TextSize

Integer

Specifies the point size of text in the control.

ToolBar

Boolean

Specifies whether a tool bar for formatting text is visible above the editing area. Values are:

TRUE -- Tool bar is visible.

FALSE -- Tool bar is not visible.

If the pop-up menu is enabled, the user can use it to turn tool bar display on and off (see the PopMenu property).

TopMargin

Long

Specifies the width of the top margin on the printed page.

Underline

Boolean

Specifies default text formatting. Values are:

TRUE -- Text displays with underlines.

FALSE -- Text displays without underlines.

Maintained for forward compatibility with PowerBuilder .NET. In PowerBuilder applications, use the check box on the Font tab of the Properties view to set this property at initialization.

Visible

Boolean

Specifies whether the control is visible:

TRUE -- Control is visible.

FALSE -- Control is not visible.

VScrollBar

Boolean

Specifies whether the RichTextEdit control has a vertical scroll bar. Values are:

TRUE -- A scroll bar displays.

FALSE -- A scroll bar does not display.

Weight

Integer

Specifies default text weight formatting for the control. Maintained for forward compatibility with PowerBuilder .NET. In PowerBuilder applications, use the Bold check box on the Font tab of the Properties view to set bold text weight formatting at initialization.

Width

Integer

Specifies the width of the control, in PowerBuilder units.

WordWrap

Boolean

Determines whether large blocks of text that do not contain spaces wrap automatically to the next line when the line reaches the margin. Values are:

TRUE -- Automatic word wrap is enabled.

FALSE  -- Automatic word wrap is disabled. Users cannot enter characters beyond the right margin, and must move the cursor to a new line to continue entering text. If an inserted document contains a block of text too large to fit on a line, the nonfitting characters are hidden.

Limitation with the new control: For the new control, this property is always true (even when it is set to false, it is treated as true).

X

Integer

Specifies the X position (the distance from the left edge of the window), in PowerBuilder units.

Y

Integer

Specifies the Y position (the distance from the top of the window), in PowerBuilder units.


Events

RichTextEdit event

Occurs

Constructor in PowerScript Reference

Immediately before the Open event occurs in the window.

Destructor in PowerScript Reference

Immediately after the Close event occurs in the window.

DoubleClicked in PowerScript Reference

When the user double-clicks anywhere in the RichTextEdit control.

DragDrop in PowerScript Reference

When a dragged control is dropped on the control.

DragEnter in PowerScript Reference

When a dragged control enters the control.

DragLeave in PowerScript Reference

When a dragged control leaves the control.

DragWithin in PowerScript Reference

When a dragged control is within the control.

FileExists in PowerScript Reference

When the document in the RichTextEdit is saved to a file, but a file of the specified name already exists.

GetFocus in PowerScript Reference

Just before the control receives focus (before it is selected and becomes active).

Help in PowerScript Reference

When the user presses the F1 key or drags the context help button (question mark) from the title bar to a menu item or control.

InputFieldSelected in PowerScript Reference

When the user selects an input field by double-clicking it.

Key in PowerScript Reference

When the user presses a key.

LoseFocus in PowerScript Reference

When the control loses focus (becomes inactive).

Modified in PowerScript Reference

When the first change is made to the contents of the RichTextEdit control, and it has not been saved.

In the Modified event script, you can set a flag indicating that the document needs to be saved.

MouseDown in PowerScript Reference

When the left or middle mouse button is pressed on the control.

MouseMove in PowerScript Reference

When the mouse has moved within the control.

MouseUp in PowerScript Reference

When the left or middle mouse button is released on the control.

Other in PowerScript Reference

When a Windows message occurs that is not a PowerBuilder event.

PictureSelected in PowerScript Reference

When the user selects a picture by clicking it.

RButtonDown in PowerScript Reference

When the right mouse button is pressed on the control. If the pop-up menu is enabled, this event does not occur.

RButtonUp in PowerScript Reference

When the right mouse button is released on the control.


Functions

RichTextEdit function

Datatype returned

Description

CanUndo in PowerScript Reference

Boolean

Returns true if there is an editing function that can be undone.

ClassName in PowerScript Reference

String

Returns the name assigned to the control.

Clear in PowerScript Reference

Long

Clears selected text (if any) from the control, but does not place it in the clipboard.

ClearAll in PowerScript Reference

Long

Clears all content from the specified control, but does not place it in the clipboard.

Copy in PowerScript Reference

Long

Copies (but does not delete) the selected contents of the RichTextEdit control (if any) to the clipboard.

CopyRTF in PowerScript Reference

String

Copies the selected contents of the RichTextEdit control to a string in rich text format.

Difference between the new control and the old control: The new control will return a longer string which contains more types of information, compared to the old control.

Cut in PowerScript Reference

Long

Cuts (deletes) the selected contents from the RichTextEdit control (if any) to the clipboard.

DataSource in PowerScript Reference

Integer

Associates a DataWindow with the RichTextEdit control, matching columns with input fields of the same name.

Drag in PowerScript Reference

Integer

Starts or ends dragging of the control.

Find in PowerScript Reference

Integer

Finds text in the control.

Enhancement of the new control: For the new control, the Find function can not only find the text string, but also can find the carriage return characters and some special characters.

FindNext in PowerScript Reference

Integer

Finds the next occurrence of text specified with the Find function.

GetAlignment in PowerScript Reference

Alignment

Obtains the alignment of the selected text.

Difference between the new control and the old control: For the new control, this property will return the alignment of the paragraph where the insertion point is located if more than one paragraph are selected.

For the old control, this property will return empty if more than one paragraph with different alignments are selected.

GetContextService in PowerScript Reference

Integer

Creates a reference to a context-specific instance of the specified service.

GetParagraphSetting in PowerScript Reference

Long

Gets the size of the indentation, left margin, or right margin of the paragraph containing the insertion point.

The returned value is different between the new control and the old control due to the different units used.

Difference between the new control and the old control: For the new control, this property will return the settings of the paragraph where the insertion point is located if more than one paragraph are selected.

For the old control, this property will return empty if more than one paragraph with different settings are selected.

GetParent in PowerScript Reference

PowerObject

Returns a reference to the name of the parent object.

GetSpacing in PowerScript Reference

Spacing

Obtains the line spacing of the selected text.

Difference between the new control and the old control: For the new control, this property will return the spacing of the paragraph where the insertion point is located if more than one paragraph are selected.

For the old control, this property will return empty if more than one paragraph with different spacing are selected.

GetTextColor in PowerScript Reference

Long

Returns the color of the selected text.

Difference between the new control and the old control: For the new control, this function will return the text color of the first character of the selected text if the selected text contains more than one text colors.

For the old control, this property will return empty if the selected text contains more than one text color.

GetTextStyle in PowerScript Reference

Boolean

Obtains font settings for the selected text.

Difference between the new control and the old control: For the new control, this function will return the font settings of the first character of the selected text if the selected text contains more than one type of font settings.

For the old control, this property will return empty if the selected text contains more than one type of font settings.

Hide in PowerScript Reference

Integer

Makes the control invisible.

InputFieldChangeData in PowerScript Reference

Integer

Modifies the data value for all input fields of the given input field name.

InputFieldCurrentName in PowerScript Reference

String

Gets the name of the selected input field.

InputFieldDeleteCurrent in PowerScript Reference

Integer

Deletes the current occurrence of the selected input field. (That is, this function does not delete all input fields of the same name, only the current occurrence.)

InputFieldGetData in PowerScript Reference

String

Obtains the data in the specified input field.

InputFieldInsert in PowerScript Reference

Integer

Inserts the named input field at the insertion point.

InputFieldLocate in PowerScript Reference

String

Locates an input field. You can find any occurrence of an input field or an input field with a specific name.

InsertDocument in PowerScript Reference

Integer

Inserts the named file in the RichTextEdit control. The file can replace the current contents or be added at the insertion point. The file can be in rich text (RTF), ASCII, HTML, or Word (DOC) format.

InsertPicture in PowerScript Reference

Integer

Inserts the specified bitmap or picture file at the insertion point.

The inserted WMF image file will fail to be saved in to a Word document, although it can be saved in to a rich text file.

IsPreview in PowerScript Reference

Boolean

Checks whether the RichTextEdit control is in preview mode.

LineCount in PowerScript Reference

Integer

Returns the total number of lines in the document.

LineLength in PowerScript Reference

Integer

Returns the length of the current line.

Move in PowerScript Reference

Integer

Moves the control to a specified location.

PageCount in PowerScript Reference

Integer

Returns the number of pages in the document.

Paste in PowerScript Reference

Integer

Inserts the contents of the clipboard (if any) at the insertion point in the control.

PasteRTF in PowerScript Reference

Long

Inserts a string at the insertion point when the string contains text in rich text format. You can specify whether to insert the string in the header or footer band, as well as the main body (detail band).

PointerX in PowerScript Reference

Integer

Returns the distance of the pointer from the left edge of the control.

PointerY in PowerScript Reference

Integer

Returns the distance of the pointer from the top of the control.

Position in PowerScript Reference

Integer

Returns the position of the insertion point or selected text in the control.

PostEvent in PowerScript Reference

Integer

Adds the specified event to the end of the event queue for the specified object

Preview in PowerScript Reference

Integer

Flips between Preview of the document (where header/footer, page size, and so on, are shown) and normal RTE control display.

Print in PowerScript Reference

Integer

Prints the contents of the control. You can specify a range of pages and other settings.

PrintEx in PowerScript Reference

Integer

Prints the contents of the control. You can specify whether a Print dialog box displays.

ReplaceText in PowerScript Reference

Integer

Replaces selected text with given string. If no text has been selected, insert given string at cursor location.

Limitation with the new control: In the new control, the text after replaced will take over the settings (such as font name, font size etc.) carried over by the given string.

Resize in PowerScript Reference

Integer

Changes the size of the control.

SaveDocument in PowerScript Reference

Integer

Saves the current document in a file in either rich text (RTF), ASCII, HTML, PDF, or Word (DOC) format.

When saving multi-byte characters to a TXT file, use the UTF8 encoding rather than the ANSI encoding.

Limitation with the new control: In the new 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.

Scroll in PowerScript Reference

Integer

Scrolls the RichTextEdit the specified direction the specified number of lines.

ScrollNextPage in PowerScript Reference

Integer

Scrolls forward to the next page in the RichTextEdit document. If the current page is the last page of a document instance, scrolls to the next instance.

ScrollNextRow in PowerScript Reference

Long

Scrolls the RichTextEdit to the next row and document instance.

ScrollPriorPage in PowerScript Reference

Long

Scrolls back to the prior page in the RichTextEdit document. If the current page is the first page of a document instance, scrolls to the prior instance.

ScrollPriorRow in PowerScript Reference

Long

Scrolls the RichTextEdit to the prior row and document instance.

ScrollToRow in PowerScript Reference

Long

Causes the control to scroll to the specified row and document instance.

SelectedColumn in PowerScript Reference

Integer

Returns the number of the character column just after the insertion point.

SelectedLength in PowerScript Reference

Long

Returns the length of the selected text.

SelectedLine in PowerScript Reference

Long

Returns the number of the line in which the insertion point is currently located within the document instance.

SelectedPage in PowerScript Reference

Long

Returns the number of the page in which the insertion point is currently located within the document instance.

Limitation with the new control: For the new control, the SelectedPage function returns the number of the page which is being viewed (rather than where the insertion point is placed).

SelectedStart in PowerScript Reference

Integer

Returns the starting position of the selected text (if any) from the beginning of the line.

SelectedText in PowerScript Reference

String

Returns a string containing the selected text from the control.

SelectText in PowerScript Reference

Long

Selects text in the RichTextEdit control.

SelectTextAll in PowerScript Reference

Integer

Selects all text in the control.

SelectTextLine in PowerScript Reference

Integer

Selects all text in the line in which the insertion point is currently located.

SelectTextWord in PowerScript Reference

Integer

Selects the word in which the insertion point is currently located.

SetAlignment in PowerScript Reference

Integer

Sets the alignment for the selected paragraphs.

SetFocus in PowerScript Reference

Integer

Sets focus to the RichTextEdit control.

SetParagraphSetting in PowerScript Reference

Integer

Specifies the size of the paragraph's indentation, left margin, or right margin.

SetPosition in PowerScript Reference

Integer

Specifies the control's position in the front-to-back order within the window.

SetRedraw in PowerScript Reference

Integer

Controls automatic redrawing of the control.

SetSpacing in PowerScript Reference

Integer

Sets the line spacing for the selected paragraphs.

SetTextColor in PowerScript Reference

Integer

Sets the color of the selected text.

SetTextStyle in PowerScript Reference

Integer

Sets the font properties of the selected text.

Show in PowerScript Reference

Integer

Makes the RichTextEdit control visible.

ShowHeadFoot in PowerScript Reference

Integer

Allows editing of the header and footer in the RichTextEdit document.

Difference between the new control and the old control: When the document is in preview mode, the old control returns 1; while the new control returns 1 and closes the preview mode, and when the parameter is true, the insertion point is placed to the header area; when the parameter is false, the insertion point is placed to the detail area.

TextLine in PowerScript Reference

String

Returns the entire text of the line in which the insertion point is currently located.

TriggerEvent in PowerScript Reference

Integer

Triggers a specified event in the control and executes the script for the event.

TypeOf in PowerScript Reference

Object

Returns the type of the control.

Undo in PowerScript Reference

Integer

Cancels the previous editing function performed in the control, if the editing function can be undone. (Some editing functions cannot be undone.)