Text Editor Widget (DtEditor)

The Common Desktop Environment text editing system consists of two components:

The text editor client, dtpad, which provides editing services through graphical, action, and ToolTalk interfaces.
The editor widget, DtEditor(3), which provides a programmatic interface for the following editing services:
- Cut and paste
- Search and replace
- Simple formatting
- Spell checking (for 8-bit locales)
- Undo previous edit
- Enhanced I/O handling capabilities that support input and output of ASCII text, multibyte text, and buffers of data
- Support for reading and writing files directly

Although the Motif text widget also provides a programmatic interface, applications that use the system-wide uniform editor should use the DtEditor(3) widget. The Common Desktop Environment Text Editor and Mailer use the editor widget. Use this widget in the following circumstances:

You want the functionality, such as spell checking, undo, and find/change, that is provided by the DtEditor(3) widget.
You do not want to write the code so that users may read and write data to and from a file.
Your program does not need to examine every character typed or every cursor movement made by a user.

This section describes the text editor widget, DtEditor(3).

The Editor Widget library provides support for creating and editing text files. It enables applications running in the desktop environment to have a consistent method of editing text data. The DtEditor(3) widget consists of a scrolled edit window for text, an optional status line, and dialogs for finding and changing text, spell checking, and specifying formatting options. The text editor widget includes a set of convenience functions for programmatically controlling the widget.

Library and Header Files

The DtEditor widget is in the libDtWidget library. The header file is Dt/Editor.h.

Demo Program

A demo containing an example of the DtEditor widget is in /usr/dt/examples/dtwidget/editor.c.

Classes

Widget subclassing is not supported for the DtEditor widget class.

DtEditor inherits behavior and resources from Core, Composite, Constraints, XmManager, and XmForm classes.

The class name for the editor widget is DtEditorWidget.

The class pointer is dtEditorWidgetClass.

Convenience Functions

The DtEditor convenience functions are described in the following tables.

Life Cycle Functions

The DtEditor life cycle functions are described in Table 7-9 “DtEditor Life Cycle Functions”

Table 7-9 DtEditor Life Cycle Functions

`Function`	`Description`
`DtCreateEditor`	Creates a new instance of a DtEditor widget and its children.
`DtEditorReset`	Restores a DtEditor widget to its initial state.

Input/Output Functions

The DtEditor input/output functions are described in Table 7-10 “DtEditor Input/Output Functions”

Table 7-10 DtEditor Input/Output Functions

`Function`	`Description`
`DtEditorAppend`	Appends content data to the end of an editor widget.
`DtEditorAppendFromFile`	Appends the contents of a file to the end of an editor widget.
`DtEditorGetContents`	Retrieves the entire contents of an editor widget.
`DtEditorInsert`	Inserts content data at the current insert position.
`DtEditorInsertFromFile`	Inserts the contents of a file at the current insert position.
`DtEditorReplace`	Replaces a portion of text with the supplied data.
`DtEditorReplaceFromFile`	Replaces a portion of text with the contents of a file.
`DtEditorSaveContentsToFile`	Saves the entire contents to a file.
`DtEditorSetContents`	Loads content data into an editor widget, replacing the entire contents of the widget.
`DtEditorSetContentsFromFile`	Loads the contents of a file into an editor widget, replacing the entire contents of the widget.

Selection Functions

The DtEditor selection functions are described in Table 7-11 “DtEditor Selection Functions”

Table 7-11 DtEditor Selection Functions

`Function`	`Description`
`DtEditorClearSelection`	Replaces the currently selected contents with blanks.
`DtEditorCopyToClipboard`	Copies the currently selected contents to the clipboard.
`DtEditorCutToClipboard`	Removes the currently selected contents, placing then on the clipboard.
`DtEditorDeleteSelection`	Removes the currently selected contents.
`DtEditorDeselect`	Deselects any selected contents.
`DtEditorPasteFromClipboard`	Pastes the contents of the clipboard into an editor widget, replacing any currently selected contents.
`DtEditorSelectAll`	Selects the entire contents of an editor widget.

Format Functions

The DtEditor format functions are described in Table 7-12 “DtEditor Format Functions”

Table 7-12 DtEditor Format Functions

`Function`	`Description`
`DtEditorFormat`	Formats all or part of the contents of an editor widget.
`DtEditorInvokeFormatDialog`	Displays the format dialog box that enables the user to specify format settings for margins and justification style and to perform formatting operations.

