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.

RichText 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. For more information about the rich text editors, see the section called “Rich text editors” in Application Techniques; and for feature difference of the rich text editor, see the section called “Feature difference” in Application Techniques.

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.

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.

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

Immediately before the Open event occurs in the window.

Destructor

Immediately after the Close event occurs in the window.

DoubleClicked

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

DragDrop

When a dragged control is dropped on the control.

DragEnter

When a dragged control enters the control.

DragLeave

When a dragged control leaves the control.

DragWithin

When a dragged control is within the control.

FileExists

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

GetFocus

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

Help

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

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

Key

When the user presses a key.

LoseFocus

When the control loses focus (becomes inactive).

Modified

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

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

MouseMove

When the mouse has moved within the control.

MouseUp

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

Other

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

PictureSelected

When the user selects a picture by clicking it.

RButtonDown

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

RButtonUp

When the right mouse button is released on the control.


Functions

RichTextEdit function

Datatype returned

Description

CanUndo

Boolean

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

ClassName

String

Returns the name assigned to the control.

Clear

Long

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

ClearAll

Long

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

Copy

Long

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

CopyRTF

String

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

Cut

Long

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

DataSource

Integer

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

Drag

Integer

Starts or ends dragging of the control.

Find

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

Integer

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

GetAlignment

Alignment

Obtains the alignment of the selected text.

GetContextService

Integer

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

GetParagraphSetting

Long

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

GetParent

PowerObject

Returns a reference to the name of the parent object.

GetSpacing

Spacing

Obtains the line spacing of the selected text.

GetTextColor

Long

Returns the color of the selected text.

GetTextStyle

Boolean

Obtains font settings for the selected text.

Hide

Integer

Makes the control invisible.

InputFieldChangeData

Integer

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

InputFieldCurrentName

String

Gets the name of the selected input field.

InputFieldDeleteCurrent

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

String

Obtains the data in the specified input field.

InputFieldInsert

Integer

Inserts the named input field at the insertion point.

InputFieldLocate

String

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

InsertDocument

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

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

Boolean

Checks whether the RichTextEdit control is in preview mode.

LineCount

Integer

Returns the total number of lines in the document.

LineLength

Integer

Returns the length of the current line.

Move

Integer

Moves the control to a specified location.

PageCount

Integer

Returns the number of pages in the document.

Paste

Integer

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

PasteRTF

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

Integer

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

PointerY

Integer

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

Position

Integer

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

PostEvent

Integer

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

Preview

Integer

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

Print

Integer

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

PrintEx

Integer

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

ReplaceText

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

Integer

Changes the size of the control.

SaveDocument

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

Integer

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

ScrollNextPage

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

Long

Scrolls the RichTextEdit to the next row and document instance.

ScrollPriorPage

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

Long

Scrolls the RichTextEdit to the prior row and document instance.

ScrollToRow

Long

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

SelectedColumn

Integer

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

SelectedLength

Long

Returns the length of the selected text.

SelectedLine

Long

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

SelectedPage

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

Integer

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

SelectedText

String

Returns a string containing the selected text from the control.

SelectText

Long

Selects text in the RichTextEdit control.

SelectTextAll

Integer

Selects all text in the control.

SelectTextLine

Integer

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

SelectTextWord

Integer

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

SetAlignment

Integer

Sets the alignment for the selected paragraphs.

SetFocus

Integer

Sets focus to the RichTextEdit control.

SetParagraphSetting

Integer

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

SetPosition

Integer

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

SetRedraw

Integer

Controls automatic redrawing of the control.

SetSpacing

Integer

Sets the line spacing for the selected paragraphs.

SetTextColor

Integer

Sets the color of the selected text.

SetTextStyle

Integer

Sets the font properties of the selected text.

Show

Integer

Makes the RichTextEdit control visible.

ShowHeadFoot

Integer

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

TextLine

String

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

TriggerEvent

Integer

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

TypeOf

Object

Returns the type of the control.

Undo

Integer

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