DtEditor(library call)

NAME
DtEditor — the DtEditor widget class

SYNOPSIS

#include &<Dt/Editor.h>

DESCRIPTION

The DtEditor widget supports creating and editing text files. It gives applications running in the desktop environment a consistent method for editing text data. The widget consists of:

•   A scrolled edit window for text

•   Dialogs for finding and changing text

•   Optional status line

•   Spell checking option

•   Formatting options

•   Convenience functions for programmatically controlling the widget

The DtEditor widget supports the following set of basic editing operations:

•   Finding and changing text

•   Simple formatting

•   Spell checking

•   Undoing the previous edit operation

All operations, except for spell checking, support locales with single- and multi-byte characters.

The DtEditor widget also supports input and output of ASCII text, multi-byte text and buffers of data. Data can be passed between the application and the DtEditor widget, or a file and the widget.

The DtEditor widget provides separate callback lists to track when text is selected or deselected. In addition, it extends the standard help callback to report help requests from any of its components.

Widget subclassing is not supported for the DtEditor widget class.

  Edit Window

The edit window supports basic editing operations such as cut and paste, find and change, simple formatting and spell checking.

  Mouse and Keyboard

The user can use the mouse to move the edit cursor and to select portions of a document for editing operations. Selection is based on the model specified in the Inter-Client Communication Conventions Manual (ICCCM). The DtEditor widget supports primary and secondary selection.

The user can cut, copy and paste text using the clipboard, primary transfer or secondary transfer. The DtEditor widget accepts drops of text, text files or buffers of data. Text drops are inserted where the mouse button is released to complete the drop. Dropped files and buffers of data are placed at the insertion cursor. The DtEditor widget supports dragging of text within the edit window or to a different widget.

The DtEditor widget provides a set of translations for the edit window. The default translations provide key bindings for moving the insertion cursor, and deleting, inserting and selecting text. The insertion cursor, displayed as an I-beam, shows where input is inserted. Input is inserted just before the insertion cursor.

  Status Line

The status line, which can be shown or hidden, displays the current line number, total line count and whether the DtEditor widget is in overstrike mode. The current line-number display shows the line number of the line containing the insertion cursor. The user can go directly to any line in the document by entering the number into the current line number display. The status line also provides a text field for displaying application-supplied messages. For information on localizing the status line, see the Localization Resources section.

  Dialogs

The DtEditor widget includes dialogs to provide a graphical user interface to its functionality:

•   Find/Change dialog

•   Spell dialog.

•   Format Settings dialog

The titles of all dialogs are controlled with the DtNdialogTitle resource. All dialogs are posted using corresponding convenience functions and remain posted until dismissed by the user. Each dialog includes Close and Help buttons in addition to buttons described in the following lists. For information on localizing these dialogs, see the Localization Resources section.

The Find/Change dialog for the DtEditor widget enables users to search for, and optionally replace, a string in the edit window. The dialog includes fields for specifying the find string and the replacement string. Buttons initiate the find or change either the next occurrence or all occurrences of the find string to the replacement string. When the user selects the Find button, the next occurrence of the specified string (regular expressions are not supported) is highlighted in the DtEditor widget, if found; otherwise, the DtEditor widget displays a message dialog stating the string was not found. If the string was found, the user has the option to change the highlighted occurrence or all occurrences.

The DtEditorFind(3) and DtEditorChange(3) functions provide a programmatic interface to the find and change functionality of the DtEditor widget.

The Spell dialog is used to check the contents of the edit window for spelling errors. It consists of a list of misspelled words, replacement string field and the same set of buttons as the Find dialog. Choosing a word from the list automatically selects it as the find string. Double-clicking on a word searches for the next occurrence of that word. The list of misspelled words is automatically generated using the filter specified by DtNspellFilter when the dialog is displayed. The actions for find, change to and change all are the same as the Find dialog.

The Format Settings dialog for the DtEditor widget enables users to format the contents of the edit window, format just the paragraph containing the insertion cursor, or specify the arguments used when formatting text. The arguments include margin settings and text alignment. The user has the choice of aligning the text flush with the left or right margin, centering each line of text between the margins, or aligning it flush with both margins. The user enter the left and right margin values into text fields and choose an alignment option from a set of toggle buttons. Two push buttons allow them to format the current paragraph or format the complete document.

The margin values used for formatting do not have to be the same as the width of the edit window. It is possible to format the text with margin values that are narrower or wider than the displayed edit window. By default, values for the format margins are the current size of the edit window. If text is formatted wider than the edit window and the DtNwordWrap resource is True, text wraps at the right edge of the edit window (see the description for DtNwordWrap), regardless of the right margin setting. To format text wider than the edit window, DtNwordWrap should be False.

The DtEditorFormat(3) function provides a programmatic interface to the format functionality of the DtEditor widget.

  Word Wrap and Formatting

