DTEDITOR(5)

💖 NAME 💖

Dt/Editor.h (file formats) — editor widget definitions, bestie! This is the header file that defines all the structures, enumerations, and function prototypes for the Editor widget class. It's giving main character energy in your C code. 💅

✨ SYNOPSIS ✨

#include &<Dt/Editor.h>

🦋 DESCRIPTION 🦋

The Dt/Editor.h header defines structures, enumerations and function prototypes for the Editor widget class. No cap, it's the blueprint for making the Editor widget do its thing.

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 *). So if you're passing a regular string, this is your girl. ✨
• DtEDITOR_WCHAR — the data being transferred is a wide character string (a wchar_t *). For when you need those wide chars, you know? 💖
• DtEDITOR_DATA — the data being transferred is a sized buffer (a DtEditor_DataObj). It's got length and everything. Iconic. 🎀

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. So it's like, "here's my data, and here's how big it is." Simple. 💅

The DtEditorContentRec structure is used to transfer data between an application and the Editor widget. It indicates the type of data being transferred along with the actual data. It's literally the go-between, the messenger, the bestie who carries your 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 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. So you pick your fighter based on type, periodt. 💖

The DtEditorChangeValues structure is used optionally to specify the string to search for and its replacement value for DtEditorChange(3). It's like find-and-replace but make it a struct. 🔥

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

The find argument is a text string to locate in a 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). It's giving formatting realness. ✨

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). So it's like, "keep my text between these columns and align it how I want." No cap. 🎀

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. All of them. Every single one. 💅
• DtEDITOR_CURRENT_SELECTION — replace the currently selected text with the replacement string. You know, the text you highlighted. ✨
• DtEDITOR_NEXT_OCCURRENCE — change the next occurrence of the find string after the insertion cursor. Just the next one, bestie. 🎀

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

• DtEDITOR_FORMAT_ALL — reformats all the text in a DtEditor. The whole thing. Go off. 🔥
• DtEDITOR_FORMAT_PARAGRAPH — reformats only the paragraph containing the insertion cursor. Just that one paragraph, iykyk. 💖
• DtEDITOR_ALIGN_CENTER — centers each line of text between the left and right margins. Centered, like your fave aesthetic. ✨
• DtEDITOR_ALIGN_JUSTIFY — aligns the text flush with both the left and right margins. Justified, like your fave influencer's feed. 💅
• DtEDITOR_ALIGN_LEFT — aligns the text flush with the left margin. Left-aligned, classic. 🎀
• DtEDITOR_ALIGN_RIGHT — aligns the text flush with the right margin. Right-aligned, a little fancy. 🦋

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. So you can jump straight to the end. Periodt. 💅

The header defines the following DtEditorErrorCode constants:

• DtEDITOR_NO_ERRORS — the function completed its task without errors. We love a success story. 💖
• DtEDITOR_INSUFFICIENT_MEMORY — not enough system memory is available to complete the task. Sad, but it happens. 😭
• 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. So you gave it something it doesn't understand. 🙈
• 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. Range issues, bestie. 💀
• DtEDITOR_NULL_ITEM — the data buffer is NULL when passing data in a buffer. You can't pass nothing. 🚫
• 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. Negative size? Not today. 💅
• DtEDITOR_SPELL_FILTER_FAILED — the DtEditor function cannot successfully execute the filter specified by the DtNspellFilter resource. The spell filter said "no." 😭
• DtEDITOR_NO_TMP_FILE — the DtEditor function cannot create a temporary file in the directory returned by tmpnam3S. No temp file for you. 🫠
• DtEDITOR_INVALID_FILENAME — no file was specified. You forgot the file, bestie. 🙈
• DtEDITOR_NONEXISTENT_FILE — the file specified for reading does not exist. It's not there. Ghosted. 👻
• DtEDITOR_UNREADABLE_FILE — the file specified is unreadable for an unspecified reason. It's giving mystery. 🔮
• DtEDITOR_READ_ONLY_FILE — the file is read only. You can look but you can't touch. 💅
• DtEDITOR_NULLS_REMOVED — the file contained embedded NULL characters, which were removed. We cleaned that up for you. ✨
• DtEDITOR_NO_FILE_ACCESS — the file cannot be accessed. Access denied. 🚫
• DtEDITOR_DIRECTORY — the file specified is a directory. That's not a file, bestie. 📁
• DtEDITOR_CHAR_SPECIAL_FILE — the file specified is a character-special device. Fancy, but not what we needed. 🎩
• DtEDITOR_BLOCK_MODE_FILE — the file specified is a block-mode device. Also fancy, also not it. 💾
• DtEDITOR_UNWRITABLE_FILE — the application does not have write permission for the file or directory. No write for you. 🚫
• DtEDITOR_WRITABLE_FILE — the specified file exists and the overwriteIfExists flag is set to False. So it's writable but you said don't overwrite. Conflict. 😬
• DtEDITOR_SAVE_FAILED — the contents of the widget could not be saved for an unspecified reason. The save didn't save. 😭

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). You highlighted something. Slay. ✨
• DtEDITOR_TEXT_DESELECT — no text is selected within the edit window (that is, the selection has become NULL). You unhighlighted. Bye. 💅

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

