Using rich edit controls

Using Rich Edit Controls

Top Previous Next

About rich edit

A "rich edit control" is a window in which the user can enter and edit text. The text can be assigned character and line formatting, and can include embedded OLE objects. Rich edit controls provide a programming interface for formatting text. However, an application must implement any user interface components necessary to make formatting operations available to the user.

Rich edit controls support almost all of the commands and notification messages used with multiline edit controls. Thus, applications that already use edit controls can be easily changed to use rich edit controls. Additional commands and notifications enable applications to access the functionality unique to rich edit controls.

Rich edit controls can save and load text in either straight ASCII format or in rich text format (*.rtf)

Creating the control

Rich edit controls are created in the same manner as the standard control types, either through the dialog editor or manually with the CONTROL statement. Rich edit controls support the same creation flags as standard multiline edit controls except for the @CTLEDITPASS style. A rich edit control can also be created as a single line edit control.

Rich edit control styles

The following rich edit style flags can be specified in the CONTROL statement or by ticking the corresponding check box in the control properties of the dialog editor:

@CTEDITLEFT

Text is left justified in the edit control

@CTEDITRIGHT

Text is right justified in the edit control

@CTEDITMULTI

Designates a multiline edit control. The default is single-line edit control. When the multiline edit control is in a dialog box, the default response to pressing the ENTER key is to activate the default button. To use the ENTER key as a carriage return, use the @CTEDITRETURN style. When the multiline edit control is not in a dialog box and the @CTEDITAUTOV style is specified, the edit control shows as many lines as possible and scrolls vertically when the user presses the ENTER key. If you do not specify @CTEDITAUTOV, the edit control shows as many lines as possible and beeps if the user presses the ENTER key when no more lines can be displayed. If you specify the @CTEDITAUTOH style, the multiline edit control automatically scrolls horizontally when the caret goes past the right edge of the control. To start a new line, the user must press the ENTER key. If you do not specify @CTEDITAUTOH, the control automatically wraps words to the beginning of the next line when necessary. A new line is also started if the user presses the ENTER key. The window size determines the position of the word wrap. If the window size changes, the word wrapping position changes and the text is redisplayed. Multiline edit controls can have scroll bars. An edit control with scroll bars processes its own scroll bar messages. Note that edit controls without scroll bars scroll as described in the previous paragraphs and process any scroll messages sent by the parent window.

@CTEDITCENTER

Text is centered within the edit control

@CTEDITRO

The edit control is read only and text can be displayed but not entered

@CTEDITAUTOH

Automatically scrolls text to the right by 10 characters when the user types a character at the end of the line. When the user presses the ENTER key, the control scrolls all text back to position zero.

@CTEDITAUTOV

Automatically scrolls text up one page when the user presses the ENTER key on the last line.

@CTEDITRETURN

Specifies that a carriage return be inserted when the user presses the ENTER key while entering text into a multiline edit control in a dialog box. If you do not specify this style, pressing the ENTER key has the same effect as pressing the dialog box’s default push button. This style has no effect on a single-line edit control.

@CTEDITNUMBER

Restricts text entered in a single line edit control to numerals only (0 - 9)

In addition to the edit styles the following window styles can also be specified:

@TABSTOP

Moves the input focus between controls if controls are in a dialog. This style has no effect for controls created in a window.

@GROUP

Specifies the first control of a group of controls in which the user can move from one control to the next with the arrow keys. All controls defined without the @GROUP style after the first control belong to the same group. The next control with the @GROUP style starts the next group (that is, one group ends where the next begins)

@HSCROLL

The control has a horizontal scroll bar

@VSCROLL

The control has a vertical scrollbar

Controlling the rich edit control.

The rich edit control is accessed through the CONTROLCMD statement/function. CONTROLCMD can be used as a statement or function depending on the command issued.

Clipboard operations

CONTROLCMD window | dialog, ID, @RTCUT

Use this command to delete (cut) the current selection (if any) in the rich edit control and copy the deleted text to the Clipboard.

CONTROLCMD window | dialog, ID, @RTCOPY

Use this command to copy the current selection (if any) in the rich edit control to the Clipboard.

CONTROLCMD window | dialog, ID, @RTPASTE

Use this command to insert the data from the Clipboard into the rich edit control at the insertion point, the location of the caret. Data is inserted only if the Clipboard contains data in a recognized format.

Line operations

count = CONTROLCMD ( window | dialog, ID, @RTGETLINECOUNT)

Use this function to retrieve the number of lines in the rich edit control

CONTROLCMD ( window | dialog, ID, @RTGETLINE, linenum, line$ {,cchLine})

Use this function to retrieve a line of text from the rich edit control.

Linenum is the 0 based index of the line to retrieve, cchLine is the size of the line$ STRING variable, defaults at 255.