Word wrap and text formatting are essentially independent operations. Word wrap pertains to the dynamic display of lines, as delimited by <newline> characters, which exceed the width of the Text Editor window and is based on the left and right window boundaries. When word wrap mode is off (the default), each line of text is displayed on a single line on the display and text entered at the right window boundary causes the window to scroll automatically to the right to accommodate the new text until an actual <newline> character is entered (normally, by pressing the Return key). When word wrap mode is on, lines longer than the window width are automatically wrapped at the right window margin to one or more display lines, and text entered at the right window boundary is automatically broken on a word boundary to the first column of the next display line. Word wrap is dynamic in that word-wrapped lines are automatically adjusted when text is inserted or deleted or when the window is resized. Word wrap only affects the display of lines; it does not actually insert <newline> characters in the text.

Text formatting is a static operation that inserts actual <newline> (and/or <space>) characters directly in the text to match it to the left and right margins (and justification mode) specified in the Format Settings dialog. Format settings affect text only when explicitly applied and have no affect on word wrap or previously formatted text. Initially, and whenever the window is resized, the right format margin is automatically set to the window width to match the word wrap boundary.

  Classes

The DtEditor widget inherits behavior and resources from Core, Composite, Constraint, XmManager, XmBulletinBoard and XmForm classes.

The class pointer is dtEditorWidgetClass.

The class name is DtEditorWidget.

  New Resources

The following table defines a set of widget resources the application uses to specify data. The application can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, the application must remove the DtN or DtC prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, the application must remove the Dt prefix and use the remaining letters (in either lower case or upper case, but including any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A).
DtEditor Resource
Set
NameClassTypeDefaultAccess
DtNautoShowCursorPositionDtCAutoShowCursorPositionBooleanTrueCSG
DtNblinkRateDtCBlinkRateint500CSG
DtNbuttonFontListDtCFontListXmFontListdynamicCSG
DtNcolumnsDtCColumnsXmNcolumnsdynamicCSG
DtNcursorPositionDtCCursorPositionXmTextPosition0CSG
DtNcursorPositionVisibleDtCCursorPositionVisibleBooleanTrueCSG
DtNdialogTitleDtCDialogTitleXmStringNULLCSG
DtNeditableDtCEditableBooleanTrueCSG
DtNlabelFontListDtCFontListXmFontListdynamicCSG
DtNmaxLengthDtCMaxLengthintlargest integerCSG
DtNoverstrikeDtCOverstrikeBooleanFalseCSG
DtNrowsDtCRowsXmNrowsdynamicCSG
DtNscrollHorizontalDtCScrollBooleanTrueCG
DtNscrollLeftSideDtCScrollSideBooleandynamicCG
DtNscrollTopSideDtCScrollSideBooleanFalseCG
DtNscrollVerticalDtCScrollBooleanTrueCG
DtNshowStatusLineDtCShowStatusLineBooleanFalseCSG
DtNspellFilterDtCspellFilterchar *spellCSG
DtNtextBackgroundDtCBackgroundPixeldynamicCSG
DtNtextDeselectCallbackDtCCallbackXtCallbackListNULLC
DtNtextFontListDtCFontListXmFontListdynamicCSG
DtNtextForegroundDtCForegroundPixeldynamicCSG
DtNtextSelectCallbackDtCCallbackXtCallbackListNULLC
DtNtextTranslationsDtCTranslationsXtTranslationsNULLCS
DtNtopCharacterDtCTextPositionXmTextPosition0CSG
DtNwordWrapDtCWordWrapBooleanFalseCSG
tgroup dispwid="7.87in"Caret

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 DtEditor widget may scroll in order to bring the insertion point into the window.

DtNblinkRate
    Specifies the blink rate of the text cursor in milliseconds. The time indicated in the blink rate relates to the time the cursor is visible and the time the cursor is invisible (that is, the time it takes to blink the insertion cursor on and off is twice the blink rate). The cursor does not blink when the blink rate is set to zero. The value cannot be negative.

DtNbuttonFontList
    Specifies the font list used for the DtEditor buttons (the buttons appearing in the DtEditor dialogs). If this value is NULL at initialization, it is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard, VendorShell or XmMenuShell widget class. If such an ancestor is found, the font list is initialized to the appropriate default font list of the ancestor widget ( XmNdefaultFontList for VendorShell and XmMenuShell, and XmNbuttonFontList for XmBulletinBoard ). If no such ancestor is found, the default is implementation dependent. Refer to XmFontList(3) for more information on the creation and structure of a font list.

DtNcolumns
    Specifies the initial width of the edit window of the DtEditor widget as an integral number of characters. The width equals the number of characters this resource specifies multiplied by the maximum character width of the associated font. For proportionate fonts, the actual number of characters that fit on a given line may be greater than the value specified. The value must be greater than zero. The default value depends on the value of the DtNwidth resource.

DtNcursorPosition
    Indicates the position in the DtEditor widget where the current insert cursor is located. This position is determined by the number of characters from the beginning of the text. The first character position is zero.

DtNcursorPositionVisible
    When set to True, this resource specifies that the insert cursor position is marked by a blinking text cursor.

