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 hard carriage returns. If the file does not exist and the directory has the correct write permissions, the file is created. If the file exists and overwriteIfExists 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.  To save a copy of the data without affecting whether DtEditorCheckForUnsavedChanges(3) reports that there are unsaved changes, markContentsAsSaved should be set to True.  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 path and name of the file relative to the local system. 

???? c.o. to follow format, need to include each argument. ????
The overwriteIfExists argument ...

The hardCarriageReturns argument, if set to True, indicates that the widget should replace any soft line feeds (word wraps) with hard carriage returns when saving the data.  When 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 have been saved.  When set to False, the DtEditor widget does not change its status regarding unsaved changes. 

For a complete definition of the DtEditor 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_UNWRITEABLE_FILE
Application does not have write permission for the file or directory

DtEDITOR_CHAR_SPECIAL_FILE
Specified file is a device-special file

DtEDITOR_BLOCK_MODE_FILE
Specified file is a block-mode device

DtEDITOR_SAVE_FAILED
Contents could not be saved for an unlisted reason

DtEDITOR_INVALID_TYPE
Specified type is unrecognized

EXAMPLES

The following code segment saves the contents of a DtEditor widget to the local file, Foo, substituting hard carriage returns for soft carriage returns.  It also indicates that all changes to the contents of the widget have been saved. 

Widgeteditor;
DtEditorErrorCode       status;
char ∗fname = "Foo";
Booleanoverwrite = False,
hardReturns = True,
markContentsAsSaved = True;
 status = DtEditorSaveContentsToFile(editor, fname, overwrite,
    hardReturns, markContentsAsSaved);
 switch ( status )
{
  case DtEDITOR_NO_ERRORS:
    break;
   case DtEDITOR_WRITEABLE_FILE:
    printf("Save failed.  The file already exists.\n" );
    break;
   default:
    printf( "Could not save contents.\n");
    break;
}

APPLICATION USAGE

To retrieve the data in a memory buffer, rather than a disk file, the application should use DtEditorGetContents(3). 

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

  —  30 July 1994