|
|
/****************************************************************************
MsoCI.h
Owner: ClarG Copyright (c) 1995 Microsoft Corporation
This file contains the exported interfaces and declarations for Office Component Integration.****************************************************************************/
#ifndef MSOCI_H
#define MSOCI_H
#if !defined(MSOSTD_H)
#include <msostd.h>
#endif
#if !defined(MSOUSER_H)
#include <msouser.h>
#endif
#if !defined(MSODEBUG_H)
#include <msodebug.h>
#endif
#if MAC
#include <events.h>
#endif
/****************************************************************************
Component integration structures and constants****************************************************************************/
// Component registration flags
enum { msocrfNeedIdleTime = 1, // needs idle time
msocrfNeedPeriodicIdleTime = 2, // needs idle time every N milliseconds
msocrfPreTranslateKeys = 4, // must process keyboard msgs
// before translation
msocrfPreTranslateAll = 8, // must process all msgs
// before translation
msocrfNeedSpecActiveNotifs = 16, // needs to be notified for special
// activation changes (currently, this will
// notify comp if ExclusiveBorderSpace
// or ExclusiveActivation mode changes)
// Top-level comps should reg this flag.
msocrfNeedTopActiveNotifs = msocrfNeedSpecActiveNotifs, // old name
msocrfNeedAllActiveNotifs = 32, // needs to be notified for every
// change in activation state
msocrfExclusiveBorderSpace = 64, // needs exclusive border space when
// active (normally only used by TopLevel
// Mac components)
msocrfExclusiveActivation = 128, // comp becomes exclusively active
// when activated
};
// Component registration advise flags (see msocstate enumeration)
enum { msocadvfModal = 1, // needs modal state change notification
// (must be registered by components
// managing a toplevel window)
msocadvfRedrawOff = 2, // needs redrawOff state change notif
msocadvfWarningsOff = 4, // needs warningsOff state change notif
msocadvfRecording = 8, // needs Recording state change notif
};
// Component registration information
typedef struct _MSOCRINFO { ULONG cbSize; // size of MSOCRINFO structure in bytes.
ULONG uIdleTimeInterval; // If msocrfNeedPeriodicIdleTime is registered
// in grfcrf, component needs to perform
// periodic idle time tasks during an idle phase
// every uIdleTimeInterval milliseconds.
DWORD grfcrf; // bit flags taken from msocrf values (above)
DWORD grfcadvf; // bit flags taken from msocadvf values (above)
} MSOCRINFO;
// Component Host flags
enum { msochostfExclusiveBorderSpace = 1, // needs exclusive border space when
// active (normally only used by
// TopLevel Mac hosts)
};
// Component Host information
typedef struct _MSOCHOSTINFO { ULONG cbSize; // size of MSOCHOSTINFO structure in bytes.
DWORD grfchostf; // bit flags taken from msochostf values (above)
} MSOCHOSTINFO;
// idle flags, passed to IMsoComponent::FDoIdle and
// IMsoStdComponentMgr::FDoIdle.
enum { msoidlefPeriodic = 1, // periodic idle tasks
msoidlefNonPeriodic = 2, // any nonperiodic idle task
msoidlefPriority = 4, // high priority, nonperiodic idle tasks
msoidlefAll = -1 // all idle tasks
};
// Reasons for pushing a message loop, passed to
// IMsoComponentManager::FPushMessageLoop and
// IMsoComponentHost::FPushMessageLoop. The host should remain in message
// loop until IMsoComponent::FContinueMessageLoop
// (or IMsoStdComponentMgr::FContinueMessageLoop) returns FALSE.
enum { msoloopFocusWait = 1, // component is activating host
msoloopDoEvents = 2, // component is asking host to process messages
msoloopDebug = 3, // component has entered debug mode
msoloopModalForm = 4 // component is displaying a modal form
};
/* msocstate values: state IDs passed to
IMsoComponent::OnEnterState, IMsoComponentManager::OnComponentEnterState/FOnComponentExitState/FInState, IMsoComponentHost::OnComponentEnterState, IMsoStdComponentMgr::OnHostEnterState/FOnHostExitState/FInState. When the host or a component is notified through one of these methods that another entity (component or host) is entering or exiting a state identified by one of these state IDs, the host/component should take appropriate action: msocstateModal (modal state): If app is entering modal state, host/component should disable its toplevel windows, and reenable them when app exits this state. Also, when this state is entered or exited, host/component should notify approprate inplace objects via IOleInPlaceActiveObject::EnableModeless. msocstateRedrawOff (redrawOff state): If app is entering redrawOff state, host/component should disable repainting of its windows, and reenable repainting when app exits this state. msocstateWarningsOff (warningsOff state): If app is entering warningsOff state, host/component should disable the presentation of any user warnings, and reenable this when app exits this state. msocstateRecording (Recording state): Used to notify host/component when Recording is turned on or off. */enum { msocstateModal = 1, // modal state; disable toplevel windows
msocstateRedrawOff = 2, // redrawOff state; disable window repainting
msocstateWarningsOff = 3, // warningsOff state; disable user warnings
msocstateRecording = 4, // Recording state
};
/* ** Comments on State Contexts **
IMsoComponentManager::FCreateSubComponentManager allows one to create a hierarchical tree of component managers. This tree is used to maintain multiple contexts with regard to msocstateXXX states. These contexts are referred to as 'state contexts'. Each component manager in the tree defines a state context. The components registered with a particular component manager or any of its descendents live within that component manager's state context. Calls to IMsoComponentManager::OnComponentEnterState/FOnComponentExitState can be used to affect all components, only components within the component manager's state context, or only those components that are outside of the component manager's state context. IMsoComponentManager::FInState is used to query the state of the component manager's state context at its root.
msoccontext values: context indicators passed to IMsoComponentManager::OnComponentEnterState/FOnComponentExitState. These values indicate the state context that is to be affected by the state change. In IMsoComponentManager::OnComponentEnterState/FOnComponentExitState, the comp mgr informs only those components/host that are within the specified state context. */enum { msoccontextAll = 0, // all state contexts in state context tree
msoccontextMine = 1, // component manager's state context
msoccontextOthers = 2, // all other state contexts outside of comp mgr's
};
/* ** WM_MOUSEACTIVATE Note (for top level compoenents and host) **
If the active (or tracking) comp's reg info indicates that it wants mouse messages, then no MA_xxxANDEAT value should be returned from WM_MOUSEACTIVATE, so that the active (or tracking) comp will be able to process the resulting mouse message. If one does not want to examine the reg info, no MA_xxxANDEAT value should be returned from WM_MOUSEACTIVATE if any comp is active (or tracking). One can query the reg info of the active (or tracking) component at any time via IMsoComponentManager::FGetActiveComponent. */
/* msogac values: values passed to
IMsoComponentManager::FGetActiveComponent. */ enum { msogacActive = 0, // retrieve true active component
msogacTracking = 1, // retrieve tracking component
msogacTrackingOrActive = 2, // retrieve tracking component if one exists,
// otherwise retrieve true active component
};
/* msocWindow values: values passed to IMsoComponent::HwndGetWindow. */ enum { msocWindowFrameToplevel = 0, /* MDI Apps should return the MDI frame (not MDI client) or App frame
window, and SDI Apps should return the frame window which hosts the component. Basically it should be the topmost window which owns the component. For a toolbar set this will be the toplevel owner of TBS::m_hwnd. */
msocWindowFrameOwner = 1, /* This is the window which owns the component. It could be same as
the window obtained by msocWindowFrameTopLevel or be an owned window of that window. For a toolbar set this will be TBS::m_hwnd. */
msocWindowComponent = 2, /* This is the "main" window of the component (if it has one). */
msocWindowDlgOwner = 3, /* Caller wishes to display a dialog to be parented by the component.
Component should return a window suitable for use as the dialog's owner window. */ };
/****************************************************************************
Defines the IMsoComponent interface
Any component that needs idle time, the ability to process messages before they are translated (for example, to call TranslateAccelerator or IsDialogMessage), notification about modal states, or the ability push message loops must implement this interface and register with the Component Manager.****************************************************************************/#undef INTERFACE
#define INTERFACE IMsoComponent
DECLARE_INTERFACE_(IMsoComponent, IUnknown) { BEGIN_MSOINTERFACE // *** IUnknown methods ***
MSOMETHOD(QueryInterface) (THIS_ REFIID riid, void **ppvObj) PURE; MSOMETHOD_(ULONG, AddRef) (THIS) PURE; MSOMETHOD_(ULONG, Release) (THIS) PURE;
/* Standard FDebugMessage method.
Since IMsoComponent is a reference counted interface, MsoDWGetChkMemCounter should be used when processing the msodmWriteBe message. */ MSODEBUGMETHOD
/* Give component a chance to process the message pMsg before it is
translated and dispatched. Component can do TranslateAccelerator, do IsDialogMessage, modify pMsg, or take some other action. Return TRUE if the message is consumed, FALSE otherwise. */ MSOMETHOD_(BOOL, FPreTranslateMessage) (THIS_ MSG *pMsg) PURE;
#if MAC
/* Give Macintosh component a chance to process the event pEvt
before it is processed by the host. Return TRUE if the event is consumed, FALSE otherwise. (WLM components can simply return FALSE.) */ MSOMETHOD_(BOOL, FPreProcessMacEvent) (THIS_ EventRecord *pEvt) PURE;#endif // MAC
/* Notify component when app enters or exits (as indicated by fEnter)
the state identified by uStateID (a value from msocstate enumeration). Component should take action depending on value of uStateID (see msocstate comments, above). Note: If n calls are made with TRUE fEnter, component should consider the state to be in effect until n calls are made with FALSE fEnter. Note: Components should be aware that it is possible for this method to be called with FALSE fEnter more times than it was called with TRUE fEnter (so, for example, if component is maintaining a state counter (incremented when this method is called with TRUE fEnter, decremented when called with FALSE fEnter), the counter should not be decremented for FALSE fEnter if it is already at zero.) */ MSOMETHOD_(void, OnEnterState) (THIS_ ULONG uStateID, BOOL fEnter) PURE;
/* Notify component when the host application gains or loses activation.
If fActive is TRUE, the host app is being activated and dwOtherThreadID is the ID of the thread owning the window being deactivated. If fActive is FALSE, the host app is being deactivated and dwOtherThreadID is the ID of the thread owning the window being activated. Note: this method is not called when both the window being activated and the one being deactivated belong to the host app. */ MSOMETHOD_(void, OnAppActivate) (THIS_ BOOL fActive, DWORD dwOtherThreadID) PURE; /* Notify the active component that it has lost its active status because
the host or another component has become active. */ MSOMETHOD_(void, OnLoseActivation) (THIS) PURE;
/* Notify component when a new object is being activated.
If pic is non-NULL, then it is the component that is being activated. In this case, fSameComponent is TRUE if pic is the same component as the callee of this method, and pcrinfo is the reg info of pic. If pic is NULL and fHostIsActivating is TRUE, then the host is the object being activated, and pchostinfo is its host info. If pic is NULL and fHostIsActivating is FALSE, then there is no current active object.
If pic is being activated and pcrinfo->grf has the msocrfExclusiveBorderSpace bit set, component should hide its border space tools (toolbars, status bars, etc.); component should also do this if host is activating and pchostinfo->grfchostf has the msochostfExclusiveBorderSpace bit set. In either of these cases, component should unhide its border space tools the next time it is activated.
If pic is being activated and pcrinfo->grf has the msocrfExclusiveActivation bit is set, then pic is being activated in "ExclusiveActive" mode. Component should retrieve the top frame window that is hosting pic (via pic->HwndGetWindow(msocWindowFrameToplevel, 0)). If this window is different from component's own top frame window, component should disable its windows and do other things it would do when receiving OnEnterState(msocstateModal, TRUE) notification. Otherwise, if component is top-level, it should refuse to have its window activated by appropriately processing WM_MOUSEACTIVATE (but see WM_MOUSEACTIVATE NOTE, above). Component should remain in one of these states until the ExclusiveActive mode ends, indicated by a future call to OnActivationChange with ExclusiveActivation bit not set or with NULL pcrinfo. */ MSOMETHOD_(void, OnActivationChange) (THIS_ IMsoComponent *pic, BOOL fSameComponent, const MSOCRINFO *pcrinfo, BOOL fHostIsActivating, const MSOCHOSTINFO *pchostinfo, DWORD dwReserved) PURE;
/* Give component a chance to do idle time tasks. grfidlef is a group of
bit flags taken from the enumeration of msoidlef values (above), indicating the type of idle tasks to perform. Component may periodically call IMsoComponentManager::FContinueIdle; if this method returns FALSE, component should terminate its idle time processing and return. Return TRUE if more time is needed to perform the idle time tasks, FALSE otherwise. Note: If a component reaches a point where it has no idle tasks and does not need FDoIdle calls, it should remove its idle task registration via IMsoComponentManager::FUpdateComponentRegistration. Note: If this method is called on while component is performing a tracking operation, component should only perform idle time tasks that it deems are appropriate to perform during tracking. */ MSOMETHOD_(BOOL, FDoIdle) (THIS_ DWORD grfidlef) PURE; /* Called during each iteration of a message loop that the component
pushed. uReason and pvLoopData are the reason and the component private data that were passed to IMsoComponentManager::FPushMessageLoop. This method is called after peeking the next message in the queue (via PeekMessage) but before the message is removed from the queue. The peeked message is passed in the pMsgPeeked param (NULL if no message is in the queue). This method may be additionally called when the next message has already been removed from the queue, in which case pMsgPeeked is passed as NULL. Return TRUE if the message loop should continue, FALSE otherwise. If FALSE is returned, the component manager terminates the loop without removing pMsgPeeked from the queue. */ MSOMETHOD_(BOOL, FContinueMessageLoop) (THIS_ ULONG uReason, void *pvLoopData, MSG *pMsgPeeked) PURE;
/* Called when component manager wishes to know if the component is in a
state in which it can terminate. If fPromptUser is FALSE, component should simply return TRUE if it can terminate, FALSE otherwise. If fPromptUser is TRUE, component should return TRUE if it can terminate without prompting the user; otherwise it should prompt the user, either 1.) asking user if it can terminate and returning TRUE or FALSE appropriately, or 2.) giving an indication as to why it cannot terminate and returning FALSE. */ MSOMETHOD_(BOOL, FQueryTerminate) (THIS_ BOOL fPromptUser) PURE; /* Called when component manager wishes to terminate the component's
registration. Component should revoke its registration with component manager, release references to component manager and perform any necessary cleanup. */ MSOMETHOD_(void, Terminate) (THIS) PURE;
/* Called to retrieve a window associated with the component, as specified
by dwWhich, a msocWindowXXX value (see msocWindow, above). dwReserved is reserved for future use and should be zero. Component should return the desired window or NULL if no such window exists. */ MSOMETHOD_(HWND, HwndGetWindow) (THIS_ DWORD dwWhich, DWORD dwReserved) PURE; };
/****************************************************************************
Defines the IMsoComponentManager interface
A component manager is an object implementing the IMsoComponentManager interface. The component manager coordinates components with its message loop for proper distribution of idle time and pre-translation message processing. It also coordinates modalities and the pushing of message loops. The host application can implement its own component manager and register it via MsoFSetComponentManager or it can make use of the office supplied component manager via MsoFCreateStdComponentManager.****************************************************************************/#undef INTERFACE
#define INTERFACE IMsoComponentManager
DECLARE_INTERFACE_(IMsoComponentManager, IUnknown) { BEGIN_MSOINTERFACE // *** IUnknown methods ***
MSOMETHOD(QueryInterface) (THIS_ REFIID riid, void **ppvObj) PURE; MSOMETHOD_(ULONG, AddRef) (THIS) PURE; MSOMETHOD_(ULONG, Release) (THIS) PURE;
/* Return in *ppvObj an implementation of interface iid for service
guidService (same as IServiceProvider::QueryService). Return NOERROR if the requested service is supported, otherwise return NULL in *ppvObj and an appropriate error (eg E_FAIL, E_NOINTERFACE). */ MSOMETHOD(QueryService) (THIS_ REFGUID guidService, REFIID iid, void **ppvObj) PURE;
/* Standard FDebugMessage method.
Since IMsoComponentManager is a reference counted interface, MsoDWGetChkMemCounter should be used when processing the msodmWriteBe message. */ MSODEBUGMETHOD
/* Register component piComponent and its registration info pcrinfo with
this component manager. Return in *pdwComponentID a cookie which will identify the component when it calls other IMsoComponentManager methods. Return TRUE if successful, FALSE otherwise. */ MSOMETHOD_(BOOL, FRegisterComponent) (THIS_ IMsoComponent *piComponent, const MSOCRINFO *pcrinfo, DWORD *pdwComponentID) PURE; /* Undo the registration of the component identified by dwComponentID
(the cookie returned from the FRegisterComponent method). Return TRUE if successful, FALSE otherwise. */ MSOMETHOD_(BOOL, FRevokeComponent) (THIS_ DWORD dwComponentID) PURE; /* Update the registration info of the component identified by
dwComponentID (the cookie returned from FRegisterComponent) with the new registration information pcrinfo. Typically this is used to update the idle time registration data, but can be used to update other registration data as well. Return TRUE if successful, FALSE otherwise. */ MSOMETHOD_(BOOL, FUpdateComponentRegistration) (THIS_ DWORD dwComponentID, const MSOCRINFO *pcrinfo) PURE; /* Notify component manager that component identified by dwComponentID
(cookie returned from FRegisterComponent) has been activated. The active component gets the chance to process messages before they are dispatched (via IMsoComponent::FPreTranslateMessage) and typically gets first crack at idle time after the host. This method fails if another component is already Exclusively Active. In this case, FALSE is returned and SetLastError is set to msoerrACompIsXActive (comp usually need not take any special action in this case). Return TRUE if successful. */ MSOMETHOD_(BOOL, FOnComponentActivate) (THIS_ DWORD dwComponentID) PURE; /* Called to inform component manager that component identified by
dwComponentID (cookie returned from FRegisterComponent) wishes to perform a tracking operation (such as mouse tracking). The component calls this method with fTrack == TRUE to begin the tracking operation and with fTrack == FALSE to end the operation. During the tracking operation the component manager routes messages to the tracking component (via IMsoComponent::FPreTranslateMessage) rather than to the active component. When the tracking operation ends, the component manager should resume routing messages to the active component. Note: component manager should perform no idle time processing during a tracking operation other than give the tracking component idle time via IMsoComponent::FDoIdle. Note: there can only be one tracking component at a time. Return TRUE if successful, FALSE otherwise. */ MSOMETHOD_(BOOL, FSetTrackingComponent) (THIS_ DWORD dwComponentID, BOOL fTrack) PURE;
/* Notify component manager that component identified by dwComponentID
(cookie returned from FRegisterComponent) is entering the state identified by uStateID (msocstateXXX value). (For convenience when dealing with sub CompMgrs, the host can call this method passing 0 for dwComponentID.) Component manager should notify all other interested components within the state context indicated by uContext (a msoccontextXXX value), excluding those within the state context of a CompMgr in rgpicmExclude, via IMsoComponent::OnEnterState (see "Comments on State Contexts", above). Component Manager should also take appropriate action depending on the value of uStateID (see msocstate comments, above). dwReserved is reserved for future use and should be zero.
rgpicmExclude (can be NULL) is an array of cpicmExclude CompMgrs (can include root CompMgr and/or sub CompMgrs); components within the state context of a CompMgr appearing in this array should NOT be notified of the state change (note: if uContext is msoccontextMine, the only CompMgrs in rgpicmExclude that are checked for exclusion are those that are sub CompMgrs of this Component Manager, since all other CompMgrs are outside of this Component Manager's state context anyway.)
Note: Calls to this method are symmetric with calls to FOnComponentExitState. That is, if n OnComponentEnterState calls are made, the component is considered to be in the state until n FOnComponentExitState calls are made. Before revoking its registration a component must make a sufficient number of FOnComponentExitState calls to offset any outstanding OnComponentEnterState calls it has made.
Note: inplace objects should not call this method with uStateID == msocstateModal when entering modal state. Such objects should call IOleInPlaceFrame::EnableModeless instead. */ MSOMETHOD_(void, OnComponentEnterState) (THIS_ DWORD dwComponentID, ULONG uStateID, ULONG uContext, ULONG cpicmExclude, IMsoComponentManager **rgpicmExclude, DWORD dwReserved) PURE; /* Notify component manager that component identified by dwComponentID
(cookie returned from FRegisterComponent) is exiting the state identified by uStateID (a msocstateXXX value). (For convenience when dealing with sub CompMgrs, the host can call this method passing 0 for dwComponentID.) uContext, cpicmExclude, and rgpicmExclude are as they are in OnComponentEnterState. Component manager should notify all appropriate interested components (taking into account uContext, cpicmExclude, rgpicmExclude) via IMsoComponent::OnEnterState (see "Comments on State Contexts", above). Component Manager should also take appropriate action depending on the value of uStateID (see msocstate comments, above). Return TRUE if, at the end of this call, the state is still in effect at the root of this component manager's state context (because the host or some other component is still in the state), otherwise return FALSE (ie. return what FInState would return). Caller can normally ignore the return value. Note: n calls to this method are symmetric with n calls to OnComponentEnterState (see OnComponentEnterState comments, above). */ MSOMETHOD_(BOOL, FOnComponentExitState) (THIS_ DWORD dwComponentID, ULONG uStateID, ULONG uContext, ULONG cpicmExclude, IMsoComponentManager **rgpicmExclude) PURE;
/* Return TRUE if the state identified by uStateID (a msocstateXXX value)
is in effect at the root of this component manager's state context, FALSE otherwise (see "Comments on State Contexts", above). pvoid is reserved for future use and should be NULL. */ MSOMETHOD_(BOOL, FInState) (THIS_ ULONG uStateID, void *pvoid) PURE; /* Called periodically by a component during IMsoComponent::FDoIdle.
Return TRUE if component can continue its idle time processing, FALSE if not (in which case component returns from FDoIdle.) */ MSOMETHOD_(BOOL, FContinueIdle) (THIS) PURE;
/* Component identified by dwComponentID (cookie returned from
FRegisterComponent) wishes to push a message loop for reason uReason. uReason is one the values from the msoloop enumeration (above). pvLoopData is data private to the component. The component manager should push its message loop, calling IMsoComponent::FContinueMessageLoop(uReason, pvLoopData) during each loop iteration (see IMsoComponent::FContinueMessageLoop comments). When IMsoComponent::FContinueMessageLoop returns FALSE, the component manager terminates the loop. Returns TRUE if component manager terminates loop because component told it to (by returning FALSE from IMsoComponent::FContinueMessageLoop), FALSE if it had to terminate the loop for some other reason. In the latter case, component should perform any necessary action (such as cleanup). */ MSOMETHOD_(BOOL, FPushMessageLoop) (THIS_ DWORD dwComponentID, ULONG uReason, void *pvLoopData) PURE;
/* Cause the component manager to create a "sub" component manager, which
will be one of its children in the hierarchical tree of component managers used to maintiain state contexts (see "Comments on State Contexts", above). piunkOuter is the controlling unknown (can be NULL), riid is the desired IID, and *ppvObj returns the created sub component manager. piunkServProv (can be NULL) is a ptr to an object supporting IServiceProvider interface to which the created sub component manager will delegate its IMsoComponentManager::QueryService calls. (see objext.h or docobj.h for definition of IServiceProvider). Returns TRUE if successful. */ MSOMETHOD_(BOOL, FCreateSubComponentManager) (THIS_ IUnknown *piunkOuter, IUnknown *piunkServProv, REFIID riid, void **ppvObj) PURE;
/* Return in *ppicm an AddRef'ed ptr to this component manager's parent
in the hierarchical tree of component managers used to maintain state contexts (see "Comments on State Contexts", above). Returns TRUE if the parent is returned, FALSE if no parent exists or some error occurred. */ MSOMETHOD_(BOOL, FGetParentComponentManager) (THIS_ IMsoComponentManager **ppicm) PURE;
/* Return in *ppic an AddRef'ed ptr to the current active or tracking
component (as indicated by dwgac (a msogacXXX value)), and its registration information in *pcrinfo. ppic and/or pcrinfo can be NULL if caller is not interested these values. If pcrinfo is not NULL, caller should set pcrinfo->cbSize before calling this method. Returns TRUE if the component indicated by dwgac exists, FALSE if no such component exists or some error occurred. dwReserved is reserved for future use and should be zero. */ MSOMETHOD_(BOOL, FGetActiveComponent) (THIS_ DWORD dwgac, IMsoComponent **ppic, MSOCRINFO *pcrinfo, DWORD dwReserved) PURE; };
/****************************************************************************
Defines the IMsoStdComponentMgr interface
IMsoStdComponentMgr is an interface exposed by the office supplied standard component manager, created by MsoFCreateStdComponentMgr. The host application uses this interface to communicate directly with the standard component manager and indirectly with registered components. By making appropriate calls to this interface and implementing IMsoComponentHost the host can avoid implementing its own IMsoComponentManager interface.****************************************************************************/#undef INTERFACE
#define INTERFACE IMsoStdComponentMgr
DECLARE_INTERFACE_(IMsoStdComponentMgr, IUnknown) { BEGIN_MSOINTERFACE // *** IUnknown methods ***
MSOMETHOD(QueryInterface) (THIS_ REFIID riid, void **ppvObj) PURE; MSOMETHOD_(ULONG, AddRef) (THIS) PURE; MSOMETHOD_(ULONG, Release) (THIS) PURE;
/* Standard FDebugMessage method.
Since IMsoStdComponentMgr is a reference counted interface, MsoDWGetChkMemCounter is used when processing the msodmWriteBe message. */ MSODEBUGMETHOD
/* Set *pchostinfo as the host info. Can be called multiple times.
Returns TRUE if successful. */ MSOMETHOD_(BOOL, FSetHostInfo) (THIS_ const MSOCHOSTINFO *pchostinfo) PURE;
/* Host calls this method to give the active component a chance to
process messages before they are translated and dispatched. The host need not call this method if no component is active. When this method is called on message pMsg, StdComponentMgr in turn calls IMsoComponent::FPreTranslateMessage on the active component if its registration info indicates that it is interested. Returns TRUE if message is consumed, in which case the host should perform no further processing on the message. Returns FALSE otherwise. */ MSOMETHOD_(BOOL, FPreTranslateMessage) (THIS_ MSG *pMsg) PURE;
#if MAC
/* On Macintosh, host calls this method to give the active component a
chance to process events before they are processed by the host. The host need not call this method if no component is active. When this method is called on event pEvt, StdComponentMgr in turn calls IMsoComponent::FPreProcessMacEvent on the active component if its registration info indicates that it is interested. Returns TRUE if event is consumed, in which case the host should perform no further processing on the event. Returns FALSE otherwise. */ MSOMETHOD_(BOOL, FPreProcessMacEvent) (THIS_ EventRecord *pEvt) PURE;#endif // MAC
/* Called by host to notify StdComponentMgr that one of the host's windows
has been activated. This causes the current active component to lose its active status. However, host should not assume that the component is no longer active until IMsoComponentHost::OnComponentActivate(NULL) is called. This method fails if a component is already Exclusively Active. In this case, FALSE is returned and SetLastError is set to msoerrACompIsXActive (host usually need not take any special action in this case). Returns TRUE if successful. */ MSOMETHOD_(BOOL, FOnHostActivate) (THIS) PURE;
/* Called by host to notify StdComponentMgr that host is entering the
state identified by uStateID (a msocstateXXX value). StdComponentMgr in turn notifies all interested components excluding those within the context of a CompMgr appearing in rgpicmExclude (an array (can be NULL) of cpicmExclude CompMgrs (can include root CompMgr and/or sub CompMgrs)). dwReserved is reserved for future use and should be zero. Note: Calls to this method are symmetric with FOnHostExitState calls. That is, if n OnHostEnterState calls are made, the host is considered to be in the state until n FOnHostExitState calls are made. */ MSOMETHOD_(void, OnHostEnterState) (THIS_ ULONG uStateID, ULONG cpicmExclude, IMsoComponentManager **rgpicmExclude, DWORD dwReserved) PURE;
/* Called by host to notify StdComponentMgr that host is exiting the state
identified by uStateID (a msocstateXXX value). StdComponentMgr in turn notifies all interested components excluding those within the context of a CompMgr appearing in rgpicmExclude (an array (can be NULL) of cpicmExclude CompMgrs (can include root CompMgr and/or sub CompMgrs)). Returns TRUE if the state is still in effect at the end of this call (because some component is still in the state), otherwise returns FALSE (ie. returns what FInState would return). Caller can normally ignore the return value. Note: n calls to this method are symmetric with n calls to OnHostEnterState (see OnHostEnterState comments, above). */ MSOMETHOD_(BOOL, FOnHostExitState) (THIS_ ULONG uStateID, ULONG cpicmExclude, IMsoComponentManager **rgpicmExclude) PURE;
/* Returns TRUE if state identified by uStateID (a value from msocstate
enumeration) is in effect, FALSE otherwise. pvoid is reserved for future use and should be NULL. */ MSOMETHOD_(BOOL, FInState) (THIS_ ULONG uStateID, void *pvoid) PURE; /* Called by host to give registered components the chance to perform idle
time tasks of the type indicated by grfidlef, a group of bit flags taken from the enumeration of msoidlef values (above). During a component tracking operation, StdComponentMgr only gives the tracking component idle time. Returns TRUE if any component needs more time to perform the idle time tasks, FALSE otherwise. */ MSOMETHOD_(BOOL, FDoIdle) (THIS_ DWORD grfidlef) PURE;
/* Called by host just before it enters the 'wait mode' resulting from a
call to WaitMessage, GetMessage, or MsgWaitForMultipleObjects. Such a 'wait mode' would prevent any components from receiving periodic idle time. If any registered components need periodic idle time, StdCompMgr starts an appropriate timer. The resulting WM_TIMER message will cause the host to exit the 'wait mode', allowing the processing of periodic idle time tasks when the host calls IMsoStdComponentMgr::FDoIdle. */ MSOMETHOD_(void, OnWaitForMessage) (THIS) PURE;
/* Called by host during each iteration of a message loop that a component
pushed. This method is to be called after peeking the next message in the queue (via PeekMessage) but before the message is removed from the queue. The peeked message is passed in the pMsgPeeked param (NULL if no message is in the queue). If this method is additionally called when the next message has already been removed from the queue, pMsgPeeked should be passed as NULL. StdComponentMgr in turn calls IMsoComponent::FContinueMessageLoop on the component, and returns the value returned by that call. Returns TRUE if the message loop should continue, FALSE otherwise. If FALSE is returned, the loop should be terminated without removing pMsgPeeked from the queue. */ MSOMETHOD_(BOOL, FContinueMessageLoop) (THIS_ MSG *pMsgPeeked) PURE;
/* Called by host to determine if all registered components can terminate.
StdComponentMgr asks each component whether it can terminate via IMsoComponent::FQueryTerminate(fPromptUser). If all components return TRUE, then StdComponentMgr returns TRUE. If any one of the components returns FALSE, then StdComponentMgr immediately returns FALSE without asking any more components. */ MSOMETHOD_(BOOL, FQueryTerminate) (THIS_ BOOL fPromptUser) PURE;
/* Called by host to terminate the StdComponentMgr.
If fRevoke is TRUE and StdComponentMgr is registered as the current thread's component manager, this registration is revoked. Then, for each registered component, StdComponentMgr calls IMsoComponent::Terminate and revokes its registration. */ MSOMETHOD_(void, Terminate) (THIS_ BOOL fRevoke) PURE; };
/****************************************************************************
Defines the IMsoComponentHost interface
IMsoComponentHost is a host implemented interface that the standard component manager uses to communicate with the host. By implementing this interface and making use of the standard component manager, the host can avoid having to implement its own component manager. ****************************************************************************/#undef INTERFACE
#define INTERFACE IMsoComponentHost
DECLARE_INTERFACE_(IMsoComponentHost, IUnknown) { BEGIN_MSOINTERFACE // *** IUnknown methods ***
MSOMETHOD(QueryInterface) (THIS_ REFIID riid, void **ppvObj) PURE; MSOMETHOD_(ULONG, AddRef) (THIS) PURE; MSOMETHOD_(ULONG, Release) (THIS) PURE;
/* StdComponentMgr delegates calls to IMsoComponentManager::QueryService
to the host by calling this method. Return in *ppvObj an implementation of interface iid for service guidService (same as IServiceProvider::QueryService). Return NOERROR if the requested service is supported, otherwise return NULL in *ppvObj and an appropriate error (eg E_FAIL, E_NOINTERFACE). */ MSOMETHOD(QueryService) (THIS_ REFGUID guidService, REFIID iid, void **ppvObj) PURE;
/* Standard FDebugMessage method.
Since IMsoComponentHost is a reference counted interface, MsoDWGetChkMemCounter should be used when processing the msodmWriteBe message. */ MSODEBUGMETHOD
/* Called when component pic is activated (or should be treated as active
by virtue of beginning a "tracking" operation (see IMsoComponentManager::FSetTrackingComponent)). pcrinfo contains component's registration information. fTracking indicates whether the component is in tracking mode or not. If pic is NULL (in which case pcrinfo will be NULL), then this indicates that no component is active. When a component is active and its registration info indicates that it needs to process untranslated messages, the host must call IMsoStdComponentMgr::FPreTranslateMessage for each appropriate message retrieved from the queue before processing it, so that the active component gets a chance to process the message appropriately. (A simple host could avoid examining the component's registration info, and simply call IMsoStdComponentMgr::FPreTranslateMessage for all retrieved messages.) If the component is in tracking mode, as indicated by fTracking, then the host app should perform no idle time processing other than to give the tracking component idle time via IMsoStdComponentMgr::FDoIdle, until the tracking operation is completed (communicated to host via a subsequent call to OnComponentActivate with fTracking == FALSE).
Additionally, if pic is nonNULL and fTracking is FALSE, then host should check if pcrinfo->grfcrf has the ExclusiveActive or ExclusiveBorderSpace bit set. If ExclusiveBorderSpace bit is set, then host should hide its border space tools (toolbars, status bars, etc.) and not show them again until the host is reactivated. If ExclusiveActivation bit is set, then pic is being activated in "ExclusiveActive" mode. Host should retrieve the top frame window that is hosting pic (via pic->HwndGetWindow(msocWindowFrameToplevel, 0)). If this window is different from host's own top frame window, host should disable its windows and do other things it would do when receiving OnComponentEnterState(msocstateModal, TRUE) notification. Otherwise, host should refuse to have its window activated by appropriately processing WM_MOUSEACTIVATE (but see WM_MOUSEACTIVATE NOTE, above). Host should remain in this state until the ExclusiveActive mode ends, indicated by a future call to OnComponentActivate (with FALSE fTracking) with ExclusiveActivation bit not set or NULL pcrinfo. */ MSOMETHOD_(void, OnComponentActivate) (THIS_ IMsoComponent *pic, const MSOCRINFO *pcrinfo, BOOL fTracking) PURE; /* Notify host that a component is entering or exiting (indicated by
fEnter) the state identified by uStateID (a msocstateXXX value). Host should take action depending on value of uStateID (see msocstate comments, above). Note: If n calls are made with TRUE fEnter, the host should consider the state to be in effect until n calls are made with FALSE fEnter.
Note: Hosts should be aware that it is possible for this method to be called with FALSE fEnter more times than it was called with TRUE fEnter (so, for example, if host is maintaining a state counter (incremented when this method is called with TRUE fEnter, decremented when called with FALSE fEnter), the counter should not be decremented for FALSE fEnter if it is already at zero.) */ MSOMETHOD_(void, OnComponentEnterState) (THIS_ ULONG uStateID, BOOL fEnter) PURE; /* Called periodically by StdComponentMgr during
IMsoStdComponentMgr::FDoIdle. Return TRUE if idle time processing can continue, FALSE if not. */ MSOMETHOD_(BOOL, FContinueIdle) (THIS) PURE;
/* Called by StdComponentMgr when a component wishes to push a message
loop for reason uReason. uReason is one the values from the msoloop enumeration (above). The host should push its message loop, calling IMsoStdComponentMgr::FContinueMessageLoop during each loop iteration (see IMsoStdComponentMgr::FContinueMessageLoop comments). When IMsoStdComponentMgr::FContinueMessageLoop returns FALSE, the host should terminate the loop. If host terminates the loop because StdComponentMgr told it to (by returning FALSE from IMsoStdComponentMgr::FContinueMessageLoop), host should return TRUE from this method. If host had to terminate the loop for some other reason, it should return FALSE. */ MSOMETHOD_(BOOL, FPushMessageLoop) (THIS_ ULONG uReason) PURE; };
/****************************************************************************
Structures and constants for simple recording.****************************************************************************/
// Simple recorder context values passed to IMsoSimpleRecorder::FGetContext
enum { msosrctxCommandBars = 0, // pv will be the IMsoToolbarSet object
msosrctxEscher = 1, msosrctxDrawing = 2, msosrctxDrawingSelection = 3, msosrctxDrawingSchemeColor = 4, msosrctxDrawingDefault = 5, };
/****************************************************************************
Defines the IMsoSimpleRecorder interface****************************************************************************/#undef INTERFACE
#define INTERFACE IMsoSimpleRecorder
DECLARE_INTERFACE_(IMsoSimpleRecorder, IUnknown){ BEGIN_MSOINTERFACE // *** IUnknown methods ***
MSOMETHOD(QueryInterface) (THIS_ REFIID riid, void **ppvObj) PURE; MSOMETHOD_(ULONG, AddRef) (THIS) PURE; MSOMETHOD_(ULONG, Release) (THIS) PURE;
/* Standard FDebugMessage method.
Since IMsoSimpleRecorder is a reference counted interface, MsoDWGetChkMemCounter is used when processing the msodmWriteBe message. */ MSODEBUGMETHOD
/* Returns a string specifying the position of the requested context
in the host's object model. The context is specified by msosrctx, and the additional value pv if needed to disambiguate different objects of that type. The string buffer should have room for 255 characters. Returns TRUE if successful, FALSE otherwise. */ MSOMETHOD_(BOOL, FGetContext)(THIS_ int msosrctx, void *pv, WCHAR *wz) PURE;
/* Asks the host to record a line of text at the current position
in the recorder stream. Returns TRUE if the line was successfully recorded, FALSE otherwise. */ MSOMETHOD_(BOOL, FRecordLine)(THIS_ WCHAR *wz) PURE;
/* Returns TRUE if the host currently has recording turned on, and
FALSE otherwise. */ MSOMETHOD_(BOOL, FRecording)(THIS) PURE;};
/****************************************************************************
Global DLL API's****************************************************************************/
/* Called by host application to register picm as the component manager for
the calling thread. Standard reference counting rules apply. picm can be NULL, indicating that the currently registered component manager should be revoked. If there is a previously registered component manager it is Released. Returns TRUE if successful. */MSOAPI_(BOOL) MsoFSetComponentManager(IMsoComponentManager *picm);
/* Return in *ppicm an AddRef'ed pointer to the currently registered
component manager for the calling thread. Returns TRUE if successful. */MSOAPI_(BOOL) MsoFGetComponentManager(IMsoComponentManager **ppicm);
/* Create an object which has the Office supplied standard implementation
of IMsoStdComponentMgr and IMsoComponentManager, and return it in *ppvObj. piUnkOuter is the controlling unknown for aggregation (can be NULL). pich (cannot be NULL) is the pointer to the IMsoComponentHost that will use the object. riid is the id of the desired interface. If fRegister is TRUE, the created object is registered as the calling thread's component manager. Returns TRUE if successful. */MSOAPI_(BOOL) MsoFCreateStdComponentManager( IUnknown *piUnkOuter, IMsoComponentHost *pich, BOOL fRegister, REFIID riid, void **ppvObj);
#endif // MSOCI_H
|