DtNdialogTitle
    Specifies an XmString that appears as part of the titles for the dialogs displayed by the DtEditor widget. If this resource is non- NULL, it is used as the prefix of the titles for the Find/Change, Spell and Format Settings dialogs.

DtNeditable
    When set to True, this resource indicates that the user can edit the text; otherwise, it prohibits the user from editing the text.

DtNlabelFontList
    Specifies the font list used for the labels for DtEditor (the labels appear in the status line and the DtEditor dialogs). If this value is NULL at initialization, it is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard, VendorShell or XmMenuShell widget class. If such an ancestor is found, the font list is initialized to the XmNlabelFontList of the ancestor widget. If no such ancestor is found, the default is implementation dependent. Refer to XmFontList(3) for more information on the creation and structure of a font list.

DtNmaxLength
    Specifies the maximum length of the text string that can be entered into the DtEditor widget from the keyboard. This value must be non-negative. Strings entered using the DtEditorSetContents(3) or DtEditorSetContentsFromFile(3) functions ignore this resource.

DtNoverstrike
    When set to False, characters typed into the DtEditor widget are inserted at the position of the insertion cursor. This is the default behavior. If set to True, characters typed into the DtEditor 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, DtNoverstrikeIndicatorLabel appears in the status line whenever DtNoverstrike is True.

DtNrows
    Specifies the initial height of the edit window of the DtEditor widget measured in character heights. The value must be greater than zero.

DtNscrollHorizontal
    When set to True, this resource adds a ScrollBar that allows the user to scroll horizontally through text.

DtNscrollLeftSide
    When set to True, this resource indicates that the vertical ScrollBar should be placed on the left side of the scrolled edit window. This attribute is ignored if DtNscrollVertical is False. The default value may depend on the value of the XmNstringDirection resource.

DtNscrollTopSide
    When set to True, this resource indicates that the horizontal ScrollBar should be placed on the top side of the scrolled edit window. This attribute is ignored if DtNscrollHorizontal is False.

DtNscrollVertical
    When set to True, this resource adds a ScrollBar that allows the user to scroll vertically through text.

DtNshowStatusLine
    When set to True, the DtEditor widget displays a status line below the edit window. 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 DtEditor widget is in overstrike mode. The user can enter a line number in the line number display to go directly to that line.

    The status line also includes a Motif Text Field widget (XmTextField) for displaying application supplied messages. This field is a convenient way for an application to display status and feedback about the document being edited. The Text Field ID 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, it can be unmanaged by calling XtUnmanageWidget(3) with its ID.

DtNspellFilter
    Specifies the filter used to identify spelling errors. The DtEditorInvokeSpellDialog(3) function filters the contents of a DtEditor widget 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 standard out. The default filter is spell(1).

DtNtextBackground
    Specifies the background of the edit window and the text fields for DtEditor (the text fields appear in the status line and DtEditor dialogs).

