DTEDITORSAVECONTENTSTOFILE(3)

✨ NAME ✨

DtEditorSaveContentsToFile — library call: save the contents of a DtEditor widget to a file. 💾✨

✨ SYNOPSIS ✨

#include &<Dt/Editor.h>
DtEditorErrorCode DtEditorSaveContentsToFile(
Widget widget,
char *fileName,
Boolean overwriteIfExists,
Boolean hardCarriageReturns,
Boolean markContentsAsSaved);

✨ DESCRIPTION ✨

Okay bestie, so DtEditorSaveContentsToFile takes the entire contents of your DtEditor widget and saves them to a file. You can optionally replace soft line feeds — aka word wraps — with <newline>s. 💅

If the file does not exist and the directory has the correct write permissions, the file gets created. If the file does exist and overwriteIfExists is set to True, the file’s contents get overwritten. If the file or its directory does not have the correct write permissions, an error is returned. No cap, permissions matter.

The DtEditor widget is lowkey tracking whether its contents have changed since they were last saved or retrieved. If markContentsAsSaved is set to False, a copy of the data is saved without affecting whether DtEditorCheckForUnsavedChanges(3) reports that there are unsaved changes. That’s the move when the app needs to save a copy of the contents to a temporary file. 🧚

The Arguments, Bestie

• widget — the DtEditor widget ID. That’s the main character right there.
• fileName — the pathname of the file, relative to the local system. 📁
• overwriteIfExists — if set to True, it causes DtEditorSaveContentsToFile to save the widget contents even though the file specified by fileName exists and has correct write permissions. If set to False, DtEditorSaveContentsToFile returns DtEDITOR_WRITABLE_FILE.
• hardCarriageReturns — if set to True, it indicates that the widget should replace any soft line feeds (word wraps) with <newline>s when saving the data. If set to False, any line wrapped because it reaches the right edge of the window is saved as one complete line.
• markContentsAsSaved — when set to True, it causes the DtEditor widget to mark that all changes made to date have been saved. When set to False, the DtEditor widget does not change its status regarding unsaved changes. And if an error arises during the save, the status does not change, regardless of the value of markContentsAsSaved. Important vibe check.

For a complete definition of the DtEditor widget and its associated resources, see DtEditor(3).

✨ RETURN VALUE ✨

Upon successful completion, DtEditorSaveContentsToFile returns DtEDITOR_NO_ERRORS. Otherwise, if it cannot save the data to the file, the function returns one of these values:

• DtEDITOR_INVALID_FILENAME — no file was specified.
• DtEDITOR_UNWRITABLE_FILE — the application does not have write permission for the file or directory.
• DtEDITOR_CHAR_SPECIAL_FILE — the file is a device-special file.
• DtEDITOR_BLOCK_MODE_FILE — the file is a block-mode device.
• DtEDITOR_NO_FILE_ACCESS — the file cannot be accessed.
• DtEDITOR_SAVE_FAILED — the contents could not be saved for an unspecified reason.
• DtEDITOR_WRITABLE_FILE — the named files exist and the overwriteIfExists argument is set to False.

✨ EXAMPLES ✨

This code segment saves the contents of a DtEditor widget to the local file Foo, substituting <newline>s for soft line feeds. It also indicates that all changes to the contents of the widget have been saved. Copy it exactly, bestie: 🎀

Widget                  editor;
DtEditorErrorCode       status;
char                    *fname = "Foo";
Boolean                 overwrite = False,
                        hardReturns = True,
                        markContentsAsSaved = True;
status = DtEditorSaveContentsToFile(editor, fname, overwrite,
                                    hardReturns, markContentsAsSaved);
switch(status)
{
        case DtEDITOR_NO_ERRORS:
                break;
        case DtEDITOR_WRITABLE_FILE:
                printf("Save failed.  The file already exists.0);
                break;
        default:
                printf("Could not save contents.0);
                break;
}

✨ APPLICATION USAGE ✨

Your app should use DtEditorGetContents(3) to retrieve the data into a memory buffer, rather than a disk file. Memory buffer is the vibe here. 🧠💅

✨ SEE ALSO ✨

• Dt/Editor.h - DtEditor(5)
• DtEditor(3)
• DtEditorAppend(3)
• DtEditorAppendFromFile(3)
• DtEditorCheckForUnsavedChanges(3)
• DtEditorGetContents(3)
• DtEditorInsert(3)
• DtEditorInsertFromFile(3)
• DtEditorReplace(3)
• DtEditorReplaceFromFile(3)
• DtEditorSetContentsFromFile(3)
• DtEditorSetContents(3)

✨ Cute footer sign-off: this is the DtEditorSav...tentsToFile(library call) page, and no version or date is listed — so that’s the whole footer vibe, bestie. 💅🫶