Find and Change Functions

The DtEditor find and change functions are described in Table 7-13 “DtEditArea Find and Change Functions”

Table 7-13 DtEditArea Find and Change Functions

`Function`	`Description`
`DtEditorChange`	Changes one or all occurrences of a string.
`DtEditorFind`	Finds the next occurrence of a string.
`DtEditorInvokeFindChangeDialog`	Displays the dialog box that enables the user to search for, and optionally change, a string.
`DtEditorInvokeSpellDialog`	Displays a dialog box with a list of misspelled words in the current contents.

Auxiliary Functions

The DtEditor auxiliary functions are described in Table 7-14 “DtEditor Auxiliary Functions”

Table 7-14 DtEditor Auxiliary Functions

`Function`	`Description`
`DtEditorCheckForUnsavedChanges`	Reports whether the contents of an editor widget have been altered since the last time they were retrieved or saved.
`DtEditorDisableRedisplay`	Prevents redisplay of an editor widget even though its visual attributes have changed.
`DtEditorEnableRedisplay`	Forces the visual update of an editor widget.
`DtEditorGetInsertPosition`	Returns the insertion cursor position of the editor widget.
`DtEditorGetLastPosition`	Returns the position of the last character in the edit window.
`DtEditorGetMessageTextFieldID`	Retrieves the widget ID of the text field widget used to display application messages.
`DtEditorGetSizeHints`	Retrieves sizing information from an editor widget.
`DtEditorGoToLine`	Moves the insertion cursor to the specified line.
`DtEditorSetInsertionPosition`	Sets the position of the insertion cursor.
`DtEditorTraverseToEditor`	Sets keyboard traversal to the edit window of an editor widget.
`DtEditorUndoEdit`	Undoes the last edit made by a user.

Resources

The DtEditor widget provides the following set of resources.

DtNautoShowCursorPosition ensures that the text visible in the scrolled edit window contains the insert cursor when set to True. If the insert cursor changes, the contents of the editor may scroll to bring the insertion point into the window.
DtNblinkRate specifies the blink rate of the text cursor in milliseconds. The time it takes to blink the insertion cursor on and off is twice the blink rate. When the blink rate is set to zero, the cursor does not blink. The value must not be negative.
DtNbuttonFontList specifies the font list used for the buttons that are displayed in the dialog boxes of DtEditor.
DtNcolumns specifies the initial width of the editor as an integer number of characters. The value must be greater than zero.
DtNcursorPosition specifies the location of the current insert cursor in the editor where the current insert cursor is placed. Position is determined by the number of characters from the beginning of the text. The first character position is 0.
DtNcursorPositionVisible marks the insert cursor position by a blinking text cursor when the Boolean value is True.
DtNdialogTitle specifies the title for all dialogs displayed by DtEditor. These include the dialogs for word search and replace, misspelled words, and format settings.
DtNeditable indicates that the user can edit the data when set to True. Prohibits the user from editing data when set to False.
DtNlabelFontList specifies the font list used for DtEditor labels (the labels are displayed in the status line and DtEditor dialog boxes).
DtNoverstrike when set to False, characters typed into the editor widget inserts at the position of the cursor (the default). When set to True, characters typed into the editor widget replace the characters that directly follow the insertion cursor. When the end of the line is reached, characters are appended to the end of the line. If the status line is visible, the DtNoverstrikeIndicatorLabel is displayed in the status line whenever DtNoverstrike is True.
DtNrows specifies the initial height of the editor measured in character heights. The value must be greater than zero.
DtNscrollHorizontal adds a scroll bar that enables the user to scroll horizontally through text when the Boolean value is True.
DtNscrollLeftSide puts a vertical scroll bar on the left side of the scrolled edit window when the Boolean value is True.
DtNshowStatusLine displays a status line below the text window when set to True. The status line contains a field that displays the current line number of the insert cursor, total number of lines in the document, and whether the editor is in overstrike mode. Users can type a line number in the line number display to go directly to that line.

The status line also includes a Motif XmTextField(3) widget for displaying messages supplied by an application. This field is a convenient place for an application to display status and feedback about the document being edited. The ID of the text field is retrieved using DtEditorGetMessageTextFieldID(3). A message is displayed by setting the XmNvalue or XmNvalueWcs resource of this widget. If the text field is not needed, you can unmanage it by calling XtUnmanageWidget(3) with its ID.

