DtEditorSaveContenUNIXFSystem V (1 ADtEditorSaveContentsToFile(3)
NAME
DtEditorSaveContentsToFile - 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
The DtEditorSaveContentsToFile() function saves the entire
contents of the DtEditor widget to a file, optionally
replacing soft line feeds (word wraps) with <newline>s. If
the file does not exist and the directory has the correct
write permissions, the file is created. If the file exists
and the overwriteIfExists argument is set to True, the
contents of the file are overwritten. If the file or its
directory does not have the correct write permissions, an
error is returned.
The DtEditor widget tracks whether its contents have changed
since they were last saved or retrieved. If the
markContentsAsSaved argument is set to False, a copy of the
data is saved without affecting whether
DtEditorCheckForUnsavedChanges(3) reports that there are
unsaved changes. This is useful if the application needs to
save a copy of the contents to a temporary file.
The widget argument specifies the DtEditor widget ID.
The fileName argument is the pathname of the file relative
to the local system.
The overwriteIfExists argument, if set to True, causes
DtEditorSaveContentsToFile() to save the widget contents
even though the file specified by the fileName argument
exists and has correct write permissions. If this argument
is set to False, DtEditorSaveContentsToFile() returns
DtEDITOR_WRITABLE_FILE.
The hardCarriageReturns argument, if set to True, indicates
that the widget should replace any soft line feeds (word
wraps) with <newline>s when saving the data. When this
argument is set to False, any line wrapped because it
reaches the right edge of the window, is saved as one
complete line.
The markContentsAsSaved argument, when set to True, causes
the DtEditor widget to mark that all changes made to date
Page 1 (printed 9/3/04)
DtEditorSaveContenUNIXFSystem V (1 ADtEditorSaveContentsToFile(3)
have been saved. When this argument is set to False, the
DtEditor widget does not change its status regarding unsaved
changes. If an error arises during the save, the status
does not change, regardless of the value of the
markContentsAsSaved argument.
For a complete definition of the DtEditor widget and its
associated resources, see DtEditor(3).
RETURN VALUE
Upon successful completion, the DtEditorSaveContentsToFile()
function returns DtEDITOR_NO_ERRORS; otherwise, if it cannot
save the data to the file, the function returns one of the
following 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
The following 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.
Widget editor;
DtEditorErrorCode status;
char *fname = "Foo";
Boolean overwrite = False,
hardReturns = True,
markContentsAsSaved = True;
status = DtEditorSaveContentsToFile(editor, fname, overwrite,
Page 2 (printed 9/3/04)
DtEditorSaveContenUNIXFSystem V (1 ADtEditorSaveContentsToFile(3)
hardReturns, markContentsAsSaved);
switch(status )
{
case DtEDITOR_NO_ERRORS:
break;
case DtEDITOR_WRITABLE_FILE:
printf("Save failed. The file already exists.\n");
break;
default:
printf("Could not save contents.\n");
break;
}
APPLICATION USAGE
The application should use DtEditorGetContents(3) to
retrieve the data in a memory buffer, rather than a disk
file.
SEE ALSO
DtEditor(5), DtEditor(3), DtEditorAppend(3),
DtEditorAppendFromFile(3),
DtEditorCheckForUnsavedChanges(3), DtEditorGetContents(3),
DtEditorInsert(3), DtEditorInsertFromFile(3),
DtEditorReplace(3), DtEditorReplaceFromFile(3),
DtEditorSetContentsFromFile(3), DtEditorSetContents(3).
Page 3 (printed 9/3/04)
