JXFileDocument Class Reference

#include <JXFileDocument.h>

Inheritance diagram for JXFileDocument:

Classes
class	NameChanged
class	WriteFailed

Public Types
enum	FileStatus {   kFileReadable ,   kNeedNewerVersion ,   kNotMyFile ,   kFileNotReadable }

Public Member Functions
	~JXFileDocument () override
bool	NeedsSave () const override
bool	Save ()
void	DataModified ()
void	DataReverted (const bool fromUndo=false)
bool	SaveInCurrentFile ()
bool	SaveInNewFile (const JString &fullName=JString::empty)
bool	SaveCopyInNewFile (const JString &origName=JString::empty, JString *fullName=nullptr)
bool	ExistsOnDisk () const
const JString &	GetFilePath () const
const JString &	GetFileName () const
JString	GetFullName (bool *onDisk) const
const JString &	GetName () const override
bool	FileModifiedByOthers (bool *modTimeChanged=nullptr, bool *permsChanged=nullptr) const
void	CheckIfModifiedByOthers ()
void	RevertIfChangedByOthers (const bool force=false)
bool	WillMakeBackupFile () const
void	ShouldMakeBackupFile (const bool wantBackup)
bool	WillMakeNewBackupEveryOpen () const
void	ShouldMakeNewBackupEveryOpen (const bool makeBackup)
bool	WillAutosaveBeforeClosing () const
void	ShouldAutosaveBeforeClosing (const bool autosave)
bool	WillAllocateTitleSpace () const
void	ShouldAllocateTitleSpace (const bool allocateSpace)
void	SafetySave (const JXDocumentManager::SafetySaveReason reason) override
bool	GetSafetySaveFileName (JString *fileName) const
const JString &	GetSaveBeforeClosePrompt () const
const JString &	GetSaveNewFilePrompt () const
const JString &	GetOKToRevertPrompt () const
void	ReadJXFDSetup (std::istream &input)
void	WriteJXFDSetup (std::ostream &output) const
Public Member Functions inherited from JXDocument
	JXDocument (JXDirector *supervisor)
	~JXDocument () override
bool	Close () override
bool	Deactivate () override
bool	GetMenuIcon (const JXImage **icon) const override
virtual bool	NeedDocument (JXDocument *doc) const
void	RevertToSaved ()
Public Member Functions inherited from JXWindowDirector
	JXWindowDirector (JXDirector *supervisor)
	~JXWindowDirector () override
void	Activate () override
bool	Deactivate () override
void	Suspend () override
void	Resume () override
JXWindow *	GetWindow () const
JXDisplay *	GetDisplay () const
Public Member Functions inherited from JXDirector
	JXDirector (JXDirector *supervisor)
	~JXDirector () override
bool	IsClosing () const
bool	IsActive () const
bool	IsSuspended () const
bool	HasSubdirectors () const
bool	GetSubdirectors (const JPtrArray< JXDirector > **list) const
Public Member Functions inherited from JBroadcaster
	JBroadcaster ()
virtual	~JBroadcaster ()
JBroadcaster &	operator= (const JBroadcaster &source)
bool	HasSenders () const
JSize	GetSenderCount () const
bool	HasRecipients () const
JSize	GetRecipientCount () const
virtual JString	ToString () const
template<class T >
void	ListenTo (const JBroadcaster *sender, const std::function< void(const T &)> &f)

Static Public Member Functions
static bool	WillAskOKToClose ()
static void	ShouldAskOKToClose (const bool ask)
static bool	CheckForSafetySaveFiles (const JString &fullName, JPtrArray< JString > *filesToOpen)
static const JUtf8Byte *	SkipNeedsSavePrefix (const JUtf8Byte *s)

Static Public Attributes
static const JUtf8Byte *	kNameChanged = "NameChanged::JXFileDocument"
static const JUtf8Byte *	kWriteFailed = "WriteFailed::JXFileDocument"

Protected Member Functions
	JXFileDocument (JXDirector *supervisor, const JString &fileName, const bool onDisk, const bool wantBackupFile, const JUtf8Byte *defaultFileNameSuffix)
