#include <docview.h>

Inheritance diagram for owl::TDocument:

Classes
class	TList
	Document list class. More...
Public Types
enum	TDocProp { PrevProperty = 0, DocumentClass, TemplateName, ViewCount, StoragePath, DocTitle, NextProperty }
typedef TList	List
Public Member Functions
	TDocument (TDocument *parent=0)
virtual	~TDocument ()
virtual TInStream *	InStream (int mode, LPCTSTR strmId=0)
TInStream *	InStream (int mode, const tstring &streamId)
virtual TOutStream *	OutStream (int mode, LPCTSTR strmId=0)
TOutStream *	OutStream (int mode, const tstring &streamId)
virtual bool	Open (int mode, LPCTSTR path=0)
bool	Open (int mode, const tstring &path)
virtual bool	Close ()
virtual bool	Commit (bool force=false)
virtual bool	Revert (bool clear=false)
virtual TDocument &	RootDocument ()
TDocManager &	GetDocManager ()
void	SetDocManager (TDocManager &dm)
TDocument *	GetParentDoc ()
TDocTemplate *	GetTemplate ()
bool	SetTemplate (TDocTemplate *tpl)
LPCTSTR	GetDocPath () const
virtual bool	SetDocPath (LPCTSTR path)
bool	SetDocPath (const tstring &path)
LPCTSTR	GetTitle () const
virtual void	SetTitle (LPCTSTR title)
void	SetTitle (const tstring &title)
virtual bool	IsDirty ()
void	SetDirty (bool dirty=true)
virtual bool	IsOpen ()
virtual bool	CanClose ()
virtual bool	HasFocus (HWND hwnd)
virtual TDocument *	DocWithFocus (HWND hwnd)
bool	NotifyViews (int event, long item=0, TView *exclude=0)
TView *	QueryViews (int event, long item=0, TView *exclude=0)
virtual uint	PostError (uint sid, uint choice=MB_OK)
virtual int	PropertyCount ()
virtual int	FindProperty (LPCTSTR name)
int	FindProperty (const tstring &name)
virtual int	PropertyFlags (int index)
virtual LPCTSTR	PropertyName (int index)
virtual int	GetProperty (int index, void *dest, int textlen=0)
virtual bool	SetProperty (int index, const void *src)
TList &	GetChildren ()
TView *	GetViewList () const
TView *	NextView (const TView *view)
TStream *	GetStreamList () const
TStream *	NextStream (const TStream *strm)
void *	GetTag () const
void	SetTag (void **tag)
int	GetOpenMode () const
void	SetOpenMode (int mode)
TView *	InitView (TView *view)
bool	IsEmbedded () const
void	SetEmbedded (bool embed)
virtual bool	InitDoc ()
	TDocument (TDocManager *docMan)
Protected Member Functions
virtual void	AttachStream (TStream &strm)
virtual void	DetachStream (TStream &strm)
Friends
class	TDocTemplate
class	TView
class	TStream
class	TDocManager
class	TList

Detailed Description

An abstract base class, TDocument is the base class for all document objects and serves as an interface between the document, its views, and the document manager (TDocManager class). TDocument creates, destroys, and sends messages about the view. For example, if the user changes a document, TDocument tells the view that the document has been updated. The DEFINE_DOC_TEMPLATE_CLASS macro associates a document with its views.

In order to send messages to its associated views, the document maintains a list of all the views existing for that document and communicates with the views using ObjectWindows event-handling mechanism. Rather than using the function SendMessage(), the document accesses the view's event table. The views can update the document's data by calling the member functions of the particular document. Views can also request streams, which are constructed by the document.

Both documents and views have lists of properties for their applications to use. When documents and views are created or destroyed, messages are sent to the application, which can then query the properties to determine how to process the document or view. It is the document manager's responsibility to determine if a particular view is appropriate for the given document.