DtNspellFilter specifies the filter used to identify spelling errors. The function DtEditorInvokeSpellDialog(3) filters the contents of an editor through the filter specified by DtNspellFilter. The filter specified should accept a file name and produce a list of misspelled and unrecognized words in this file on stdout. The default filter is spell(1).
DtNtextBackground specifies the background for the edit window.
DtNtextDeselectCallback specifies a function called whenever no text is selected within the edit area. The reason sent by the callback is DtEDITOR_TEXT_DESELECT.
DtNtextFontList specifies the font list used for the DtEditor edit window and its text fields. The text fields are displayed in the status line and DtEditor dialog boxes.
DtNtextForeground specifies the foreground for the edit window.
DtNtextSelectCallback specifies a function called whenever text is selected within the edit area. The reason sent by the callback is DtEDITOR_TEXT_SELECT.
DtNtextTranslations specifies translations that are added to the edit window. Translations specified with this resource override any duplicate translations defined for the edit window. See the DtEditor(3) man page for a list of translations provided by DtEditor.
DtNtopCharacter displays the line that contains the position of text at the top of the scrolled edit window. The line is displayed at the top of the widget without shifting the text left or right. Position is determined by the number of characters from the beginning of the text. The first character position is zero.
XGetValues(3) for DtNtopCharacter returns the position of the first character in the line that is displayed at the top of the widget.
DtNwordWrap breaks lines at word breaks with soft carriage returns when they reach the right edge of the window. Note that word wrap affects only the visual appearance of the contents of an editor widget. The line breaks (soft carriage returns) are not physically inserted into the text. The editor does support substituting hard carriage returns when the contents of the widget are retrieved or saved to a file. See the DtEditorGetContents(3) and DtEditorSaveContentsToFile(3) man pages for more information.

Table 7-15 “DtEditor Resources” lists the class, type, default, and access for each resource. You can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or class in an .Xdefaults file, remove the DtN or DtC prefix and use the remaining letters. To specify one of the defined values for a resource in an .Xdefaults file, remove the Dt prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words).

The codes in the access column show if you can:

Set the resource at creation time (C)
Set by using XtSetValues (S)
Retrieve by using XtGetValues (G)

See the DtEditor(3) man page for more information.

Table 7-15 DtEditor Resources

`Name`	`Class`	`Type`	`Default`	`Access`
`DtNautoShowCursorPosition`	`DtCAutoShowCursor Position`	`Boolean`	`True`	`CSG`
`DtNblinkRate`	`DtCBlinkRate`	`int`	`500`	`CSG`
`DtNbuttonFontList`	`DtCFontList`	`XmFontList`	`Dynamic`	`CSG`
`DtNcolumns`	`DtCColumns`	`XmNcolumns`	`Dynamic`	`CSG`
`DtNcursorPosition`	`DtCCursorPosition`	`XmTextPosition`	`0`	`CSG`
`DtNcursorPositionVisible`	`DtCCursorPosition Visible`	`Boolean`	`True`	`CSG`
`DtNdialogTitle`	`DtCDialogTitle`	`XmString`	`NULL`	`CSG`
`DtNeditable`	`DtCEditable`	`Boolean`	`True`	`CSG`
`DtNlabelFontList`	`DtCFontList`	`XmFontList`	`Dynamic`	`CSG`
`DtNmaxLength`	`DtCMaxLength`	`int`	`Largest integer`	`CSG`
`DtNoverstrike`	`DtCOverstrike`	`Boolean`	`False`	`CSG`
`DtNrows`	`DtCRows`	`XmNrows`	`Dynamic`	`CSG`
`DtNscrollHorizontal`	`DtCScroll`	`Boolean`	`True`	`CG`
`DtNscrollLeftSide`	`DtCScrollSide`	`Boolean`	`Dynamic`	`CG`
`DtNscrollTopSide`	`DtCScrollSide`	`Boolean`	`False`	`CG`
`DtNscrollVertical`	`DtCScroll`	`Boolean`	`True`	`CG`
`DtNshowStatusLine`	`DtCShowStatusLine`	`Boolean`	`False`	`CSG`
`DtNspellFilter`	`DtCspellFilter`	`char *`	`Spell`	`CSG`
`DtNtextBackground`	`DtCBackground`	`Pixel`	`Dynamic`	`CSG`
`DtNtextDeselectCallback`	`DtCCallback`	`XtCallbackList`	`NULL`	`C`
`DtNtextFontList`	`DtCFontList`	`XmFontList`	`Dynamic`	`CSG`
`DtNtextForeground`	`DtCForeground`	`Pixel`	`Dynamic`	`CSG`
`DtNtextTranslations`	`DtCTranslations`	`XtTranslations`	`NULL`	`CS`
`DtNtextSelectCallback`	`DtCCallback`	`XtCallbackList`	`NULL`	`C`
`DtNtopCharacter`	`DtCTextPosition`	`XmTextPosition`	`0`	`CSG`
`DtNwordWrap`	`DtCWordWrap`	`Boolean`	`True`	`CSG`