void	AdjustWindowTitle ()
void	FileChanged (const JString &fileName, const bool onDisk)
bool	OKToClose () override
bool	OKToRevert () override
bool	CanRevert () override
virtual void	HandleFileModifiedByOthers (const bool modTimeChanged, const bool permsChanged)
virtual bool	AskOverwriteFileModifiedByOthers () const
virtual JError	WriteFile (const JString &fullName, const bool safetySave) const
virtual void	WriteTextFile (std::ostream &output, const bool safetySave) const
virtual JString	GetWindowTitle () const
virtual JXSaveFileDialog *	CreateSaveFileDialog (const JString &startName)
void	SetSaveBeforeClosePrompt (const JString &prompt)
void	SetSaveNewFilePrompt (const JString &prompt)
void	SetOKToRevertPrompt (const JString &prompt)
Protected Member Functions inherited from JXDocument
virtual void	DiscardChanges ()=0
bool	OKToDeactivate () override
Protected Member Functions inherited from JXDirector
JXDirector *	GetSupervisor () const
bool	CloseAllSubdirectors ()
virtual void	DirectorClosed (JXDirector *theDirector)
Protected Member Functions inherited from JBroadcaster
	JBroadcaster (const JBroadcaster &source)
void	ListenTo (const JBroadcaster *sender)
void	StopListening (const JBroadcaster *sender)
void	ClearWhenGoingAway (const JBroadcaster *sender, void *pointerToMember)
void	StopListening (const JBroadcaster *sender, const std::type_info &messageType)
template<class T >
void	Send (JBroadcaster *recipient, const T &message)
template<class T >
void	Broadcast (const T &message)
virtual void	Receive (JBroadcaster *sender, const Message &message)
void	SendWithFeedback (JBroadcaster *recipient, Message *message)
void	BroadcastWithFeedback (Message *message)
virtual void	ReceiveWithFeedback (JBroadcaster *sender, Message *message)
virtual void	ReceiveGoingAway (JBroadcaster *sender)

Static Protected Member Functions
static FileStatus	DefaultCanReadASCIIFile (std::istream &input, const JUtf8Byte *fileSignature, const JFileVersion currFileVersion, JFileVersion *actualFileVersion)

Detailed Description

Document class that represents data stored in any type of file.  This can
be used for a multi-file document if there is a unique file that the
user selects to open the document.  This particular file can then be
the file stored by JXFileDocument.

Derived classes should not implement OKToClose().  Instead, they must
implement either WriteFile() or WriteTextFile().  For documents stored
in text files (the easiest, safest, and most portable method), simply
override WriteTextFile().  For other types of files, override WriteFile().

The safetySave flag passed to WriteFile() and WriteTextFile() should
obviously not affect what is written, but it can affect other actions.
As an example, see TestTextEditDocument::WriteFile() in testjx.

CheckForSafetySaveFiles() is provided to look for safety saved versions
of files that the user opens.  We cannot provide the equivalent feature
for untitled documents because, while we could easily check for #untitled#_
files in the user's home directory, we do not know which application created
them.

Member Enumeration Documentation

FileStatus

enum JXFileDocument::FileStatus

Enumerator
kFileReadable
kNeedNewerVersion
kNotMyFile
kFileNotReadable

Constructor & Destructor Documentation

~JXFileDocument()

JXFileDocument::~JXFileDocument ( )

override

JXFileDocument()

JXFileDocument::JXFileDocument ( JXDirector *  supervisor, const JString &  fileName, const bool  onDisk, const bool  wantBackupFile, const JUtf8Byte *  defaultFileNameSuffix  )

protected

Derived class should call AdjustWindowTitle() after creating a window.

defaultFileNameSuffix can be the empty string. If it isn't, SaveInNewFile() appends it to the file name before opening the "Save file" dialog.

Member Function Documentation

AdjustWindowTitle()

void JXFileDocument::AdjustWindowTitle ( )

protected

AskOverwriteFileModifiedByOthers()

bool JXFileDocument::AskOverwriteFileModifiedByOthers ( ) const

protectedvirtual

CanRevert()

bool JXFileDocument::CanRevert ( )