Because the property attribute functions are virtual, a derived class (which is called first) might override the properties defined in a base class. Each derived class must implement its own property attribute types of either string or binary data. If the derived class duplicates the property names of the parent class, it should provide the same behavior and data type as the parent.

In order to add persistence to documents, TDocument contains several virtual functions (for example, InStream and OutStream) that support streaming. Your derived classes need to override these functions in order to read and write data.

Although documents are usually associated with files, they do not necessarily have to be files; they can also consist of database tables, mail systems, fax or modem transmissions, disk directories, and so on.

Member Enumeration Documentation

enum owl::TDocument::TDocProp

These property values, which describe the basic properties of a document, are available in classes derived from TDocument. They can be used to update and query the attributes of a document. PrevProperty and NextProperty are delimiters for every document's property list. See GetProperty() and SetProperty() for more information.

Enumerator:

PrevProperty	Index of last property in base class (none in this case)
DocumentClass	text Property: Name of C++ class encapsulating document
TemplateName	text property: Name of template attached to document
ViewCount	int property: Number of views displaying this document
StoragePath	text property: Identifies object holding data of this document
DocTitle	text property: Caption of this document
NextProperty	Next index to be used by derived class.

Constructor & Destructor Documentation

owl::TDocument::TDocument ( TDocument * parent = 0 )

Although you do not create a TDocument object directly, you must call the constructor when you create a derived class. parent points to the parent of the new document. If no parent exists, parent is 0.

References owl::TAppDictionary::GetApplication(), owl::TApplication::GetDocManager(), and owl::TDocument::TList::Insert().

owl::TDocument::~TDocument ( ) [virtual]

Deletes a TDocument object. Normally, Close is called first. TDocument's destructor destroys all children and closes all open streams. If this is the last document that used the template, it closes the object's template and any associated views, deletes the object's stream, and removes itself from the parent's list of children if a parent exists. If there is no parent, it removes itself from the document manager's document list.

References Close(), owl::TDocument::TList::Destroy(), owl::dnClose, owl::TDocManager::PostEvent(), owl::TDocument::TList::Remove(), and SetTemplate().

owl::TDocument::TDocument ( TDocManager * docMan ) [inline]

create a dummy document to hold docmgr

Create a dummy document to hold docmgr.

Member Function Documentation

void owl::TDocument::AttachStream ( TStream & strm ) [protected, virtual]

called from TStream constructor

Called from TStream's constructor, AttachStream attaches a stream to the current document.

References owl::TStream::NextStream.

bool owl::TDocument::CanClose ( ) [virtual]

Returns false if unable to close.

Checks to see if all child documents can be closed before closing the current document. If any child returns false, CanClose returns false and aborts the process. If all children return true, calls TDocManager::FlushDoc. If FlushDoc finds that the document has been changed but not saved, it displays a message asking the user to either save the document, discard any changes, or cancel the operation. If the document has not been changed and all children's CanClose functions return true, this CanClose function returns true.

Reimplemented in ocf::TOleDocument.

References CanClose(), owl::TDocManager::FlushDoc(), and owl::TDocument::TList::Next().

bool owl::TDocument::Close ( ) [virtual]

close document, does not delete or detach

Closes the document but does not delete or detach the document. Before closing the document, Close checks any child documents and tries to close them before closing the parent document. Even if you write your own Close function, call TDocument's version to ensure that all child documents are checked before the parent document is closed.

Reimplemented in owl::TFileDocument, ocf::TOleDocument, and ocf::TStorageDocument.

References Close(), and owl::TDocument::TList::Next().

bool owl::TDocument::Commit ( bool force = false ) [virtual]

save current data, force write

Saves the current data to storage. When a file is closed, the document manager calls either Commit or Revert. If force is true, all data is written to storage. Commit checks any child documents and commits their changes to storage also. Before the current data is saved, all child documents must return true. If all child documents return true, Commit flushes the views for operations that occurred since the last time the view was checked. After all data for the document is updated and saved, Commit returns true.

