Dt/Editor.h(file formats)                         Dt/Editor.h(file formats)




 NAME    [Toc]    [Back]
      Dt/Editor.h - editor widget definitions

 SYNOPSIS    [Toc]    [Back]
      #include <Dt/Editor.h>

 DESCRIPTION    [Toc]    [Back]
      The Dt/Editor.h header defines structures, enumerations and function
      prototypes for the Editor widget class.

      The header defines the DtEditorDataFormat enumeration data type, with
      at least the following members:

      DtEDITOR_TEXT
                The data being transferred is a pointer to a NULL-terminated
                string of characters (a char *).

      DtEDITOR_WCHAR
                The data being transferred is a wide character string (a
                wchar_t *).

      DtEDITOR_DATA
                The data being transferred is a sized buffer (a
                DtEditor_DataObj).

      The header defines the following structure:

      typedef struct {
              unsigned int length;
              void *buf;
      } DtEditor_DataObj;

      The length argument is the size in bytes of the data buffer.  The buf
      argument is a pointer to the data buffer.

      The DtEditorContentRec structure is used to transfer data between an
      application and Editor widget.  It indicates the type of data being
      transferred along with the actual data.

      typedef struct {
              DtEditorDataFormat type;
              union {
                      char *string;
                      wchar_t *wchar;
                      DtEditor_DataObj data;
              } value;
      } DtEditorContentRec;

      The type argument indicates the type of data contained in the
      structure.  The string argument points to a NULL-terminated string of
      characters.  It is valid when type is DtEDITOR_TEXT. The wchar



                                    - 1 -       Formatted:  January 24, 2005






 Dt/Editor.h(file formats)                         Dt/Editor.h(file formats)




      argument points to a wide character string.  It is valid when type is
      DtEDITOR_WCHAR. The data argument is a DtEditor_DataObj that contains
      the size of the data and a pointer to it.  It is valid when type is
      DtEDITOR_DATA.

      The DtEditorChangeValues structure is used optionally to specify the
      string to search for and its replacement value for DtEditorChange(3).

      typedef struct {
              char *find,
              char *changeTo,
      } DtEditorChangeValues;

      The find argument is a text string to locate in an DtEditor widget.
      The changeTo argument is the replacement string for the one or more
      occurrences of the string specified in find. It can be NULL.

      The DtEditorFormatSettings structure is used to optionally specify the
      left margin setting, right margin setting, and alignment style for
      DtEditorFormat(3).

      typedef struct {
              int leftMargin,
              int rightMargin,
              unsigned int alignment,
      } DtEditorFormatSettings;

      The leftMargin argument is the column number of the left boundary when
      formatting text.  Text is not extended to the left of this column.  It
      must be non-negative.  The rightMargin argument is the column number
      of the right boundary when formatting text.  Text is not extended to
      the right of this column.  It must be larger than leftMargin. The
      alignment argument specifies the style of alignment when formatting
      text (see the constants listed in this header).

      The header declares the following variable:

      WidgetClass      dtEditorWidgetClass;

      The header defines the following constants for use with the
      DtEditorChange(3) function:

      DtEDITOR_ALL_OCCURRENCES
                Change all instances of the find string.

      DtEDITOR_CURRENT_SELECTION
                Replace the currently selected text with the replacement
                string.

      DtEDITOR_NEXT_OCCURRENCE
                Change the next occurrence of the find string after the



                                    - 2 -       Formatted:  January 24, 2005






 Dt/Editor.h(file formats)                         Dt/Editor.h(file formats)




                insertion cursor.

      The header defines the following constants for use with the
      DtEditorFormat(3) function:

      DtEDITOR_FORMAT_ALL
                Reformats all the text in a DtEditor.

      DtEDITOR_FORMAT_PARAGRAPH
                Reformats only the paragraph containing the insertion
                cursor.

      DtEDITOR_ALIGN_CENTER
                Centers each line of text between the left and right
                margins.

      DtEDITOR_ALIGN_JUSTIFY
                Aligns the text flush with both the left and right margins.

      DtEDITOR_ALIGN_LEFT
                Aligns the text flush with the left margin.

      DtEDITOR_ALIGN_RIGHT
                Aligns the text flush with the right margin.

      The header defines the following constant for use with the
      DtEditorGoToLine(3) function:

      DtEDITOR_LAST_LINE
                Moves the cursor to the beginning of the last line in the
                widget.

      The header defines the following DtEditorErrorCode constants:

      DtEDITOR_NO_ERRORS
                The function completed its task without errors.

      DtEDITOR_INSUFFICIENT_MEMORY
                Not enough system memory is available to complete the task.

      DtEDITOR_INVALID_TYPE
                The specified type is not a recognized DtEditorDataFormat
                when setting or retrieving contents or the specified
                Alignment type is not recognized when formatting text.

      DtEDITOR_INVALID_RANGE
                The starting character position in a text replacement is
                greater than the ending character position or the specified
                Amount To Format when formatting text is not recognized.





                                    - 3 -       Formatted:  January 24, 2005






 Dt/Editor.h(file formats)                         Dt/Editor.h(file formats)




      DtEDITOR_NULL_ITEM
                The data buffer is NULL when passing data in a buffer.

      DtEDITOR_ILLEGAL_SIZE
                The specified size of a data buffer is negative when passing
                data in a buffer, or the left and right margin values are
                illegal when formatting text.

      DtEDITOR_SPELL_FILTER_FAILED
                The DtEditor function cannot successfully execute the filter
                specified by the DtNspellFilter resource.

      DtEDITOR_NO_TMP_FILE
                The DtEditor function cannot create a temporary file in the
                directory returned by tmpnam3S.

      DtEDITOR_INVALID_FILENAME
                No file was specified.

      DtEDITOR_NONEXISTENT_FILE
                The file specified for reading does not exist.

      DtEDITOR_UNREADABLE_FILE
                The file specified is unreadable for an unspecified reason.

      DtEDITOR_READ_ONLY_FILE
                The file is read only.

      DtEDITOR_NULLS_REMOVED
                The file contained embedded NULL characters, which were
                removed.

      DtEDITOR_NO_FILE_ACCESS
                The file cannot be accessed.

      DtEDITOR_DIRECTORY
                The file specified is a directory.

      DtEDITOR_CHAR_SPECIAL_FILE
                The file specified is a character-special device.

      DtEDITOR_BLOCK_MODE_FILE
                The file specified is a block-mode device.

      DtEDITOR_UNWRITABLE_FILE
                The application does not have write permission for the file
                or directory.

      DtEDITOR_WRITABLE_FILE
                The specified file exists and the overwriteIfExists flag is
                set to False.



                                    - 4 -       Formatted:  January 24, 2005






 Dt/Editor.h(file formats)                         Dt/Editor.h(file formats)




      DtEDITOR_SAVE_FAILED
                The contents of the widget could not be saved for an
                unspecified reason.

      The header defines the following enumeration values as reasons for the
      DtNtextSelectCallback:

      DtEDITOR_TEXT_SELECT
                Some text has been selected within the edit window (that is,
                the selection has become non- NULL).

      DtEDITOR_TEXT_DESELECT
                No text is selected within the edit window (that is, the
                selection has become NULL).

      The header defines the following constants as reasons for the
      XmNhelpCallback:

      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 from the Current Line Number
                display in the status line.

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

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

      DtEDITOR_HELP_STATUS_OVERSTRIKE
                The help request originated from the Overstrike indicator in
                the status line.

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

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

      DtEDITOR_HELP_FORMAT_RIGHT_MARGIN
                The help request originated from the Right Margin Field in
                the Format Settings dialog.



                                    - 5 -       Formatted:  January 24, 2005






 Dt/Editor.h(file formats)                         Dt/Editor.h(file formats)




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

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

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

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

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

      DtEDITOR_HELP_SPELL_MISSPELLED_WORDS
                The help request originated from the list of misspelled
                words in the Spell dialog.

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

      The header defines the following as functions:

      Widget DtCreateEditor(Widget parent,
              char *name,
              ArgList arglist,
              Cardinal argcount);

      DtEditorErrorCode DtEditorAppend(Widget widget,
              DtEditorContentRec *data);

      DtEditorErrorCode DtEditorAppendFromFile(Widget widget,
              char *fileName);

      Boolean DtEditorChange(Widget widget,
              DtEditorChangeValues *findChangeStrings,
              unsigned int instanceToChange);

      Boolean DtEditorCheckForUnsavedChanges(Widget widget);

      Boolean DtEditorClearSelection(Widget widget);

      Boolean DtEditorCopyToClipboard(Widget widget);




                                    - 6 -       Formatted:  January 24, 2005






 Dt/Editor.h(file formats)                         Dt/Editor.h(file formats)




      Boolean DtEditorCutToClipboard(Widget widget);

      Boolean DtEditorDeleteSelection(Widget widget);

      Boolean DtEditorDeselect(Widget widget);

      void DtEditorDisableRedisplay(Widget widget);

      void DtEditorEnableRedisplay(Widget widget);

      Boolean DtEditorFind(Widget widget,
              char * find);

      DtEditorErrorCode DtEditorFormat(Widget widget,
              DtEditorFormatSettings *formatSettings,
              unsigned int amountToFormat);

      DtEditorErrorCode DtEditorGetContents(Widget widget,
              DtEditorContentRec *data,
              Boolean hardCarriageReturns,
              Boolean markContentsAsSaved);

      XmTextPosition DtEditorGetInsertionPosition(Widget widget);

      XmTextPosition DtEditorGetLastPosition(Widget widget);

      Widget DtEditorGetMessageTextFieldID(Widget widget);

      void DtEditorGetSizeHints(Widget widget,
              XSizeHints *pHints);

      void DtEditorGoToLine(Widget widget,
              int lineNumber);

      DtEditorErrorCode DtEditorInsert(Widget widget,
              DtEditorContentRec *data);

      DtEditorErrorCode DtEditorInsertFromFile(Widget widget,
              char *fileName);

      void DtEditorInvokeFindChangeDialog(Widget widget);

      void DtEditorInvokeFormatDialog(Widget widget);

      DtEditorErrorCode DtEditorInvokeSpellDialog(Widget widget);

      Boolean DtEditorPasteFromClipboard(Widget widget);

      DtEditorErrorCode DtEditorReplace(Widget widget,
              XmTextPosition startPos,
              XmTextPosition endPos,



                                    - 7 -       Formatted:  January 24, 2005






 Dt/Editor.h(file formats)                         Dt/Editor.h(file formats)




              DtEditorContentRec *data);

      DtEditorErrorCode DtEditorReplaceFromFile(Widget widget,
              XmTextPosition startPos,
              XmTextPosition endPos,
              char *fileName);

      void DtEditorReset(Widget widget);

      DtEditorErrorCode DtEditorSaveContentsToFile(Widget widget,
              char *fileName,
              Boolean overwriteIfExists,
              Boolean hardCarriageReturns,
              Boolean markContentsAsSaved);

      Boolean DtEditorSelectAll(Widget widget);

      DtEditorErrorCode DtEditorSetContents(Widget widget,
              DtEditorContentRec *data);

      DtEditorErrorCode DtEditorSetContentsFromFile(Widget widget,
              char *fileName);

      void DtEditorSetInsertionPosition(Widget widget,
                      XmTextPosition position);

      void DtEditorTraverseToEditor(Widget widget);

      Boolean DtEditorUndoEdit(Widget widget);

 SEE ALSO    [Toc]    [Back]
      DtCreateEditor(3), DtEditor(3), DtEditorAppend(3),
      DtEditorAppendFromFile(3), DtEditorChange(3),
      DtEditorCheckForUnsavedChanges(3), DtEditorClearSelection(3),
      DtEditorCopyToClipboard(3), DtEditorCutToClipboard(3),
      DtEditorDeleteSelection(3), DtEditorDeselect(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).


                                    - 8 -       Formatted:  January 24, 2005