
HRESULT Clone(
IOleInPlaceSite *pIPSiteNew
IOleDocumentView **ppViewNew
);
Creates a duplicate view object with an internal state identical to that of the current view.
| S_OK | Success. |
| E_FAIL | The method was not successful. |
| E_NOTIMPL | The view object does not implement this interface. |
| E_POINTER | The value in the ppViewNew parameter is NULL. |
This method is useful for creating a new view with a different view port and view site but with the same view context as the view being cloned. Typically, containers hosting a multiple document interface (MDI) application will call this method to provide "Window/New window" capability.
HRESULT CloseView(
DWORD dwReserved
);
Instructs a document view to close and release its IOleInPlaceSite pointer.
When a separate window is no longer needed, the container calls IOleDocumentView::CloseView, whereupon the view releases its site pointer to the separate window and destroys the window. Unlike the normal in-place deactivation sequence for in-place active objects, a document view continues to hold the IOleInPlaceSite pointer. This pointer is released only when the view's container calls IOleDocumentView::SetInPlaceSite, with the pIPSite parameter set to NULL, or calls IOleDocumentView::CloseView.
When a user closes a view's window, the view should not shut itself down. Instead, it should call IOleInPlaceSite::OnInPlaceActivate. The view site then decides whether to call IOleDocumentView::UIActivate with FALSE to UI-deactivate the view immediately or later. In this way, a document view displayed in a window remains available for activation in the container's own window.
The container must call this method before it deletes the view, that is, releases its last reference to the view. In general, implementation of this method will call IOleDocumentView::Show with FALSE to hide the view if it is not already hidden, then call IOleDocumentView::SetInPlaceSite with NULL and release the view site pointer.
Because IOleDocumentView::CloseView is called when a container is going to completely shut down a view, this method must be implemented and has no reason to fail.
HRESULT GetDocument(
IUnknown **ppunk
);
Obtains the IUnknown interface pointer on the Active Document that owns this view.
The caller is responsible for incrementing the reference count on the interface pointer obtained by this method. The caller must call IUnknown::Release on this pointer when it is no longer needed.
Because a view object must always be contained or aggregated in an Active Document, this method will always succeed. Before returning, this method should call IUnknown::AddRef on the pointer in the ppunk parameter.
HRESULT GetInPlaceSite(
IOleInPlaceSite **ppIPSite
);
Retrieves the view site associated with this view object.
IOleDocumentView::GetInPlaceSite obtains the most recent IOleInPlaceSite pointer passed by IOleDocumentView::SetInPlaceSite, or NULL if IOleDocumentView::SetInPlaceSite has not yet been called. If this pointer is not NULL, this method will call IUnknown::AddRef on the pointer. The caller is responsible for releasing it. A document view must implement this method completely; E_NOTIMPL is not an acceptable return value.
HRESULT GetRect(
LPRECT prcView
);
Retrieves the rectangular coordinates of the view port in which the view is or will be activated.
For a single document interface (SDI) application, the view port is the client area of the frame window minus the space allocated for toolbars, status bar, and such. For a multiple document interface (MDI) window, the view port is the client area of the MDI document window minus any other frame-level user-interface elements.
The view port coordinates obtained by this method are those set in the most recent call to either the IOleDocumentView::SetRect or IOleDocumentView::SetRectComplex method.
A document view must implement this method completely; E_NOTIMPL is not an acceptable return value.
HRESULT Open(Void);
Displays the view in a separate pop-up window. The result is similar to calling IOleObject::DoVerb with OLEIVERB_OPEN.
| S_OK | Success. |
| E_FAIL | The method was not successful. |
| E_NOTIMPL | The Active Document that owns this view does not support separate window activation. |
| E_OUTOFMEMORY | There is not enough memory to complete this operation. |
| E_UNEXPECTED | The method was called at a time when the view object was not expecting it. |
A user viewing an Active Document in a container application such as a browser or binder might want to see two or more views or documents at once. Because the browser displays only one view at a time, the container needs a way to ask the other views or documents to display themselves, as required, in separate windows. The IOleDocumentView::Open method provides that way.
Notes to Callers
A successful call to IOleDocumentView::Open should be followed by a call to IOleDocumentView::Show to hide the window or to show the window and bring it to the foreground. While the view is active in its separate window, a container can show or hide the window as many times as it may require.
Notes to Implementers
An Active Document indicates that it does not support activation in a separate window by setting the DOCMISC_CANTOPENEDIT status flag and returning E_NOTIMPL to containers that call this method.
Implementation consists mainly of the view object calling its own IOleInPlaceObject::InPlaceDeactivate method, which leaves the Active Document in a running state but without in-place activation. The Active Document's user interface is not visible until the container calls IOleDocumentView::Show (see "Notes to Callers" above).
See also IOleDocumentView::CloseView, IOleDocumentView::UIActivate, IOleInPlaceSite, IOleInPlaceSite::OnInPlaceActivate
HRESULT SaveViewState(
IStream *pstm
);
Saves the view state into the specified stream.
| S_OK | Success. |
| E_NOTIMPL | This view has no meaningful state to save. |
| E_POINTER | The value in the pstm parameter is NULL. |
The E_NOTIMPL error should be rare because most views have at least some state information worth saving.
The view's state includes properties such as the view type, zoom factor, and location of insertion point. The container typically calls this function before deactivating the view. The stream can then later be used to reinitialize a view of the same document to this saved state through the IOleDocumentView::ApplyViewState method.
According to the rules governing the IPersistStream interface, a view must write its class identifier (CLSID) as the first element in the stream. Any cross-platform file format compatibility issues that apply to the document's storage representation also apply to this context.
HRESULT SetInPlaceSite(
IOleInPlaceSite * pIPSite
);
Associates a container's document view site with a document's document view object.
As part of activating an Active Document, a container must pass the object a pointer to the container's implementation of IOleInPlaceSite. This pointer designates the document view site that is to be associated with the view on which this method is called.
A container normally passes this pointer in response to a document's request to be activated. A document makes such a request by calling IOleDocumentSite::ActivateMe and passing the container a pointer to the view to be activated. The container, in turn, uses this pointer to call IOleDocumentView::SetInPlaceSite.
Notes to Callers
If the container is requesting creation and activation of a new instance of an Active Document, rather than merely the activation of a loaded instance of an Active Document, the view site is passed in the pIPSite argument of IOleDocument::CreateView. Therefore, an explicit call to IOleDocumentView::SetInPlaceSite is unnecessary.
Notes to Implementers
If this method is called on a view that is already associated with a view site, the view must do some housekeeping in preparation for activating itself in the new site. First, the view must deactivate itself in the current site and release its pointer to that site. Next, if the new IOleInPlaceSite pointer is not NULL, the view should both save the pointer and call IUnknown::AddRef on it. The view should then wait for the container to tell it when to activate itself in the new view site.
A document view must implement this method completely; E_NOTIMPL is not an acceptable return value.
See also IOleDocumentView::GetInPlaceSite
[input_sync] HRESULT SetRect(
LPRECT prcView
);
Sets the rectangular coordinates of the view port in which a view is to be activated, or resets the coordinates of the view port in which a view is currently activated.
For a single document interface (SDI) application, the view port is the client area of the frame window minus the space allocated for toolbars, status bar, and such. For a multiple document interface (MDI) window, the view port is the client area of the MDI document window minus any other frame-level user-interface elements.
Notes to Callers
Calling IOleDocumentView::SetRect or IOleDocumentView::SetRectComplex is part of the normal activation sequence for Active Documents, usually following a call to IOleDocumentView::UIActivate and preceding a call to IOleDocumentView::Show.
Whenever the window used to display an Active Document is resized, the container should call IOleDocumentView::SetRect (or IOleDocumentView::SetRectComplex) to tell the document view object to resize itself to the new window dimensions.
Notes to Implementers
The coordinates of the view port are within the coordinates of the view window, which is obtained through IOleWindow::GetWindow. The view must resize itself to fit the new coordinates passed in the prcView parameter.
This method is defined with the [input_sync] attribute, which means that the view object cannot yield or make another, non-input_sync RPC call while executing this method.
A document view must implement this method completely; E_NOTIMPL is not an acceptable return value.
[input_sync] HRESULT SetRectComplex(
LPRECT prcView,
LPRECT prcHScroll,
LPRECT prcVScroll,
LPRECT prcSizeBox
);
Sets the rectangular coordinates of the view port, horizontal and vertical scroll bars, and the size box.
| S_OK | Success. |
| E_FAIL | The method was not successful. |
| E_NOTIMPL | The Active Document doesn't support complex rectangles. |
View frames that support a workbook metaphor, in which a single document comprises multiple sheets or pages, typically call this method to set the coordinates to be used in common by all the sheets or pages.
Notes to Callers
Calling IOleDocumentView::SetRectComplex is part of the normal activation sequence for Active Documents that support complex rectangles, usually following a call to IOleDocumentView::UIActivate and preceding a call to IOleDocumentView::Show.
Whenever the window used to display an Active Document is resized, the container should call IOleDocumentView::SetRectComplex or IOleDocumentView::SetRect to tell the view object to resize itself to the new window dimensions.
Notes to Implementers
Active Documents that support complex rectangles mark themselves with DOCMISC_SUPPORTCOMPLEXRECTANGLES, as described in DOCMISC and IOleDocument::GetDocMiscStatus. Active Documents that do not support this method can return E_NOTIMPL.
Upon receiving a call to this method, a view should resize itself to fit the coordinates specified in prcView and fit its scroll bars and size box to the areas described in prcHScroll, prcVScroll, and prcSizeBox.
This method is defined with the [input_sync] attribute, which means that the implementing object cannot yield or make another, non-input_sync RPC call while executing this method.
HRESULT Show(
BOOL fShow
);
Requests a view to show or hide itself, activating or deactivating itself as necessary.
| S_OK | Success. |
| E_FAIL | The method was not successful. |
| E_OUTOFMEMORY | There was not enough memory to complete this operation. |
| E_UNEXPECTED | The method was called at an unexpected time. This is most likely due to the fact that the view object was not properly initialized before the Show method was called. |
Calling IOleDocumentView::Show is the last step in the activation sequence; before showing itself an Active Document must know exactly what space it occupies and have all its tools available.
Notes to Callers
A call to this method for the purpose of activating a view should follow calls to IOleDocumentView::SetInPlaceSite, IOleDocumentView::UIActivate, and IOleDocumentView::SetRect (or IOleDocumentView::SetRectComplex).
Notes to Implementers
Implementations of this method should embody the following pseudo-code.
if (fShow)
{
if(!fInPlaceActive)
{
//In-place activate the view but do not UI activate it.
}
//Show the view window.
}
else
{
if(fUIActive)
{
//UI-deactivate the view.
}
//Hide the view window.
}
All views of an Active Document must at least support in-place activation; E_NOTIMPL is not an acceptable return value.
HRESULT UIActivate(
BOOL fUIActivate
);
Activates or deactivates a document view's user interface elements, such as menus, toolbars, and accelerators.
| S_OK | Success. |
| E_FAIL | The method was not successful. |
| E_OUTOFMEMORY | There was not enough memory to complete this operation. |
| E_UNEXPECTED | The method was called at a time when it was not expected by the view object. |
Notes to Callers
Calling this method before calling IOleDocumentView::SetInPlaceSite returns E_UNEXPECTED, because the view must be associated with a view site before it can activate itself.
When IOleDocumentView::UIActivate is called as part of the activation sequence, the call should precede a call to IOleDocumentView::SetRect or IOleDocumentView::SetRectComplex, because otherwise the view dimensions would not account for toolbar space.
To deactivate a view, the container should call IOleDocumentView::Show with FALSE, followed by IOleDocumentView::UIActivate with FALSE.
Notes to Implementers
Implementations of this method should embody the following pseudo-code.
if (fActivate)
{
UI activate the view (do menu merging, show frame level tools, process accelerators)
Take focus, and bring the view window forward.
}
else
call IOleInPlaceObject::UIDeactivate on this view
In addition, the view can and should participate in extended Help menu merging.
All views of an Active Document must support in-place activation. E_NOTIMPL is not an acceptable return value.
The IPrint interface enables compound documents in general and Active Documents in particular to support programmatic printing. When a document is loaded, containers and other clients can call IPrint::Print to instruct a document to print itself, specifying printing control flags, the target device, the particular pages to print, and other options. The client can control the continuation of printing by calling the IContinueCallback interface.
An object that implements IPrint registers itself with the Printable key stored under its CLSID as follows:
HKEY_CLASSES_ROOT\CLSID\{...}\Printable
Callers determine whether a particular object class supports programmatic printing of its persistent state by looking in the registry for this key.
When to Implement
Implementing IPrint is optional. You usually implement IPrint on a view object.
When to Use
Call the methods of IPrint when you want an object to print its current state. Using this interface, a caller can tell the object to print itself, set the initial page number of the printed document, and obtain both the number of pages and the number of the first page to be printed.
Methods in Vtable Order
| IPrint methods | Description |
| SetInitialPageNum | Sets the page number of the first page. |
| GetPageInfo | Retrieves the number of pages and the number of the first page. |
| Prints the object's persistent state. |
HRESULT GetPageInfo(
LONG *pnFirstPage,
LONG *pcPages
);
Retrieves the number of a document's first page and the total number of pages.
HRESULT Print(
DWORD grfFlags,
DVTARGETDEVICE **pptd,
PAGESET **ppPageSet,
STGMEDIUM *pstgmOptions,
IContinueCallback *pCallback,
LONG nFirstPage,
LONG *pcPagesPrinted,
LONG *pnLastPage
);
Prints an object on the specified printer, using the specified job requirements.
| S_OK | Success. |
| PRINT_E_CANCELED | Printing was canceled before the operation completed. |
| PRINT_E_NOSUCHPAGE | A page specified in ppPageSet or nFirstPage does not exist. |
| E_UNEXPECTED | The method was called when it was not expected by the object. |
The printer on which the object is to be printed is indicated by the DVTARGETDEVICE structure pointed to by pptd. The DEVMODE structure in the target device indicates whole-job printer-specific options, such as number of copies, paper size, and print quality. The DEVMODE structure can also contain orientation information in the dmOrientation member (this is indicated in the dmFields member). If present, this paper orientation should be used; if absent, natural orientation as determined by the object content is to be used.
Due to the possibility of user input, the parameters pptd and ppPageSet are both [in,out] structures. In the absence of user interaction (that is, if the PRINTFLAG_PROMPTUSER flag is not set), both the target device and the page set will necessarily be the same for input and output. However, if the user is prompted for print options, the object returns target device and page-set information appropriate to what the user has actually chosen.
The pstgmOptions parameter is also [in,out]. On exit, the object should write to pstgmOptions any object-specific information that it would need to reproduce this exact print job. Examples might include whether the user selected "sheet, notes, or both" in a spreadsheet application. The data passed is in the format of a serialized property set. The data is normally useful only when passed back in a subsequent call to the same object. Because a subsequent call might specify different user interaction flags, target device, or other settings, the caller can cause the document to be printed multiple times in the same way in slightly different printing contexts.
HRESULT SetInitialPageNum(
LONG nFirstPage
);
Sets the number of the first page of a document.
| S_OK | Success. |
| E_FAIL | The method was not successful. |
| E_UNEXPECTED | The method was called when the object was not expecting it. |
Setting the first page to a negative number is valid. This can be useful in printing a portion of the document with page numbers that specify an offset from the usual pagination.
Not all implementations permit the initial page number to be set, as some implementations simply lack the information as to how the page number should be presented in the final output.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.