COleControl Class

A powerful base class for developing OLE controls.

Syntax

class COleControl : public CWnd

Members

Public Constructors

Name	Description
COleControl::COleControl	Creates a COleControl object.

Public Methods

Name	Description
COleControl::AmbientAppearance	Retrieves the current appearance of the control.
COleControl::AmbientBackColor	Returns the value of the ambient BackColor property.
COleControl::AmbientDisplayName	Returns the name of the control as specified by the container.
COleControl::AmbientFont	Returns the value of the ambient Font property.
COleControl::AmbientForeColor	Returns the value of the ambient ForeColor property.
COleControl::AmbientLocaleID	Returns the container's locale ID.
COleControl::AmbientScaleUnits	Returns the type of units used by the container.
COleControl::AmbientShowGrabHandles	Determines if grab handles should be displayed.
COleControl::AmbientShowHatching	Determines if hatching should be displayed.
COleControl::AmbientTextAlign	Returns the type of text alignment specified by the container.
COleControl::AmbientUIDead	Determines if the control should respond to user-interface actions.
COleControl::AmbientUserMode	Determines the mode of the container.
COleControl::BoundPropertyChanged	Notifies the container that a bound property has been changed.
COleControl::BoundPropertyRequestEdit	Requests permission to edit the property value.
COleControl::ClientToParent	Translates a point relative to the control's origin to a point relative to its container's origin.
COleControl::ClipCaretRect	Adjusts a caret rectangle if it is overlapped by a control.
COleControl::ControlInfoChanged	Call this function after the set of mnemonics handled by the control has changed.
COleControl::DisplayError	Displays stock Error events to the control's user.
COleControl::DoClick	Implementation of the stock DoClick method.
COleControl::DoPropExchange	Serializes the properties of a COleControl object.
COleControl::DoSuperclassPaint	Redraws an OLE control that has been subclassed from a Windows control.
COleControl::EnableSimpleFrame	Enables simple frame support for a control.
COleControl::ExchangeExtent	Serializes the control's width and height.
COleControl::ExchangeStockProps	Serializes the control's stock properties.
COleControl::ExchangeVersion	Serializes the control's version number.
COleControl::FireClick	Fires the stock Click event.
COleControl::FireDblClick	Fires the stock DblClick event.
COleControl::FireError	Fires the stock Error event.
COleControl::FireEvent	Fires a custom event.
COleControl::FireKeyDown	Fires the stock KeyDown event.
COleControl::FireKeyPress	Fires the stock KeyPress event.
COleControl::FireKeyUp	Fires the stock KeyUp event.
COleControl::FireMouseDown	Fires the stock MouseDown event.
COleControl::FireMouseMove	Fires the stock MouseMove event.
COleControl::FireMouseUp	Fires the stock MouseUp event.
COleControl::FireReadyStateChange	Fires an event when the control's ready state changes.
COleControl::GetActivationPolicy	Alters the default activation behavior of a control that supports the IPointerInactive interface.
COleControl::GetAmbientProperty	Returns the value of the specified ambient property.
COleControl::GetAppearance	Returns the value of the stock Appearance property.
COleControl::GetBackColor	Returns the value of the stock BackColor property.
COleControl::GetBorderStyle	Returns the value of the stock BorderStyle property.
COleControl::GetCapture	Determines whether a windowless, activated control object has the mouse capture.
COleControl::GetClassID	Retrieves the OLE class ID of the control.
COleControl::GetClientOffset	Retrieves the difference between the upper left corner of the control's rectangular area and the upper left corner of its client area.
COleControl::GetClientRect	Retrieves the size of the control's client area.
COleControl::GetClientSite	Queries an object for the pointer to its current client site within its container.
COleControl::GetControlFlags	Retrieves the control flag settings.
COleControl::GetControlSize	Returns the position and size of the OLE control.
COleControl::GetDC	Provides a means for a windowless control to get a device context from its container.
COleControl::GetEnabled	Returns the value of the stock Enabled property.
COleControl::GetExtendedControl	Retrieves a pointer to an extended control object belonging to the container.
COleControl::GetFocus	Determines whether the control has the focus.
COleControl::GetFont	Returns the value of the stock Font property.
COleControl::GetFontTextMetrics	Returns the metrics of a CFontHolder object.
COleControl::GetForeColor	Returns the value of the stock ForeColor property.
COleControl::GetHwnd	Returns the value of the stock hWnd property.
COleControl::GetMessageString	Provides status bar text for a menu item.
COleControl::GetNotSupported	Prevents access to a control's property value by the user.
COleControl::GetReadyState	Returns the control's readiness state.
COleControl::GetRectInContainer	Returns the control's rectangle relative to its container.
COleControl::GetStockTextMetrics	Returns the metrics of the stock Font property.
COleControl::GetText	Returns the value of the stock Text or Caption property.
COleControl::GetWindowlessDropTarget	Override to allow a windowless control to be the target of drag and drop operations.
COleControl::InitializeIIDs	Informs the base class of the IIDs the control will use.
COleControl::InternalGetFont	Returns a CFontHolder object for the stock Font property.
COleControl::InternalGetText	Retrieves the stock Caption or Text property.
COleControl::InternalSetReadyState	Sets the control's readiness state and fires the ready-state-change event.
COleControl::InvalidateControl	Invalidates an area of the displayed control, causing it to be redrawn.
COleControl::InvalidateRgn	Invalidates the container window's client area within the given region. Can be used to redraw windowless controls in the region.
COleControl::IsConvertingVBX	Allows specialized loading of an OLE control.
COleControl::IsModified	Determines if the control state has changed.
COleControl::IsOptimizedDraw	Indicates whether the container supports optimized drawing for the current drawing operation.
COleControl::IsSubclassedControl	Called to determine if the control subclasses a Windows control.
COleControl::Load	Resets any previous asynchronous data and initiates a new load of the control's asynchronous property.
COleControl::LockInPlaceActive	Determines if your control can be deactivated by the container.
COleControl::OnAmbientPropertyChange	Called when an ambient property is changed.
COleControl::OnAppearanceChanged	Called when the stock Appearance property is changed.
COleControl::OnBackColorChanged	Called when the stock BackColor property is changed.
COleControl::OnBorderStyleChanged	Called when the stock BorderStyle property is changed.
COleControl::OnClick	Called to fire the stock Click event.
COleControl::OnClose	Notifies the control that IOleControl::Close has been called.
COleControl::OnDoVerb	Called after a control verb has been executed.
COleControl::OnDraw	Called when a control is requested to redraw itself.
COleControl::OnDrawMetafile	Called by the container when a control is requested to redraw itself using a metafile device context.
COleControl::OnEdit	Called by the container to UI Activate an OLE control.
COleControl::OnEnabledChanged	Called when the stock Enabled property is changed.
COleControl::OnEnumVerbs	Called by the container to enumerate a control's verbs.
COleControl::OnEventAdvise	Called when event handlers are connected or disconnected from a control.
COleControl::OnFontChanged	Called when the stock Font property is changed.
COleControl::OnForeColorChanged	Called when the stock ForeColor property is changed.
COleControl::OnFreezeEvents	Called when a control's events are frozen or unfrozen.
COleControl::OnGetColorSet	Notifies the control that IOleObject::GetColorSet has been called.
COleControl::OnGetControlInfo	Provides mnemonic information to the container.
COleControl::OnGetDisplayString	Called to obtain a string to represent a property value.
COleControl::OnGetInPlaceMenu	Requests the handle of the control's menu that will be merged with the container menu.
COleControl::OnGetNaturalExtent	Override to retrieve the control's display size closest to the proposed size and extent mode.
COleControl::OnGetPredefinedStrings	Returns strings representing possible values for a property.
COleControl::OnGetPredefinedValue	Returns the value corresponding to a predefined string.
COleControl::OnGetViewExtent	Override to retrieve the size of the control's display areas (can be used to enable two-pass drawing).
COleControl::OnGetViewRect	Override to convert control's size into a rectangle starting at a specific position.
COleControl::OnGetViewStatus	Override to retrieve the control's view status.
COleControl::OnHideToolBars	Called by the container when the control is UI deactivated.
COleControl::OnInactiveMouseMove	Override to have the container for the inactive control under the mouse pointer dispatch WM_MOUSEMOVE messages to the control.
COleControl::OnInactiveSetCursor	Override to have the container for the inactive control under the mouse pointer dispatch WM_SETCURSOR messages to the control.
COleControl::OnKeyDownEvent	Called after the stock KeyDown event has been fired.
COleControl::OnKeyPressEvent	Called after the stock KeyPress event has been fired.
COleControl::OnKeyUpEvent	Called after the stock KeyUp event has been fired.
COleControl::OnMapPropertyToPage	Indicates which property page to use for editing a property.
COleControl::OnMnemonic	Called when a mnemonic key of the control has been pressed.
COleControl::OnProperties	Called when the control's "Properties" verb has been invoked.
COleControl::OnQueryHitPoint	Override to query whether a control's display overlaps a given point.
COleControl::OnQueryHitRect	Override to query whether a control's display overlaps any point in a given rectangle.
COleControl::OnRenderData	Called by the framework to retrieve data in the specified format.
COleControl::OnRenderFileData	Called by the framework to retrieve data from a file in the specified format.
COleControl::OnRenderGlobalData	Called by the framework to retrieve data from global memory in the specified format.
COleControl::OnResetState	Resets a control's properties to the default values.
COleControl::OnSetClientSite	Notifies the control that IOleControl::SetClientSite has been called.
COleControl::OnSetData	Replaces the control's data with another value.
COleControl::OnSetExtent	Called after the control's extent has changed.
COleControl::OnSetObjectRects	Called after the control's dimensions have been changed.
COleControl::OnShowToolBars	Called when the control has been UI activated.
COleControl::OnTextChanged	Called when the stock Text or Caption property is changed.
COleControl::OnWindowlessMessage	Processes window messages (other than mouse and keyboard messages) for windowless controls.
COleControl::ParentToClient	Translates a point relative to the container's origin to a point relative to the control's origin.
COleControl::PostModalDialog	Notifies the container that a modal dialog box has been closed.
COleControl::PreModalDialog	Notifies the container that a modal dialog box is about to be displayed.
COleControl::RecreateControlWindow	Destroys and re-creates the control's window.
COleControl::Refresh	Forces a repaint of a control's appearance.
COleControl::ReleaseCapture	Releases mouse capture.
COleControl::ReleaseDC	Releases the display device context of a container of a windowless control.
COleControl::ReparentControlWindow	Resets the parent of the control window.
COleControl::ResetStockProps	Initializes COleControl stock properties to their default values.
COleControl::ResetVersion	Initializes the version number to a given value.
COleControl::ScrollWindow	Allows a windowless control to scroll an area within its in-place active image on the display.
COleControl::SelectFontObject	Selects a custom Font property into a device context.
COleControl::SelectStockFont	Selects the stock Font property into a device context.
COleControl::SerializeExtent	Serializes or initializes the display space for the control.
COleControl::SerializeStockProps	Serializes or initializes the COleControl stock properties.
COleControl::SerializeVersion	Serializes or initializes the control's version information.
COleControl::SetAppearance	Sets the value of the stock Appearance property.
COleControl::SetBackColor	Sets the value of the stock BackColor property.
COleControl::SetBorderStyle	Sets the value of the stock BorderStyle property.
COleControl::SetCapture	Causes the control's container window to take possession of the mouse capture on the control's behalf.
COleControl::SetControlSize	Sets the position and size of the OLE control.
COleControl::SetEnabled	Sets the value of the stock Enabled property.
COleControl::SetFocus	Causes the control's container window to take possession of the input focus on the control's behalf.
COleControl::SetFont	Sets the value of the stock Font property.
COleControl::SetForeColor	Sets the value of the stock ForeColor property.
COleControl::SetInitialSize	Sets the size of an OLE control when first displayed in a container.
COleControl::SetModifiedFlag	Changes the modified state of a control.
COleControl::SetNotPermitted	Indicates that an edit request has failed.
COleControl::SetNotSupported	Prevents modification to a control's property value by the user.
COleControl::SetRectInContainer	Sets the control's rectangle relative to its container.
COleControl::SetText	Sets the value of the stock Text or Caption property.
COleControl::ThrowError	Signals that an error has occurred in an OLE control.
COleControl::TransformCoords	Transforms coordinate values between a container and the control.
COleControl::TranslateColor	Converts an OLE_COLOR value to a COLORREF value.
COleControl::WillAmbientsBeValidDuringLoad	Determines whether ambient properties will be available the next time the control is loaded.
COleControl::WindowProc	Provides a Windows procedure for a COleControl object.

Protected Methods

Name	Description
COleControl::DrawContent	Called by the framework when the control's appearance needs to be updated.
COleControl::DrawMetafile	Called by the framework when the metafile device context is being used.
COleControl::IsInvokeAllowed	Enables automation method invocation.
COleControl::SetInitialDataFormats	Called by the framework to initialize the list of data formats supported by the control.

Remarks

Derived from CWnd, this class inherits all the functionality of a Windows window object plus additional functionality specific to OLE, such as event firing and the ability to support methods and properties.

OLE controls can be inserted into OLE container applications and communicate with the container by using a two-way system of event firing and exposing methods and properties to the container. Note that standard OLE containers only support the basic functionality of an OLE control. They are unable to support extended features of an OLE control. Event firing occurs when events are sent to the container as a result of certain actions taking place in the control. In turn, the container communicates with the control by using an exposed set of methods and properties analogous to the member functions and data members of a C++ class. This approach allows the developer to control the appearance of the control and notify the container when certain actions occur.

Windowless Controls

OLE controls can be used in-place active without a window. Windowless controls have significant advantages:

• Windowless controls can be transparent and non-rectangular

