Document/View and you

TStream, TInStream, TOutStream

TStream

1) An abstract base class, TStream provides links between streams and documents, views, and document files.

3) This class isn’t abstract in the usual C++ sense with =0 pure virtual functions, it is made abstract because it’s only constructor is protected.

Public members

Protected members

3)

TInStream and TOutStream simply add public constructors and mix in istream and ostream.

Related classes TStorageInStream, TStorageOutStream, TStorageStreamBase, and TStorageBuf are used by TStorageDocument and TOleDocument but are declared in the .cpp files and so cannot be used.

Support for Doc/View in other classes:

TApplication

TDocManager* GetDocManager() returns the document manager. This is used when you want to programmatically cause Doc/View things to happen, such as loading a document on startup. From any TWindow, you can call GetApplication()->GetDocManager() to get the document manager.

In addition, your application will need an EvNewView() and possibly an EvCloseView() member in your application class.

TMenuDescr

This class is used to alter an applications menu. It is normally used with Doc/View to merge menu items specific to a view with menu items which are always available. See the on-line help and the docview.ide sample program.

Events and how to make them

Let's take a look at how the standard events are defined. They are defined in two pieces: First, the argument types to the various functions are defined, then the EV_VN_ messages are defined, like this:

NOTIFY_SIG(vnViewOpened,TView*)

NOTIFY_SIG(vnViewClosed,TView*)

NOTIFY_SIG(vnDocOpened, int)

NOTIFY_SIG(vnDocClosed, int)

NOTIFY_SIG(vnCommit, BOOL)

NOTIFY_SIG(vnRevert, BOOL)

NOTIFY_SIG(vnIsDirty, void)

NOTIFY_SIG(vnIsWindow, HWND)

#define EV_VN_VIEWOPENED VN_DEFINE(vnViewOpened,VnViewOpened,pointer)

#define EV_VN_VIEWCLOSED VN_DEFINE(vnViewClosed,VnViewClosed,pointer)

#define EV_VN_DOCOPENED VN_DEFINE(vnDocOpened, VnDocOpened, int)

#define EV_VN_DOCCLOSED VN_DEFINE(vnDocClosed, VnDocClosed, int)

#define EV_VN_COMMIT VN_DEFINE(vnCommit, VnCommit, int)

#define EV_VN_REVERT VN_DEFINE(vnRevert, VnRevert, int)

#define EV_VN_ISDIRTY VN_DEFINE(vnIsDirty, VnIsDirty, void)

#define EV_VN_ISWINDOW VN_DEFINE(vnIsWindow, VnIsWindow, int)

Here is a handy table of the meanings of the constants:

Constant Meaning

vnCommit 1) Changes are committed to the document.

2) document is committing, flush cached changes

3) The document is about to write changes to the file. If the

view is keeping changes from the document for efficiency

reasons, it has to tell the document about them all when it

gets this notification.

vnCustomBase 1) Base event for document notifications.

2) base of document class specific notifications

3) Has the value of 100. Document classes you write are

supposed to use vnCustomBase+x for each of their custom

notifications. Documents don't send events to views that are

not their own, so you don't need to guarantee unique #s among

documents. Define these in your document and not your views

so they can be shared.

vnDocOpened 1&2) Document has been opened.

vnDocClosed 1&2) Document has been closed.

vnIsDirty 1&2) Is TRUE if uncommitted changes are present.

vnIsWindow 1&2) Is TRUE if the HWND passed belongs to this view.

vnRevert 1) Document's previous data is reloaded and overwrites the

view's current data.

2) document has reverted, reload data from doc

vnViewOpened 1) A new view has been constructed.

vnViewClosed 2) A view is about to be destroyed.

Now, in the Borland supplied line drawing example, three additional events were defined: Append a line, Delete a line, and Modify a line. Each of these worked with an unsigned int which was the # of the line. These events were defined thusly:

const int vnDrawAppend = vnCustomBase+0;

