DtEditorSaveContentsToFile(3)

DtEditorSaveContentsToFClLIBRARY FUNDtEditorSaveContentsToFile(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 con-
     tents 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 markCon-
     tentsAsSaved argument is set to False, a copy of the data is
     saved    without	affecting   whether   DtEditorCheckForUn-
     savedChanges(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  com-
     plete line.

Unix System LaboratoLast change: 1 August 1995			1

DtEditorSaveContentsToFClLIBRARY FUNDtEditorSaveContentsToFile(3)

     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 of the markCon-
     tentsAsSaved 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,

Unix System LaboratoLast change: 1 August 1995			2

DtEditorSaveContentsToFClLIBRARY FUNDtEditorSaveContentsToFile(3)

				  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.\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), DtEditorAp-
     pendFromFile(3), DtEditorCheckForUnsavedChanges(3), DtEdi-
     torGetContents(3),	DtEditorInsert(3), DtEditorInsertFrom-
     File(3), DtEditorReplace(3), DtEditorReplaceFromFile(3),
     DtEditorSetContentsFromFile(3), DtEditorSetContents(3).

Unix System LaboratoLast change: 1 August 1995			3