• Windowless controls reduce instance size and creation time of the object

Controls do not need a window. Services that a window offers can easily be provided via a single shared window (usually the container's) and a bit of dispatching code. Having a window is mostly an unnecessary complication on the object.

When windowless activation is used, the container (which does have a window) is responsible for providing services that would otherwise have been provided by the control's own window. For example, if your control needs to query the keyboard focus, query the mouse capture, or obtain a device context, these operations are managed by the container. The COleControl windowless-operation member functions invoke these operations on the container.

When windowless activation is enabled, the container delegates input messages to the control's IOleInPlaceObjectWindowless interface (an extension of IOleInPlaceObject for windowless support). COleControl's implementation of this interface will dispatch these messages through your control's message map, after adjusting the mouse coordinates appropriately. You can process these messages like ordinary window messages, by adding the corresponding entries to the message map.

In a windowless control, you should always use the COleControl member functions instead of the corresponding CWnd member functions or their related Windows API functions.

OLE control objects can also create a window only when they become active, but the amount of work needed for the inactive-active transition goes up and the speed of the transition goes down. There are cases when this is a problem: as an example, consider a grid of text boxes. When cursoring up and down through the column, each control must be in-place activated and then deactivated. The speed of the inactive/active transition will directly affect the scrolling speed.

For more information on developing an OLE control framework, see the articles MFC ActiveX Controls and Overview: Creating an MFC ActiveX Control Program. For information on optimizing OLE controls, including windowless and flicker-free controls, see MFC ActiveX Controls: Optimization.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

COleControl

Requirements

Header: afxctl.h

COleControl::AmbientBackColor

Returns the value of the ambient BackColor property.

OLE_COLOR AmbientBackColor();

Return Value

The current value of the container's ambient BackColor property, if any. If the property is not supported, this function returns the system-defined Windows background color.

Remarks

The ambient BackColor property is available to all controls and is defined by the container. Note that the container is not required to support this property.

COleControl::AmbientDisplayName

The name the container has assigned to the control can be used in error messages displayed to the user.

CString AmbientDisplayName();

Return Value

The name of the OLE control. The default is a zero-length string.

Remarks

Note that the container is not required to support this property.

COleControl::AmbientFont

Returns the value of the ambient Font property.

LPFONTDISP AmbientFont();

Return Value

A pointer to the container's ambient Font dispatch interface. The default value is NULL. If the return is not equal to NULL, you are responsible for releasing the font by calling its IUnknown::Release member function.

Remarks

The ambient Font property is defined by the container and available to all controls.Note that the container is not required to support this property.

COleControl::AmbientForeColor

Returns the value of the ambient ForeColor property.

OLE_COLOR AmbientForeColor();

Return Value

The current value of the container's ambient ForeColor property, if any. If not supported, this function returns the system-defined Windows text color.

Remarks

The ambient ForeColor property is available to all controls and is defined by the container. Note that the container is not required to support this property.

COleControl::AmbientLocaleID

Returns the container's locale ID.

LCID AmbientLocaleID();

Return Value

The value of the container's LocaleID property, if any. If this property is not supported, this function returns 0.

Remarks

The control can use the LocaleID to adapt its user interface for specific locales. Note that the container is not required to support this property.

COleControl::AmbientAppearance

Retrieves the current appearance setting for the control object.

short AmbientAppearance();

Return Value

The appearance of the control:

• 0 Flat appearance

• 1 3D appearance

Remarks

Call this function to retrieve the current value of the DISPID_AMBIENT_APPEARANCE property for the control.

COleControl::AmbientScaleUnits

Returns the type of units used by the container.

CString AmbientScaleUnits();

Return Value

A string containing the ambient ScaleUnits of the container. If this property is not supported, this function returns a zero-length string.

Remarks

The container's ambient ScaleUnits property can be used to display positions or dimensions, labeled with the chosen unit, such as twips or centimeters. Note that the container is not required to support this property.

COleControl::AmbientShowGrabHandles

Determines whether the container allows the control to display grab handles for itself when active.

BOOL AmbientShowGrabHandles();

Return Value

Nonzero if grab handles should be displayed; otherwise 0. If this property is not supported, this function returns nonzero.

Remarks

Note that the container is not required to support this property.

COleControl::AmbientShowHatching

Determines whether the container allows the control to display itself with a hatched pattern when UI active.

BOOL AmbientShowHatching();

Return Value

Nonzero if the hatched pattern should be shown; otherwise 0. If this property is not supported, this function returns nonzero.

Remarks

Note that the container is not required to support this property.

COleControl::AmbientTextAlign

Determines the ambient text alignment preferred by the control container.

short AmbientTextAlign();

Return Value

The status of the container's ambient TextAlign property. If this property is not supported, this function returns 0.

The following is a list of valid return values:

Return value	Meaning
0	General alignment (numbers to the right, text to the left).
1	Left justify
2	Center
3	Right justify

Remarks

This property is available to all embedded controls and is defined by the container. Note that the container is not required to support this property.

COleControl::AmbientUIDead

Determines if the container wants the control to respond to user-interface actions.

BOOL AmbientUIDead();

Return Value

Nonzero if the control should respond to user-interface actions; otherwise 0. If this property is not supported, this function returns 0.

Remarks

For example, a container might set this to TRUE in design mode.

COleControl::AmbientUserMode

Determines if the container is in design mode or user mode.

BOOL AmbientUserMode();

Return Value

Nonzero if the container is in user mode; otherwise 0 (in design mode). If this property is not supported, this function returns TRUE.

Remarks

For example, a container might set this to FALSE in design mode.

COleControl::BoundPropertyChanged

Signals that the bound property value has changed.

void BoundPropertyChanged(DISPID dispid);

Parameters

dispid
The dispatch ID of a bound property of the control.

Remarks

This must be called every time the value of the property changes, even in cases where the change was not made through the property Set method. Be particularly aware of bound properties that are mapped to member variables. Any time such a member variable changes, BoundPropertyChanged must be called.

COleControl::BoundPropertyRequestEdit

Requests permission from the IPropertyNotifySink interface to change a bound property value provided by the control.

BOOL BoundPropertyRequestEdit(DISPID dispid);

Parameters

dispid
The dispatch ID of a bound property of the control.

Return Value

Nonzero if the change is permitted; otherwise 0. The default value is nonzero.

Remarks

If permission is denied, the control must not let the value of the property change. This can be done by ignoring or failing the action that attempted to change the property value.

COleControl::ClientToParent

Translates the coordinates of pPoint into parent coordinates.

virtual void ClientToParent(
    LPCRECT lprcBounds,
    LPPOINT pPoint) const;

Parameters

lprcBounds
Pointer to the bounds of the OLE control within the container. Not the client area but the area of the entire control including borders and scroll bars.

pPoint
Pointer to the OLE client area point to be translated into the coordinates of the parent (container).

Remarks

On input pPoint is relative to the origin of the client area of the OLE control (upper left corner of the client area of the control). On output pPoint is relative to the origin of the parent (upper left corner of the container).

COleControl::ClipCaretRect

Adjusts a caret rectangle if it is entirely or partially covered by overlapping, opaque objects.

BOOL ClipCaretRect(LPRECT lpRect);

Parameters

lpRect
On input, a pointer to a RECT structure that contains the caret area to be adjusted. On output, the adjusted caret area, or NULL if the caret rectangle is completely covered.

Return Value

Nonzero if successful; otherwise 0.

Remarks

A caret is a flashing line, block, or bitmap that typically indicates where text or graphics will be inserted.

A windowless object cannot safely show a caret without first checking whether the caret is partially or totally hidden by overlapping objects. In order to make that possible, an object can use ClipCaretRect to get the caret adjusted (reduced) to ensure it fits in the clipping region.

Objects creating a caret should submit the caret rectangle to ClipCaretRect and use the adjusted rectangle for the caret. If the caret is entirely hidden, this method will return FALSE and the caret should not be shown at all in this case.

COleControl::COleControl

Constructs a COleControl object.

COleControl();

Remarks

This function is normally not called directly. Instead the OLE control is usually created by its class factory.

COleControl::ControlInfoChanged

Call this function when the set of mnemonics supported by the control has changed.

void ControlInfoChanged();

Remarks

Upon receiving this notification, the control's container obtains the new set of mnemonics by making a call to IOleControl::GetControlInfo. Note that the container is not required to respond to this notification.

COleControl::DisplayError

Called by the framework after the stock Error event has been handled (unless the event handler has suppressed the display of the error).

virtual void DisplayError(
    SCODE scode,
    LPCTSTR lpszDescription,
    LPCTSTR lpszSource,
    LPCTSTR lpszHelpFile,
    UINT nHelpID);

Parameters

scode
The status code value to be reported. For a complete list of possible codes, see the article ActiveX Controls: Advanced Topics.

lpszDescription
The description of the error being reported.

lpszSource
The name of the module generating the error (typically, the name of the OLE control module).

lpszHelpFile
The name of the help file containing a description of the error.

nHelpID
The Help Context ID of the error being reported.

Remarks

The default behavior displays a message box containing the description of the error, contained in lpszDescription.

Override this function to customize how errors are displayed.

COleControl::DoClick

Simulates a mouse click action on the control.

void DoClick();

Remarks

The overridable COleControl::OnClick member function will be called, and a stock Click event will be fired, if supported by the control.

This function is supported by the COleControl base class as a stock method, called DoClick. For more information, see the article ActiveX Controls: Methods.

COleControl::DoPropExchange

Called by the framework when loading or storing a control from a persistent storage representation, such as a stream or property set.

virtual void DoPropExchange(CPropExchange* pPX);

Parameters

pPX
A pointer to a CPropExchange object. The framework supplies this object to establish the context of the property exchange, including its direction.

Remarks

This function normally makes calls to the PX_ family of functions to load or store specific user-defined properties of an OLE control.

If Control Wizard has been used to create the OLE control project, the overridden version of this function will serialize the stock properties supported by COleControl with a call to the base class function, COleControl::DoPropExchange. As you add user-defined properties to your OLE control you will need to modify this function to serialize your new properties. For more information on serialization, see the article ActiveX Controls: Serializing.

COleControl::DoSuperclassPaint

Redraws an OLE control that has been subclassed from a Windows control.

void DoSuperclassPaint(
    CDC* pDC,
    const CRect& rcBounds);

Parameters

pDC
A pointer to the device context of the control container.

rcBounds
The area in which the control is to be drawn.

Remarks

Call this function to properly handle the painting of a nonactive OLE control. This function should only be used if the OLE control subclasses a Windows control and should be called in the OnDraw function of your control.

For more information on this function and subclassing a Windows control, see the article ActiveX Controls: Subclassing a Windows Control.

COleControl::DrawContent

Called by the framework when the control's appearance needs to be updated.

void DrawContent(
    CDC* pDC,
    CRect& rc);

Parameters

pDC
Pointer to the device context.

rc
Rectangular area to be drawn in.

Remarks

This function directly calls the overridable OnDraw function.

COleControl::DrawMetafile

Called by the framework when the metafile device context is being used.

void DrawMetafile(
    CDC* pDC,
    CRect& rc);

Parameters

pDC
Pointer to the metafile device context.

rc
Rectangular area to be drawn in.

COleControl::EnableSimpleFrame

Enables the simple frame characteristic for an OLE control.

void EnableSimpleFrame();

Remarks

This characteristic allows a control to support visual containment of other controls, but not true OLE containment. An example would be a group box with several controls inside. These controls are not OLE contained, but they are in the same group box.

COleControl::ExchangeExtent

Serializes or initializes the state of the control's extent (its dimensions in HIMETRIC units).

BOOL ExchangeExtent(CPropExchange* pPX);

Parameters

pPX
A pointer to a CPropExchange object. The framework supplies this object to establish the context of the property exchange, including its direction.

Return Value

Nonzero if the function succeeded; 0 otherwise.

Remarks

This function is normally called by the default implementation of COleControl::DoPropExchange.

COleControl::ExchangeStockProps

Serializes or initializes the state of the control's stock properties.

void ExchangeStockProps(CPropExchange* pPX);

Parameters

pPX
A pointer to a CPropExchange object. The framework supplies this object to establish the context of the property exchange, including its direction.

Remarks

This function is normally called by the default implementation of COleControl::DoPropExchange.

COleControl::ExchangeVersion

Serializes or initializes the state of a control's version information.

BOOL ExchangeVersion(
    CPropExchange* pPX,
    DWORD dwVersionDefault,
    BOOL bConvert = TRUE);

Parameters

pPX
A pointer to a CPropExchange object. The framework supplies this object to establish the context of the property exchange, including its direction.

dwVersionDefault
The current version number of the control.

bConvert
Indicates whether persistent data should be converted to the latest format when saved, or maintained in the same format that was loaded.

Return Value

Nonzero of the function succeeded; 0 otherwise.

Remarks

Typically, this will be the first function called by a control's override of COleControl::DoPropExchange. When loading, this function reads the version number of the persistent data, and sets the version attribute of the CPropExchange object accordingly. When saving, this function writes the version number of the persistent data.

For more information on persistence and versioning, see the article ActiveX Controls: Serializing.

COleControl::FireClick

Called by the framework when the mouse is clicked over an active control.

void FireClick();

Remarks

If this event is defined as a custom event, you determine when the event is fired.

For automatic firing of a Click event to occur, the control's Event map must have a stock Click event defined.

COleControl::FireDblClick

Called by the framework when the mouse is double-clicked over an active control.

void FireDblClick();

Remarks

If this event is defined as a custom event, you determine when the event is fired.

For automatic firing of a DblClick event to occur, the control's Event map must have a stock DblClick event defined.

COleControl::FireError

Fires the stock Error event.

void FireError(
    SCODE scode,
    LPCTSTR lpszDescription,
    UINT nHelpID = 0);

Parameters

scode
The status code value to be reported. For a complete list of possible codes, see the article ActiveX Controls: Advanced Topics.

lpszDescription
The description of the error being reported.

nHelpID
The Help ID of the error being reported.

Remarks

This event provides a way of signalling, at appropriate places in your code, that an error has occurred within your control. Unlike other stock events, such as Click or MouseMove, Error is never fired by the framework.

To report an error that occurs during a property get function, property set function, or automation method, call COleControl::ThrowError.

The implementation of an OLE control's Stock Error event uses an SCODE value. If your control uses this event, and is intended to be used in Visual Basic 4.0, you will receive errors because the SCODE value is not supported in Visual Basic.

To fix this, manually change the SCODE parameter in the control's .ODL file to a long. In addition, any custom event, method, or property that uses an SCODE parameter also causes the same problem.

COleControl::FireEvent

Fires a user-defined event from your control with any number of optional arguments,.

void AFX_CDECL FireEvent(
    DISPID dispid,
    BYTE* pbParams,
...);

Parameters

dispid
The dispatch ID of the event to be fired.

pbParams
A descriptor for the event's parameter types.

Remarks

Usually this function should not be called directly. Instead you will call the event-firing functions in the event map section of your control's class declaration.

The pbParams argument is a space-separated list of VTS_. One or more of these values, separated by spaces (not commas), specifies the function's parameter list. Possible values are as follows:

Symbol	Parameter type
VTS_COLOR	OLE_COLOR
VTS_FONT	IFontDisp*
VTS_HANDLE	HWND
VTS_PICTURE	IPictureDisp*
VTS_OPTEXCLUSIVE	OLE_OPTEXCLUSIVE*
VTS_TRISTATE	OLE_TRISTATE
VTS_XPOS_HIMETRIC	OLE_XPOS_HIMETRIC
VTS_YPOS_HIMETRIC	OLE_YPOS_HIMETRIC
VTS_XPOS_PIXELS	OLE_XPOS_PIXELS
VTS_YPOS_PIXELS	OLE_YPOS_PIXELS
VTS_XSIZE_PIXELS	OLE_XSIZE_PIXELS
VTS_YSIZE_PIXELS	OLE_XSIZE_PIXELS
VTS_XSIZE_HIMETRIC	OLE_XSIZE_HIMETRIC
VTS_YSIZE_HIMETRIC	OLE_XSIZE_HIMETRIC

COleControl::FireKeyDown

Called by the framework when a key is pressed while the control is UI active.

void FireKeyDown(
    USHORT* pnChar,
    short nShiftState);

Parameters

pnChar
Pointer to the virtual key code value of the pressed key. For a list of standard virtual key codes, see Winuser.h

nShiftState
Contains a combination of the following flags:

• SHIFT_MASK The SHIFT key was pressed during the action.

• CTRL_MASK The CTRL key was pressed during the action.

• ALT_MASK The ALT key was pressed during the action.

Remarks

If this event is defined as a custom event, you determine when the event is fired.

For automatic firing of a KeyDown event to occur, the control's Event map must have a stock KeyDown event defined.

COleControl::FireKeyPress

Called by the framework when a key is pressed and released while the custom control is UI Active within the container.

void FireKeyPress(USHORT* pnChar);

Parameters

pnChar
A pointer to the character value of the key pressed.

Remarks

If this event is defined as a custom event, you determine when the event is fired.

The recipient of the event may modify pnChar, for example, convert all lowercase characters to uppercase. If you want to examine the modified character, override OnKeyPressEvent.

For automatic firing of a KeyPress event to occur, the control's Event map must have a stock KeyPress event defined.

COleControl::FireKeyUp

Called by the framework when a key is released while the custom control is UI Active within the container.

void FireKeyUp(
    USHORT* pnChar,
    short nShiftState);

Parameters

pnChar
Pointer to the virtual key code value of the released key. For a list of standard virtual key codes, see Winuser.h

nShiftState
Contains a combination of the following flags:

• SHIFT_MASK The SHIFT key was pressed during the action.

• CTRL_MASK The CTRL key was pressed during the action.

• ALT_MASK The ALT key was pressed during the action.

Remarks

If this event is defined as a custom event, you determine when the event is fired.

For automatic firing of a KeyUp event to occur, the control's Event map must have a stock KeyUp event defined.

COleControl::FireMouseDown

Called by the framework when a mouse button is pressed over an active custom control.

void FireMouseDown(
    short nButton,
    short nShiftState,
    OLE_XPOS_PIXELS x,
    OLE_YPOS_PIXELS y);

Parameters

nButton
The numeric value of the mouse button pressed. It can contain one of the following values:

• LEFT_BUTTON The left mouse button was pressed down.

• MIDDLE_BUTTON The middle mouse button was pressed down.

• RIGHT_BUTTON The right mouse button was pressed down.

nShiftState
Contains a combination of the following flags:

• SHIFT_MASK The SHIFT key was pressed during the action.

• CTRL_MASK The CTRL key was pressed during the action.

• ALT_MASK The ALT key was pressed during the action.

x
The x-coordinate of the cursor when a mouse button was pressed down. The coordinate is relative to the upper-left corner of the control window.

y
The y-coordinate of the cursor when a mouse button was pressed down. The coordinate is relative to the upper-left corner of the control window.

Remarks

If this event is defined as a custom event, you determine when the event is fired.

For automatic firing of a MouseDown event to occur, the control's Event map must have a stock MouseDown event defined.

COleControl::FireMouseMove

Called by the framework when the cursor is moved over an active custom control.

void FireMouseMove(
    short nButton,
    short nShiftState,
    OLE_XPOS_PIXELS x,
    OLE_YPOS_PIXELS y);

Parameters

nButton
The numeric value of the mouse buttons pressed. Contains a combination of the following values:

• LEFT_BUTTON The left mouse button was pressed down during the action.

• MIDDLE_BUTTON The middle mouse button was pressed down during the action.

• RIGHT_BUTTON The right mouse button was pressed down during the action.

nShiftState
Contains a combination of the following flags:

• SHIFT_MASK The SHIFT key was pressed during the action.

• CTRL_MASK The CTRL key was pressed during the action.

• ALT_MASK The ALT key was pressed during the action.

x
The x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the control window.

y
The y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the control window.

Remarks

If this event is defined as a custom event, you determine when the event is fired.

For automatic firing of a MouseMove event to occur, the control's Event map must have a stock MouseMove event defined.

COleControl::FireMouseUp

Called by the framework when a mouse button is released over an active custom control.

void FireMouseUp(
    short nButton,
    short nShiftState,
    OLE_XPOS_PIXELS x,
    OLE_YPOS_PIXELS y);

Parameters

nButton
The numeric value of the mouse button released. It can have one of the following values:

• LEFT_BUTTON The left mouse button was released.

• MIDDLE_BUTTON The middle mouse button was released.

• RIGHT_BUTTON The right mouse button was released.

nShiftState
Contains a combination of the following flags:

• SHIFT_MASK The SHIFT key was pressed during the action.

• CTRL_MASK The CTRL key was pressed during the action.

• ALT_MASK The ALT key was pressed during the action.

x
The x-coordinate of the cursor when a mouse button was released. The coordinate is relative to the upper-left corner of the control window.

y
The y-coordinate of a cursor when a mouse button was released. The coordinate is relative to the upper-left corner of the control window.

Remarks

If this event is defined as a custom event, you determine when the event is fired.

For automatic firing of a MouseUp event to occur, the control's Event map must have a stock MouseUp event defined.

COleControl::FireReadyStateChange

Fires an event with the current value of the ready state of control.

void FireReadyStateChange();

Remarks

The ready state can be one of the following values:

Name	Description
READYSTATE_UNINITIALIZED	Default initialization state
READYSTATE_LOADING	Control is currently loading its properties
READYSTATE_LOADED	Control has been initialized
READYSTATE_INTERACTIVE	Control has enough data to be interactive but not all asynchronous data is yet loaded
READYSTATE_COMPLETE	Control has all its data

Use GetReadyState to determine the control's current readiness.

InternalSetReadyState changes the ready state to the value supplied, then calls FireReadyStateChange.

COleControl::GetActivationPolicy

Alters the default activation behavior of a control that supports the IPointerInactive interface.

virtual DWORD GetActivationPolicy();

Return Value

A combination of flags from the POINTERINACTIVE enumeration. Possible flags are:

Name	Description
POINTERINACTIVE_ACTIVATEONENTRY	The object should be in-place activated when the mouse enters it during a mouse move operation.
POINTERINACTIVE_DEACTIVATEONLEAVE	The object should be deactivated when the mouse leaves the object during a mouse move operation.
POINTERINACTIVE_ACTIVATEONDRAG	The object should be in-place activated when the mouse is dragged over it during a drag and drop operation.

Remarks

When the IPointerInactive interface is enabled, the container will delegate WM_SETCURSOR and WM_MOUSEMOVE messages to it. COleControl's implementation of this interface will dispatch these messages through your control's message map, after adjusting the mouse coordinates appropriately.

Whenever the container receives a WM_SETCURSOR or WM_MOUSEMOVE message with the mouse pointer over an inactive object supporting IPointerInactive, it should call GetActivationPolicy on the interface and return flags from the POINTERINACTIVE enumeration.

You can process these messages just like ordinary window messages, by adding the corresponding entries to the message map. In your handlers, avoid using the m_hWnd member variable (or any member functions that uses it) without first checking that its value is non- NULL.

Any object intended to do more than set the mouse cursor and/or fire a mouse move event, such as give special visual feedback, should return the POINTERINACTIVE_ACTIVATEONENTRY flag and draw the feedback only when active. If the object returns this flag, the container should activate it in-place immediately and then forward it the same message that triggered the call to GetActivationPolicy.

If both the POINTERINACTIVE_ACTIVATEONENTRY and POINTERINACTIVE_DEACTIVATEONLEAVE flags are returned, then the object will only be activated when the mouse is over the object. If only the POINTERINACTIVE_ACTIVATEONENTRY flag is returned, then the object will only be activated once when the mouse first enters the object.

You may also want an inactive control to be the target of an OLE drag and drop operation. This requires activating the control at the moment the user drags an object over it, so that the control's window can be registered as a drop target. To cause activation to occur during a drag, return the POINTERINACTIVE_ACTIVATEONDRAG flag:

DWORD CMyAxCtrl::GetActivationPolicy()
{
   return POINTERINACTIVE_ACTIVATEONDRAG;
}

The information communicated by GetActivationPolicy should not be cached by a container. Instead, this method should be called every time the mouse enters an inactive object.

If an inactive object does not request to be in-place activated when the mouse enters it, its container should dispatch subsequent WM_SETCURSOR messages to this object by calling OnInactiveSetCursor as long as the mouse pointer stays over the object.

Enabling the IPointerInactive interface typically means that you want the control to be capable of processing mouse messages at all times. To get this behaviour in a container that doesn't support the IPointerInactive interface, you will need to have your control always activated when visible, which means the control should have the OLEMISC_ACTIVATEWHENVISIBLE flag among its miscellaneous flags. However, to prevent this flag from taking effect in a container that does support IPointerInactive, you can also specify the OLEMISC_IGNOREACTIVATEWHENVISIBLE flag:

static const DWORD BASED_CODE _dwMyOleMisc =
    OLEMISC_ACTIVATEWHENVISIBLE |
    OLEMISC_IGNOREACTIVATEWHENVISIBLE |
    OLEMISC_SETCLIENTSITEFIRST |
    OLEMISC_INSIDEOUT |
    OLEMISC_CANTLINKINSIDE |
    OLEMISC_RECOMPOSEONRESIZE;

COleControl::GetAmbientProperty

Gets the value of an ambient property of the container.

BOOL GetAmbientProperty(
    DISPID dispid,
    VARTYPE vtProp,
    void* pvProp);

Parameters

dwDispid
The dispatch ID of the desired ambient property.

vtProp
A variant type tag that specifies the type of the value to be returned in pvProp.

pvProp
A pointer to the address of the variable that will receive the property value or return value. The actual type of this pointer must match the type specified by vtProp.

vtProp	Type of pvProp
VT_BOOL	BOOL*
VT_BSTR	CString*
VT_I2	short*
VT_I4	long*
VT_R4	float*
VT_R8	double*
VT_CY	CY*
VT_COLOR	OLE_COLOR*
VT_DISPATCH	LPDISPATCH*
VT_FONT	LPFONTDISP*

Return Value

Nonzero if the ambient property is supported; otherwise 0.

Remarks

If you use GetAmbientProperty to retrieve the ambient DisplayName and ScaleUnits properties, set vtProp to VT_BSTR and pvProp to CString*. If you are retrieving the ambient Font property, set vtProp to VT_FONT and pvProp to LPFONTDISP*.

Note that functions have already been provided for common ambient properties, such as AmbientBackColor and AmbientFont.

COleControl::GetAppearance

Implements the Get function of your control's stock Appearance property.

short GetAppearance ();

Return Value

The return value specifies the current appearance setting as a short (VT_I2) value, if successful. This value is zero if the control's appearance is flat and 1 if the control's appearance is 3D.

COleControl::GetBackColor

Implements the Get function of your control's stock BackColor property.

OLE_COLOR GetBackColor();

Return Value

The return value specifies the current background color as a OLE_COLOR value, if successful. This value can be translated to a COLORREF value with a call to TranslateColor.

COleControl::GetBorderStyle

Implements the Get function of your control's stock BorderStyle property.

short GetBorderStyle();

Return Value

1 if the control has a normal border; 0 if the control has no border.

COleControl::GetCapture

Determines whether the COleControl object has the mouse capture.

CWnd* GetCapture();

Return Value

If the control is activated and windowless, returns this if the control currently has the mouse capture (as determined by the control's container), or NULL if it does not have the capture.

Otherwise, returns the CWnd object that has the mouse capture (same as CWnd::GetCapture).

Remarks

An activated windowless control receives the mouse capture when SetCapture is called.

COleControl::GetClassID

Called by the framework to retrieve the OLE class ID of the control.

virtual HRESULT GetClassID(LPCLSID pclsid) = 0;

Parameters

pclsid
Pointer to the location of the class ID.

Return Value

Nonzero if the call was not successful; otherwise 0.

Remarks

Usually implemented by the IMPLEMENT_OLECREATE_EX.

COleControl::GetClientOffset

Retrieves the difference between the upper left corner of the control's rectangular area and the upper left corner of its client area.

virtual void GetClientOffset(long* pdxOffset, long* pdyOffset) const;

Parameters

pdxOffset
Pointer to the horizontal offset of the OLE control's client area.

pdyOffset
Pointer to the vertical offset of the OLE control's client area.

Remarks

The OLE control has a rectangular area within its container. The client area of the control is the control area excluding borders and scroll bars. The offset retrieved by GetClientOffset is the difference between the upper left corner of the control's rectangular area and the upper left corner of its client area. If your control has non-client elements other than the standard borders and scrollbars, override this member function to specify the offset.

COleControl::GetClientRect

Retrieves the size of the control's client area.

virtual void GetClientRect(LPRECT lpRect) const;

Parameters

lpRect
Pointer to a RECT structure containing the dimensions of the windowless control's client area; that is, the control's size minus window borders, frames, scroll bars, and so on. The lpRect parameter indicates the size of the control's client rectangle, not its position.

COleControl::GetClientSite

Queries an object for the pointer to its current client site within its container.

LPOLECLIENTSITE GetClientSite();

Return Value

A pointer to the control's current client site in its container.

Remarks

The returned pointer points to an instance of IOleClientSite. The IOleClientSite interface, implemented by containers, is the object's view of its context: where it is anchored in the document, where it gets its storage, user interface, and other resources.

COleControl::GetControlFlags

Retrieves the control flag settings.

virtual DWORD GetControlFlags();

Return Value

An ORed combination of the flags in the ControlFlags enumeration:

enum ControlFlags {
    fastBeginPaint = 0x0001,
    clipPaintDC = 0x0002,
    pointerInactive = 0x0004,
    noFlickerActivate = 0x0008,
    windowlessActivate = 0x0010,
    canOptimizeDraw = 0x0020,
    };

Remarks

By default, GetControlFlags returns fastBeginPaint | clipPaintDC.

Name	Description
fastBeginPaint	If set, uses a begin-paint function tailored for OLE controls instead of the BeginPaint API (set by default).
clipPaintDC	If not set, disables the call to IntersectClipRect made by COleControl and gains a small speed advantage. If you are using windowless activation, the flag has no effect.
pointerInactive	If set, provides mouse interaction while your control is inactive by enabling COleControl's implementation of the IPointerInactive interface, which is disabled by default.
noFlickerActivate	If set, eliminates extra drawing operations and the accompanying visual flicker. Use when your control draws itself identically in the inactive and active states. If you are using windowless activation, the flag has no effect.
windowlessActivate	If set, indicates your control uses windowless activation.
canOptimizeDraw	If set, indicates that the control will perform optimized drawing, if the container supports it.

For more information about GetControlFlags and other optimizations of OLE controls, see ActiveX Controls: Optimization.

COleControl::GetControlSize

Retrieves the size of the OLE control window.

void GetControlSize(
    int* pcx,
    int* pcy);

Parameters

pcx
Specifies the width of the control in pixels.

pcy
Specifies the height of the control in pixels.

Remarks

Note that all coordinates for control windows are relative to the upper-left corner of the control.

COleControl::GetDC

Provides for a windowless object to get a screen (or compatible) device context from its container.

CDC* GetDC(
    LPCRECT lprcRect = NULL,
    DWORD dwFlags = OLEDC_PAINTBKGND);

Parameters

lprcRect
A pointer to the rectangle the windowless control wants to redraw, in client coordinates of the control. NULL means the full object's extent.

dwFlags
Drawing attributes of the device context. Choices are:

• OLEDC_NODRAW Indicates that the object won't use the device context to perform any drawing but merely to get information about the display device. The container should simply pass the window's DC without further processing.

• OLEDC_PAINTBKGND Requests that the container paint the background before returning the DC. An object should use this flag if it is requesting a DC for redrawing an area with transparent background.

• OLEDC_OFFSCREEN Informs the container that the object wishes to render into an off-screen bitmap that should then be copied to the screen. An object should use this flag when the drawing operation it is about to perform generates a lot of flicker. The container is free to honor this request or not. However, if this flag is not set, the container must hand back an on-screen DC. This allows objects to perform direct screen operations such as showing a selection (via an XOR operation).

Return Value

Pointer to the display device context for the container CWnd client area if successful; otherwise, the return value is NULL. The display device context can be used in subsequent GDI functions to draw in the client area of the container's window.

Remarks

The ReleaseDC member function must be called to release the context after painting. When calling GetDC, objects pass the rectangle they wish to draw into in their own client coordinates. GetDC translates these to coordinates of the container client area. The object should not request a desired drawing rectangle larger than its own client area rectangle, the size of which can be retrieved with GetClientRect. This prevents objects from inadvertently drawing where they are not supposed to.

COleControl::GetEnabled

Implements the Get function of your control's stock Enabled property.

BOOL GetEnabled();

Return Value

Nonzero if the control is enabled; otherwise 0.

COleControl::GetExtendedControl

Obtains a pointer to an object maintained by the container that represents the control with an extended set of properties.

LPDISPATCH GetExtendedControl();

Return Value

A pointer to the container's extended control object. If there is no object available, the value is NULL.

This object may be manipulated through its IDispatch interface. You can also use QueryInterface to obtain other available interfaces provided by the object. However, the object is not required to support a specific set of interfaces. Note that relying on the specific features of a container's extended control object limits the portability of your control to other arbitrary containers.

Remarks

The function that calls this function is responsible for releasing the pointer when finished with the object. Note that the container is not required to support this object.

COleControl::GetFocus

Determines whether the COleControl object has the focus.

CWnd* GetFocus();

Return Value

If the control is activated and windowless, returns this if the control currently has the keyboard focus (as determined by the control's container), or NULL if it does not have the focus.

Otherwise, returns the CWnd object that has the focus (same as CWnd::GetFocus).

Remarks

An activated windowless control receives the focus when SetFocus is called.

COleControl::GetFont

Implements the Get function of the stock Font property.

LPFONTDISP GetFont();

Return Value

A pointer to the font dispatch interface of the control's stock Font property.

Remarks

Note that the caller must release the object when finished. Within the implementation of the control, use InternalGetFont to access the control's stock Font object. For more information on using fonts in your control, see the article ActiveX Controls: Using Fonts in an ActiveX Control.

COleControl::GetFontTextMetrics

Measures the text metrics for any CFontHolder object owned by the control.

void GetFontTextMetrics(
    LPTEXTMETRIC lptm,
    CFontHolder& fontHolder);

Parameters

lptm
Pointer to a TEXTMETRIC structure.

fontHolder
Reference to a CFontHolder object.

Remarks

Such a font can be selected with the COleControl::SelectFontObject function. GetFontTextMetrics will initialize the TEXTMETRIC structure pointed to by lptm with valid metrics information about fontHolder's font if successful, or fill the structure with zeros if not successful. You should use this function instead of GetTextMetrics when painting your control because controls, like any embedded OLE object, may be required to render themselves into a metafile.

The TEXTMETRIC structure for the default font is refreshed when the SelectFontObject function is called. You should call GetFontTextMetrics only after selecting the stock Font property to assure the information it provides is valid.

COleControl::GetForeColor

Implements the Get function of the stock ForeColor property.

OLE_COLOR GetForeColor();

Return Value

The return value specifies the current foreground color as a OLE_COLOR value, if successful. This value can be translated to a COLORREF value with a call to TranslateColor.

COleControl::GetHwnd

Implements the Get function of the stock hWnd property.

OLE_HANDLE GetHwnd();

Return Value

The OLE control's window handle, if any; otherwise NULL.

COleControl::GetMessageString

Called by the framework to obtain a short string that describes the purpose of the menu item identified by nID.

virtual void GetMessageString(
    UINT nID,
    CString& rMessage) const;

Parameters

nID
A menu item ID.

rMessage
A reference to a CString object through which a string will be returned.

Remarks

This can be used to obtain a message for display in a status bar while the menu item is highlighted. The default implementation attempts to load a string resource identified by nID.

COleControl::GetNotSupported

Prevents access to a control's property value by the user.

void GetNotSupported();

Remarks

Call this function in place of the Get function of any property where retrieval of the property by the control's user is not supported. One example would be a property that is write only.

COleControl::GetReadyState

Returns the readiness state of the control.

long GetReadyState();

Return Value

The readiness state of the control, one of the following values:

Name	Description
READYSTATE_UNINITIALIZED	Default initialization state
READYSTATE_LOADING	Control is currently loading its properties
READYSTATE_LOADED	Control has been initialized
READYSTATE_INTERACTIVE	Control has enough data to be interactive but not all asynchronous data is yet loaded
READYSTATE_COMPLETE	Control has all its data

Remarks

Most simple controls never need to differentiate between LOADED and INTERACTIVE. However, controls that support data path properties may not be ready to be interactive until at least some data is received asynchronously. A control should attempt to become interactive as soon as possible.

COleControl::GetRectInContainer

Obtains the coordinates of the control's rectangle relative to the container, expressed in device units.

BOOL GetRectInContainer(LPRECT lpRect);

Parameters

lpRect
A pointer to the rectangle structure into which the control's coordinates will be copied.

Return Value

Nonzero if the control is in-place active; otherwise 0.

Remarks

The rectangle is only valid if the control is in-place active.

COleControl::GetStockTextMetrics

Measures the text metrics for the control's stock Font property, which can be selected with the SelectStockFont function.

void GetStockTextMetrics(LPTEXTMETRIC lptm);

Parameters

lptm
A pointer to a TEXTMETRIC structure.

Remarks

The GetStockTextMetrics function will initialize the TEXTMETRIC structure pointed to by lptm with valid metrics information if successful, or fill the structure with zeros if not successful. Use this function instead of GetTextMetrics when painting your control because controls, like any embedded OLE object, may be required to render themselves into a metafile.

The TEXTMETRIC structure for the default font is refreshed when the SelectStockFont function is called. You should call this function only after selecting the stock font to assure the information it provides is valid.

COleControl::GetText

Implements the Get function of the stock Text or Caption property.

BSTR GetText();

Return Value

The current value of the control text string or a zero-length string if no string is present.

Remarks

Note that the caller of this function must call SysFreeString on the string returned in order to free the resource. Within the implementation of the control, use InternalGetText to access the control's stock Text or Caption property.

COleControl::GetWindowlessDropTarget

Override GetWindowlessDropTarget when you want a windowless control to be the target of an OLE drag and drop operation.

virtual IDropTarget* GetWindowlessDropTarget();

Return Value

Pointer to the object's IDropTarget interface. Since it does not have a window, a windowless object cannot register an IDropTarget interface. However, to participate in drag and drop, a windowless object can still implement the interface and return it in GetWindowlessDropTarget.

Remarks

Normally, this would require that the control's window be registered as a drop target. But since the control has no window of its own, the container will use its own window as a drop target. The control simply needs to provide an implementation of the IDropTarget interface to which the container can delegate calls at the appropriate time. For example:

IDropTarget *CMyAxCtrl::GetWindowlessDropTarget()
{
   m_xDropTarget.AddRef();
   return &m_xDropTarget;
}

COleControl::InitializeIIDs

Informs the base class of the IIDs the control will use.

void InitializeIIDs(
    const IID* piidPrimary,
    const IID* piidEvents);

Parameters

piidPrimary
Pointer to the interface ID of the control's primary dispatch interface.

piidEvents
Pointer to the interface ID of the control's event interface.

Remarks

Call this function in the control's constructor to inform the base class of the interface IDs your control will be using.

COleControl::InternalGetFont

Accesses the stock Font property of your control

CFontHolder& InternalGetFont();

Return Value

A reference to a CFontHolder object that contains the stock Font object.

COleControl::InternalGetText

Accesses the stock Text or Caption property of your control.

const CString& InternalGetText();

Return Value

A reference to the control text string.

COleControl::InternalSetReadyState

Sets the readiness state of the control.

void InternalSetReadyState(long lNewReadyState);

Parameters

lNewReadyState
The readiness state to set for the control, one of the following values:

Name	Description
READYSTATE_UNINITIALIZED	Default initialization state
READYSTATE_LOADING	Control is currently loading its properties
READYSTATE_LOADED	Control has been initialized
READYSTATE_INTERACTIVE	Control has enough data to be interactive but not all asynchronous data is yet loaded
READYSTATE_COMPLETE	Control has all its data

Remarks

Most simple controls never need to differentiate between LOADED and INTERACTIVE. However, controls that support data path properties may not be ready to be interactive until at least some data is received asynchronously. A control should attempt to become interactive as soon as possible.

COleControl::InvalidateControl

Forces the control to redraw itself.

void InvalidateControl(
    LPCRECT lpRect = NULL,
    BOOL bErase = TRUE);

Parameters

lpRect
A pointer to the region of the control to be invalidated.

bErase
Specifies whether the background within the update region is to be erased when the update region is processed.

Remarks

If lpRect has a NULL value, the entire control will be redrawn. If lpRect is not NULL, this indicates the portion of the control's rectangle that is to be invalidated. In cases where the control has no window, or is currently not active, the rectangle is ignored, and a call is made to the client site's IAdviseSink::OnViewChange member function. Use this function instead of CWnd::InvalidateRect or InvalidateRect.

COleControl::InvalidateRgn

Invalidates the container window's client area within the given region.

void InvalidateRgn(CRgn* pRgn, BOOL bErase = TRUE);

Parameters

pRgn
A pointer to a CRgn object that identifies the display region of the OLE object to invalidate, in client coordinates of the containing window. If this parameter is NULL, the extent is the entire object.

bErase
Specifies whether the background within the invalidated region is to be erased. If TRUE, the background is erased. If FALSE, the background remains unchanged.

Remarks

This can be used to redraw windowless controls within the container. The invalidated region, along with all other areas in the update region, is marked for painting when the next WM_PAINT message is sent.

If bErase is TRUE for any part of the update region, the background in the entire region, not just in the given part, is erased.

COleControl::IsConvertingVBX

Allows specialized loading of an OLE control.

BOOL IsConvertingVBX();

Return Value

Nonzero if the control is being converted; otherwise 0.

Remarks

When converting a form that uses VBX controls to one that uses OLE controls, special loading code for the OLE controls may be required. For example, if you are loading an instance of your OLE control, you might have a call to PX_Font in your DoPropExchange:

PX_Font(pPX, _T("Font"), *m_pMyFont, &DefaultFont);

However, VBX controls did not have a Font object; each font property was saved individually. In this case, you would use IsConvertingVBX to distinguish between these two cases:

if (!IsConvertingVBX())
{
   PX_Font(pPX, _T("Font"), *m_pMyFont, &DefaultFont);
}
else
{
   PX_String(pPX, _T("FontName"), tempString, DefaultName);
   m_pMyFont->m_pFont->put_Name(tempString.AllocSysString());
   PX_Bool(pPX, _T("FontUnderline"), tempBool, DefaultValue);
   m_pMyFont->m_pFont->put_Underline(tempBool);
}

Another case would be if your VBX control saved proprietary binary data (in its VBM_SAVEPROPERTY message handler), and your OLE control saves its binary data in a different format. If you want your OLE control to be backward-compatible with the VBX control, you could read both the old and new formats using the IsConvertingVBX function by distinguishing whether the VBX control or the OLE control was being loaded.

In your control's DoPropExchange function, you can check for this condition and if true, execute load code specific to this conversion (such as the previous examples). If the control is not being converted, you can execute normal load code. This ability is only applicable to controls being converted from VBX counterparts.

COleControl::IsInvokeAllowed

Enables automation method invocation.

BOOL IsInvokeAllowed(DISPID dispid);

Return Value

Nonzero if the control has been initialized; otherwise 0.

Remarks

The framework's implementation of IDispatch::Invoke calls IsInvokeAllowed to determine if a given function (identified by dispid) may be invoked. The default behavior for an OLE control is to allow automation methods to be invoked only if the control has been initialized; however, IsInvokeAllowed is a virtual function and may be overridden if necessary (for example, when the control is being used as an automation server).

COleControl::IsModified

Determines if the control's state has been modified.

BOOL IsModified();

Return Value

Nonzero if the control's state has been modified since it was last saved; otherwise 0.

Remarks

The state of a control is modified when a property changes value.

COleControl::IsOptimizedDraw

Determines whether the container supports optimized drawing for the current drawing operation.

BOOL IsOptimizedDraw();

Return Value

TRUE if the container supports optimized drawing for the current drawing operation; otherwise FALSE.

Remarks

If optimized drawing is supported, then the control need not select old objects (pens, brushes, fonts, etc.) into the device context when drawing is finished.

COleControl::IsSubclassedControl

Called by the framework to determine if the control subclasses a Windows control.

virtual BOOL IsSubclassedControl();

Return Value

Nonzero if the control is subclassed; otherwise 0.

Remarks

You must override this function and return TRUE if your OLE control subclasses a Windows control.

COleControl::Load

Resets any previous data loaded asynchronously and initiates a new loading of the control's asynchronous property.

void Load(LPCTSTR strNewPath, CDataPathProperty& prop);

Parameters

strNewPath
A pointer to a string containing the path that references the absolute location of the asynchronous control property.

prop
A CDataPathProperty object implementing an asynchronous control property.

COleControl::LockInPlaceActive

Prevents the container from deactivating your control.

BOOL LockInPlaceActive(BOOL bLock);

Parameters

bLock
TRUE if the in-place active state of the control is to be locked; FALSE if it is to be unlocked.

Return Value

Nonzero if the lock was successful; otherwise 0.

Remarks

Note that every locking of the control must be paired with an unlocking of the control when finished. You should only lock your control for short periods, such as while firing an event.

COleControl::OnAmbientPropertyChange

Called by the framework when an ambient property of the container has changed value.

virtual void OnAmbientPropertyChange(DISPID dispid);

Parameters

dispID
The dispatch ID of the ambient property that changed, or DISPID_UNKNOWN if multiple properties have changed.

COleControl::OnAppearanceChanged

Called by the framework when the stock Appearance property value has changed.

virtual void OnAppearanceChanged ();

Remarks

Override this function if you want notification after this property changes. The default implementation calls InvalidateControl.

COleControl::OnBackColorChanged

Called by the framework when the stock BackColor property value has changed.

virtual void OnBackColorChanged();

Remarks

Override this function if you want notification after this property changes. The default implementation calls InvalidateControl.

COleControl::OnBorderStyleChanged

Called by the framework when the stock BorderStyle property value has changed.

virtual void OnBorderStyleChanged();

Remarks

The default implementation calls InvalidateControl.

Override this function if you want notification after this property changes.

COleControl::OnClick

Called by the framework when a mouse button has been clicked or the DoClick stock method has been invoked.

virtual void OnClick(USHORT iButton);

Parameters

iButton
Index of a mouse button. Can have one of the following values:

• LEFT_BUTTON The left mouse button was clicked.

• MIDDLE_BUTTON The middle mouse button was clicked.

• RIGHT_BUTTON The right mouse button was clicked.

Remarks

The default implementation calls COleControl::FireClick.

Override this member function to modify or extend the default handling.

COleControl::OnClose

Called by the framework when the container has called the control's IOleControl::Close function.

virtual void OnClose(DWORD dwSaveOption);

Parameters

dwSaveOption
Flag that indicates whether the object should be saved before loading. Valid values are:

• OLECLOSE_SAVEIFDIRTY

• OLECLOSE_NOSAVE

• OLECLOSE_PROMPTSAVE

Remarks

By default, OnClose saves the control object if it has been modified and dwSaveOption is either OLECLOSE_SAVEIFDIRTY or OLECLOSE_PROMPTSAVE.

COleControl::OnDoVerb

Called by the framework when the container calls the IOleObject::DoVerb member function.

virtual BOOL OnDoVerb(
    LONG iVerb,
    LPMSG lpMsg,
    HWND hWndParent,
    LPCRECT lpRect);

Parameters

iVerb
The index of the control verb to be invoked.

lpMsg
A pointer to the Windows message that caused the verb to be invoked.

hWndParent
The handle to the parent window of the control. If the execution of the verb creates a window (or windows), hWndParent should be used as the parent.

lpRect
A pointer to a RECT structure into which the coordinates of the control, relative to the container, will be copied.

Return Value

Nonzero if call was successful; otherwise 0.

Remarks

The default implementation uses the ON_OLEVERB and ON_STDOLEVERB message map entries to determine the proper function to invoke.

Override this function to change the default handling of verb.

COleControl::OnDraw

Called by the framework to draw the OLE control in the specified bounding rectangle using the specified device context.

virtual void OnDraw(
    CDC* pDC,
    const CRect& rcBounds,
    const CRect& rcInvalid);

Parameters

pDC
The device context in which the drawing occurs.

rcBounds
The rectangular area of the control, including the border.

rcInvalid
The rectangular area of the control that is invalid.

Remarks

OnDraw is typically called for screen display, passing a screen device context as pDC. The rcBounds parameter identifies the rectangle in the target device context (relative to its current mapping mode). The rcInvalid parameter is the actual rectangle that is invalid. In some cases this will be a smaller area than rcBounds.

COleControl::OnDrawMetafile

Called by the framework to draw the OLE control in the specified bounding rectangle using the specified metafile device context.

virtual void OnDrawMetafile(
    CDC* pDC,
    const CRect& rcBounds);

Parameters

pDC
The device context in which the drawing occurs.

rcBounds
The rectangular area of the control, including the border.

Remarks

The default implementation calls the OnDraw function.

COleControl::OnEdit

Causes the control to be UI activated.

virtual BOOL OnEdit(
    LPMSG lpMsg,
    HWND hWndParent,
    LPCRECT lpRect);

Parameters

lpMsg
A pointer to the Windows message that invoked the verb.

hWndParent
A handle to the parent window of the control.

lpRect
A pointer to the rectangle used by the control in the container.

Return Value

Nonzero if the call is successful; otherwise 0.

Remarks

This has the same effect as invoking the control's OLEIVERB_UIACTIVATE verb.

This function is typically used as the handler function for an ON_OLEVERB message map entry. This makes an "Edit" verb available on the control's "Object" menu. For example:

ON_OLEVERB(AFX_IDS_VERB_EDIT, OnEdit)

COleControl::OnEnabledChanged

Called by the framework when the stock Enabled property value has changed.

virtual void OnEnabledChanged();

Remarks

Override this function if you want notification after this property changes. The default implementation calls InvalidateControl.

COleControl::OnEnumVerbs

Called by the framework when the container calls the IOleObject::EnumVerbs member function.

virtual BOOL OnEnumVerbs(LPENUMOLEVERB* ppenumOleVerb);

Parameters

ppenumOleVerb
A pointer to the IEnumOLEVERB object that enumerates the control's verbs.

Return Value

Nonzero if verbs are available; otherwise 0.

Remarks

The default implementation enumerates the ON_OLEVERB entries in the message map.

Override this function to change the default way of enumerating verbs.

COleControl::OnEventAdvise

Called by the framework when an event handler is connected to or disconnected from an OLE control.

virtual void OnEventAdvise(BOOL bAdvise);

Parameters

bAdvise
TRUE indicates that an event handler has been connected to the control. FALSE indicates that an event handler has been disconnected from the control.

COleControl::OnFontChanged

Called by the framework when the stock Font property value has changed.

virtual void OnFontChanged();

Remarks

The default implementation calls COleControl::InvalidateControl. If the control is subclassing a Windows control, the default implementation also sends a WM_SETFONT message to the control's window.

Override this function if you want notification after this property changes.

Example

void CMyAxCtrl::OnFontChanged()
{
   // Always set it to the container's font
   if (m_MyEdit.m_hWnd != NULL)
   {
      IFontDisp *pFontDisp = NULL;
      IFont *pFont = NULL;
      HRESULT hr;

      // Get the container's FontDisp interface
      pFontDisp = AmbientFont();
      if (pFontDisp)
      {
         hr = pFontDisp->QueryInterface(IID_IFont, (LPVOID*)&pFont);
         if (FAILED(hr))
         {
            pFontDisp->Release();
            return;
         }
      }

      HFONT hFont = NULL;
      if (pFont)
      {
         pFont->get_hFont(&hFont);
         m_MyEdit.SendMessage(WM_SETFONT, (WPARAM)hFont, 0L);
      }

      pFontDisp->Release();
   }

   // Invalidate the control
   m_MyEdit.Invalidate();
   m_MyEdit.UpdateWindow();

   COleControl::OnFontChanged();
}

COleControl::OnForeColorChanged

Called by the framework when the stock ForeColor property value has changed.

virtual void OnForeColorChanged();

Remarks

The default implementation calls InvalidateControl.

Override this function if you want notification after this property changes.

COleControl::OnFreezeEvents

Called by the framework after the container calls IOleControl::FreezeEvents.

virtual void OnFreezeEvents(BOOL bFreeze);

Parameters

bFreeze
TRUE if the control's event handling is frozen; otherwise FALSE.

Remarks

The default implementation does nothing.

Override this function if you want additional behavior when event handling is frozen or unfrozen.

COleControl::OnGetColorSet

Called by the framework when the container calls the IViewObject::GetColorSet member function.

virtual BOOL OnGetColorSet(
    DVTARGETDEVICE* ptd,
    HDC hicTargetDev,
    LPLOGPALETTE* ppColorSet);

Parameters

ptd
Points to the target device for which the picture should be rendered. If this value is NULL, the picture should be rendered for a default target device, usually a display device.

hicTargetDev
Specifies the information context on the target device indicated by ptd. This parameter can be a device context, but is not one necessarily. If ptd is NULL, hicTargetDev should also be NULL.

ppColorSet
A pointer to the location into which the set of colors that would be used should be copied. If the function does not return the color set, NULL is returned.

Return Value

Nonzero if a valid color set is returned; otherwise 0.

Remarks

The container calls this function to obtain all the colors needed to draw the OLE control. The container can use the color sets obtained in conjunction with the colors it needs to set the overall color palette. The default implementation returns FALSE.

Override this function to do any special processing of this request.

COleControl::OnGetControlInfo

Called by the framework when the control's container has requested information about the control.

virtual void OnGetControlInfo(LPCONTROLINFO pControlInfo);

Parameters

pControlInfo
Pointer to a CONTROLINFO structure to be filled in.

Remarks

This information consists primarily of a description of the control's mnemonic keys. The default implementation fills pControlInfo with default information.

Override this function if your control needs to process mnemonic keys.

COleControl::OnGetDisplayString

Called by the framework to obtain a string that represents the current value of the property identified by dispid.

virtual BOOL OnGetDisplayString(
    DISPID dispid,
    CString& strValue);

Parameters

dispid
The dispatch ID of a property of the control.

strValue
A reference to a CString object through which a string will be returned.

Return Value

Nonzero if a string has been returned in strValue; otherwise 0.

Remarks

Override this function if your control has a property whose value cannot be directly converted to a string and you want the property's value to be displayed in a container-supplied property browser.

COleControl::OnGetInPlaceMenu

Called by the framework when the control is UI activated to obtain the menu to be merged into the container's existing menu.

virtual HMENU OnGetInPlaceMenu();

Return Value

The handle of the control's menu, or NULL if the control has none. The default implementation returns NULL.

Remarks

For more information on merging OLE resources, see the article Menus and Resources (OLE).

COleControl::OnGetNaturalExtent

Called by the framework in response to a container's IViewObjectEx::GetNaturalExtent request.

virtual BOOL OnGetNaturalExtent(
    DWORD dwAspect,
    LONG lindex,
    DVTARGETDEVICE* ptd,
    HDC hicTargetDev,
    DVEXTENTINFO* pExtentInfo,
    LPSIZEL psizel);

Parameters

dwAspect
Specifies how the object is to be represented. Representations include content, an icon, a thumbnail, or a printed document. Valid values are taken from the enumeration DVASPECT or DVASPECT2.

lindex
The portion of the object that is of interest. Currently only -1 is valid.

ptd
Points to the DVTARGETDEVICE structure defining the target device for which the object's size should be returned.

hicTargetDev
Specifies the information context for the target device indicated by the ptd parameter from which the object can extract device metrics and test the device's capabilities. If ptd is NULL, the object should ignore the value in the hicTargetDev parameter.

pExtentInfo
Points to the DVEXTENTINFO structure that specifies sizing data. The DVEXTENTINFO structure is:

typedef struct tagExtentInfo
{
    UINT cb;
    DWORD dwExtentMode;
    SIZEL sizelProposed;
}   DVEXTENTINFO;

The structure member dwExtentMode can take one of two values:

• DVEXTENT_CONTENT Inquire how big the control should be to exactly fit content (snap-to-size)

• DVEXTENT_INTEGRAL When resizing, pass proposed size to control

psizel
Points to sizing data returned by control. The returned sizing data is set to -1 for any dimension that was not adjusted.

Return Value

Nonzero if it successfully returns or adjusts the size; otherwise 0.

Remarks

Override this function to return the object's display size closest to the proposed size and extent mode in the DVEXTENTINFO structure. The default implementation returns FALSE and makes no adjustments to the size.

COleControl::OnGetPredefinedStrings

Called by the framework to obtain a set of predefined strings representing the possible values for a property.

virtual BOOL OnGetPredefinedStrings(
    DISPID dispid,
    CStringArray* pStringArray,
    CDWordArray* pCookieArray);

Parameters

dispid
The dispatch ID of a property of the control.

pStringArray
A string array to be filled in with return values.

pCookieArray
A DWORD array to be filled in with return values.

Return Value

Nonzero if elements have been added to pStringArray and pCookieArray.

Remarks

Override this function if your control has a property with a set of possible values that can be represented by strings. For each element added to pStringArray, you should add a corresponding "cookie" element to pCookieArray. These "cookie" values may later be passed by the framework to the COleControl::OnGetPredefinedValue function.

COleControl::OnGetPredefinedValue

Called by the framework to obtain the value corresponding to one of the predefined strings previously returned by an override of COleControl::OnGetPredefinedStrings.

virtual BOOL OnGetPredefinedValue(
    DISPID dispid,
    DWORD dwCookie,
    VARIANT* lpvarOut);

Parameters

dispid
The dispatch ID of a property of the control.

dwCookie
A cookie value previously returned by an override of COleControl::OnGetPredefinedStrings.

lpvarOut
Pointer to a VARIANT structure through which a property value will be returned.

Return Value

Nonzero if a value has been returned in lpvarOut; otherwise 0.

COleControl::OnGetViewExtent

Called by the framework in response to a container's IViewObject2::GetExtent request.

virtual BOOL OnGetViewExtent(
    DWORD dwDrawAspect,
    LONG lindex,
    DVTARGETDEVICE* ptd,
    LPSIZEL lpsizel);

Parameters

dwDrawAspect
DWORD describing which form, or aspect, of an object is to be displayed. Valid values are taken from the enumeration DVASPECT or DVASPECT2.

lindex
The portion of the object that is of interest. Currently only -1 is valid.

ptd
Points to the DVTARGETDEVICE structure defining the target device for which the object's size should be returned.

lpsizel
Points to the location where the object's size is returned.

Return Value

Nonzero if extent information is successfully returned; otherwise 0.

Remarks

Override this function if your control uses two-pass drawing, and its opaque and transparent parts have different dimensions.

COleControl::OnGetViewRect

Called by the framework in response to a container's IViewObjectEx::GetRect request.

virtual BOOL OnGetViewRect(DWORD dwAspect, LPRECTL pRect);

Parameters

dwAspect
DWORD describing which form, or aspect, of an object is to be displayed. Valid values are taken from the enumeration DVASPECT or DVASPECT2:

• DVASPECT_CONTENT Bounding rectangle of the whole object. Top-left corner at the object's origin and size equal to the extent returned by GetViewExtent.

• DVASPECT_OPAQUE Objects with a rectangular opaque region return that rectangle. Others fail.

• DVASPECT_TRANSPARENT Rectangle covering all transparent or irregular parts.

pRect
Points to the RECTL structure specifying the rectangle in which the object should be drawn. This parameter controls the positioning and stretching of the object.

Return Value

Nonzero if the rectangle sized to the object is successfully returned; otherwise 0.

Remarks

The object's size is converted by OnGetViewRect into a rectangle starting at a specific position (the default is the upper left corner of the display). Override this function if your control uses two-pass drawing, and its opaque and transparent parts have different dimensions.

COleControl::OnGetViewStatus

Called by the framework in response to a container's IViewObjectEx::GetViewStatus request.

virtual DWORD OnGetViewStatus();

Return Value

One of the values of the VIEWSTATUS enumeration if successful; otherwise 0. Possible values are any combination of the following:

Name	Description
VIEWSTATUS_OPAQUE	Object is completely opaque. If this bit is not set, the object contains transparent parts. This bit applies only to content-related aspects and not to DVASPECT_ICON or DVASPECT_DOCPRINT.
VIEWSTATUS_SOLIDBKGND	Object has a solid background (consisting in a solid color, not a brush pattern). This bit is meaningful only if VIEWSTATUS_OPAQUE is set and applies only to content-related aspects and not to DVASPECT_ICON or DVASPECT_DOCPRINT.
VIEWSTATUS_DVASPECTOPAQUE	Object supports DVASPECT_OPAQUE. All IViewObjectEx methods that take a drawing aspect as a parameter can be called with this aspect.
VIEWSTATUS_DVASPECTTRANSPARENT	Object supports DVASPECT_TRANSPARENT. All IViewObjectEx methods that take a drawing aspect as a parameter can be called with this aspect.

Remarks

Override this function if your control uses two-pass drawing. The default implementation returns VIEWSTATUS_OPAQUE.

COleControl::OnHideToolBars

Called by the framework when the control is UI deactivated.

virtual void OnHideToolBars();

Remarks

The implementation should hide all toolbars displayed by OnShowToolbars.

COleControl::OnInactiveMouseMove

Called by the container for the inactive object under the mouse pointer on receipt of a WM_MOUSEMOVE message.

virtual void OnInactiveMouseMove(
    LPCRECT lprcBounds,
    long x,
    long y,
    DWORD dwKeyState);

Parameters

lprcBounds
The object bounding rectangle, in client coordinates of the containing window. Tells the object its exact position and size on the screen when the WM_MOUSEMOVE message was received.

x
The x coordinate of the mouse location in client coordinates of the containing window.

y
The y coordinate of the mouse location in client coordinates of the containing window.

dwKeyState
Identifies the current state of the keyboard modifier keys on the keyboard. Valid values can be a combination of any of the flags MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON, and MK_RBUTTON.

Remarks

Note that window client coordinates (pixels) are used to pass the mouse cursor position. This is made possible by also passing the bounding rectangle of the object in the same coordinate system.

COleControl::OnInactiveSetCursor

Called by the container for the inactive object under the mouse pointer on receipt of a WM_SETCURSOR message.

virtual BOOL OnInactiveSetCursor(
    LPCRECT lprcBounds,
    long x,
    long y,
    DWORD dwMouseMsg,
    BOOL bSetAlways);

Parameters

lprcBounds
The object bounding rectangle, in client coordinates of the containing window. Tells the object its exact position and size on the screen when the WM_SETCURSOR message was received.

x
The x coordinate of the mouse location in client coordinates of the containing window.

y
The y coordinate of the mouse location in client coordinates of the containing window.

dwMouseMsg
The identifier of the mouse message for which a WM_SETCURSOR occurred.

bSetAlways
Specifies whether or not the object must set the cursor. If TRUE, the object must set the cursor; if FALSE, the cursor is not obligated to set the cursor, and should return S_FALSE in that case.

Return Value

Nonzero if successful; otherwise 0.

Remarks

Note that window client coordinates (pixels) are used to pass the mouse cursor position. This is made possible by also passing the bounding rectangle of the object in the same coordinate system.

COleControl::OnKeyDownEvent

Called by the framework after a stock KeyDown event has been processed.

virtual void OnKeyDownEvent(
    USHORT nChar,
    USHORT nShiftState);

Parameters

nChar
The virtual key code value of the pressed key. For a list of standard virtual key codes, see Winuser.h

nShiftState
Contains a combination of the following flags:

• SHIFT_MASK The SHIFT key was pressed during the action.

• CTRL_MASK The CTRL key was pressed during the action.

• ALT_MASK The ALT key was pressed during the action.

Remarks

Override this function if your control needs access to the key information after the event has been fired.

COleControl::OnKeyPressEvent

Called by the framework after the stock KeyPress event has been fired.

virtual void OnKeyPressEvent(USHORT nChar);

Parameters

nChar
Contains the virtual key code value of the key pressed. For a list of standard virtual key codes, see Winuser.h

Remarks

Note that the nChar value may have been modified by the container.

Override this function if you want notification after this event occurs.

COleControl::OnKeyUpEvent

Called by the framework after a stock KeyDown event has been processed.

virtual void OnKeyUpEvent(
    USHORT nChar,
    USHORT nShiftState);

Parameters

nChar
The virtual key code value of the pressed key. For a list of standard virtual key codes, see Winuser.h

nShiftState
Contains a combination of the following flags:

• SHIFT_MASK The SHIFT key was pressed during the action.

• CTRL_MASK The CTRL key was pressed during the action.

• ALT_MASK The ALT key was pressed during the action.

Remarks

Override this function if your control needs access to the key information after the event has been fired.

COleControl::OnMapPropertyToPage

Called by the framework to obtain the class ID of a property page that implements editing of the specified property.

virtual BOOL OnMapPropertyToPage(
    DISPID dispid,
    LPCLSID lpclsid,
    BOOL* pbPageOptional);

Parameters

dispid
The dispatch ID of a property of the control.

lpclsid
Pointer to a CLSID structure through which a class ID will be returned.

pbPageOptional
Returns an indicator of whether use of the specified property page is optional.

Return Value

Nonzero if a class ID has been returned in lpclsid; otherwise 0.

Remarks

Override this function to provide a way to invoke your control's property pages from the container's property browser.

COleControl::OnMnemonic

Called by the framework when the container has detected that a mnemonic key of the OLE control has been pressed.

virtual void OnMnemonic(LPMSG pMsg);

Parameters

pMsg
Pointer to the Windows message generated by a mnemonic key press.

COleControl::OnProperties

Called by the framework when the control's properties verb has been invoked by the container.

virtual BOOL OnProperties(
    LPMSG lpMsg,
    HWND hWndParent,
    LPCRECT lpRect);

Parameters

lpMsg
A pointer to the Windows message that invoked the verb.

hWndParent
A handle to the parent window of the control.

lpRect
A pointer to the rectangle used by the control in the container.

Return Value

Nonzero if the call is successful; otherwise 0.

Remarks

The default implementation displays a modal property dialog box.

You can also use this function to cause the display of your control's property pages. Make a call to the OnProperties function, passing the handle of your control's parent in the hWndParent parameter. In this case, the values of the lpMsg and lpRect parameters are ignored.

COleControl::OnQueryHitPoint

Called by the framework in response to a container's IViewObjectEx::QueryHitPoint request.

virtual BOOL OnQueryHitPoint(
    DWORD dwAspect,
    LPCRECT pRectBounds,
    POINT ptlLoc,
    LONG lCloseHint,
    DWORD* pHitResult);

Parameters

dwAspect
Specifies how the object is represented. Valid values are taken from the enumeration DVASPECT or DVASPECT2.

pRectBounds
Pointer to a RECT structure specifying the bounding rectangle of the OLE control client area.

ptlLoc
Pointer to the POINT structure specifying the point to be checked for a hit. The point is specified in OLE client area coordinates.

lCloseHint
The distance that defines "close" to the point checked for a hit.

pHitResult
Pointer to the result of the hit query. One of the following values:

• HITRESULT_OUTSIDE ptlLoc is outside the OLE object and not close.

• HITRESULT_TRANSPARENT ptlLoc is within the bounds of the OLE object, but not close to the image. For example, a point in the middle of a transparent circle could be HITRESULT_TRANSPARENT.

• HITRESULT_CLOSE ptlLoc is inside or outside the OLE object but close enough to the object to be considered inside. Small, thin, or detailed objects may use this value. Even if a point is outside the bounding rectangle of an object it may still be close (this is needed for hitting small objects).

• HITRESULT_HIT ptlLoc is within the image of the object.

Return Value

Nonzero if a hit result is successfully returned; otherwise 0. A hit is an overlap with the OLE control display area.

Remarks

Queries whether an object's display rectangle overlaps the given point (hits the point). QueryHitPoint can be overridden to test hits for non-rectangular objects.

COleControl::OnQueryHitRect

Called by the framework in response to a container's IViewObjectEx::QueryHitRect request.

virtual BOOL OnQueryHitRect(
    DWORD dwAspect,
    LPCRECT pRectBounds,
    LPCRECT prcLoc,
    LONG lCloseHint,
    DWORD* pHitResult);

Parameters

dwAspect
Specifies how the object is to be represented. Valid values are taken from the enumeration DVASPECT or DVASPECT2.

pRectBounds
Pointer to a RECT structure specifying the bounding rectangle of the OLE control client area.

prcLoc
Pointer to the RECT structure specifying the rectangle to be checked for a hit (overlap with the object rectangle), relative to the upper left corner of the object.

lCloseHint
Not used.

pHitResult
Pointer to the result of the hit query. One of the following values:

• HITRESULT_OUTSIDE no point in the rectangle is hit by the OLE object.

• HITRESULT_HIT at least one point in the rectangle would be a hit on the object.

Return Value

Nonzero if a hit result is successfully returned; otherwise 0.

Remarks

Queries whether an object's display rectangle overlaps any point in the given rectangle (hits the rectangle). QueryHitRect can be overridden to test hits for non-rectangular objects.

COleControl::OnRenderData

Called by the framework to retrieve data in the specified format.

virtual BOOL OnRenderData(
    LPFORMATETC lpFormatEtc,
    LPSTGMEDIUM lpStgMedium);

Parameters

lpFormatEtc
Points to the FORMATETC structure specifying the format in which information is requested.

lpStgMedium
Points to a STGMEDIUM structure in which the data is to be returned.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The specified format is one previously placed in the control object using the DelayRenderData or DelayRenderFileData member functions for delayed rendering. The default implementation of this function calls OnRenderFileData or OnRenderGlobalData, respectively, if the supplied storage medium is either a file or memory. If the requested format is CF_METAFILEPICT or the persistent property set format, the default implementation renders the appropriate data and returns nonzero. Otherwise, it returns 0 and does nothing.

If lpStgMedium->tymed is TYMED_NULL, the STGMEDIUM should be allocated and filled as specified by lpFormatEtc->tymed. If not TYMED_NULL, the STGMEDIUM should be filled in place with the data.

Override this function to provide your data in the requested format and medium. Depending on your data, you may want to override one of the other versions of this function instead. If your data is small and fixed in size, override OnRenderGlobalData. If your data is in a file, or is of variable size, override OnRenderFileData.

For more information, see the FORMATETC and STGMEDIUM structures in the Windows SDK.

COleControl::OnRenderFileData

Called by the framework to retrieve data in the specified format when the storage medium is a file.

virtual BOOL OnRenderFileData(
    LPFORMATETC lpFormatEtc,
    CFile* pFile);

Parameters

lpFormatEtc
Points to the FORMATETC structure specifying the format in which information is requested.

pFile
Points to a CFile object in which the data is to be rendered.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The specified format is one previously placed in the control object using the DelayRenderData member function for delayed rendering. The default implementation of this function simply returns FALSE.

Override this function to provide your data in the requested format and medium. Depending on your data, you might want to override one of the other versions of this function instead. If you want to handle multiple storage mediums, override OnRenderData. If your data is in a file, or is of variable size, override OnRenderFileData.

For more information, see the FORMATETC structure in the Windows SDK.

COleControl::OnRenderGlobalData

Called by the framework to retrieve data in the specified format when the specified storage medium is global memory.

virtual BOOL OnRenderGlobalData(
    LPFORMATETC lpFormatEtc,
    HGLOBAL* phGlobal);

Parameters

lpFormatEtc
Points to the FORMATETC structure specifying the format in which information is requested.

phGlobal
Points to a handle to global memory in which the data is to be returned. If no memory has been allocated, this parameter can be NULL.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The specified format is one previously placed in the control object using the DelayRenderData member function for delayed rendering. The default implementation of this function simply returns FALSE.

If phGlobal is NULL, then a new HGLOBAL should be allocated and returned in phGlobal. Otherwise, the HGLOBAL specified by phGlobal should be filled with the data. The amount of data placed in the HGLOBAL must not exceed the current size of the memory block. Also, the block cannot be reallocated to a larger size.

Override this function to provide your data in the requested format and medium. Depending on your data, you may want to override one of the other versions of this function instead. If you want to handle multiple storage mediums, override OnRenderData. If your data is in a file, or is of variable size, override OnRenderFileData.

For more information, see the FORMATETC structure in the Windows SDK.

COleControl::OnResetState

Called by the framework when the control's properties should be set to their default values.

virtual void OnResetState();

Remarks

The default implementation calls DoPropExchange, passing a CPropExchange object that causes properties to be set to their default values.

The control writer can insert initialization code for the OLE control in this overridable. This function is called when IPersistStream::Load or IPersistStorage::Load fails, or IPersistStreamInit::InitNew or IPersistStorage::InitNew is called, without first calling either IPersistStream::Load or IPersistStorage::Load.

COleControl::OnSetClientSite

Called by the framework when the container has called the control's IOleControl::SetClientSite function.

virtual void OnSetClientSite();

Remarks

By default, OnSetClientSite checks whether data path properties are loaded and, if they are, calls DoDataPathPropExchange.

Override this function to do any special processing of this notification. In particular, overrides of this function should call the base class.

COleControl::OnSetData

Called by the framework to replace the control's data with the specified data.

virtual BOOL OnSetData(
    LPFORMATETC lpFormatEtc,
    LPSTGMEDIUM lpStgMedium,
    BOOL bRelease);

Parameters

lpFormatEtc
Pointer to a FORMATETC structure specifying the format of the data.

lpStgMedium
Pointer to a STGMEDIUM structure in which the data resides.

bRelease
TRUE if the control should free the storage medium; FALSE if the control should not free the storage medium.

Return Value

Nonzero if successful; otherwise 0.

Remarks

If the data is in the persistent property set format, the default implementation modifies the control's state accordingly. Otherwise, the default implementation does nothing. If bRelease is TRUE, then a call to ReleaseStgMedium is made; otherwise not.

Override this function to replace the control's data with the specified data.

For more information, see the FORMATETC and STGMEDIUM structures in the Windows SDK.

COleControl::OnSetExtent

Called by the framework when the control's extent needs to be changed, as a result of a call to IOleObject::SetExtent.

virtual BOOL OnSetExtent(LPSIZEL lpSizeL);

Parameters

lpSizeL
A pointer to the SIZEL structure that uses long integers to represent the width and height of the control, expressed in HIMETRIC units.

Return Value

Nonzero if the size change was accepted; otherwise 0.

Remarks

The default implementation handles the resizing of the control's extent. If the control is in-place active, a call to the container's OnPosRectChanged is then made.

Override this function to alter the default resizing of your control.

COleControl::OnSetObjectRects

Called by the framework to implement a call to IOleInPlaceObject::SetObjectRects.

virtual BOOL OnSetObjectRects(
    LPCRECT lpRectPos,
    LPCRECT lpRectClip);

Parameters

lpRectPos
A pointer to a RECT structure indicating the control's new position and size relative to the container.

lpRectClip
A pointer to a RECT structure indicating a rectangular area to which the control is to be clipped.

Return Value

Nonzero if the repositioning was accepted; otherwise 0.

Remarks

The default implementation automatically handles the repositioning and resizing of the control window and returns TRUE.

Override this function to alter the default behavior of this function.

COleControl::OnShowToolBars

Called by the framework when the control has been UI activated.

virtual void OnShowToolBars();

Remarks

The default implementation does nothing.

COleControl::OnTextChanged

Called by the framework when the stock Caption or Text property value has changed.

virtual void OnTextChanged();

Remarks

The default implementation calls InvalidateControl.

Override this function if you want notification after this property changes.

COleControl::OnWindowlessMessage

Called by the framework in response to a container's IOleInPlaceObjectWindowless::OnWindowMessage request.

virtual BOOL OnWindowlessMessage(
    UINT msg,
    WPARAM wParam,
    LPARAM lParam,
    LRESULT* plResult);

Parameters

msg
Message identifier as passed by Windows.

wParam
As passed by Windows. Specifies additional message-specific information. The contents of this parameter depend on the value of the msg parameter.

lParam
As passed by Windows. Specifies additional message-specific information. The contents of this parameter depend on the value of the msg parameter.

plResult
Windows result code. Specifies the result of the message processing and depends on the message sent.

Return Value

Nonzero if successful; otherwise 0.

Remarks

Processes window messages for windowless controls. COleControl's OnWindowlessMessage should be used for window messages other than mouse messages and keyboard messages. COleControl provides SetCapture and SetFocus specifically to get mouse capture and keyboard focus for windowless OLE objects.

Because windowless objects do not have a window, they need a mechanism to let the container dispatch messages to them. A windowless OLE object gets messages from its container, through the OnWindowMessage method on the IOleInPlaceObjectWindowless interface (an extension of IOleInPlaceObject for windowless support). OnWindowMessage does not take an HWND parameter.

COleControl::ParentToClient

Translates the coordinates of pPoint into client coordinates.

virtual UINT ParentToClient(
    LPCRECT lprcBounds,
    LPPOINT pPoint,
    BOOL bHitTest = FALSE) const;

Parameters

lprcBounds
Pointer to the bounds of the OLE control within the container. Not the client area but the area of the entire control including borders and scroll bars.

pPoint
Pointer to the parent (container) point to be translated into the coordinates of the client area of the control.

bHitTest
Specifies whether or not hit testing is to be done on the point.

Return Value

If bHitTest is FALSE, returns HTNOWHERE. If bHitTest is TRUE, returns the location in which the parent (container) point landed in the client area of the OLE control and is one of the following mouse hit-test values:

• HTBORDER In the border of a window that does not have a sizing border.

• HTBOTTOM In the lower horizontal border of the window.

• HTBOTTOMLEFT In the lower-left corner of the window border.

• HTBOTTOMRIGHT In the lower-right corner of the window border.

• HTCAPTION In a title-bar area.

• HTCLIENT In a client area.

• HTERROR On the screen background or on a dividing line between windows (same as HTNOWHERE except that the DefWndProc Windows function produces a system beep to indicate an error).

• HTGROWBOX In a size box.

• HTHSCROLL In the horizontal scroll bar.

• HTLEFT In the left border of the window.

• HTMAXBUTTON In a Maximize button.

• HTMENU In a menu area.

• HTMINBUTTON In a Minimize button.

• HTNOWHERE On the screen background or on a dividing line between windows.

• HTREDUCE In a Minimize button.

• HTRIGHT In the right border of the window.

• HTSIZE In a size box (same as HTGROWBOX).

• HTSYSMENU In a Control menu or in a Close button in a child window.

• HTTOP In the upper horizontal border of the window.

• HTTOPLEFT In the upper-left corner of the window border.

• HTTOPRIGHT In the upper-right corner of the window border.

• HTTRANSPARENT In a window currently covered by another window.

• HTVSCROLL In the vertical scroll bar.

• HTZOOM In a Maximize button.

Remarks

On input pPoint is relative to the origin of the parent (upper left corner of the container). On output pPoint is relative to the origin of the client area of the OLE control (upper left corner of the client area of the control).

COleControl::PostModalDialog

Notifies the container that a modal dialog box has been closed.

void PostModalDialog(HWND hWndParent = NULL);

Parameters

hWndParent
Handle to the parent window of the modal dialog box.

Remarks

Call this function after displaying any modal dialog box. You must call this function so that the container can enable any top-level windows disabled by PreModalDialog. This function should be paired with a call to PreModalDialog.

COleControl::PreModalDialog

Notifies the container that a modal dialog box is about to be displayed.

void PreModalDialog(HWND hWndParent = NULL);

Parameters

hWndParent
Handle to the parent window of the modal dialog box.

Remarks

Call this function before displaying any modal dialog box. You must call this function so that the container can disable all its top-level windows. After the modal dialog box has been displayed, you must then call PostModalDialog.

COleControl::RecreateControlWindow

Destroys and re-creates the control's window.

void RecreateControlWindow();

Remarks

This may be necessary if you need to change the window's style bits.

COleControl::Refresh

Forces a repaint of the OLE control.

void Refresh();

Remarks

This function is supported by the COleControl base class as a stock method, called Refresh. This allows users of your OLE control to repaint the control at a specific time. For more information on this method, see the article ActiveX Controls: Methods.

COleControl::ReleaseCapture

Releases mouse capture.

BOOL ReleaseCapture();

Return Value

Nonzero if successful; otherwise 0.

Remarks

If the control currently has the mouse capture, the capture is released. Otherwise, this function has no effect.

COleControl::ReleaseDC

Releases the display device context of a container of a windowless control, freeing the device context for use by other applications.

int ReleaseDC(CDC* pDC);

Parameters

pDC
Identifies the container device context to be released.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The application must call ReleaseDC for each call to GetDC.

COleControl::ReparentControlWindow

Sets the parent of the control.

virtual void ReparentControlWindow(
    HWND hWndOuter,
    HWND hWndParent);

Parameters

hWndOuter
The handle of the control window.

hWndParent
The handle of the new parent window.

Remarks

Call this function to reset the parent of the control window.

COleControl::ResetStockProps

Initializes the state of the COleControl stock properties to their default values.

void ResetStockProps();

Remarks

The properties are: Appearance, BackColor, BorderStyle, Caption, Enabled, Font, ForeColor, hWnd, and Text. For a description of stock properties, see ActiveX Controls: Adding Stock Properties.

You can improve a control's binary initialization performance by using ResetStockProps and ResetVersion to override COleControl::OnResetState. See the example below. For further information on optimizing initialization, see ActiveX Controls: Optimization.

Example

void CMyAxCtrl::OnResetState()
{
   ResetVersion(MAKELONG(_wVerMinor, _wVerMajor));
   ResetStockProps();

   // initialize custom properties here
}

COleControl::ResetVersion

Initializes the version number to specified value.

void ResetVersion(DWORD dwVersionDefault);

Parameters

dwVersionDefault
The version number to be assigned to the control.

Remarks

You can improve a control's binary initialization performance by using ResetVersion and ResetStockProps to override COleControl::OnResetState. See the example at ResetStockProps. For further information on optimizing initialization, see ActiveX Controls: Optimization.

COleControl::ScrollWindow

Allows a windowless OLE object to scroll an area within its in-place active image on the screen.

void ScrollWindow(
    int xAmount,
    int yAmount,
    LPCRECT lpRect = NULL,
    LPCRECT lpClipRect = NULL);

Parameters

xAmount
Specifies the amount, in device units, of horizontal scrolling. This parameter must be a negative value to scroll to the left.

yAmount
Specifies the amount, in device units, of vertical scrolling. This parameter must be a negative value to scroll upward.

lpRect
Points to a CRect object or RECT structure that specifies the portion of the OLE object's client area to scroll, in client coordinates of the containing window. If lpRect is NULL, the entire OLE object's client area is scrolled.

lpClipRect
Points to a CRect object or RECT structure that specifies the rectangle to clip to. Only pixels inside the rectangle are scrolled. Bits outside the rectangle are not affected even if they are in the lpRect rectangle. If lpClipRect is NULL, no clipping is performed on the scroll rectangle.

COleControl::SelectFontObject

Selects a font into a device context.

CFont* SelectFontObject(
    CDC* pDC,
    CFontHolder& fontHolder);

Parameters

pDC
Pointer to a device context object.

fontHolder
Reference to the CFontHolder object representing the font to be selected.

Return Value

A pointer to the previously selected font. When the caller has finished all drawing operations that use fontHolder, it should reselect the previously selected font by passing it as a parameter to CDC::SelectObject.

COleControl::SelectStockFont

Selects the stock Font property into a device context.

CFont* SelectStockFont(CDC* pDC);

Parameters

pDC
The device context into which the font will be selected.

Return Value

A pointer to the previously selected CFont object. You should use CDC::SelectObject to select this font back into the device context when you are finished.

COleControl::SerializeExtent

Serializes or initializes the state of the display space allotted to the control.

void SerializeExtent(CArchive& ar);

Parameters

ar
A CArchive object to serialize to or from.

Remarks

You can improve a control's binary persistence performance by using SerializeExtent, SerializeStockProps, and SerializeVersion to override COleControl::Serialize. See the example below. For further information on optimizing initialization, see ActiveX Controls: Optimization.

Example

void CMyAxCtrl::Serialize(CArchive &ar)
{
   SerializeVersion(ar, MAKELONG(_wVerMinor, _wVerMajor));
   SerializeExtent(ar);
   SerializeStockProps(ar);

   if (ar.IsStoring())
   { // storing code
   }
   else
   { // loading code
   }
}

COleControl::SerializeStockProps

Serializes or initializes the state of the COleControl stock properties: Appearance, BackColor, BorderStyle, Caption, Enabled, Font, ForeColor, and Text.

void SerializeStockProps(CArchive& ar);

Parameters

ar
A CArchive object to serialize to or from.

Remarks

For a description of stock properties, see ActiveX Controls: Adding Stock Properties.

You can improve a control's binary persistence performance by using SerializeStockProps, SerializeExtent, and SerializeVersion to override COleControl::Serialize. For an example, see the code at SerializeExtent. For further information on optimizing initialization, see ActiveX Controls: Optimization.

COleControl::SerializeVersion

Serializes or initializes the state of a control's version information.

DWORD SerializeVersion(
    CArchive& ar,
    DWORD dwVersionDefault,
    BOOL bConvert = TRUE);

Parameters

ar
A CArchive object to serialize to or from.

dwVersionDefault
The current version number of the control.

bConvert
Indicates whether persistent data should be converted to the latest format when it is saved, or maintained in the same format it had when it was loaded.

Return Value

The version number of the control. If the specified archive is loading, SerializeVersion returns the version loaded from that archive. Otherwise, it returns the currently loaded version.

Remarks

You can improve a control's binary persistence performance by using SerializeVersion, SerializeExtent, and SerializeStockProps to override COleControl::Serialize. For an example, see the code at SerializeExtent. For further information on optimizing initialization, see ActiveX Controls: Optimization.

COleControl::SetAppearance

Sets the stock Appearance property value of your control.

void SetAppearance (short sAppearance);

Parameters

sAppearance
A short (VT_I2) value to be used for the appearance of your control. A value of zero sets the control's appearance to flat and a value of 1 sets the control's appearance to 3D.

Remarks

For more about stock properties, see ActiveX Controls: Properties.

COleControl::SetBackColor

Sets the stock BackColor property value of your control.

void SetBackColor(OLE_COLOR dwBackColor);

Parameters

dwBackColor
An OLE_COLOR value to be used for background drawing of your control.

Remarks

For more information on using this property and other related properties, see the article ActiveX Controls: Properties.

COleControl::SetBorderStyle

Sets the stock BorderStyle property value of your control.

void SetBorderStyle(short sBorderStyle);

Parameters

sBorderStyle
The new border style for the control; 0 indicates no border and 1 indicates a normal border.

Remarks

The control window will then be re-created and OnBorderStyleChanged called.

COleControl::SetCapture

Causes the control's container window to take possession of the mouse capture on the control's behalf.

CWnd* SetCapture();

Return Value

A pointer to the CWnd window object that previously received mouse input.

Remarks

If the control is activated and windowless, this function causes the control's container window to take possession of the mouse capture, on the control's behalf. Otherwise, this function causes the control itself to take possession of the mouse capture (same as CWnd::SetCapture).

COleControl::SetControlSize

Sets the size of the OLE control window and notifies the container that the control site is changing.

BOOL SetControlSize(int cx, int cy);

Parameters

cx
Specifies the new width of the control in pixels.

cy
Specifies the new height of the control in pixels.

Return Value

Nonzero if the call was successful; otherwise 0.

Remarks

This function should not be used in your control's constructor.

Note that all coordinates for control windows are relative to the upper-left corner of the control.

COleControl::SetEnabled

Sets the stock Enabled property value of your control.

void SetEnabled(BOOL bEnabled);

Parameters

bEnabled
TRUE if the control is to be enabled; otherwise FALSE.

Remarks

After setting this property, OnEnabledChange is called.

COleControl::SetFocus

Causes the control's container window to take possession of the input focus on the control's behalf.

CWnd* SetFocus();

Return Value

A pointer to the CWnd window object that previously had the input focus, or NULL if there is no such window.

Remarks

If the control is activated and windowless, this function causes the control's container window to take possession of the input focus, on the control's behalf. The input focus directs keyboard input to the container's window, and the container dispatches all subsequent keyboard messages to the OLE object that calls SetFocus. Any window that previously had the input focus loses it.

If the control is not windowless, this function causes the control itself to take possession of the input focus (same as CWnd::SetFocus).

COleControl::SetFont

Sets the stock Font property of your control.

void SetFont(LPFONTDISP pFontDisp);

Parameters

pFontDisp
A pointer to a Font dispatch interface.

COleControl::SetForeColor

Sets the stock ForeColor property value of your control.

void SetForeColor(OLE_COLOR dwForeColor);

Parameters

dwForeColor
An OLE_COLOR value to be used for foreground drawing of your control.

Remarks

For more information on using this property and other related properties, see the article ActiveX Controls: Properties.

COleControl::SetInitialDataFormats

Called by the framework to initialize the list of data formats supported by the control.

virtual void SetInitialDataFormats();

Remarks

The default implementation specifies two formats: CF_METAFILEPICT and the persistent property set.

COleControl::SetInitialSize

Sets the size of an OLE control when first displayed in a container.

void SetInitialSize(
    int cx,
    int cy);

Parameters

cx
The initial width of the OLE control in pixels.

cy
The initial height of the OLE control in pixels.

Remarks

Call this function in your constructor to set the initial size of your control. The initial size is measured in device units, or pixels. It is recommended that this call be made in your control's constructor.

COleControl::SetModifiedFlag

Changes the modified state of a control.

void SetModifiedFlag(BOOL bModified = TRUE);

Parameters

bModified
The new value for the control's modified flag. TRUE indicates that the control's state has been modified; FALSE indicates that the control's state has just been saved.

Remarks

Call this function whenever a change occurs that would affect your control's persistent state. For example, if the value of a persistent property changes, call this function with bModified TRUE.

COleControl::SetNotPermitted

Indicates that an edit request has failed.

void SetNotPermitted();

Remarks

Call this function when BoundPropertyRequestEdit fails. This function throws an exception of type COleDispScodeException to indicate that the set operation was not permitted.

COleControl::SetNotSupported

Prevents modification to a control's property value by the user.

void SetNotSupported();

Remarks

Call this function in place of the Set function of any property where modification of the property value by the control's user is not supported. One example would be a property that is read only.

COleControl::SetRectInContainer

Sets the coordinates of the control's rectangle relative to the container, expressed in device units.

BOOL SetRectInContainer(LPCRECT lpRect);

Parameters

lpRect
A pointer to a rectangle containing the control's new coordinates relative to the container.

Return Value

Nonzero if the call was successful; otherwise 0.

Remarks

If the control is open, it is resized; otherwise the container's OnPosRectChanged function is called.

COleControl::SetText

Sets the value of your control's stock Caption or Text property.

void SetText(LPCTSTR pszText);

Parameters

pszText
A pointer to a character string.

Remarks

Note that the stock Caption and Text properties are both mapped to the same value. This means that any changes made to either property will automatically change both properties. In general, a control should support either the stock Caption or Text property, but not both.

COleControl::ThrowError

Signals the occurrence of an error in your control.

void ThrowError(
    SCODE sc,
    UINT nDescriptionID,
    UINT nHelpID = -1);

void ThrowError(
    SCODE sc,
    LPCTSTR pszDescription = NULL,
    UINT nHelpID = 0);

Parameters

sc
The status code value to be reported. For a complete list of possible codes, see the article ActiveX Controls: Advanced Topics.

nDescriptionID
The string resource ID of the exception to be reported.

nHelpID
The help ID of the topic to be reported on.

pszDescription
A string containing an explanation of the exception to be reported.

Remarks

This function should only be called from within a Get or Set function for an OLE property, or the implementation of an OLE automation method. If you need to signal errors that occur at other times, you should fire the stock Error event.

COleControl::TransformCoords

Transforms coordinate values between HIMETRIC units and the container's native units.

void TransformCoords(
    POINTL* lpptlHimetric,
    POINTF* lpptfContainer,
    DWORD flags);

Parameters

lpptlHimetric
Pointer to a POINTL structure containing coordinates in HIMETRIC units.

lpptfContainer
Pointer to a POINTF structure containing coordinates in the container's unit size.

flags
A combination of the following values:

• XFORMCOORDS_POSITION A position in the container.

• XFORMCOORDS_SIZE A size in the container.

• XFORMCOORDS_HIMETRICTOCONTAINER Transform HIMETRIC units to the container's units.

• XFORMCOORDS_CONTAINERTOHIMETRIC Transform the container's units to HIMETRIC units.

Remarks

The first two flags, XFORMCOORDS_POSITION and XFORMCOORDS_SIZE, indicate whether the coordinates should be treated as a position or a size. The remaining two flags indicate the direction of transformation.

COleControl::TranslateColor

Converts a color value from the OLE_COLOR data type to the COLORREF data type.

COLORREF TranslateColor(
    OLE_COLOR clrColor,
    HPALETTE hpal = NULL);

Parameters

clrColor
A OLE_COLOR data type. For more information, see the Windows OleTranslateColor function.

hpal
A handle to an optional palette; can be NULL.

Return Value

An RGB (red, green, blue) 32-bit color value that defines the solid color closest to the clrColor value that the device can represent.

Remarks

This function is useful to translate the stock ForeColor and BackColor properties to COLORREF types used by CDC member functions.

COleControl::WillAmbientsBeValidDuringLoad

Determines whether your control should use the values of ambient properties as default values, when it is subsequently loaded from its persistent state.

BOOL WillAmbientsBeValidDuringLoad();

Return Value

Nonzero indicates that ambient properties will be valid; otherwise ambient properties will not be valid.

Remarks

In some containers, your control may not have access to its ambient properties during the initial call to the override of COleControl::DoPropExchange. This is the case if the container calls IPersistStreamInit::Load or IPersistStorage::Load prior to calling IOleObject::SetClientSite (that is, if it does not honor the OLEMISC_SETCLIENTSITEFIRST status bit).

COleControl::WindowProc

Provides a Windows procedure for a COleControl object.

virtual LRESULT WindowProc(
    UINT message,
    WPARAM wParam,
    LPARAM lParam);

Parameters

message
Specifies the Windows message to be processed.

wParam
Provides additional information used in processing the message. The parameter value depends on the message.

lParam
Provides additional information used in processing the message. The parameter value depends on the message.

Return Value

The return value of the message dispatched.

Remarks

Call this function to dispatch specific messages through the control's message map.

See also

MFC Sample CIRC3
MFC Sample TESTHELP
COlePropertyPage Class
CWnd Class
Hierarchy Chart
CFontHolder Class
CPictureHolder Class