overrideprotectedvirtual

Returns true if the data has not been saved or the file has been modified behind our back.

Implements JXDocument.

CheckForSafetySaveFiles()

bool JXFileDocument::CheckForSafetySaveFiles ( const JString &  origFullName, JPtrArray< JString > *  filesToOpen  )

static

Checks for the existence of a safety save version with a later modification date. If it exists, asks the user if it should be opened. *filesToOpen contains the names of these files, if any.

CheckIfModifiedByOthers()

void JXFileDocument::CheckIfModifiedByOthers

(

)

Checks if the file exists and has been modified behind our back.

CreateSaveFileDialog()

JXSaveFileDialog * JXFileDocument::CreateSaveFileDialog ( const JString &  startName )

protectedvirtual

Virtual to allow customized dialogs.

DataModified()

void JXFileDocument::DataModified ( )

inline

DataReverted()

void JXFileDocument::DataReverted

(

const bool

fromUndo = false

)

Call this after a "Revert to saved" operation

DefaultCanReadASCIIFile()

JXFileDocument::FileStatus JXFileDocument::DefaultCanReadASCIIFile ( std::istream &  input, const JUtf8Byte *  fileSignature, const JFileVersion  latestFileVersion, JFileVersion *  actualFileVersion  )

staticprotected

We provide this as a convenience for simple derived classes. It assumes that the front of the file is {signature, version} and that all older versions are readable. It returns the actual file version so the caller can perform further checks if necessary.

ExistsOnDisk()

bool JXFileDocument::ExistsOnDisk

(

)

const

FileChanged()

void JXFileDocument::FileChanged ( const JString &  fileName, const bool  onDisk  )

protected

Call this to notify us that the document is now displaying a different file. (e.g. after New or Open on the File menu)

FileModifiedByOthers()

bool JXFileDocument::FileModifiedByOthers	(	bool *	modTimeChanged = nullptr,
		bool *	permsChanged = nullptr
	)		const

Returns true if the file exists and has been modified behind our back.

GetFileName()

const JString & JXFileDocument::GetFileName ( ) const

inline

GetFilePath()

const JString & JXFileDocument::GetFilePath ( ) const

inline

GetFullName()

JString JXFileDocument::GetFullName

(

bool *

onDisk

)

const

GetName()

const JString & JXFileDocument::GetName ( ) const

overridevirtual

Override of JXDocument::GetName().

Reimplemented from JXWindowDirector.

GetOKToRevertPrompt()

const JString & JXFileDocument::GetOKToRevertPrompt ( ) const

inline

GetSafetySaveFileName()

bool JXFileDocument::GetSafetySaveFileName

(

JString *

fileName

)

const

Returns true if the file has been safety saved.

GetSaveBeforeClosePrompt()

const JString & JXFileDocument::GetSaveBeforeClosePrompt ( ) const

inline

GetSaveNewFilePrompt()

const JString & JXFileDocument::GetSaveNewFilePrompt ( ) const

inline

GetWindowTitle()

JString JXFileDocument::GetWindowTitle ( ) const

protectedvirtual

This is virtual so derived classes can adjust the window's title. This should be overridden in conjunction with GetName().

HandleFileModifiedByOthers()

void JXFileDocument::HandleFileModifiedByOthers ( const bool  modTimeChanged, const bool  permsChanged  )

protectedvirtual

The default is to do nothing.

NeedsSave()

bool JXFileDocument::NeedsSave ( ) const

overridevirtual

Implementation of JXDocument::NeedsSave().

Reimplemented from JXDocument.

OKToClose()

bool JXFileDocument::OKToClose ( )

overrideprotectedvirtual

Implements JXDocument.

OKToRevert()

bool JXFileDocument::OKToRevert ( )

overrideprotectedvirtual

If the data hasn't been saved or the file has been changed behind our back, asks the user if it is ok to revert to the data stored in the file.

Implements JXDocument.

ReadJXFDSetup()

void JXFileDocument::ReadJXFDSetup

(

std::istream &

input

)

RevertIfChangedByOthers()

void JXFileDocument::RevertIfChangedByOthers