Inherited Resources

DtEditor inherits behavior and resources from the following superclasses:

XmForm
XmManager
Composite
Core

Refer to the appropriate man page for more information.

Localization Resources

The following list describes a set of widget resources that are designed for localization of the DtEditor widget and its dialog boxes. Default values for these resources depend on the locale.

DtNcenterToggleLabel specifies the label for the center alignment toggle button in the Format Settings dialog box. The default value in the C locale is Center.
DtNchangeAllButtonLabel specifies the label for the button in the Find/Change dialog box that changes all occurrences of the Find string in the document. The default value in the C locale is Change All.
DtNchangeButtonLabel specifies the label for the button in the Find/Change dialog box that changes the next occurrence of the find string in the document. The default value in the C locale is Change.
DtNchangeFieldLabel specifies the label for the field in the Find/Change dialog box where the user specifies the replacement string. The default value in the C locale is Change To.
DtNcurrentLineLabel specifies the label for the current line number field in the status line. The default value in the C locale is Line.
DtNfindButtonLabel specifies the label for the button in the Find/Change dialog box that finds the next occurrence of the find string in the document. The default value in the C locale is Find.
DtNfindChangeDialogTitle specifies the title for the Find/Change dialog box. If DtNdialogTitle is non-null, it is added to the front of this resource to form the title. The default value in the C locale is Find/Change.
DtNfindFieldLabel specifies the label for the field in the Find/Change dialog box where the user specifies the search string. The default value in the C locale is Find.
DtNformatAllButtonLabel specifies the label for the button in the Format Settings dialog box that formats the complete document. The default value in the C locale is All.
DtNformatParagraphButtonLabel specifies the label for the button in the Format Settings dialog box that formats the paragraph containing the insertion cursor. The default value in the C locale is Paragraph.
DtNformatSettingsDialogTitle specifies the title for the Format Settings dialog box. If DtNdialogTitle is non-null, it is added to the front of this resource to form the title. The default value in the C locale is Format Settings.
DtNinformationDialogTitle specifies the title for the Information dialog box that is used to present feedback and general information to the user. If DtNdialogTitle is non-null, it is added to the front of this resource to form the title. The default value in the C locale is Information.
DtNjustifyToggleLabel specifies the label for the justify alignment toggle button in the Format Settings dialog box. The default value in the C locale is Justify.
DtNleftAlignToggleLabel specifies the label for the left alignment toggle button in the Format Settings dialog box. The default value in the C locale is Left Align.
DtNleftMarginFieldLabel specifies the label for the left margin value field in the Format Settings dialog box. The default value in the C locale is Left Margin.
DtNmisspelledListLabel specifies the label for the list of unrecognized and misspelled words in the Spell dialog box. The default value in the C locale is Misspelled Words.
DtNoverstrikeLabel specifies the label in the status line that shows that the editor is in overstrike mode. The default value in the C locale is Overstrike.
DtNrightAlignToggleLabel specifies the label for the right alignment toggle button in the Format Settings dialog box. The default value in the C locale is Right Align.
DtNrightMarginFieldLabel specifies the label for the right margin value field in the Format Settings dialog box. The default value in the C locale is Right Margin.
DtNspellDialogTitle specifies the title for the Format Settings dialog box. If DtNdialogTitle is non-null, it is added to the front of this resource to form the title. The default value in the C locale is Spell.
DtNtotalLineCountLabel specifies the label for the display as part of the status line that shows the total number of lines in the document. The default value in the C locale is Total.

