Share via


COleControl Class

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

See Also

Reference

COlePropertyPage Class

CWnd Class

Hierarchy Chart

CFontHolder Class

CPictureHolder Class

Concepts

MFC Sample CIRC3

MFC Sample TESTHELP