Reimplemented in owl::TFileDocument, ocf::TOleDocument, and ocf::TStorageDocument.

References Commit(), owl::TDocument::TList::Next(), NotifyViews(), and owl::vnCommit.

void owl::TDocument::DetachStream ( TStream & strm ) [protected, virtual]

called from TStream destructor

Called from TStream's destructor, DetachStream detaches the stream from the current document.

References owl::TStream::NextStream.

TDocument * owl::TDocument::DocWithFocus ( HWND hWnd ) [virtual]

Return pointer to this document or one of its child documents if the spcecified window parameter is a view associated with the document.

Note:: Unlike 'HasFocus', this method allows you to distinguish whether the document with focus is a child document.

References DocWithFocus(), owl::TDocument::TList::Next(), QueryViews(), and owl::vnIsWindow.

int owl::TDocument::FindProperty ( LPCTSTR name ) [virtual]

return property index

Gets the property index, given the property name (name). Returns either the integer index number that corresponds to the name or 0 if the name isn't found in the list of properties.

Reimplemented in owl::TFileDocument, and ocf::TStorageDocument.

References NextProperty, and PrevProperty.

TDocument::TList & owl::TDocument::GetChildren ( ) [inline]

Return reference to the children document list.

TDocManager & owl::TDocument::GetDocManager ( ) [inline]

Returns a pointer to the current document manager.

LPCTSTR owl::TDocument::GetDocPath ( ) const [inline]

Returns the directory path for the document. This might change the SaveAs operation.

int owl::TDocument::GetOpenMode ( ) const [inline]

Gets the mode and protection flag values for the current document.

TDocument * owl::TDocument::GetParentDoc ( ) [inline]

Returns either the parent document of the current document or 0 if there is no parent document.

int owl::TDocument::GetProperty	(	int	prop,
		void *	dest,
		int	textlen = `0`
	)		`[virtual]`

Returns the total number of properties for this document, where index is the property index, dest contains the property data, and textlen is the size of the array. If textlen is 0, property data is returned as binary data; otherwise, property data is returned as text data.

Reimplemented in owl::TFileDocument, and ocf::TStorageDocument.

References DocTitle, DocumentClass, owl::TDocTemplate::GetDescription(), StoragePath, TemplateName, and ViewCount.

TStream * owl::TDocument::GetStreamList ( ) const [inline]

Returns head of the link list of streams associated with this document.

Note:: To iterate through all the streams, use the 'NextStream' method with the pointer returned from this method.

void * owl::TDocument::GetTag ( ) const [inline]

Returns pointer to user-defined data [i.e. tag] attached to this document.

TDocTemplate * owl::TDocument::GetTemplate ( ) [inline]

Gets the template used for document creation. The template can be changed during a SaveAs operation.

LPCTSTR owl::TDocument::GetTitle ( ) const [inline]

Returns the title of the document.

TView * owl::TDocument::GetViewList ( ) const [inline]

Return pointer to the head of the link list of views associated with this document.

Note:: To iterate through all the views, use the 'NextView' method with the pointer obtained from this method.

bool owl::TDocument::HasFocus ( HWND hWnd ) [virtual]

Document (or child doc) has Focus.

Used by the document manager, HasFocus returns true if this document's view has focus. hwnd is a handle to the document. to determine if the document contains a view with a focus.

References DocWithFocus().

bool owl::TDocument::InitDoc ( ) [inline, virtual]

A virtual method that is overridden by TOleDocument::InitDoc. You can use this function to prepare the document before the view is constructed and before the dnCreate event, which indicates that the document has been created and is posted.

Reimplemented in ocf::TOleDocument.

TView * owl::TDocument::InitView ( TView * view )

called from template InitView

Initializes the view. Notifies others a view is created by posting the dnCreate event.

References owl::TView::BumpNextViewId(), owl::dnCreate, owl::TView::IsOK(), and owl::TDocManager::PostEvent().