const int vnDrawDelete = vnCustomBase+1;

const int vnDrawModify = vnCustomBase+2;

NOTIFY_SIG(vnDrawAppend, unsigned int)

NOTIFY_SIG(vnDrawDelete, unsigned int)

NOTIFY_SIG(vnDrawModify, unsigned int)

#define EV_VN_DRAWAPPEND VN_DEFINE(vnDrawAppend, VnAppend, int)

#define EV_VN_DRAWDELETE VN_DEFINE(vnDrawDelete, VnDelete, int)

#define EV_VN_DRAWMODIFY VN_DEFINE(vnDrawModify, VnModify, int)

When I first started trying to make Doc/View apps, I didn't realize that I could put any old type I wanted into NOTIFY_SIG, because I didn't understand how it figured out what to do. But you can, provided it fits into 32 bits. Just follow the examples from DOCVIEW.H above. (DOCVIEW.H has a bunch of secret stuff in it to make this all work, it is quite hard to read...)

Frequently asked Questions

The document manager is lazy; it doesn't open your document. Why? Well lets say you are writing the Borland C++ IDE with Doc/View. Now, you are going to need the .IDE, the .EXE (for debugging and browsing) and the .APX (for Class Expert) when a project is opened up. But loading in the whole .EXE might be a waste, so the system waits until it needs it. If you look at the line drawing example it does this to show you how to do it, although you don't get an actual benefit out of it in this case. (I'm not sure though if you wouldn't model a system like the C++ IDE with the .IDE file being a parent document, and the .EXE and .APX being children though...)

What the DOCVIEW.IDE line drawing example does is have the following code at the top of its GetLine() method:

if (!IsOpen() && !Open(ofRead | ofWrite))

return 0;

Paint() calls GetLine() which will call Open() the first time through. If you don’t like this you can add the bit dtAutoOpen in your DocTypeN declaration.

If you decide to add dtAutoOpen to an existing project, be warned that your Open() will not be called for File|New operations as it was when Open() was called in the document.

You copied the CanClose() member from the line drawing example:

bool CanClose() {return TListBox::CanClose() && Doc->CanClose();}

This bit of code asks the document if it can close when the view closes, even though the document is not going to close. If your view doesn't hold any data, you don't want to call TDocument::CanClose() unless you are the last view on the screen:

bool CanClose()

{ return TListBox::CanClose() &&

(Doc->NextView(this) || Doc->NextView(0) != this ||

Doc->CanClose()); }

SetDocTitle doesn't do anything except call the parent document, and there is rarely one of those. The only SetDocTitle() in OWL that does anything interesting is the one in TFrameWindow (which wasn’t in the BC 4.0x help). What it does is takes the frame's title, the document name, and the index number, and make a window caption. If you want to set the frame's title, you can do it in TMyApp::EvNewView by replacing the call to your MDI child constructor with something like this:

TMyMDIChild* child = new TMyMDIChild(*mdiClient,

view.GetViewName(), // caption

view.GetWindow());

You have to write a VnIsWindow() member AND you must put a EV_VN_ISWINDOW in the response table. If you don't the document manager thinks that your view isn't the active view, even when it has the focus. See TListBox::VnIsWindow() for an example.

If your view has controls on it (for example if you are deriving from TView and TDialog), the example VnIsWindow() will not work for you, because the document manager is passing around the window with the focus, and you have given the focus to a control. Try this:

bool TMyDialog::VnIsWindow(HWND hWnd)

{

return ((HWindow == hWnd) || IsChild(hWnd));

}

This is frustrating for projects created by the "Dialog main window" option of BC 4.5x, because the AppExpert will generate a VnIsWindow() like this:

bool VnIsWindow(HWND hWnd) {return HWindow == hWnd;}

which will NEVER work for a dialog.

I haven't found a clean way to do this, although a property could probably take care of it. In your EvNewView(), set the icon based upon the view class:

if (TYPESAFE_DOWNCAST(&view, TAlphaView))

child->SetIcon(this, IDI_ALPHA);

else if (TYPESAFE_DOWNCAST(&view, TBetaView))

child->SetIcon(this, IDI_BETA);

else if (TYPESAFE_DOWNCAST(&view, TGammaView))

child->SetIcon(this, IDI_GAMMA);

(When I suggested this method on the OWL mailing list, I was blasted for the non-object oriented nature of this solution. Some people think that all the views should inherit from a single view with a GetDesiredIcon() method, and the view should be TYPESAFE_DOWNCAST into that type and its GetDesiredIcon() method called. This is a good solution, although it would be better if the stock TView had something like this or even better if the ClassExpert could derive classes from your own base classes.)

Changing the menus is your code's job, not the document manager's. In your EvNewView() member you want to add the following code before the call to setting the icon:

if (view.GetViewMenu())

child->SetMenuDescr(*view.GetViewMenu());

This of course assumes that you are setting the view menu up correctly in the constructor for your view. Once this has been done, TMDIChild::EvMDIActivate() will call TFrameWindow::MergeMenu() when the active view changes.

I believe if you want to change the speed bar for different window types as the Borland IDE does that you would need to do this in EvMDIActivate for your TMDIChild descendent but I have not tried this yet.

This is done in your InitInstance() member of your application class AFTER the call to TApplication::InitInstance(), like this:

// If a command line argument was given, try to open it as a file

if (_argc == 2)

GetDocManager()->CreateDoc(&__dvt1, _argv[1], 0, 0);

__dvt1 is a doc/view template given at the top of your application .cpp. If you have more than one document type, you need to get the file extension from _argv[1] and use that to determine which __dvtx variable to use. If you have more than one view, you need to specify the one you want to open by default. F Note that this method doesn’t work with OWL 2.0.

There is no notification when a Document closes, but you can monitor for view closings and if you see the last view for a document closing add that item to the menu. Here is a code sample for an EvCloseView() method. Two variables, bool fAddedSeparator and the array char szFileCache[5][MAXPATH] were added to the application class, as well as changes in InitInstance() and ~TApplication() to read and write the cache list for the next time the program was started:

void myApp::EvCloseView (TView& view)

{

// Only update menu if this is the last view. TDocument::GetViewList() and

// TView::GetNextView() are undocumented public inline functions.

if (view.GetDocument().GetViewList()->GetNextView())

return;

const char *psz = view.GetDocument().GetDocPath();

// Don't update if there is no filename (After File|New...)

if (!psz)

return;

AddCacheTop(psz);

// Erase the existing menu items

TMenu menu(GetSubMenu(GetMainWindow()->GetMenu(), 0));

for (i = 0; i < nelems(szFileCache); i++)

menu.RemoveMenu(CM_FILE0+i, MF_BYCOMMAND);

// Put 'em on the menu

AddCachedFilenames(menu);

I don’t know if this is the best solution for updating this menu (other choices are requiring all of your documents to call a function when they are closed/destroyed and subclassing the document manager. nelems is a handy #define from K&R C which gives the number of elements in an array:

#define nelems(a) (sizeof (a)/sizeof (a)[0])

You will need to #define CM_FILE0 .. CM_FILEn in your .rh file, and you will need to write functions and response table entries to handle the menu items. (This example function only handles the first menu item, you would probably modify this to use a subroutine or a catch-all menu command function instead).

void myApp::CmFileCache0()

{

TryLoadDocument(szFileCache[0]);

}

I have not been able to find a good place to get the list of documents out of the document manager when the document manager is shutting down. I put this code in my applications CanClose which is generally called right before shutdown:

TDocument* doc = GetDocManager()->DocList.Next(0);

while (doc) {

AddCacheTop(doc->GetDocPath());

doc = GetDocManager()->DocList.Next(doc);

}

This code uses three subroutines I wrote:

void myApp::TryLoadDocument(const char *psz)

{

TDocument *doc;

if ((doc = GetDocManager()->FindDocument(psz)) != 0) {

GetDocManager()->PostDocError(*doc, IDS_DUPLICATEDOC);

return ;

}

GetDocManager()->CreateDoc(&__dvt2, psz, 0, 0);

}

void myApp::AddCachedFilenames(TMenu &menu)

{

// Add the menu items

char szBuffer[MAXPATH + 10];

for (int i = 0; i < nelems(szFileCache); i++)

if (szFileCache[i][0]) {

if (!fAddedSeparator) {

menu.AppendMenu(MF_BYCOMMAND|MF_SEPARATOR);

fAddedSeparator = TRUE;

}

wsprintf(szBuffer, "&%d %s", i+1, szFileCache[i]);

menu.AppendMenu(MF_BYCOMMAND|MF_ENABLED, CM_FILE0+i, szBuffer);

}

}

void myApp::AddCacheTop(const char *psz)

{

// Don't cache unnamed (File|New) documents

if (!psz)

return;

// psz must now be made first in szFileCache

for (int n = 0; n < nelems(szFileCache); )

if (stricmp(szFileCache[n++], psz) == 0)

break;

// Now copy the files down to allow the latest file to be first

for (int i = n-1; i > 0; i--)

strcpy(szFileCache[i], szFileCache[i-1]);

// Put the newly closed menu item at the top

strcpy(szFileCache[0], psz);

}

This routine adds the items under the last choice on the File menu, as the Borland IDE does. Newer programs like Microsoft Word ’95 seem to be adding the files before the exit item, so you may want to update this code. F Note that this method doesn’t work with OWL 2.0.

Common Pitfalls with Doc/View

Class Expert might know a lot about dialogs and such, but it doesn't know much about Doc/View and if you think it does you will make certain common errors:

1. Class Expert makes you think you want to derive from TListView. You probably don't.
2. Class Expert doesn't know about multiple inheritance. You are going to be using multiple inheritance if you are using something like a list box that isn't a TWindow. Get used to only seeing a few functions for your class even when there are actually dozens.
3. Class Expert doesn't know about StaticName(), because it is not virtual.
4. Class Expert doesn't know about the EV_VN_ notifications.
5. The code class expert will write for you often doesn't make any sense. For example, it will always put in a call to the base class's GetViewName(). You want to make sure you know what the call to the base class is doing.

I/O is done by TInStream and TOutStream classes. TFileDocument knows two things: How to open and close files, and how to create those streams. The actual I/O is going to be done by either a TDocument descendent or a TView descendent. TFileDocument isn't going to be doing any I/O.

TInStream and TOutStream are for writing out structs, not objects. All of the type information falls off your class as you write it to disk. You either need to prepend a word of type information before writing and look up the word in a table to call the correct constructor, or you need to use Borland's pstream, which do that for you. However, pstreams being what they are they don't mix well with regular streams. (You don't have to worry about this if you are writing out all of the same kind of object together, like the lines in the drawing example.)

First, do an experiment. Bring up the DOCVIEW example, and create a new line document. Set your pen to something thick, like 50, and draw some lazy meandering lines. Then use Window|Add View to add two copies of the view, and a single copy of line list view. Tile the windows, and then draw another line. Changes go to all of the views nicely. Then go to the line list view and change the color of a line. There is an ugly redraw.

In this case, the ugly redraw is unavoidable, because we changed the line and we want to see the change in all of the views. There is no way to "un-draw" a line easily. What you want to do is to make sure that you don't get this symptom unnecessarily. Keeping the data in the view keeps the system fast, but people like to be able to work on a single document in several different ways at the same time.

You forgot to set the style bits of your listbox, and it is trying to maintain an integral height. TListView uses the following modifications to the style bits:

Attr.Style &= ~(LBS_SORT);

Attr.Style |= (WS_HSCROLL | LBS_NOINTEGRALHEIGHT);

The standard way to not open a document is to return FALSE in ::Open(). However, that will not work unless you have the dtAutoOpen flag set, you will end up with an empty view instead of the "could not open document" message.

dtAutoOpen set up, you can display your own MessageBox and return TRUE if you want to accept the part of the file you could read, or FALSE if you want to fail the open.

If you need to throw exceptions when you fail, you probably want to catch them and return false so that your objects get cleared up correctly. The following seems to work inside open (you need a TRY, too):

CATCH( (xmsg& x)

{

GetDocManager().GetApplication()->Error(x, 0, 0);

return FALSE;

}

)

Not clearing up objects can cause the document manager to refuse to try to load them again if you aren't using dtAutoOpen.

In your EvNewView(), check for TDialog descendants:

bool fIsDialog = (TYPESAFE_DOWNCAST(&view, TDialog)) ?

TRUE : FALSE;

myMDIChild* child = new myMDIChild(*mdiClient,

view.GetViewName(), // caption

view.GetWindow(),

fIsDialog);

(This sets the frame to shrink to the view's initial size.)

if (fIsDialog)

child->Attr.Style &= ~(WS_THICKFRAME|WS_MAXIMIZEBOX);

(This makes the frame look like a modeless dialog's frame.)

TOcDocument and TOcView are used by TOleDocument and TOleView. By themselves, they are not Doc/View classes. TOcDocument isn’t derived from anything, and TOcView is derived from TUnknown, IBContainer, IBContains, and IBDropDest.

You need to subclass the document manager. Write a constructor and copy the function TDocManager::SelectDocPath(). Under Win’95, but NOT under NT, or the flag member of the ofn structure with OFN_EXPLORER (0x80000). (Under NT this seems to prevent the box from coming up at all. I haven’t tried this in an environment in which more than only template exists, so I am not sure if the hook still works.)

Glossary

Parent

(All of the examples use 0 for a parent, when would I put something else in?) The idea behind the parent is that documents can contain other documents as objects. For example, you can often insert a .BMP file by reference directly into a word processor. Because you aren't inserting the bits, you have another file, and you might want to have a graphical tool and be drawing on the picture in one window, and have the picture in a page of text in another. When you close the .BMP file you want to keep the word processing document up, but when you close the word processing document you want the .BMP to go away. The word processing document would then be considered the parent of the .BMP.

Property

Properties are facts about the document, like its filename and size. A lot of tricks are used with enums to get properties to inherit correctly. Properties also have the annoying problem of being any type, so you have to know what you want before you can get it. Properties defined in the base class TDocument are:

DocumentClass, // text

TemplateName, // text

ViewCount, // int

StoragePath, // text

DocTitle, // text

TFileDocument adds:

CreateTime, // FILETIME

ModifyTime, // FILETIME

AccessTime, // FILETIME

StorageSize, // unsigned long

FileHandle, // platform file handle (HFILE if Windows)

TStorageDocument adds:

CreateTime, // FILETIME

ModifyTime, // FILETIME

AccessTime, // FILETIME

StorageSize, // unsigned long

IStorageInstance, // IStorage*

TOleDocument doesn’t add any.

The example TDrawDocument for drawing lines adds:

LineCount,

Description,

etc.

Mix class

This is a class which is multiply derived from more than one class. It isn’t a Doc/View concept, but it is used in the documentation. An example is TWindowView, which mixes the functionality of TWindow and TView.

Appendix 1: Modes

1) This enum defines the document and open sharing modes used for constructing streams and storing data. Any constants that have the same functionality as those used by OLE 2.0 docfiles are indicated in the following table; for example, STGM_TRANSACTED, STGM_CONVERT, STGM_PRIORITY, and STGM_DELETEONRELEASE.

Although files are typically used for data storage, databases or spreadsheets can also be used. I/O streams rather than DOS use these bit values. Documents open the object used for storage in one of the following modes:

Constant Value Meaning

ofParent 0 A storage object is opened using the parent's mode.

ofRead 1 A storage object is opened for reading.

ofWrite 2 A storage object is opened for writing.

ofReadWrite 1|2 A storage object is opened for reading and writing.

ofAtEnd 4 Seek to end-of-file when opened originally.

ofAppend 8 Data is appended to the end of the storage object.

ofTruncate 10 An already existing file is truncated.

ofNoCreate 20 Open fails if file doesn't exist.

ofNoReplace 40 Open fails if file already exists.

ofBinary 80 Data is stored in a binary, not text, format. Carriage returns.

are not stripped.

ofIosMask FF All of the above bits are used by the ios class.

ofTransacted 1000 Changes to the storage object are preserved until the data is

either committed to permanent storage or discarded.

(STGM_TRANSACTED)

ofPreserve 2000 Backs up previous storage data using before creating a new

storage object with the same name. (STGM_CONVERT)

ofPriority 4000 Supports temporary, efficient reading before opening the storage.

(STGM_PRIORITY)

ofTemporary 8000 The storage or stream is automatically destroyed when it is

destructed. (STGM_DELETEONRELEASE)

3) These modes use used all over the place by the TDocument descendants and the document manager to figure out what it is supposed to be doing. So, when you look at a function, you have to figure out not only where it is called from and when it is called, but what modes were passed into it.

Appendix 2: Template constants

1) dtxxxx constants are used by TDocument and TDocTemplate to create templates. Several constants are equivalent to the OFN_xxxx constants defined by Windows in commdlg.h.

(All of the OFN_ flags relate to common dialog stuff. Look at the common dialog information in your help text.)

Appendix 3: Property flags

pfGetText    Property is accessible in a text format.
pfGetBinary    Property is accessible as a native nontext format.
pfConstant        Property can't be changed for the object instance.
pfSettable    Property can be set as a native format.
pfUnknown    Property is defined but unavailable for the object.
pfHidden           Property should be hidden from the user during normal browsing.
pfUserDef         Property has been user-defined at run time.

Appendix 4: Borland C++ and OWL versions

Borland C++ 3.x included OWL 1.x. OWL 1.x did not include Doc/View.

Borland C++ 4.0x included OWL 2.0x. OWL 2.0 included Doc/View, but not the OLE classes. It also didn’t have an AppExpert that could generate "Dialog Main Window" applications.

Borland C++ 4.5x and Turbo C++ 4.5 included OWL 2.5x. OWL 2.5 includes the OLE classes for Doc/View. It also supports a new built-in type, "bool". This replaces the old type "BOOL". The new type has two values, true and false. The old bool had TRUE and FALSE. Because this document was started in the old OWL 2.0 days, it uses bool for classes which existed in OWL 2.0. Note: The old BOOL is compatible with the new bool, so old programs will still compile. New programs should use "bool" unless they need to be distributed with source to people who are still using version 4.02.

Borland C++ 5.0 is to include OWL 3.0. This has not yet been released. At the time of this writing (9/13/95), OWL 3.0 promises "DocView enhancements for improved extensibility" but no details are available.

Resources for OWL programmers

There is an OWL mailing list. Details can be found on the WWW at http://www.mind.net/jfs/owl.html

There is an OWL newsgroup, comp.os.ms-windows.programmer.tools.owl

The only book I have found which discusses Doc/View is Object Windows 2.0 Programming by Tom Swan. Unlike some of the authors out there, Tom Swan knows OWL well, he even wrote some of the classes in OWL 2.0 such as TPrintout.

© Copyright

Regarding copyright, assume that everything marked with a 3) (that is, the stuff I wrote). is public domain.

I'm hoping everything marked with a 1) or a 2) is considered fair-use of Borland's copyrighted works...

Ed Snible

esnible@goodnet.com

Revised: December 04, 1999.