DtEditorSaveContentsToFile(library cDatlEld)itorSaveContentsToFile(library call)




 NAME    [Toc]    [Back]
      DtEditorSaveContentsToFile - save the contents of a DtEditor widget to
      a file

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

 DESCRIPTION    [Toc]    [Back]
      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 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



                                    - 1 -       Formatted:  January 24, 2005






 DtEditorSaveContentsToFile(library cDatlEld)itorSaveContentsToFile(library call)




      of the markContentsAsSaved argument.

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

 RETURN VALUE    [Toc]    [Back]
      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    [Toc]    [Back]
      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,
                                          hardReturns, markContentsAsSaved);
      switch(status)
      {
              case DtEDITOR_NO_ERRORS:
                      break;



                                    - 2 -       Formatted:  January 24, 2005






 DtEditorSaveContentsToFile(library cDatlEld)itorSaveContentsToFile(library call)




              case DtEDITOR_WRITABLE_FILE:
                      printf("Save failed.  The file already exists.\n");
                      break;
              default:
                      printf("Could not save contents.\n");
                      break;
      }

 APPLICATION USAGE    [Toc]    [Back]
      The application should use DtEditorGetContents(3) to retrieve the data
      in a memory buffer, rather than a disk file.

 SEE ALSO    [Toc]    [Back]
      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).


                                    - 3 -       Formatted:  January 24, 2005