TInStream * owl::TDocument::InStream	(	int	mode,
		LPCTSTR	strmId = `0`
	)		`[inline, virtual]`

Generic input for the particular storage medium, InStream returns a pointer to a TInStream. mode is a combination of the ios bits defined in iostream.h. See the document open mode constants for a list of the open modes. Used for documents that support named streams, strmId is a pointer to the name of a stream. Override this function to provide streaming for your document class.

Reimplemented in owl::TFileDocument, and ocf::TStorageDocument.

bool owl::TDocument::IsDirty ( ) [virtual]

Also queries doc and view hierarchy.

Returns true if the document or one of its views has changed but has not been saved.

References IsDirty(), owl::TDocument::TList::Next(), QueryViews(), and owl::vnIsDirty.

bool owl::TDocument::IsEmbedded ( ) const [inline]

Returns true if the document is embedded in an OLE 2 container.

bool owl::TDocument::IsOpen ( ) [inline, virtual]

Checks to see if the document has any streams in its stream list. Returns false if no streams are open; otherwise, returns true.

Reimplemented in owl::TFileDocument, and ocf::TStorageDocument.

TStream * owl::TDocument::NextStream ( const TStream * strm )

Gets the next entry in the stream. Holds 0 if none exists.

References owl::TStream::NextStream.

TView * owl::TDocument::NextView ( const TView * view )

Gets the next view in the list of views. Holds 0 if none exists.

bool owl::TDocument::NotifyViews	(	int	event,
		long	item = `0`,
		TView *	exclude = `0`
	)

Notifies the views of the current document and the views of any child documents of a change. In contrast to QueryViews, NotifyViews sends notification of an event to all views and returns true if any views returned a true result. The event, EV_OWLNOTIFY, is sent with an event code, which is private to the particular document and view class, and a long argument, which can be cast appropriately to the actual type passed in the argument of the response function.

References owl::TEventHandler::Dispatch(), owl::TEventHandler::Find(), owl::TDocument::TList::Next(), and NotifyViews().

bool owl::TDocument::Open	(	int	mode,
		LPCTSTR	path = `0`
	)		`[inline, virtual]`

Opens the document using the path specified by DocPath. Sets OpenMode to mode. TDocument::Open always returns true and actually performs no actions. Other classes override this function to open specified file documents and views.

Reimplemented in owl::TFileDocument, ocf::TOleDocument, and ocf::TStorageDocument.

TOutStream * owl::TDocument::OutStream	(	int	mode,
		LPCTSTR	strmId = `0`
	)		`[inline, virtual]`

Generic output for the particular storage medium, OutStream returns a pointer to a TOutStream. mode is a combination of the ios bits defined in iostream.h. Used for documents that support named streams, strmId points to the name of the stream. TDocument::OutStream version always returns 0. Override this function to provide streaming for your document class.

Reimplemented in owl::TFileDocument, and ocf::TStorageDocument.

uint owl::TDocument::PostError	(	uint	sid,
		uint	choice = `MB_OK`
	)		`[virtual]`

Posts the error message passed as a string resource ID in sid. choice is one or more of the MB_Xxxx style constants.

References owl::TDocManager::PostDocError().

int owl::TDocument::PropertyCount ( ) [inline, virtual]

Gets the total number of properties for the TDocument object. Returns NextProperty -1.

Reimplemented in owl::TFileDocument, and ocf::TStorageDocument.

References NextProperty.

int owl::TDocument::PropertyFlags ( int index ) [virtual]

pfXxxxx bit array

Returns the attributes of a specified property given the index (index) of the property whose attributes you want to retrieve.

Reimplemented in owl::TFileDocument, and ocf::TStorageDocument.

References NextProperty, and PrevProperty.

LPCTSTR owl::TDocument::PropertyName ( int index ) [virtual]

locale invariant name