line = CONTROLCMD ( window | dialog, ID, @RTGETFIRSTLINE)

Use this function to retrieve the zero-based index of the uppermost visible line.

line = CONTROLCMD ( window | dialog, ID, @RTLINEFROMCHAR, index)

Use this function to retrieve the line number of the line that contains the specified character index.

Index is the number of characters from the beginning of the rich edit control. For character counting, an OLE item is counted as a single character

char_index = CONTROLCMD ( window | dialog, ID, @RTCHARFROMLINE, linenum)

Use this function to retrieve the character index of the first character of the specified line.

length = CONTROLCMD ( window | dialog, ID, @RTGETLINELENGTH, index)

Use this function to retrieve the length of a line in a rich edit control. When @RTGETLINELENGTH is called for a multiple-line edit control, the return value is the length (in bytes) of the line specified by index. When @RTGETLINELENGTH is called for a single-line edit control, the return value is the length (in bytes) of the text in the edit control. Index specifies the character index of a character in the line whose length is to be retrieved. If this parameter is –1, the length of the current line (the line that contains the caret) is returned

CONTROLCMD window | dialog, ID, @RTSCROLL, lines, chars

Use this command to scroll the text of a multiple-line edit control. The rich edit control does not scroll vertically past the last line of text in the edit control. If the current line plus the number of lines specified by lines exceeds the total number of lines in the edit control, the value is adjusted so that the last line of the edit control is scrolled to the top of the edit-control window.

Selection operations

CONTROLCMD window | dialog, ID, @RTGETSELECTION, varStart, varEnd

Use this command to retrieve the current selection of the rich edit control.

varStart and varEnd must be of type INT. The zero-based index of the first and last characters selected are copied into the two variables. The selection includes everything if varStart =0 and varEnd = -1.

CONTROLCMD ( window | dialog, ID, @RTGETSELTEXT, text$ {,cchText})

Use this function to retrieve the text of the selection. cchText is the size of the text$ variable, defaults to 255

CONTROLCMD window | dialog, ID, @RTDELETESEL

Use this statement to delete the current selection. The deletion performed by @RTDELETESEL can be undone by using @RTUNDO

CONTROLCMD window | dialog, ID, @RTSETSELECTION, start, end

Use this statement to set the current selection in the rich edit control

start and end are the zero-based character indexes of the selection. If start = 0 and end = -1 then all of the text is selected.

CONTROLCMD window | dialog, ID, @RTREPLACESEL, text$

Use this statement to replace the current selection text

CONTROLCMD window | dialog, ID, @RTHIDESEL, hide

Use this statement to change the visibility of the current selection. If hide = 1 then the selection is hidden. If hide = 0 then the selection is shown.

Formatting operations

CONTROLCMD window | dialog, ID, @RTSETDEFAULTFONT, name$, height, bold, effects

Changes the default font in the rich edit control. The default font is used when no other character formatting has been specified.

Height is specified in points. If a bold font is required set bold = 1. Effects can be a combination of @SFITALIC, @SFUNDERLINE, or @SFSTRIKEOUT. Combine effects with the '|' operator.

CONTROLCMD window | dialog, ID, @RTSETSELFONT, name$, height, bold, effects

Changes the font of the currently selected text in the rich edit control. If there is no selection the font is changed for all characters entered after the insertion point.

Height is specified in points. If a bold font is required set bold = 1. Effects can be a combination of @SFITALIC, @SFUNDERLINE, or @SFSTRIKEOUT. Combine effects with the '|' operator.

CONTROLCMD window | dialog, ID, @RTSETDEFAULTCOLOR, color

Changes the default text color of the rich edit control. The default text color is used when no other character formatting has been specified.

Color is a color value created with the RGB funciton.

CONTROLCMD window | dialog, ID, @RTSETSELCOLOR, color

Changes the selection text color of the rich edit control. If there is no selection the color is changed for all characters entered after the insertion point.

Color is a color value created with the RGB funciton.

CONTROLCMD window | dialog, ID, @RTSETALIGNMENT, alignment

Changes the alignment of the current selection. If there is no selection the alignment is set for the insertion point.

Valid alignment values are @RTALIGNLEFT, @RTALIGNCENTER and @RTALIGNRIGHT

CONTROLCMD window | dialog, ID, @RTSETCHAROFFSET, offset

Character offset, in twips, from the baseline. If offset is positive, the character is a superscript; if it is negative, the character is a subscript. There are 1440 twips in an inch, 20 twips in a point.

Editing operations

CONTROLCMD window | dialog, ID, @RTUNDO

Use this statement to undo the last editing operation.An undo operation can also be undone. For example, you can restore deleted text with the first call to Undo. As long as there is no intervening edit operation, you can remove the text again with a second call to Undo.