(

const bool

force = false

)

SafetySave()

void JXFileDocument::SafetySave ( const JXDocumentManager::SafetySaveReason  reason )

overridevirtual

Save the data in a temporary file, in case the program crashes. No error reporting is allowed because one possibility is that the GUI itself has died.

Implements JXDocument.

Save()

bool JXFileDocument::Save ( )

inline

Returns true if successful.

SaveCopyInNewFile()

bool JXFileDocument::SaveCopyInNewFile	(	const JString &	origUserName = JString::empty,
		JString *	fullName = nullptr
	)

Save a copy of the data in a new file. Our file is not changed. Returns true if a file is successfully written.

If origName is not empty, it is passed to JChooseSaveFile::SaveFile().

If fullName != nullptr and the save is successful, *fullName is the name of the file that was created.

SaveInCurrentFile()

bool JXFileDocument::SaveInCurrentFile

(

)

SaveInNewFile()

bool JXFileDocument::SaveInNewFile

(

const JString &

newFullName = JString::empty

)

Save the data in a new file and update ourselves to refer to this new file.

SetOKToRevertPrompt()

void JXFileDocument::SetOKToRevertPrompt ( const JString &  prompt )

protected

SetSaveBeforeClosePrompt()

void JXFileDocument::SetSaveBeforeClosePrompt ( const JString &  prompt )

protected

SetSaveNewFilePrompt()

void JXFileDocument::SetSaveNewFilePrompt ( const JString &  prompt )

protected

ShouldAllocateTitleSpace()

void JXFileDocument::ShouldAllocateTitleSpace ( const bool  allocateSpace )

inline

ShouldAskOKToClose()

void JXFileDocument::ShouldAskOKToClose ( const bool  ask )

inlinestatic

ShouldAutosaveBeforeClosing()

void JXFileDocument::ShouldAutosaveBeforeClosing ( const bool  autosave )

inline

ShouldMakeBackupFile()

void JXFileDocument::ShouldMakeBackupFile ( const bool  wantBackup )

inline

ShouldMakeNewBackupEveryOpen()

void JXFileDocument::ShouldMakeNewBackupEveryOpen ( const bool  makeBackup )

inline

SkipNeedsSavePrefix()

const JUtf8Byte * JXFileDocument::SkipNeedsSavePrefix ( const JUtf8Byte *  s )

static

WillAllocateTitleSpace()

bool JXFileDocument::WillAllocateTitleSpace ( ) const

inline

WillAskOKToClose()

bool JXFileDocument::WillAskOKToClose ( )

inlinestatic

WillAutosaveBeforeClosing()

bool JXFileDocument::WillAutosaveBeforeClosing ( ) const

inline

This controls whether the file is always saved before closing. This is usually a good idea because data files should store things like window positions, scrollbar setup, etc., which shouldn't bother the user with a "Save before closing?" message, but should still be updated when the document is closed.

WillMakeBackupFile()

bool JXFileDocument::WillMakeBackupFile ( ) const

inline

WillMakeNewBackupEveryOpen()

bool JXFileDocument::WillMakeNewBackupEveryOpen ( ) const

inline

This controls whether a backup file is created only if none exists or whenever the file is first saved after being opened.

WriteFile()

JError JXFileDocument::WriteFile ( const JString &  fullName, const bool  safetySave  ) const

protectedvirtual

This must be overridden if there is more than one file, or the file is not a plain text file.

WriteJXFDSetup()

void JXFileDocument::WriteJXFDSetup

(

std::ostream &

output

)

const

WriteTextFile()

void JXFileDocument::WriteTextFile ( std::ostream &  output, const bool  safetySave  ) const

protectedvirtual

This must be overridden if WriteFile() is not overridden.

Member Data Documentation

kNameChanged

const JUtf8Byte * JXFileDocument::kNameChanged = "NameChanged::JXFileDocument"

static

kWriteFailed

const JUtf8Byte * JXFileDocument::kWriteFailed = "WriteFailed::JXFileDocument"

static

---

The documentation for this class was generated from the following files:

• libjx/code/JXFileDocument.h
• libjx/code/JXFileDocument.cpp