DtNtextDeselectCallback
    Specifies a function called whenever the selection becomes NULL (that is, 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 edit window and the text fields for DtEditor (the text fields appear in the status line and DtEditor dialogs). If this value is NULL at initialization, it is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard or VendorShell widget class. If such an ancestor is found, the font list is initialized to the XmNtextFontList of the ancestor widget. If no such ancestor is found, the default is implementation dependent. Refer to XmFontList(3) for more information on the creation and structure of a font list.

DtNtextForeground
    Specifies the foreground of the edit window and the text fields for DtEditor (the text fields appear in the status line and DtEditor dialogs).

DtNtextSelectCallback
    Specifies a function called whenever the selection becomes non-NULL (that is, some text is selected within the edit area). The reason sent by the callback is DtEDITOR_TEXT_SELECT.

DtNtextTranslations
    Adds translations to the edit window. Translations specified with DtNtextTranslations override any duplicate translations defined for the edit window.

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 DtEditor widget without shifting the text left or right. The position is determined by the number of characters from the beginning of the text. The first character position is zero.

    XtGetValues(3) for DtNtopCharacter returns the position of the first character in the line that is displayed at the top of the DtEditor widget.

DtNwordWrap
    Indicates that text not go off the right edge of the window, but that lines are broken at word breaks with soft line feeds when they reach the right edge of the window.

    Word wrap affects only the visual appearance of the contents of a DtEditor widget. The line breaks (soft line feeds) are not physically inserted into the text. The DtEditor widget supports substituting <newline>s when the contents of the widget are retrieved or saved to a file (see DtEditorGetContents(3) and DtEditorSaveContentsToFile(3)).

  Localization Resources

The following table defines a set of widget resources designed for localization of the DtEditor widget and its dialogs. Default values for these resources depends on the locale.
DtEditor
Localization Resource Set
NameClassTypeDefaultAccess
DtNcenterToggleLabelDtCCenterToggleLabelXmStringDynamicCSG
DtNchangeAllButtonLabelDtCChangeAllButtonLabelXmStringDynamicCSG
DtNchangeButtonLabelDtCChangeButtonLabelXmStringDynamicCSG
DtNchangeFieldLabelDtCChangeFieldLabelXmStringDynamicCSG
DtNcurrentLineLabelDtCCurrentLineLabelXmStringDynamicCSG
DtNfindButtonLabelDtCFindButtonLabelXmStringDynamicCSG
DtNfindChangeDialogTitleDtCFindChangeDialogTitleXmStringDynamicCSG
DtNfindFieldLabelDtCFindFieldLabelXmStringDynamicCSG
DtNformatAllButtonLabelDtCFormatAllButtonLabelXmStringDynamicCSG
DtNformatParagraphButtonLabelDtCFormatParagraphButtonLabelXmStringDynamicCSG
DtNformatSettingsDialogTitleDtCFormatSettingsDialogTitleXmStringDynamicCSG
DtNinformationDialogTitleDtCInformationDialogTitleXmStringDynamicCSG
DtNjustifyToggleLabelDtCJustifyToggleLabelXmStringDynamicCSG
DtNleftAlignToggleLabelDtCLeftAlignToggleLabelXmStringDynamicCSG
DtNleftMarginFieldLabelDtCLeftMarginFieldLabelXmStringDynamicCSG
DtNmisspelledListLabelDtCMisspelledListLabelXmStringDynamicCSG
DtNoverstrikeLabelDtCOverstrikeLabelXmStringDynamicCSG
DtNrightAlignToggleLabelDtCRightAlignToggleLabelXmStringDynamicCSG
DtNrightMarginFieldLabelDtCRightMarginFieldLabelXmStringDynamicCSG
DtNspellDialogTitleDtCSpellDialogTitleXmStringDynamicCSG
DtNtotalLineCountLabelDtCTotalLineCountLabelXmStringDynamicCSG
tgroup dispwid="7.46in"

DtNcenterToggleLabel
    Specifies the label for the center alignment toggle button in the Format Settings dialog. The default value in the C locale is Center.

DtNchangeAllButtonLabel
    Specifies the label for the button in the Find/Change and Spell dialogs that change 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 and Spell dialogs that change 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 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 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. If DtNdialogTitle is non- NULL, it is added as a prefix to 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 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 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 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. If DtNdialogTitle is non- NULL, it is added as a prefix to this resource to form the title. The default value in the C locale is Format Settings.

DtNinformationDialogTitle
    Specifies the title for the Information dialog used to present feedback and general information to the user. If DtNdialogTitle is non- NULL, it is added as a prefix to 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. The default value in the C locale is Justify.

DtNleftAlignToggleLabel
    Specifies the label for the left alignment toggle button in the Format Settings dialog. 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. 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. The default value in the C locale is Misspelled Words:.

DtNoverstrikeLabel
    Specifies the label in the status line that indicates that the DtEditor widget 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. 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. The default value in the C locale is Right Margin:.

DtNspellDialogTitle
    Specifies the title for the Spell dialog. If DtNdialogTitle is non- NULL, it is added as a prefix to this resource to form the title. The default value in the C locale is Spell.

DtNtotalLineCountLabel
    Specifies the label for the display showing the total number of lines in the document. The total number of lines displayed is part of the status line. The default value in the C locale is Total:.

  Inherited Resources

The DtEditor widget inherits behavior and resources from the following named superclasses. For a complete description of each resource, see the man page for that superclass.
XmForm Resource
Set
NameClassTypeDefaultAccess
XmNfractionBaseXmCMaxValueint100CSG
XmNhorizontalSpacingXmCSpacingDimension0CSG
XmNrubberPositioningXmCRubberPositioningBooleanFalseCSG
XmNverticalSpacingXmCSpacingDimension0CSG
tgroup dispwid="7.60in"
XmBulletinBoard
Resource Set
NameClassTypeDefaultAccess
XmNallowOverlapXmCAllowOverlapBooleanTrueCSG
XmNautoUnmanageXmCAutoUnmanageBooleanTrueCG
XmNbuttonFontListXmCButtonFontListXmFontListdynamicCSG
XmNcancelButtonXmCWidgetWindowNULLSG
XmNdefaultButtonXmCWidgetWindowSG
XmNdefaultPositionXmCDefaultPositionBooleanTrueCSG
XmNdialogStyleXmCDialogStyleunsigned chardynamicCSG
XmNdialogTitleXmCDialogTitleXmStringNULLCSG
XmNfocusCallbackXmCCallbackXtCallbackListNULLC
XmNlabelFontListXmCLabelFontListkXmFontListdynamicCSG
XmNmapCallbackXmCCallbackXtCallbackListNULLC
XmNmarginHeightXmCMarginHeightDimension10CSG
XmNmarginWidthXmCMarginWidthDimension10CSG
XmNnoResizeXmCNoResizeBooleanFalseCSG
XmNresizePolicyXmCResizePolicyunsigned charXmRESIZE_ANYCSG
XmNshadowTypeXmCShadowTypeunsigned charXmSHADOW_OUTCSG
XmNtextFontListXmCTextFontListXmFontListdynamicCSG
XmNtextTranslationsXmCTranslationsXtTranslationsNULLC
XmNunmapCallbackXmCCallbackXtCallbackListNULLC
tgroup dispwid="7.73in"
XmManager Resource
Set
NameClassTypeDefaultAccess
XmNbottomShadowColorXmCBottomShadowColorPixeldynamicCSG
XmNbottomShadowPixmapXmCBottomShadowPixmapPixmapXmUNSPECIFIED_PIXMAPCSG
XmNforegroundXmCForegroundPixeldynamicCSG
XmNhelpCallbackXmCCallbackXtCallbackListNULLC
XmNhighlightColorXmCHighlightColorPixeldynamicCSG
XmNhighlightPixmapXmCHighlightPixmapPixmapdynamicCSG
XmNinitialFocusXmCInitialFocusWidgetNULLCSG
XmNnavigationTypeXmCNavigationTypeXmNavigationTypedynamicCSG
XmNshadowThicknessXmCShadowThicknessDimensiondynamicCSG
XmNstringDirectionXmCStringDirectionXmStringDynamicdynamicCG
XmNtopShadowColorXmCTopShadowColorPixeldynamicCSG
XmNtopShadowPixmapXmCTopShadowPixmapPixmapdynamicCSG
XmNtraversalOnXmCTraversalOnBooleandynamicCSG
XmNunitTypeXmCUnitTypeunsigned chardynamicCSG
XmNuserDataXmCUserDataXtPointerNULLCSG
tgroup dispwid="7.82in"
Composite Resource
Set
NameClassTypeDefaultAccess
XmNchildrenXmCReadOnlyWidgetListNULLG
XmNinsertPositionXmCInsertPositionXtOrderProcdefault procedureCSG
XmNnumChildrenXmCReadOnlyCardinal0G
tgroup dispwid="7.46in"
Core Resource Set
NameClassTypeDefaultAccess
XmNacceleratorsXmCAcceleratorsXtAcceleratorsdynamicCSG
XmNancestorSensitiveXmCSensitiveBooleandynamicG
XmNbackgroundXmCBackgroundPixeldynamicCSG
XmNbackgroundPixmapXmCPixmapPixmapXmUNSPECIFIED_PIXMAPCSG
XmNborderColorXmCBorderColorPixelXtDefaultForegroundCSG
XmNborderPixmapXmCPixmapPixmapXmUNSPECIFIED_PIXMAPCSG
XmNborderWidthXmCBorderWidthDimension0CSG
XmNcolormapXmCColormapColormapdynamicCG
XmNdepthXmCDepthintdynamicCG
XmNdestroyCallbackXmCCallbackXtCallbackListNULLC
XmNheightXmCHeightDimensiondynamicCSG
XmNinitialResourcesPersistentXmCInitialResourcesPersistentBooleanTrueC
XmNmappedWhenManagedXmCMappedWhenManagedBooleanTrueCSG
XmNscreenXmCScreenScreen *dynamicCG
XmNsensitiveXmCSensitiveBooleanTrueCSG
XmNtranslationsXmCTranslationsXtTranslationsdynamicCSG
XmNwidthXmCWidthDimensiondynamicCSG
XmNxXmCPositionPosition0CSG
XmNyXmCPositionPosition0CSG
tgroup dispwid="7.91in"

  Callback Information

The DtEditor widget has three callback functions of interest:

DtNtextSelectCallback
    and DtNtextDeselectCallback" 10 The DtNtextSelectCallback and DtNtextDeselectCallback resources allow an application to enable and disable certain commands or menu items based on whether there is a selection. DtNtextSelectCallback specifies a function called whenever the selection becomes non-NULL (that is, some text is selected within the edit window), while DtNtextDeselectCallback specifies a function called whenever the selection becomes NULL (that is, no text is selected within the edit window). The reasons sent by the callbacks are DtEDITOR_TEXT_SELECT and DtEDITOR_TEXT_DESELECT.

XmNhelpCallback
    An application that wishes to present help information to the user on the DtEditor widget and its dialogs should set the XmNhelpCallback resource and use the Reason field passed as part of DtEditorHelpCallbackStruct to set the contents of its Help dialog. A pointer to the following structure is passed to the XmNHelpCallback callback.

typedef struct {
        int reason,
        XEvent *event
} XmAnyCallbackStruct;

reason
    Indicates why the callback was invoked. The possible reasons are:

    DtEDITOR_HELP_EDIT_WINDOW
        The help request originated in the edit window.

    DtEDITOR_HELP_STATUS_LINE
        The help request originated in the status line.

    DtEDITOR_HELP_STATUS_CURRENT_LINE
        The help request originated in the Current Line number display in the status line.

    DtEDITOR_HELP_STATUS_TOTAL_LINES
        The help request originated in the Total Lines display in the status line.

    DtEDITOR_HELP_STATUS_MESSAGE
        The help request originated in the Message field in the status line.

    DtEDITOR_HELP_STATUS_OVERSTRIKE
        The help request originated in the Overstrike Indicator in the status line.

    DtEDITOR_HELP_FORMAT_DIALOG
        The help request originated in the Help button in the Format dialog.

    DtEDITOR_HELP_FORMAT_LEFT_MARGIN
        The help request originated in the Left Margin field in the Format dialog.

    DtEDITOR_HELP_FORMAT_RIGHT_MARGIN
        The help request originated in the Right Margin field in the Format dialog.

    DtEDITOR_HELP_FORMAT_ALIGNMENT
        The help request originated in the Alignment buttons in the Format dialog.

    DtEDITOR_HELP_CHANGE_DIALOG
        The help request originated in the Help button in the Find/Change dialog.

    DtEDITOR_HELP_CHANGE_FIND
        The help request originated in the Find field in the Find/Change dialog.

    DtEDITOR_HELP_CHANGE_CHANGE
        The help request originated in the Change To field in the Find/Change dialog.

    DtEDITOR_HELP_SPELL_DIALOG
        The help request originated in the help button in the Spell dialog.

    DtEDITOR_HELP_SPELL_MISSPELLED_WORDS
        The help request originated in the List of Misspelled Words in the Spell dialog.

    DtEDITOR_HELP_SPELL_CHANGE
        The help request originated in the Change To field in the Spell dialog.

event
    A pointer to the XEvent that caused this callback to be invoked. It may be NULL.

  Translations

The DtEditor widget translations for the edit window are described in the following list. The DtNtextTranslations resource can be used to modify these translations.

KLeft
    backward-character

MShift KLeft
    key-select

    (left)

MCtrl KLeft
    backward-word

MShift MCtrl KLeft
    backward-word

    (extend)

KRight
    forward-character

MShift KRight
    key-select

    (right)

MCtrl KRight
    forward-word

MShift MCtrl KRight
    forward-word

    (extend)

KUp process-up

MShift KUp
    process-shift-up

MCtrl KUp
    backward-paragraph

MShift MCtrl KUp
    backward-paragraph

    (extend)

KDown
    process-down

MShift KDown
    process-shift-down

MCtrl KDown
    forward-paragraph

MShift MCtrl KDown
    forward-paragraph

    (extend)

KBeginLine
    beginning-of-line

MShift KBeginLine
    beginning-of-line

    (extend)

KEndLine
    end-of-line

MShift KEndLine
    end-of-line

    (extend)

KPageUp
    previous-page

MShift KPageUp
    previous-page

    (extend)

KPageLeft
    page-left

KPageDown
    next-page

MShift KPageDown
    next-page

    (extend)

KPageRight
    page-right

KBeginData
    beginning-of-file

MShift KBeginData
    beginning-of-file

    (extend)

KEndData
    end-of-file

MShift KEndData
    end-of-file

    (extend)

KDelete
    delete-next-character

MCtrl KDelete
    delete-to-end-of-line

KBackSpace
    delete-previous-character

MCtrl KBackSpace
    delete-previous-word

MShift KBackSpace
    delete-to-start-of-line

MAlt KBackSpace
    undo-edit

MCtrl Kz
    undo-edit

MCtrl K/
    select-all

MCtrl K
    deselect-all

MCtrl Kg
    go-to-line

MCtrl Kq
    quote-next-character

MCtrl Kx
    cut-clipboard

MCtrl Kc
    copy-clipboard

MCtrl Kv
    paste-clipboard

KHelp
    Help

KInsert
    toggle-insert-mode

KEnter
    new-line-and-indent

MAnyKCancel
    process-cancel

  Action Routines

The DtEditor widget action routines are described here:

backward-character()
    This action moves the insertion cursor one character to the left. This action may have different behavior in a right-to-left language environment.

backward-paragraph(extend)
    If this action is called with no argument, it moves the insertion cursor to the first non-whitespace character following the first previous blank line or beginning of the text. If the insertion cursor is already at the beginning of a paragraph, the action moves the insertion cursor to the beginning of the previous paragraph.

    If this action is called with an argument of extend, it moves the insertion cursor, as in the case of no argument, and extends the current selection.

backward-word( extend)
    If this action is called with no argument, it moves the insertion cursor to the first non-whitespace character after the first whitespace character to the left or after the beginning of the line. If the insertion cursor is already at the beginning of a word, this action moves the insertion cursor to the beginning of the previous word. This action may have different behavior in a locale other than the C locale.

    If this action is called with an argument of extend, it moves the insertion cursor, as in the case of no argument, and extends the current selection.

beginning-of-file(extend)
    If this action is called with no argument, it moves the insertion cursor to the beginning of the text.

    If this action is called with an argument of extend, it moves the insertion cursor, as in the case of no argument, and extends the current selection.

beginning-of-line(extend)
    If this action is called with no argument, it moves the insertion cursor to the beginning of the line.

    If this action is called with an argument of extend, it moves the insertion cursor, as in the case of no argument, and extends the current selection.

clear-selection()
    This action clears the current selection by replacing each character except <carriage-return> with a <space> character.

copy-clipboard()
    This action copies the current selection to the clipboard.

cut-clipboard()
    This action cuts the current selection to the clipboard.

delete-next-character()
    If there is a non-NULL selection, this action deletes the selection; otherwise, it deletes the character following the insertion cursor.

delete-next-word()
    If there is a non-NULL selection, this action deletes the selection; otherwise, it deletes the characters following the insertion cursor to the next space, tab or end of line character.

delete-previous-character()
    If there is a non-NULL selection, this action deletes the selection; otherwise, it deletes the character of text immediately preceding the insertion cursor.

delete-previous-word()
    If there is a non-NULL selection, this action deletes the selection; otherwise, it deletes the characters preceding the insertion cursor to the next space, tab or beginning of the line character. This action may have different behavior in a locale other than the C locale.

delete-to-end-of-line()
    If there is a non-NULL selection, this action deletes the selection; otherwise, it deletes the characters following the insertion cursor to the next end-of-line character.

delete-to-start-of-line()
    If there is a non-NULL selection, this action deletes the selection; otherwise, it deletes the characters preceding the insertion cursor to the previous beginning-of-line character.

deselect-all()
    This action deselects the current selection.

end-of-file( extend)
    If this action is called with no argument, it moves the insertion cursor to the end of the text.

    If this action is called with an argument of extend, it moves the insertion cursor, as in the case of no argument, and extends the current selection.

end-of-line( extend)
    If this action is called with no argument, it moves the insertion cursor to the end of the line.

    If this action is called with an argument of extend, it moves the insertion cursor, as in the case of no argument, and extends the current selection.

forward-character()
    This action moves the insertion cursor one character to the right. This action may have different behavior in a right-to-left language environment.

forward-paragraph(extend)
    If this action is called with no argument, it moves the insertion cursor to the first non-whitespace character following the next blank line. If the insertion cursor is already at the beginning of a paragraph, this action moves the insertion cursor to the beginning of the next paragraph.

    If this action is called with an argument of extend, it moves the insertion cursor, as in the case of no argument, and extends the current selection.

forward-word( extend)
    If this action is called with no argument, it moves the insertion cursor to the first whitespace character or end-of-line following the next non-whitespace character. If the insertion cursor is already at the end of a word, this action moves the insertion cursor to the end of the next word. This action may have different behavior in a locale other than the C locale.

    If called with an argument of extend, this action moves the insertion cursor, as in the case of no argument, and extends the current selection.

go-to-line()
    This action moves the keyboard focus to the Current Line text field to allow the user to move the insertion cursor to a new line. This action is only valid if DtNshowStatusLine has a value of True. For a description of the status line, see the Editor Status Line heading in this manual page.

Help()
    This action calls the callbacks for XmNhelpCallback if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them.

insert-string( string)
    This action deletes the entire selection if there is a non-NULL selection and the cursor is not disjoint from it. It inserts string before the insertion cursor.

key-select( direction)
    If this action is called with an argument of right, it moves the insertion cursor one character to the right and extends the current selection. If this action is called with an argument of left, it moves the insertion cursor one character to the left and extends the current selection. If this action is called with no argument, it extends the current selection.

newline-and-backup()
    If there is a non-NULL selection and the cursor is not disjoint from it, this action deletes the entire selection, inserts a newline just before the insertion cursor and repositions the insertion cursor to the end of the line before the newline.

newline-and-indent()
    If there is a non-NULL selection and the cursor is not disjoint from it, this action deletes the entire selection, inserts a newline and then the same number of whitespace characters as at the beginning of the previous line.

next-page( extend)
    If this action is called with no argument, it moves the insertion cursor forward one page.

    If this action is called with an argument of extend, it moves the insertion cursor, as in the case of no argument, and extends the current selection.

page-left()
    This action scrolls the viewing window left one page of text.

page-right()
    This action scrolls the viewing window right one page of text.

paste-clipboard()
    This action pastes the contents of the clipboard before the insertion cursor.

previous-page( extend)
    If this action is called with no argument, it moves the insertion cursor back one page.

    If this action is called with an argument of extend, it moves the insertion cursor, as in the case of no argument, and extends the current selection.

process-cancel()
    This action cancels the current extend-adjust or secondary-adjust operation and leaves the selection state as it was before the operation; otherwise, (and if the parent is a manager) it passes the event to the parent.

process-down()
    This action moves the insertion cursor down one line.

process-shift-down()
    This action moves the insertion cursor down one line, extending the current selection.

process-shift-up()
    This action moves the insertion cursor up one line, extending the current selection.

process-up()
    This action moves the insertion cursor up one line.

select-all()
    Selects all text.

toggle-insert-mode()
    This action toggles the state of the text insertion mode. By default, characters typed into the DtEditor widget are inserted at the position of the insertion cursor. In overstrike mode, characters entered into the DtEditor widget replace the characters that directly follow the insertion cursor. In overstrike mode, characters are appended to the end of the line when the end of a line is reached.

quote-next-character()
    This action treats the next typed character as a special character and inserts it into the text without interpreting it. Enables the insertion of special instructional characters or special language characters, such as the character marking a form feed or the umlaut used in German text.

undo-edit()
    This action undoes the last change (deletion or insertion) made to the text. A change consists of either a set of consecutive insertions, or a set of consecutive deletions followed by up to one set of consecutive insertions. An insertion is consecutive if there have been no intervening deletions, and it is continuing forward from the same point. A deletion is consecutive if there have been no intervening insertions, and its start or end position is coincidental with the last deletion (that is, the deletion is continuing from the same point, either forward or backward). Undoing an edit once restores the original text. Undoing an edit twice restores the last change.

  Convenience Functions

The Widget Library contains a number of functions that apply to the DtEditor widget. The following lists summarize these functions.

  DtEditor Life Cycle Functions

DtCreateEditor()
    Creates a new instance of a DtEditor widget.

DtEditorReset()
    Restores a DtEditor widget to its initial state.

  DtEditor Input/Output Functions

DtEditorAppend()
    Appends content data to the end of a DtEditor widget.

DtEditorAppendFromFile()
    Appends the contents of a file to the end of a DtEditor widget.

DtEditorGetContents()
    Retrieves the entire contents of a DtEditor 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 a DtEditor widget, replacing the entire contents of the widget.

DtEditorSetContentsFromFile()
    Loads the contents of a file into a DtEditor widget, replacing the entire contents of the widget.

  DtEditor Selection Functions

DtEditorClearSelection()
    Replaces the currently selected contents with blanks.

DtEditorCopyToClipboard()
    Copies the currently selected contents to the clipboard.

DtEditorCutToClipboard()
    Removes the currently selected contents, placing it on the clipboard.

DtEditorDeleteSelection()
    Removes the currently selected contents.

DtEditorDeselect()
    Deselects any selected contents.

DtEditorPasteFromClipboard()
    Pastes the contents of the clipboard into a DtEditor widget, replacing any currently selected contents.

DtEditorSelectAll()
    Selects the entire contents of a DtEditor widget.

  DtEditor Format Functions

DtEditorFormat()
    Formats the contents of all or part of a DtEditor widget.

DtEditorInvokeFormatDialog()
    Displays the format dialog that enables the user to specify format settings for margins and justification style and to perform formatting operations.

  DtEditor Find and Change Text Functions

DtEditorChange()
    Changes one or all occurrences of a string.

DtEditorFind()
    Finds the next occurrence of a string.

DtEditorInvokeFindChangeDialog()
    Displays the dialog that enables the user to search for, and optionally change, a string.

DtEditorInvokeSpellDialog()
    Displays a dialog with a list of misspelled words in the current contents.

  DtEditor Auxiliary Functions

DtEditorDisableRedisplay()
    Temporarily prevents visual update of a DtEditor widget.

DtEditorEnableRedisplay()
    Forces the visual update of a DtEditor widget.

DtEditorCheckForUnsavedChanges()
    Reports whether the contents of a DtEditor widget have been altered since they were last retrieved or saved.

DtEditorGetInsertionPosition()
    Returns the insertion cursor position of a DtEditor 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 a DtEditor widget.

DtEditorGoToLine()
    Moves the insert cursor to the specified line.

DtEditorSetInsertionPosition()
    Sets the position of the insertion cursor.

DtEditorTraverseToEditor()
    Sets keyboard traversal to the edit window of a DtEditor widget.

DtEditorUndoEdit()
    Undoes the last edit made by a user.

FILES

/usr/pkg/dt/lib/nls/msg/$LANG/DtWidget.cat()
    Message catalog for DtWidget library.

SEE ALSO

Dt/Editor.h - DtEditor(5), DtCreateEditor(3), DtEditorAppend(3), DtEditorAppendFromFile(3), DtEditorChange(3), DtEditorCheckForUnsavedChanges(3), DtEditorClearSelection(3), DtEditorCopyToClipboard(3), DtEditorCutToClipboard(3), DtEditorDeleteSelection(3), DtEditorDeselect(3), DtEditorDisableRedisplay(3), DtEditorEnableRedisplay(3), DtEditorFind(3), DtEditorFormat(3), DtEditorGetContents(3), DtEditorGetInsertionPosition(3), DtEditorGetLastPosition(3), DtEditorGetMessageTextFieldID(3), DtEditorGetSizeHints(3), DtEditorGoToLine(3), DtEditorInsert(3), DtEditorInsertFromFile(3), DtEditorInvokeFindChangeDialog(3), DtEditorInvokeFormatDialog(3), DtEditorInvokeSpellDialog(3), DtEditorPasteFromClipboard(3), DtEditorReplace(3), DtEditorReplaceFromFile(3), DtEditorReset(3), DtEditorSaveContentsToFile(3), DtEditorSelectAll(3), DtEditorSetContents(3), DtEditorSetContentsFromFile(3), DtEditorSetInsertionPosition(3), DtEditorTraverseToEditor(3), DtEditorUndoEdit(3); Composite(3), Constraint(3), Core(3), XmBulletinBoard(3), XmFontList(3), XmForm(3), XmManager(3), XmTextField(3).