TextEdit UNIX System V TextEdit
NAME
TextEdit - provides multiple line editing
SYNOPSIS
#include <stdio.h>
#include <buffutil.h>
#include <textbuff.h>
#include <Intrinsic.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:
10/89 Page 1
TextEdit UNIX System V TextEdit
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.
Page 2 10/89
TextEdit UNIX System V TextEdit
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.
Keyboard Traversal
The default value of the XtNtraversalOn resource is True.
The widget responds to the following keyboard navigation keys:
- NEXT_FIELD moves to the first control in the next group
- PREV_FIELD moves to the first control in the previous group
- NEXTWINDOW moves to the next window in the application
- PREVWINDOW moves to the previous window in the application
- NEXTAPP moves to the first window in the next application
- PREVAPP moves to the first window in the previous application
- ROWUP moves the caret up one line in the current column
- ROWDOWN moves the caret down one line in the current column
- CHARBAK moves the caret backward one character
- CHARFWD moves the caret forward one character
- WORDFWD moves the caret forward one word
- WORDBAK moves the caret back one word
- LINESTART moves the caret to the beginning of the line
- LINEEND moves the caret to the end of the line
- PANESTART moves the caret to the first row and column on the display
- PANEEND moves the caret to the last row and column on the display
10/89 Page 3
TextEdit UNIX System V TextEdit
- DOCSTART moves the caret to the beginning of the document
- DOCEND moves the caret to the end of the document
NOTE: It is expected that the user will use the alternate bindings for
NEXT_FIELD and PREV_FIELD because the primary binding, <Tab> and
<Shift><Tab>, are valid characters in a Text pane.
The TextEdit widget responds to the following selection keys:
- SELCHARFWD adjusts the selection one character forward
- SELWORDFWD adjusts the selection to the end of the current (or next)
word
- SELLINEFWD adjusts the selection to the end of the current (or next)
line
- SELCHARBAK adjusts the selection one character backward
- SELWORDBAK adjusts the selection to the beginning of the current (or
previous) word
- SELLINEBAK adjusts the selection to the beginning of the current (or
previous) line
- SELLINE adjusts the selection to include the entire current line
- SELFLIPENDS reverses the "anchor" and cursor position of the selection
The TextEdit widget responds to the following scrolling keys:
- SCROLLUP scroll the view up one screen line
- SCROLLDOWN scroll the view down one screen line
- PAGEUP scroll to the next page up
- PAGEDOWN scroll to the next page down
- PAGERIGHT scroll to the next page to the right
- PAGELEFT scroll to the next page to the left
- SCROLLLEFT scroll the view one screen to the left
- SCROLLRIGHT scroll the view one screen to the right
- SCROLLTOP scroll to the beginning of the document
Page 4 10/89
TextEdit UNIX System V TextEdit
- SCROLLBOTTOM scroll to the end of the document
- SCROLLLEFTEDGE scroll to the left edge of the document
- SCROLLRIGHTEDGE scroll to the right edge of the document
The TextEdit widget responds to the following edit keys:
- DELCHARFWD deletes the character to the right of the caret
- DELCHARBAK deletes the character to the left of the caret
- DELWORDFWD deletes the word to the right of the caret
- DELWORDBAK deletes the word to the left of the caret
- DELLINEFWD deletes to the end of the line from the caret
- DELLINEBAK deletes from the beginning of the line to the caret
- DELLINE deletes the line containing the caret
- UNDO undoes the previous edit operation
Coloration
When this widget receives the input focus, it changes the text caret in
the text field to the active caret and the color specified in
XtNinputFocusColor.
Display of Keyboard Mnemonic
The TextEdit does not display the mnemonic. If the TextEdit widget is
the child of a Caption widget, the Caption widget can be used to display
the mnemonic.
Display of Keyboard Accelerators
The TextEdit does not display the keyboard accelerator. If the TextEdit
is the child of a Caption widget, the Caption widget can be used to
display the accelerator as part of the label.
RESOURCES
__________________________________________________________________________________________________
| TextEdit Resource Set |
||||||
| Name | Class | Type | Default | Access|
||||||
XtNaccelerator XtCAccelerator String NULL SGI
XtNacceleratorText XtCAcceleratorText String Dynamic SGI
XtNancestorSensitive XtCSensitive Boolean DYNAMIC G
XtNbackground XtCBackground Pixel XtDefaultBackground SGI
10/89 Page 5
TextEdit UNIX System V TextEdit
__________________________________________________________________________________________________
| TextEdit Resource Set |
||||||
| Name | Class | Type | Default | Access|
||||||
XtNbackgroundPixmap XtCPixmap Pixmap Unspecified SGI
XtNblinkRate XtCBlinkRate Int 1000 SGI
XtNborderColor XtCBorderColor Pixel XtDefaultForeground SGI
XtNborderPixmap XtCPixmap Pixmap Unspecified SGI
XtNborderWidth XtCBorderWidth Dimension 0 SGI
XtNbottomMargin XtCMargin Dimension 4 SGI
XtNcharsVisible XtCCharsVisible Int 50 GI
XtNcolormap XtCColormap Pointer DYNAMIC G
XtNconsumeEvent XtCConsumeEvent XtCallbackList NULL SGI
XtNcursorPosition XtCTextPosition Int 0 SGI
XtNdepth XtCDepth Int DYNAMIC GI
XtNdisplayPosition XtCTextPosition Int 0 SGI
XtNeditType XtCEditType OlEditType OLTEXTEDIT SGI
XtNfont XtCFont FontStruct NULL FontStruct SGI
XtNfontColor XtCFontColor Pixel Black SGI
XtNheight XtCHeight Dimension 0 SGI
XtNinputFocusColor XtCInputFocusColor Pixel Black SGI
XtNinsertTab XtCInsertTab Boolean TRUE SGI
XtNleftMargin XtCMargin Dimension 4 SGI
XtNlinesVisible XtCLinesVisible Int 16 GI
XtNmappedWhenManaged XtCMappedWhenManaged Boolean TRUE SGI
XtNmargin XtCCallback Callback NULL Callback SGI
XtNmnemonic XtCMnemonic unsigned char NULL SGI
Page 6 10/89
TextEdit UNIX System V TextEdit
__________________________________________________________________________________________________
| TextEdit Resource Set |
||||||
| Name | Class | Type | Default | Access|
||||||
| XtNmodifyVerification | XtCCallback | Callback | NULL Callback | SGI |
||||||
| XtNmotionVerification | XtCCallback | Callback | NULL Callback | SGI |
||||||
| XtNpostModifyNotification| XtCCallback | Callback | NULL Callback | SGI |
||||||
| XtNreferenceName | XtCReferenceName | String | NULL | SGI |
||||||
| XtNreferenceWidget | XtCReferenceWidget | Widget | NULL | SGI |
||||||
| XtNrightMargin | XtCMargin | Dimension | 4 | SGI |
||||||
| XtNscreen | XtCScreen | Pointer | DYNAMIC | G |
||||||
| XtNselectEnd | XtCTextPosition | Int | 0 | SGI |
||||||
| XtNselectStart | XtCTextPosition | Int | 0 | SGI |
||||||
| XtNsensitive | XtCSensitive | Boolean | TRUE | GI |
||||||
| XtNsource | XtCSource | String | NULL | SGI |
||||||
| XtNsourceType | XtCSourceType | OlSourceType | OLSTRINGSOURCE | SGI |
||||||
| XtNtabTable | XtCTabTable | Pointer | NULL | SGI |
||||||
| XtNtopMargin | XtCMargin | Dimension | 4 | SGI |
||||||
| XtNtraversalOn | XtCTraversalOn | Boolean | TRUE | SGI |
||||||
| XtNuserData | XtCUserData | Pointer | NULL Pointer | SGI |
||||||
| XtNwidth | XtCWidth | Dimension | 0 | SGI |
||||||
| XtNwrapMode | XtCWrapMode | OlWrapMode | OLWRAPWHITESPACE| SGI |
||||||
| XtNx | XtCPosition | Position | 0 | SGI |
||||||
| XtNy | XtCPosition | Position | 0 | SGI |
||||||
At setvalues time, the following resources are copied to the TextEdit
widget:
XtNstring is passed to TextEdit as XtNsource, and these resources are
set:
10/89 Page 7
TextEdit UNIX System V TextEdit
XtNsourceType = OL_STRING_SOURCE
XtNcursorPosition = 0
XtNselectStart = 0
XtNselectEnd = 0
XtNinsertTab is passed to TextEdit as XtNinsertTab
XtNbackground is passed to TextEdit as XtNbackground
At creation time, these resources are passed to TextEdit:
XtNwrapMode = OL_WRAP_OFF
XtNlinesVisible = 1
XtNwidth = width of textfield
XtNcharsVisible = depends on size of textfield
XtNtopMargin = 1
XtNbottomMargin = 3
XtNleftMargin = 1
XtNrightMargin = 1
XtNfont = textfield's font
XtNregisterFocusFunc = EditsRegisterFocus (textfield's private routine)
XtNinsertTab = textfield's XtNinsertTab
XtNbackground = textfield's XtNbackground
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.
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
Page 8 10/89
TextEdit UNIX System V TextEdit
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
10/89 Page 9
TextEdit UNIX System V TextEdit
dynamically maintained. This dynamic behavior is abandoned if the
application explicitly sets this resource either at initialization or
through a SetValues.
XtNinsertTab
If this resource is set to FALSE, a TAB character is not insertable.
Setting this resource to FALSE makes traversal of the controls easier if
the TAB key is bound as OL_NEXT_FIELD; if set to TRUE, a TAB character is
insertable.
XtNmargin
This is the callback list used when the pane is redisplayed. The
calldata 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 (OLMARGINEXPOSED) or if
the rectangle was calculated relative to the textual display
(OLMARGINCALCULATED). The margin callback should respond to the
OLMARGINEXPOSED hint by repainting the area defined by the XRectangle
rect. The margin callback may wish to calculate its own rectangle in the
OLMARGINCALCULATED 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 calldata parameter is a pointer to an
OlTextModifyCallData structure:
typedef struct {
Boolean ok;
Page 10 10/89
TextEdit UNIX System V TextEdit
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 calldata 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 currentcursor and newcursor 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 currentcursor and newcursor 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.
10/89 Page 11
TextEdit UNIX System V TextEdit
XtNpostModifyNotification
This is the callback list used after a buffer update has completed. The
calldata 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.
Page 12 10/89
TextEdit UNIX System V TextEdit
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.
10/89 Page 13