Table 7-16 “DtEditor Localization Resources” lists the class, type, default, and access for each of the localization resources. The codes in the access column show if you can:

Set the resource at creation time (C)
Set by using XtSetValues (S)
Retrieve by using XtGetValues (G)

See the DtEditor(3) man page for more information.

Table 7-16 DtEditor Localization Resources

`Name`	`Class`	`Type`	`Default`	`Access`
`DtNcenterToggleLabel`	`DtCCenterToggleLabel`	`XmString`	`Dynamic`	`CSG`
`DtNchangeAllButtonLabel`	`DtCChangeAllButtonLabel`	`XmString`	`Dynamic`	`CSG`
`DtNchangeButtonLabel`	`DtCChangeButtonLabel`	`XmString`	`Dynamic`	`CSG`
`DtNchangeFieldLabel`	`DtCChangeFieldLabel`	`XmString`	`Dynamic`	`CSG`
`DtNcurrentLineLabel`	`DtCCurrentLineLabel`	`XmString`	`Dynamic`	`CSG`
`DtNfindButtonLabel`	`DtCFindButtonLabel`	`XmString`	`Dynamic`	`CSG`
`DtNfindChangeDialogTitle`	`DtCFindChangeDialog Title`	`XmString`	`Dynamic`	`CSG`
`DtNfindFieldLabel`	`DtCFindFieldLabel`	`XmString`	`Dynamic`	`CSG`
`DtNformatAllButtonLabel`	`DtCFormatAllButtonLabel`	`XmString`	`Dynamic`	`CSG`
`DtNformatParagraphButton Label`	`DtCFormatParagraph ButtonLabel`	`XmString`	`Dynamic`	`CSG`
`DtNformatSettingsDialog Title`	`DtCFormatSettingsDialogTitle`	`XmString`	`Dynamic`	`CSG`
`DtNinformationDialogTitle`	`DtCInformationDialog Title`	`XmString`	`Dynamic`	`CSG`
`DtNjustifyToggleLabel`	`DtCJustifyToggleLabel`	`XmString`	`Dynamic`	`CSG`
`DtNleftAlignToggleLabel`	`DtCLeftAlignToggleLabel`	`XmString`	`Dynamic`	`CSG`
`DtNleftMarginFieldLabel`	`DtCLeftMarginFieldLabel`	`XmString`	`Dynamic`	`CSG`
`DtNmisspelledListLabel`	`DtCMisspelledListLabel`	`XmString`	`Dynamic`	`CSG`
`DtNoverstrikeLabel`	`DtCOverstrikeLabel`	`XmString`	`Dynamic`	`CSG`
`DtNrightAlignToggleLabel`	`DtCRightAlignToggle Label`	`XmString`	`Dynamic`	`CSG`
`DtNrightMarginFieldLabel`	`DtCRightMarginField Label`	`XmString`	`Dynamic`	`CSG`
`DtNspellDialogTitle`	`DtCSpellDialogTitle`	`XmString`	`Dynamic`	`CSG`
`DtNtotalLineCountLabel`	`DtCTotalLineCountLabel`	`XmString`	`Dynamic`	`CSG`

Callback Functions

The DtEditor widget supports three callback functions:

DtEditorNHelpCallback
DtNtextSelectCallback
DtNtextDeselectCallback

If you want to present help information about the editor widget and its dialog boxes, set the XmNhelpCallback resource and use the reason field passed as part of DtEditorHelpCallbackStruct to set the contents of the Help dialog box. A pointer to the following structure is passed to XmNHelpCallback. The callback structure and is described in Table 7-17 “DtEditorHelp Callback Structure”

typedef struct {
 int       reason;
 XEvent    *event;
} DtEditorHelpCallbackStruct;

Table 7-17 DtEditorHelp Callback Structure

`Structure`	`Description`
`reason`	The reason why the callback was invoked. Refer to the `DtEditor`(3) man page for a list of reasons.
`event`	A pointer to the event that invoked this callback. The value can be NULL.

Use the DtNtextSelectCallback and DtNtextDeselectCallback resources when you want to enable and disable menu items and commands depending on whether text is selected. DtNtextSelectCallback specifies a function that is called whenever some text is selected in the edit window. DtNtextDeselectCallback specifies a function that is called whenever no text is selected within the edit window. The reasons sent by the callbacks are DtEDITOR_TEXT_SELECT and DtEDITOR_TEXT_DESELECT.