TEXTEDIT() — MISC REFERENCE MANUAL PAGES
WIDGET CLASS NAME
TextEdit
SYNOPSIS
#include <stdio.h>
#include <buffutil.h>
#include <textbuff.h>
#include <Intrinsic.h>
#include <Dynamic.h>
#include <OpenLook.h>
#include <TextEdit.h>
widget = XtCreateWidget(name, textEditWidgetClass, ...);
DESCRIPTION
The TextEdit widget provides an n-line text editing facility that has both a customizable user interface and a programmatic interface. It can be used for single line string entry as well as full-window editing. It provides a consistent editing paradigm for textual data.
The TextEdit widget provides three text wrap modes: wrapoff, wrapany, and wrapwhitespace.
The TextEdit widget provides several distinct callback lists used to monitor the state of the textual data: insertion cursor movement, modification of the text, and post modification notification. Each of these callbacks provide information to the application regarding the intended action. The application can simply examine this information to maintain its current state or can disallow the action and perform any of the programmatic manipulations instead.
The TextEdit widget also provides distinct callback lists for user input: mouse button down and key press. The call data for these callbacks decodes the input for the application. The application can examine the input and either consume the action, and perform any of the programmatic manipulations, or allow the widget to act upon it.
The TextEdit widget also provides the application with a callback list used when the widget is redisplayed. With this callback the application can add callbacks which can be used to display information in the margins of the TextEdit such as line numbers or update marks.
Editing Capabilities
The TextEdit widget provides editing capabilities to move the insert point, select text, delete text, scroll the display, perform cut, copy, paste, and undo operations, and refresh the text display. All of these capabilities are bound to global resources stored in the X server. Many of these settings can be changed using the property windows available in the OPEN LOOK Workspace Manager. All of these settings dynamically change immediately after new settings are stored in the server. The following table lists all of the key bindings used by the TextEdit widget:
Editing Capabilities
The TextEdit widget provides the editing capabilities listed in the following table.
Table 1 TextEdit Editing Capabilities
NameEditing Action
CHARFWD Move the caret forward one character CHARBAK Move the caret back one character ROWDOWN Move the caret down one line in the current column ROWUP Move the caret up one line in the current column WORDFWD Move the caret forward one word WORDBAK Move the caret back one word LINESTART Move the caret to the beginning of the current display line LINEEND Move the caret to the end of the current display line DOCSTART Move the caret to the beginning of the source DOCEND Move the caret to the end of the source DELCHARFWD Delete the character to the right of the caret DELCHARBAK Delete the character to the left of the caret DELWORDFWD Delete the word to the right of the caret DELWORDBAK Delete the word to the left of the caret DELLINEFWD Delete to the end of the current display line from the caret DELLINEBAK Delete to the beginning of the current display line from the caret UNDO Undo the previous edit operation This second table displays the virtual expressions and keyboard equivalents for the editing functions. See VIRTUAL KEY/BUTTON(3W) earlier in this guide for more information on virtual expressions.
Table 2 TextEdit Virtual Expression Keyboard Equivalents
Name Keyboard Equivalents
CHARFWD CTRL-F, →
CHARBAK CTRL-B, ←
ROWDOWN CTRL-N, ↓
ROWUP CTRL-P, ↑
WORDFWD ALT-F, ALT- →
WORDBAK ALT-B, ALT- ←
LINESTART CTRL-A, CTRL- ←
LINEEND CTRL-E, CTRL- →
DOCSTART ALT-↑, ALT- <
DOCEND ALT-↓, ALT- > DELCHARFWD CTRL-D, DELETE DELCHARBAK CTRL-H, BACKSPACE
DELWRDFWD ALT-D DELWORDBAK ALT-H DELLINEFWD CTRL-K DELLINEBAK ALT-K
UNDO CTRL-BACKSPACE Hierarchical Text
Text is considered to be hierarchically composed of white space, spans, lines, paragraphs, within a document. Whitespace is defined as any non-empty sequence of the ASCII characters space, tab, linefeed, or carriage return (decimal values 32, 9, 10, 13; respectively); a span is any non-empty sequence of characters bounded by whitespace. A source line is any (possibly empty) sequence of characters bounded by newline characters; a display line is any (possibly empty) sequence of characters appearing on a single screen display line. A paragraph is any sequence of characters bounded by sets of two or more adjacent newline characters. A document is the entire content of the text.
In all cases, the beginning or end of the edit text is an acceptable bounding element in the previous definitions. Sizing the Display
When making display decisions, the TextEdit widget first will use either the application specified width and height or, if these values are not specified, calculate width and height by applying the values of the XtNcharsVisible and XtNlinesVisible resources. Once the width and height are determined the TextEdit widget will request an appropriate size from its parent (considering the margins). If the request is denied or only partially satisfied, no future growth requests will be made unless there is an intervening resize operation externally imposed.
Once the size of the display is settled, the TextEdit widget calculates the display lines based on this size, the various margins, the font, tab table, and wrap mode. Wrapping
If the wrap mode is OL_WRAP_ANY, as many characters from the source line as will entirely fit before the right margin are written to the current display line, then the next character starts at the left margin of the next display line, and so on. If the wrap mode is OL_WRAP_WHITE_SPACE, the line wrap occurs at the first whitespace character that follows the last full word that does fit on the current display line. If, however, under OL_WRAP_WHITE_SPACE, the first full word that does not fit is the first word on the display line, the wrap is made as if OL_WRAP_ANY were selected. If the wrap mode is OL_WRAP_OFF the lines are not wrapped but are clipped at the right margin. In this mode the text is horizontally scrollable. ScrolledWindow
The application can place the TextEdit widget within a ScrolledWindow widget. When this arrangement is used, the text is easily scrollable using the Scrollbars provided by the ScrolledWindow.
The proportion indicators on the scrollbars show relatively how much of the text is currently in the display.
As the user enters text, the view automatically scrolls when the insert point moves beyond a margin boundary (right or bottom) to keep the insert point in view. Application Access
The TextEdit widget provides complete programmatic control of the text and its display.
RESOURCES
Table 3 TextEdit Resource Set
cssss. TextEdit Resource Set
Name Type Default Access
XtNancestorSensitive Boolean DYNAMIC G
XtNbackground Pixel XtDefaultBackground SGI
XtNbackgroundPixmap Pixmap Unspecified SGI
XtNblinkRate Int 1000 SGI
XtNborderColor Pixel XtDefaultForeground SGI
XtNborderPixmap Pixmap Unspecified SGI
XtNborderWidth Dimension 0 SGI
XtNbottomMargin Dimension 4 SGI
XtNbuttons Callback NULL Callback SGI
XtNcharsVisible Int 50 GI
XtNcolormap Pointer DYNAMIC G
XtNcursorPosition Int 0 SGI
XtNdepth Int DYNAMIC GI
XtNdisplayPosition Int 0 SGI
XtNfont FontStruct NULL FontStruct SGI
XtNfontColor Pixel Black SGI
XtNheight Dimension 0 SGI
XtNinputFocusColor Pixel Black SGI
XtNkeys Callback NULL Callback SGI
XtNleftMargin Dimension 4 SGI
XtNlinesVisible Int 16 GI
XtNmappedWhenManaged Boolean TRUE SGI
XtNmargin Callback NULL Callback SGI
XtNmodifyVerification Callback NULL Callback SGI
XtNmotionVerification Callback NULL Callback SGI XtNpostModifyNotification Callback NULL Callback SGI
XtNreferenceWidget Widget NULL Widget GI
XtNrightMargin Dimension 4 SGI
XtNscreen Pointer DYNAMIC G
XtNselectEnd Int 0 SGI
XtNselectStart Int 0 SGI
XtNsensitive Boolean TRUE GI
XtNsource String NULL SGI
XtNtabTable Pointer NULL SGI
XtNtopMargin Dimension 4 SGI
XtNtraversalOn Boolean TRUE SGI
cssss. TextEdit Resource Set
Name Type Default Access XtNuserData Pointer NULL Pointer SGI
XtNwidth Dimension 0 SGI
XtNx Position 0 SGI
XtNy Position 0 SGI XtNblinkRate
This resource is used to specify the rate that the active input caret blinks. The value of this resource is interpreted as the number of milliseconds between blinks. Setting this value to zero (0) turns the blink effect off. XtNbottomMargin
Range of Values:
1 <= XtNbottomMargin <= height - XtNtopMargin - font_height
This resource specifies the number of pixels used for the bottom margin. Note: the range is relative to the top margin value. XtNbuttons
This is the callback list used when a mouse button press is made in the pane. The call_data parameter is a pointer to an OlInputCallData structure:
typedef enum {
OL_UNKNOWN_INPUT,
OL_UNKNOWN_BTN_INPUT,
OL_SELECT, OL_ADJUST, OL_MENU,
OL_CONSTRAIN, OL_DUPLICATE, OL_PAN,
OL_UNKNOWN_KEY_INPUT,
OL_CUT, OL_COPY, OL_PASTE,
OL_HELP, OL_CANCEL, OL_PROP, OL_STOP, OL_UNDO,
OL_NEXT_FIELD, OL_PREV_FIELD,
OL_CHARFWD, OL_CHARBAK,
OL_ROWDOWN, OL_ROWUP,
OL_WORDFWD, OL_WORDBAK,
OL_LINESTART, OL_LINEEND,
OL_DOCSTART, OL_DOCEND,
OL_PANESTART, OL_PANEEND,
OL_DELCHARFWD, OL_DELCHARBAK,
OL_DELWORDFWD, OL_DELWORDBAK,
OL_DELLINEFWD, OL_DELLINEBAK, OL_DELLINE,
OL_SELCHARFWD, OL_SELCHARBAK,
OL_SELWORDFWD, OL_SELWORDBAK,
OL_SELLINEFWD, OL_SELLINEBAK, OL_SELLINE,
OL_SELFLIPENDS,
OL_REDRAW, OL_RETURN,
OL_PAGEUP, OL_PAGEDOWN,
OL_HOME, OL_END,
OL_SCROLLUP, OL_SCROLLDOWN,
OL_SCROLLLEFT, OL_SCROLLRIGHT,
OL_SCROLLLEFTEDGE, OL_SCROLLRIGHTEDGE,
OL_PGM_GOTO,
} OlInputEvent;
typedef struct {
Boolean consumed;
XEvent ∗ event;
KeySym ∗ keysym;
char ∗∗ buffer;
OlInputEvent ol_event;
} OlInputCallData, ∗OlInputCallDataPointer;
This callback can be used to remap or consume button events.
For example, this callback may be used to override the default Edit menu. To do so, the application would add a XtNbuttons callback that checks the ol_event member of the OlInputCallData structure. If the value of the ol_event member is OL_MENU the callback posts the application defined menu and sets the member of the OlInputCallData structure to TRUE. XtNcharsVisible
This resource is used to specify the initial width of the text in terms of characters. It overrides the XtNwidth resource setting. The XtNwidth is recalculated to be the value of XtNcharsVisible multiplied by the width of the ’n’ (en) character in the font plus the values for the left and right margins. The value of this resource changes to reflect the effects of geometry changes imposed by the widget tree and the user. SetValues for this resource is ignored. XtNcursorPosition
Range of Values: 0 <= cursorPosition < size of buffer
This resource is used to specify the relative character position in the text source of the insert cursor. Changing the value of this resource may affect the XtNdisplayPosition resource if the cursorPosition is not visible in the pane. XtNdisplayPosition
Range of Values:
0 <= displayPosition < size of buffer
This resource contains the position in the text source that will be displayed at the top of the pane. A value of 0 indicates the beginning of the text source. When the position is near the end of the buffer, this position is recalculated to ensure that the last line in the buffer appears as the last line in the pane. XtNeditType
Range of Values:
OL_TEXT_READ/"textread"
OL_TEXT_EDIT/"textedit"
This resource controls the edit state of the source:
OL_TEXT_READ
The source is read-only; the end-user cannot edit it. OL_TEXT_EDIT
The source is fully editable. XtNfont
Range of Values:
(Valid XFontStruct ∗)/(Valid font name)
This resource is used the specify the font to be used to display text within the widget. XtNfontColor
Range of Values:
Valid Pixel value for the display)/(Valid color name)
This resource specifies the color of the text. Normally, this color is derived from the value of the XtNtextEditFontColor resource and is dynamically maintained. This dynamic behavior is abandoned if the application explicitly sets this resource either at initialization or through a SetValues. XtNinputFocusColor
Range of Values:
(Valid Pixel value for the display)/(Valid color name)
This resource specifies the color of the input caret. Normally, this color is derived from the value of the XtNinputFocusColor resource and is dynamically maintained. This dynamic behavior is abandoned if the application explicitly sets this resource either at initialization or through a SetValues.
XtNkeys
This is the callback list used when a key press is made in the pane. The call_data parameter is a pointer to an OlInputCallData structure:
typedef enum {
OL_UNKNOWN_INPUT,
OL_UNKNOWN_BTN_INPUT,
OL_SELECT, OL_ADJUST, OL_MENU,
OL_CONSTRAIN, OL_DUPLICATE, OL_PAN,
OL_UNKNOWN_KEY_INPUT,
OL_CUT, OL_COPY, OL_PASTE,
OL_HELP, OL_CANCEL, OL_PROP, OL_STOP, OL_UNDO,
OL_NEXT_FIELD, OL_PREV_FIELD,
OL_CHARFWD, OL_CHARBAK,
OL_ROWDOWN, OL_ROWUP,
OL_WORDFWD, OL_WORDBAK,
OL_LINESTART, OL_LINEEND,
OL_DOCSTART, OL_DOCEND,
OL_PANESTART, OL_PANEEND,
OL_DELCHARFWD, OL_DELCHARBAK,
OL_DELWORDFWD, OL_DELWORDBAK,
OL_DELLINEFWD, OL_DELLINEBAK, OL_DELLINE,
OL_SELCHARFWD, OL_SELCHARBAK,
OL_SELWORDFWD, OL_SELWORDBAK,
OL_SELLINEFWD, OL_SELLINEBAK, OL_SELLINE,
OL_SELFLIPENDS,
OL_REDRAW, OL_RETURN,
OL_PAGEUP, OL_PAGEDOWN,
OL_HOME, OL_END,
OL_SCROLLUP, OL_SCROLLDOWN,
OL_SCROLLLEFT, OL_SCROLLRIGHT,
OL_SCROLLLEFTEDGE, OL_SCROLLRIGHTEDGE,
OL_PGM_GOTO,
} OlInputEvent;
typedef struct {
Boolean consumed;
XEvent ∗ event;
KeySym ∗ keysym;
char ∗∗ buffer;
OlInputEvent ol_event;
} OlInputCallData, ∗OlInputCallDataPointer;
This callback can be used to remap or consume key events.
For example, this callback may be used to post a property window for the text. To do so, the application would add a XtNkeys callback that checks the ol_event member of the OlInputCallData structure. If the value of the ol_event member is OL_PROP the callback posts the property window (or raises it if it’s already mapped) and sets the consumed member of the OlInputCallData structure to TRUE. XtNleftMargin
Range of Values:
1 <= XtNleftMargin <= width - XtNrightMargin - font_width
This resource specifies the number of pixels used for the left margin. Note: the range is relative to the right margin value. XtNlinesVisible
This resource is used to specify the initial height of the text in terms of lines. It overrides the XtNheight resource setting. The XtNheight is recalculated to be the value of XtNlinesVisible multiplied by the height of the font plus the values for the top and bottom margins. The value of this resource changes to reflect the effects of geometry changes imposed by the widget tree and the user. SetValues for this resource is ignored. XtNmargin
This is the callback list used when the pane is redisplayed. The call_data parameter is a pointer to an OlTextMarginCallData structure:
typedef enum {
OL_MARGIN_EXPOSED,
OL_MARGIN_CALCULATED,
} OlTextMarginHint;
typedef struct {
OlTextMarginHint hint;
XRectangle ∗ rect;
} OlTextMarginCallData, ∗OlTextMarginCallDataPointer;
The OlTextMarginHint indicates whether the area to be redrawn was explicitly known because of an exposure event (OL_MARGIN_EXPOSED) or if the rectangle was calculated relative to the textual display (OL_MARGIN_CALCULATED). The margin callback should respond to the OL_MARGIN_EXPOSED hint by repainting the area defined by the XRectangle rect. The margin callback may wish to calculate its own rectangle in the OL_MARGIN_CALCULATED case. It can freely use the rectangle structure passed in with the call data for this purpose.
This callback can be used to repair the margins for the text.
For example, this callback may be used to display line numbers for the text in the left margin. XtNmodifyVerification
This is the callback list used when a modification of the buffer is attempted. The call_data parameter is a pointer to an OlTextModifyCallData structure:
typedef struct {
Boolean ok;
TextPosition current_cursor;
TextPosition select_start;
TextPosition select_end;
TextPosition new_cursor;
TextPosition new_select_start;
TextPosition new_select_end;
char ∗ text;
int text_length;
} OlTextModifyCallData, ∗OlTextModifyCallDataPointer;
All of the fields in this structure, with the exception of the ok flag, are treated as read-only information. The application can return without changing the value of the ok flag, in which case the update will occur. The application can also set the ok flag to FALSE, perform any other operations it desires, and return, in which case the update will not be performed. XtNmotionVerification
This callback list is used whenever the cursor position moves within the widget. The call_data parameter is a pointer to an OlTextMotionCallData structure:
typedef struct {
Boolean ok;
TextPosition current_cursor;
TextPosition new_cursor;
TextPosition select_start;
TextPosition select_end;
} OlTextMotionCallData, ∗OlTextMotionCallDataPointer;
This callback list is used whenever the cursor position changes due to cursor movement operations or by modification of the text.
The application can distinguish between a simple cursor movement and a modify operation by comparing the current_cursor and new_cursor values.
When these values are equal the callback is the result of a modify operation. In this case the ok field is ignored and the application should not attempt to perform updates to the text or its display during this callback.
If the values of current_cursor and new_cursor are different, the application is guaranteed that the operation is the result of a cursor movement. In this mode all of the fields in this structure, with the exception of the ok flag, are treated as read-only information. The application can return without changing the value of the ok flag, in which case the movement will occur. The application can also set the ok flag to FALSE, perform any other operations it desires, and return, in which case the movement will not be performed.
XtNpostModifyNotification
This is the callback list used after a buffer update has completed. The call_data parameter is a pointer to an OlTextFocusCallData structure:
typedef struct {
Boolean requestor;
TextPosition new_cursor;
TextPosition new_select_start;
TextPosition new_select_end;
char ∗ inserted;
char ∗ deleted;
TextLocation delete_start;
TextLocation delete_end;
TextLocation insert_start;
TextLocation insert_end;
TextLocation cursor_position;
} OlTextFocusCallData, ∗OlTextFocusCallDataPointer;
This callback is used to synchronize the application with the text once a modify operation is completed. For example, the application may record successful edit operations in an undo buffer to provide multi-level undo functionality. The data provided in this callback is considered read-only and volatile (i.e., the application should copy what it needs from this structure before returning). XtNrightMargin
Range of Values:
1 <= XtNrightMargin <= width - XtNleftMargin - font_width
This resource specifies the number of pixels used for the right margin. Note: the range is relative to the left margin value. XtNselectEnd
This resource is used to specify the last character position selected in the text. It is used along with the XtNselectStart and XtNcursorPosition resources to specify a selection. To be effective, the XtNselectStart value must be less than or equal to XtNselectEnd and the XtNcursorPosition must be equal to either XtNselectStart or XtNselectEnd. If either of these tests fails then XtNselectStart and XtNselectEnd are set equal to the value of the XtNcursorPosition. XtNselectStart
This resource is used to specify the first character position selected in the text. It is used along with the XtNselectEnd and XtNcursorPosition resources to specify a selection. To be effective, the XtNselectStart value must be less than or equal to XtNselectEnd and the XtNcursorPosition must be equal to either XtNselectStart or XtNselectEnd. If either of these tests fails then XtNselectStart and XtNselectEnd are set equal to the value of the XtNcursorPosition. XtNsource
Range of Values:
<string> for OL_STRING_SOURCE
<name of file> for OL_DISK_SOURCE
<pointer to an existing TextBuffer> for OL_TEXT_BUFFER_SOURCE
This resource is used in tandem with the XtNsourceType resource to specify the source. See the XtNsourceType resource for a full description of these resources. XtNsourceType
Range of Values:
OL_STRING_SOURCE/"stringsource"
OL_DISK_SOURCE/"disksource"
OL_TEXT_BUFFER_SOURCE/NA
This resource controls the interpretation of the XtNsource resource value. When set to OL_STRING_SOURCE the XtNsource value is interpreted as the string to be used as the source, when set to OL_DISK_SOURCE the XtNsource value is interpreted as the name of the file containing the source, when set to OL_TEXT_BUFFER_SOURCE the XtNsource value is interpreted as a pointer to a previously initialized TextBuffer (see the TextBuffer Utilities manual page for a description of TextBuffers). XtNtabTable
This resource is used to specify a pointer to an array of tab Positions. These tab positions are specified in terms of pixels and must be terminated by a zero (0) entry. The widget calculates tabs by finding the next tab table entry that exceeds the current x offset for the line. If no such entry exists in the table or if the pointer to the tab table is NULL, the tab is set to the next greater multiple of eight (8) times the size of the ’n’ (en) character in the font. XtNtopMargin
Range of Values:
1 <= XtNtopMargin <= height - XtNbottomMargin - font_height
This resource specifies the number of pixels used for the top margin. Note: the range is relative to the bottom margin value. XtNwrapMode
Range of Values:
OL_WRAP_WHITE_SPACE/"wrapwhitespace"
OL_WRAP_ANY/"wrapany"
OL_WRAP_OFF/"wrapoff"
This resource is used to control how the source is wrapped in the pane. When OL_WRAP_ANY, lines are wrapped at the last character before the right margin; when set to OL_WRAP_WHITE_SPACE, lines are wrapped at the last white space before the right margin or as in OL_WRAP_ANY if the line does not contain any white space; when OL_WRAP_OFF, lines are not wrapped and the pane may horizontally scroll.
4/16/90 — Last change: