README.TXT
======================================================
Notes for Active Documents "Framer" (Container) Sample
======================================================
Framer is intended to demonstrate simple Active Document Objects hosting as
a container. That is, Framer demonstrates the basic support necessary to
host Active Documents. It is implemented according to the guidlines in the
"Active Documents Specification" document and has been tested against
Microsoft Word and Microsoft Excel as well as a few other OLE-enabled
applications that do not support Active Documents.
Framer itself has almost nothing in the way of its own user interface such
as a more complete host would, such as the Office Binder. Framer has these
menu commands available:
Command Description
----------------------------------------------------------------------
File Open Displays a File Open dialog and allows the user to select
a file. Framer will attempt to activate the file as an
Active Document. Failing that it will create a standard
embedded object and activate it in a separate window.
This command is disabled when an object already exists.
File/Close must be used before creating another object.
File Close Closes the document that is currently open; if the object
is just an embedding it will destroy that object which has
the effect of closing the server as well. Try opening
a .BMP file (which should activate PaintBrush, for instance)
and use Close to see the effect. There are some variations to
this behavior (see next section below).
File Exit Performs File/Close if necessary and terminates Framer.
Help About Displays Framer's About box. This command exists to
demonstrate Active Document Help menu merging.
Whenever Framer knows it has an object it displays a small message in its
client area to remind you that you have to File/Close before creating another.
Creating and Activating an Object
---------------------------------
Framer allows you to open documents regardless of whether or not
there is a server that supports Active Documents for the document
type and regardless of whether or not the document server even knows
about Active Documents at all.
When you "Open" a file in Framer, the code call OleCreateFromFile to create
an embedded object from the contents of the file. This has two possible
results:
1. If there is an Active Documents server associated with the file,
an embedded object initialized with the file contents is created.
2. If there is not an Active Documents server associated with the file,
a package object is created.
Immediately after creation, Framer activates the object with IOleObject::DoVerb
passing OLEIVERB_SHOW.
If the object is a true embedding with server support, one of two things
will happen:
1a. If the object doesn't know about Active Documents, it is activated in
another window. Using File/Close in this case will close the server.
Closing the server itself will cause Framer to do the equivalent
of File/Close, which frees the object and re-enables File/Open.
See CImpIIAdviseSink::OnClose in iadvsink.cpp. The closing
sequence is in CFrame::Close in framer.cpp. Using Framer with the
Paint application will demonstrate this behavior.
1b. If the object has Active Document support, then its server will start
activation sequence, primarily by calling IOleDocumentSite::ActivateMe
which is found in idocsite.cpp. Inside this member, Framer
then performs the standard sequence of document object activation
steps. After these steps the Active Document will be fully
interactive; using File/Close on the menu, which Framer still owns,
will deactivate the object through CFrame::Close which performs the
same set of steps as in #1b above. Using Framer with Microsoft Word
will demonstrate this behavior.
If you activate a package object, the result is that you launch an application
and have it open the file. Since the application has no OLE support in it
whatsoever, there is no communication link between Framer and that application.
This means that closing Framer will not close that other application. This is
what one observes with opening a .TXT file in Framer which will launch Notepad.
Once Notepad is running, it's separate and disconnected from Framer. You have
to close Notepad manually.
Framer might have been written to disallow insertion of files that do not have
Active Documents support. Framer rather demonstrates how to view any file
regardless of server support.
Help Menu Merging
-----------------
Framer implements the container side of the Help menu merging protocol
described in the Active Documents Specification. This involves the members
CFrame::InsertMenus, CFrame::SetMenu, and CFrame::RemoveMenus. The
InsertMenus method will install Framer's Help menu in the correct location
on the shared menu. The container-side popup used here is loaded from
Framer's resources on startup in CFrame::Init.
Inside CFrame::SetMenu, Framer checks if there's more than one item on
the menu added in InsertMenus. If so, then Framer remembers this fact
for later message handling. Otherwise Framer removes this menu from the
shared menu entirely as the dicument object itself isn't using this shared
capability.
Inside CFrame::RemoveMenus, Framer simply makes sure that its own Help
menu is removed as it should be.
The really interesting stuff happens in FrameWndProc (framer.cpp) in the
WM_INITMENU, WM_INITMENUPOPUP, WM_MENUSELECT, and WM_COMMAND cases. Inside
WM_INITMENU Framer clears a flag that indicates whether the last popup menu
that was being used was the object's additions to the Help menu. Inside
WM_MENUSELECT, Framer checks if the originating menu is a popup and if so,
it checks if that popup is on the shared "Help" popup, and if that is also
true then Framer checks if the item being used is the first one or some
other one. The first item is what Framer knows to be its own Help item, so
it just handles the messages as usual. Otherwise the user is working with
an Active Document-owned menu, so Framer sets the flag m_fInObjectHelp variable
to TRUE and forwards the message to the object's window (available from
IOleInPlaceObject::GetWindow).
As long as m_fInObjectHelp is set, Framer will forward WM_COMMAND,
WM_INITMENUPOPUP, and WM_MENUSELECT messages. As soon as another
WM_MENUSELECT message is seen for another non-object menu, then Framer
will reset the flag and begin processing messages once again itself.
In this way you'll see, with Microsoft Word for example, the correct
behavior of a shared Help popup. Note that Microsoft Excel does not
exhibit this shared Help menu behavior as it only displays its own
Help menus.
Known Feature Limitations
-------------------------
1. Framer does not print so it does not use the IPrint interface nor does
it implement IContinueCallback.
2. Framer does nothing with command targets.
3. Framer does not forward owner-draw menu messages to the object which
means that if owner-draw menus are used in a DocObject help menu,
this sample will not work correctly.
4. Framer does not provide for actually saving any changes made to an
Active Document. Because an Active Document is an embedding, Framer has
to provide an instance of IStorage through IPersistStorage::InitNew
or IPersistStorage::Load. It does this using a temporary Compound File
that is deleted when Framer exits. Therefore any changes made to the data
in the Active Document will simply be discarded.
Potential for Better UI
-----------------------
The item #4 above takes a little more explanation. When OleCreateFromFile is
used in the File/Open command, Framer is making a COPY of the file contents.
When an Active Document is activated with this content, the document has a copy
of the file contents, not the contents of the file itself. Therefore any
changes made there will not be reflected back into the original file, although
Framer's UI suggests that this should happen.
A real Active Document container like the Office Binder actually stores all the
object data in its own Compound File, not as separate files. If one needs
to have an Active Document save into a separate file, then the container needs
to either use command-targets or has to call IPersistFile::Save to accomplish
this step.
In short, Active Documents is not about activating the apps that manipulate
files; it's about activating embedded *documents* saved within the container
file *as if* those documents were stand alone.
Framer's UI, which is really inappropriate for DocObjects, exists as it does
for simplicity's sake.
A more appropraite container application would maintain its own "files" in
which it collected data from a number of other "documents" which are stored
simply as embedded objects. The Office Binder does exactly this, where
a "Binder" is a Compound File with sub-storages for each "section" in the
document.
Certainly with some more work on UI, Framer could become such an application.