return = CONTROLCMD (window | dialog, ID, @RTCANUNDO)

Use this function to determine if the last editing operation can be undone. Returns 0 if the last operation cannot be undone.

CONTROLCMD window | dialog, ID, @RTEMPTYUNDO

Use this statement to reset (clear) the undo flag of this rich edit control. The control will now be unable to undo the last editing operation. The undo flag is set whenever an operation within the rich edit control can be undone.

return = CONTROLCMD (window | dialog, ID, @RTSAVE, FILE | STRING, type)

Use this function to save the contents of the rich edit control to an open file or into a string variable.

Type is either 0 to store the contents in plain ASCII format or 1 to store the contents in rich text format (*.rtf). Returns the number of characters saved. FILE is a variable of type FILE and must have been successfully opened for writing with the OPENFILE function.

return = CONTROLCMD (window | dialog, ID, @RTLOAD, FILE | STRING, type)

Use this function to load the contents of the rich edit control from an open file or a string variable.

Type is either 0 to load the contents in plain ASCII format or 1 to load the contents in rich text format (*.rtf). Returns number of characters loaded. FILE is a variable of type FILE and must have been successfully opened for reading with the OPENFILE function.

General operations

return = CONTROLCMD (window | dialog, ID, @RTGETMODIFIED)

Use this function to determine if the contents of the rich edit control have changed. Returns 1 if the contents have been modified, 0 otherwise.

CONTROLCMD window | dialog, ID, @RTSETMODIFIED, mod

Sets the modified flag of the rich edit control.

Mod can be 0 to reset the flag or 1 to set it.

pos = CONTROLCMD (window | dialog, ID, @RTFINDTEXT, text$, start_pos, ignore_case)

Use this function to find text within the rich edit control. Returns the zero-based index of the first character in the control that matches the string in text$. Returns -1 if there are no matches. start_pos specifies a starting character index to begin the search. If ignore_case = 0 then the function performs a case sensitive search, if ignore_case = 1 then the case of the search string is ignored.

length = CONTROLCMD (window | dialog, ID, @RTGETLIMITTEXT)

Use this function to get the text limit for this rich edit control. The text limit is the maximum amount of text, in bytes, the rich edit control can accept either through pasting, typing or with the @RTLOAD function.

CONTROLCMD window | dialog, ID, @RTSETLIMITTEXT, length

Use this function to set the text limit for this rich edit control. The text limit is the maximum amount of text, in bytes, the rich edit control can accept either through pasting, typing or with the @RTLOAD function. The default limit is 32767 bytes.

CONTROLCMD window | dialog, ID, @RTSETLINEWIDTH, width

Use this statement to set the line width for word wrapping in the rich edit control.

Width is specified in twips. There are 1440 twips in 1 inch.

CONTROLCMD window | dialog, ID, @RTSETMARGINS, left, right

Use this statement to set the visible left and right margins of the rich edit control.

Left and right are specified in pixels.

length = CONTROLCMD (window | dialog, ID, @RTGETTEXTLENGTH)

Returns the text length, in bytes, of the rich edit control.

CONTROLCMD window | dialog, ID, @RTPRINT {, margin}

Opens the standard print dialog and prints the contents of the rich edit control. Optional margin value specifies the printer margin in twips. 1440 twips = 1 inch. Default margin is 1/2 inch.

Notification event control

mask = CONTROLCMD (window | dialog, ID, @RTGETEVENTMASK)

Returns the event mask of the rich edit control.

CONTROLCMD window | dialog, ID, @RTSETEVENTMASK, mask

Sets the notification event mask for the rich edit control. The event mask controls which notification messages are sent to the parent window or dialog in the @NOTIFYCODE variable. Multiple events can be specified by using the | operator The following mask values are available:

@ENMNONE

Only the standard events @ENKILLFOCUS, @ENSETFOCUS, @ENMAXTEXT and @ENERRSPACE are sent.

@ENMCHANGE

The control sends @ENCHANGE events

@ENMUPDATE

The control sends @ENUPDATE events

@ENMSCROLL

The controls sends @ENHSCROLL and @ENVSCROLL events

@ENMREQUESTRESIZE

The control sends @ENREQUESTRESIZE events

@ENMSELCHANGE

The control sends @ENSELCHANGE events

Notification messages

A rich edit controls sends notification messages to the parent window or dialog in the @NOTIFYCODE variable. The ID of the control is found in @CONTROLID the same as standard controls. The following notification messages are supported:

@ENKILLFOCUS

Control has lost input focus

@ENSETFOCUS

Control has been given the input focus

@ENERRSPACE

Control could not complete an operation because there was not enough memory available

@ENMAXTEXT

The limit set by @RTSETLIMITTEXT has been reached,

@ENUPDATE

The contents of the control are about to change