COleControl Class

Article
04/28/2015

A powerful base class for developing OLE controls.

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 Class

Members

Public Constructors

Public Methods

Protected Methods

Remarks

Windowless Controls

Inheritance Hierarchy

Requirements

See Also

Reference

Concepts

Additional resources