• DtEDITOR_HELP_EDIT_WINDOW — the help request originated in the edit window. You asked for help from the main character. 👑
• DtEDITOR_HELP_STATUS_LINE — the help request originated in the status line. Help from the status bar. 📊
• DtEDITOR_HELP_STATUS_CURRENT_LINE — the help request originated from the Current Line Number display in the status line. The line number needs help. 🔢
• DtEDITOR_HELP_STATUS_TOTAL_LINES — the help request originated from the Total Lines display in the status line. How many lines? Help. 📈
• DtEDITOR_HELP_STATUS_MESSAGE — the help request originated from the Message field in the status line. The message field is asking for help. 💬
• DtEDITOR_HELP_STATUS_OVERSTRIKE — the help request originated from the Overstrike indicator in the status line. Overstrike needs assistance. ⌨️
• DtEDITOR_HELP_FORMAT_DIALOG — the help request originated from the Help button in the Format Settings dialog. The format dialog's help button. 🆘
• DtEDITOR_HELP_FORMAT_LEFT_MARGIN — the help request originated from the Left Margin field in the Format Settings dialog. Left margin help. ⬅️
• DtEDITOR_HELP_FORMAT_RIGHT_MARGIN — the help request originated from the Right Margin Field in the Format Settings dialog. Right margin help. ➡️
• DtEDITOR_HELP_FORMAT_ALIGNMENT — the help request originated from the Alignment buttons in the Format Settings dialog. Alignment help. 📐
• DtEDITOR_HELP_CHANGE_DIALOG — the help request originated from the Help button in the Find/Change dialog. Find/change help. 🔍
• DtEDITOR_HELP_CHANGE_FIND — the help request originated from the Find field in the Find/Change dialog. The find field needs help. 🔎
• DtEDITOR_HELP_CHANGE_CHANGE — the help request originated from the Change To field in the Find/Change dialog. The change-to field needs help. 🔄
• DtEDITOR_HELP_SPELL_DIALOG — the help request originated from the Help button in the Spell dialog. Spell dialog help. 📝
• DtEDITOR_HELP_SPELL_MISSPELLED_WORDS — the help request originated from the list of misspelled words in the Spell dialog. The misspelled words need help. 🤦‍♀️
• DtEDITOR_HELP_SPELL_CHANGE — the help request originated from the Change To field in the Spell dialog. The spell change field needs help. ✏️

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);

       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);

And that's where part 1 wraps up, bestie — part 2 has the rest of the function prototypes and all the other good stuff. Don't go anywhere! 💅

okay so picking up right where we left off — here’s the rest of the function lineup, literally exactly as written, no cap:

       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,
               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);

the way that DtEditorUndoEdit just takes a Widget and hands you a Boolean? iconic. and yes, every parameter is staying exactly where it is — Widget widget, XSizeHints *pHints, int lineNumber, DtEditorContentRec *data, char *fileName, XmTextPosition startPos, XmTextPosition endPos, Boolean overwriteIfExists, Boolean hardCarriageReturns, Boolean markContentsAsSaved, and XmTextPosition position are all untouched, periodt. 💅

---

💜 SEE ALSO 💜

bestie, these are the sister pages — go read them when you wanna spiral in the best way: 🦋

• 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).

---

footer tea time, fr fr: source/version is Dt/Editor.h(file formats) 💖 and the date? this chunk didn’t give me one, so I’m not inventing a timestamp — no cap, no fake calendar energy. 🎀✨