Returns the name of the property given the index value (index).

Reimplemented in owl::TFileDocument, and ocf::TStorageDocument.

References NextProperty, and PrevProperty.

TView * owl::TDocument::QueryViews	(	int	event,
		long	item = `0`,
		TView *	exclude = `0`
	)

Queries the views of the current document and the views of any child documents about a specified event, but stops at the first view that returns true. In contrast to NotifyViews(), QueryViews returns a pointer to the first view that responded to an event with a true result. The event, EV_OWLNOTIFY, is sent with an event code (which is private to the particular document and view class) and a long argument (which can be cast appropriately to the actual type passed in the argument of the response function).

References owl::TEventHandler::Dispatch(), owl::TEventHandler::Find(), owl::TDocument::TList::Next(), and QueryViews().

bool owl::TDocument::Revert ( bool clear = false ) [virtual]

abort changes, no reload if true

Performs the reverse of Commit() and cancels any changes made to the document since the last commit. If clear is true, data is not reloaded for views. Revert also checks all child documents and cancels any changes if all children return true. When a file is closed, the document manager calls either Commit() or Revert. Returns true if the operation is successful.

Reimplemented in owl::TFileDocument, ocf::TOleDocument, and ocf::TStorageDocument.

References owl::TDocument::TList::Next(), NotifyViews(), Revert(), and owl::vnRevert.

TDocument & owl::TDocument::RootDocument ( ) [virtual]

Returns the this pointer as the root document.

void owl::TDocument::SetDirty ( bool dirty = true ) [inline]

Updates the document's dirty flag using the specified parameter.

void owl::TDocument::SetDocManager ( TDocManager & dm )

Sets the current document manager to the argument dm.

References owl::TDocument::TList::Insert(), and owl::TDocument::TList::Remove().

bool owl::TDocument::SetDocPath ( LPCTSTR path ) [virtual]

Sets the document path for Open and Save operations.

Reimplemented in ocf::TStorageDocument.

References owl::dmMDI, owl::TDocManager::GetApplication(), owl::TCommDlg::GetFileTitle(), owl::TDocManager::GetUntitledIndex(), owl::TDocManager::IsFlagSet(), owl::TModule::LoadString(), and SetTitle().

void owl::TDocument::SetEmbedded ( bool embed ) [inline]

Marks the document as being embedded in an OLE 2 container. Typically, this happens when the server is created and when the factory template class creates the component.

void owl::TDocument::SetOpenMode ( int mode ) [inline]

Sets the mode and protection flag values for the current document.

bool owl::TDocument::SetProperty	(	int	prop,
		const void *	src
	)		`[virtual]`

native type

Sets the value of the property, given index, the index value of the property, and src, the data type (either binary or text) to which the property must be set.

Reimplemented in owl::TFileDocument, and ocf::TStorageDocument.

References DocTitle, SetDocPath(), SetTitle(), and StoragePath.

void owl::TDocument::SetTag ( void ** tag ) [inline]

Attach an arbitrary (user-defined) pointer with this document.

Note:: The 'Tag' is a place-holder. It is not used by the Doc/View subsystem.

bool owl::TDocument::SetTemplate ( TDocTemplate * tpl )

Sets the document template. However, if the template type is incompatible with the file, the document manager will refuse to save the file as this template type.

References owl::TDocManager::RefTemplate(), and owl::TDocManager::UnRefTemplate().

void owl::TDocument::SetTitle ( LPCTSTR title ) [virtual]

Sets the title of the document.

Friends And Related Function Documentation

friend class TDocTemplate [friend]

access to InitView()

friend class TList [friend]

access to NextDoc

friend class TStream [friend]

access to Attach/DetachStream()

friend class TView [friend]

access to Attach/DetatchView()

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

D:/Work/OWLNext/Subversion/branches/632/include/owl/docview.h
D:/Work/OWLNext/Subversion/branches/632/source/owlcore/document.cpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation