| title | ms.custom | ms.date | ms.reviewer | ms.suite | ms.technology | ms.tgt_pltfrm | ms.topic | f1_keywords | dev_langs | helpviewer_keywords | ms.assetid | caps.latest.revision | author | ms.author | manager | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
COleControl Class | Microsoft Docs |
11/04/2016 |
|
reference |
|
|
|
53e95299-38e8-447b-9c5f-a381d27f5123 |
25 |
mikeblome |
mblome |
ghogen |
A powerful base class for developing OLE controls.
class COleControl : public CWnd
| Name | Description |
|---|---|
| COleControl::COleControl | Creates a COleControl object. |
| 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. |
| 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. |
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.
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 COleControlwindowless-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.
COleControl
Header: afxctl.h
Returns the value of the ambient BackColor property.
OLE_COLOR AmbientBackColor();
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.
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.
The name the container has assigned to the control can be used in error messages displayed to the user.
CString AmbientDisplayName();
The name of the OLE control. The default is a zero-length string.
Note that the container is not required to support this property.
Returns the value of the ambient Font property.
LPFONTDISP AmbientFont();
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.
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.
Returns the value of the ambient ForeColor property.
OLE_COLOR AmbientForeColor();
The current value of the container's ambient ForeColor property, if any. If not supported, this function returns the system-defined Windows text color.
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.
Returns the container's locale ID.
LCID AmbientLocaleID();
The value of the container's LocaleID property, if any. If this property is not supported, this function returns 0.
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.
Retrieves the current appearance setting for the control object.
short AmbientAppearance();
The appearance of the control:
-
0 Flat appearance
-
1 3D appearance
Call this function to retrieve the current value of the DISPID_AMBIENT_APPEARANCE property for the control.
Returns the type of units used by the container.
CString AmbientScaleUnits();
A string containing the ambient ScaleUnits of the container. If this property is not supported, this function returns a zero-length string.
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.
Determines whether the container allows the control to display grab handles for itself when active.
BOOL AmbientShowGrabHandles();
Nonzero if grab handles should be displayed; otherwise 0. If this property is not supported, this function returns nonzero.
Note that the container is not required to support this property.
Determines whether the container allows the control to display itself with a hatched pattern when UI active.
BOOL AmbientShowHatching();
Nonzero if the hatched pattern should be shown; otherwise 0. If this property is not supported, this function returns nonzero.
Note that the container is not required to support this property.
Determines the ambient text alignment preferred by the control container.
short AmbientTextAlign();
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 |
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.
Determines if the container wants the control to respond to user-interface actions.
BOOL AmbientUIDead();
Nonzero if the control should respond to user-interface actions; otherwise 0. If this property is not supported, this function returns 0.
For example, a container might set this to TRUE in design mode.
Determines if the container is in design mode or user mode.
BOOL AmbientUserMode();
Nonzero if the container is in user mode; otherwise 0 (in design mode). If this property is not supported, this function returns TRUE.
For example, a container might set this to FALSE in design mode.
Signals that the bound property value has changed.
void BoundPropertyChanged(DISPID dispid);
dispid
The dispatch ID of a bound property of the control.
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.
Requests permission from the IPropertyNotifySink interface to change a bound property value provided by the control.
BOOL BoundPropertyRequestEdit(DISPID dispid);
dispid
The dispatch ID of a bound property of the control.
Nonzero if the change is permitted; otherwise 0. The default value is nonzero.
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.
Translates the coordinates of pPoint into parent coordinates.
virtual void ClientToParent(
LPCRECT lprcBounds,
LPPOINT pPoint) const;
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).
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).
Adjusts a caret rectangle if it is entirely or partially covered by overlapping, opaque objects.
BOOL ClipCaretRect(LPRECT lpRect);
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.
Nonzero if successful; otherwise 0.
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.
Constructs a COleControl object.
COleControl();
This function is normally not called directly. Instead the OLE control is usually created by its class factory.
Call this function when the set of mnemonics supported by the control has changed.
void ControlInfoChanged();
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.
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);
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.
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.
Simulates a mouse click action on the control.
void DoClick();
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.
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);
pPX
A pointer to a CPropExchange object. The framework supplies this object to establish the context of the property exchange, including its direction.
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.
Redraws an OLE control that has been subclassed from a Windows control.
void DoSuperclassPaint(
CDC* pDC,
const CRect& rcBounds);
pDC
A pointer to the device context of the control container.
rcBounds
The area in which the control is to be drawn.
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.
Called by the framework when the control's appearance needs to be updated.
void DrawContent(
CDC* pDC,
CRect& rc);
pDC
Pointer to the device context.
rc
Rectangular area to be drawn in.
This function directly calls the overridable OnDraw function.
Called by the framework when the metafile device context is being used.
void DrawMetafile(
CDC* pDC,
CRect& rc);
pDC
Pointer to the metafile device context.
rc
Rectangular area to be drawn in.
Enables the simple frame characteristic for an OLE control.
void EnableSimpleFrame();
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.
Serializes or initializes the state of the control's extent (its dimensions in HIMETRIC units).
BOOL ExchangeExtent(CPropExchange* pPX);
pPX
A pointer to a CPropExchange object. The framework supplies this object to establish the context of the property exchange, including its direction.
Nonzero if the function succeeded; 0 otherwise.
This function is normally called by the default implementation of COleControl::DoPropExchange.
Serializes or initializes the state of the control's stock properties.
void ExchangeStockProps(CPropExchange* pPX);
pPX
A pointer to a CPropExchange object. The framework supplies this object to establish the context of the property exchange, including its direction.
This function is normally called by the default implementation of COleControl::DoPropExchange.
Serializes or initializes the state of a control's version information.
BOOL ExchangeVersion(
CPropExchange* pPX,
DWORD dwVersionDefault,
BOOL bConvert = TRUE);
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.
Nonzero of the function succeeded; 0 otherwise.
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.
Called by the framework when the mouse is clicked over an active control.
void FireClick();
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.
Called by the framework when the mouse is double-clicked over an active control.
void FireDblClick();
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.
Fires the stock Error event.
void FireError(
SCODE scode,
LPCTSTR lpszDescription,
UINT nHelpID = 0);
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.
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.
Fires a user-defined event from your control with any number of optional arguments,.
void AFX_CDECL FireEvent(
DISPID dispid,
BYTE* pbParams,
...);
dispid
The dispatch ID of the event to be fired.
pbParams
A descriptor for the event's parameter types.
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 |
Note
Additional variant constants have been defined for all variant types, with the exception of VTS_FONT and VTS_PICTURE, that provide a pointer to the variant data constant. These constants are named using the VTS_Pconstantname convention. For example, VTS_PCOLOR is a pointer to a VTS_COLOR constant.
Called by the framework when a key is pressed while the control is UI active.
void FireKeyDown(
USHORT* pnChar,
short nShiftState);
pnChar
Pointer to the virtual key code value of the pressed key. For a list of 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.
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.
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);
pnChar
A pointer to the character value of the key pressed.
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.
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);
pnChar
Pointer to the virtual key code value of the released key. For a list of 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.
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.
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);
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.
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.
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);
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.
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.
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);
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.
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.
Fires an event with the current value of the ready state of control.
void FireReadyStateChange();
The ready state can be one of the following values:
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.
Alters the default activation behavior of a control that supports the IPointerInactive interface.
virtual DWORD GetActivationPolicy();
A combination of flags from the POINTERINACTIVE enumeration. Possible flags are:
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.
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:
[!code-cppNVC_MFCAxCtl#1]
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:
[!code-cppNVC_MFCAxCtl#10]
Gets the value of an ambient property of the container.
BOOL GetAmbientProperty(
DISPID dispid,
VARTYPE vtProp,
void* pvProp);
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* |
Nonzero if the ambient property is supported; otherwise 0.
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.
Implements the Get function of your control's stock Appearance property.
short GetAppearance ();
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.
Implements the Get function of your control's stock BackColor property.
OLE_COLOR GetBackColor();
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.
Implements the Get function of your control's stock BorderStyle property.
short GetBorderStyle();
1 if the control has a normal border; 0 if the control has no border.
Determines whether the COleControl object has the mouse capture.
CWnd* GetCapture();
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).
An activated windowless control receives the mouse capture when SetCapture is called.
Called by the framework to retrieve the OLE class ID of the control.
virtual HRESULT GetClassID(LPCLSID pclsid) = 0;
pclsid
Pointer to the location of the class ID.
Nonzero if the call was not successful; otherwise 0.
Usually implemented by the IMPLEMENT_OLECREATE_EX.
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;
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.
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.
Retrieves the size of the control's client area.
virtual void GetClientRect(LPRECT lpRect) const;
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.
Queries an object for the pointer to its current client site within its container.
LPOLECLIENTSITE GetClientSite();
A pointer to the control's current client site in its container.
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.
Retrieves the control flag settings.
virtual DWORD GetControlFlags();
An ORed combination of the flags in the ControlFlags enumeration:
enum ControlFlags {
fastBeginPaint = 0x0001,
clipPaintDC = 0x0002,
pointerInactive = 0x0004,
noFlickerActivate = 0x0008,
windowlessActivate = 0x0010,
canOptimizeDraw = 0x0020,
};
By default, GetControlFlags returns fastBeginPaint | clipPaintDC.
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.
Retrieves the size of the OLE control window.
void GetControlSize(
int* pcx,
int* pcy);
pcx
Specifies the width of the control in pixels.
pcy
Specifies the height of the control in pixels.
Note that all coordinates for control windows are relative to the upper-left corner of the control.
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);
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).
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.
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.
Implements the Get function of your control's stock Enabled property.
BOOL GetEnabled();
Nonzero if the control is enabled; otherwise 0.
Obtains a pointer to an object maintained by the container that represents the control with an extended set of properties.
LPDISPATCH GetExtendedControl();
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.
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.
Determines whether the COleControl object has the focus.
CWnd* GetFocus();
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).
An activated windowless control receives the focus when SetFocus is called.
Implements the Get function of the stock Font property.
LPFONTDISP GetFont();
A pointer to the font dispatch interface of the control's stock Font property.
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.
Measures the text metrics for any CFontHolder object owned by the control.
void GetFontTextMetrics(
LPTEXTMETRIC lptm,
CFontHolder& fontHolder);
lptm
Pointer to a TEXTMETRIC structure.
fontHolder
Reference to a CFontHolder object.
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.
Implements the Get function of the stock ForeColor property.
OLE_COLOR GetForeColor();
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.
Implements the Get function of the stock hWnd property.
OLE_HANDLE GetHwnd();
The OLE control's window handle, if any; otherwise NULL.
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;
nID
A menu item ID.
rMessage
A reference to a CString object through which a string will be returned.
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.
Prevents access to a control's property value by the user.
void GetNotSupported();
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.
Returns the readiness state of the control.
long GetReadyState();
The readiness state of the control, one of the following values:
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
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.
Obtains the coordinates of the control's rectangle relative to the container, expressed in device units.
BOOL GetRectInContainer(LPRECT lpRect);
lpRect
A pointer to the rectangle structure into which the control's coordinates will be copied.
Nonzero if the control is in-place active; otherwise 0.
The rectangle is only valid if the control is in-place active.
Measures the text metrics for the control's stock Font property, which can be selected with the SelectStockFont function.
void GetStockTextMetrics(LPTEXTMETRIC lptm);
lptm
A pointer to a TEXTMETRIC structure.
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.
Implements the Get function of the stock Text or Caption property.
BSTR GetText();
The current value of the control text string or a zero-length string if no string is present.
Note
For more information on the BSTR data type, see Data Types in the Macros and Globals section.
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.
Override GetWindowlessDropTarget when you want a windowless control to be the target of an OLE drag and drop operation.
virtual IDropTarget* GetWindowlessDropTarget();
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.
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:
[!code-cppNVC_MFCAxCtl#2]
Informs the base class of the IIDs the control will use.
void InitializeIIDs(
const IID* piidPrimary,
const IID* piidEvents);
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.
Call this function in the control's constructor to inform the base class of the interface IDs your control will be using.
Accesses the stock Font property of your control
CFontHolder& InternalGetFont();
A reference to a CFontHolder object that contains the stock Font object.
Accesses the stock Text or Caption property of your control.
const CString& InternalGetText();
A reference to the control text string.
Sets the readiness state of the control.
void InternalSetReadyState(long lNewReadyState);
lNewReadyState
The readiness state to set for the control, one of the following values:
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
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.
Forces the control to redraw itself.
void InvalidateControl(
LPCRECT lpRect = NULL,
BOOL bErase = TRUE);
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.
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.
Invalidates the container window's client area within the given region.
void InvalidateRgn(CRgn* pRgn, BOOL bErase = TRUE);
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.
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.
Allows specialized loading of an OLE control.
BOOL IsConvertingVBX();
Nonzero if the control is being converted; otherwise 0.
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:
[!code-cppNVC_MFCAxCtl#3]
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:
[!code-cppNVC_MFCAxCtl#4]
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.
Enables automation method invocation.
BOOL IsInvokeAllowed(DISPID dispid);
Nonzero if the control has been initialized; otherwise 0.
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). For more information, see Knowledge Base article Q166472, "HOWTO: Use an OLE Control as an Automation Server." Knowledge Base articles are available at http://support.microsoft.com.
Determines if the control's state has been modified.
BOOL IsModified();
Nonzero if the control's state has been modified since it was last saved; otherwise 0.
The state of a control is modified when a property changes value.
Determines whether the container supports optimized drawing for the current drawing operation.
BOOL IsOptimizedDraw();
TRUE if the container supports optimized drawing for the current drawing operation; otherwise FALSE.
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.
Called by the framework to determine if the control subclasses a Windows control.
virtual BOOL IsSubclassedControl();
Nonzero if the control is subclassed; otherwise 0.
You must override this function and return TRUE if your OLE control subclasses a Windows control.
Resets any previous data loaded asynchronously and initiates a new loading of the control's asynchronous property.
void Load(LPCTSTR strNewPath, CDataPathProperty& prop);
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.
Prevents the container from deactivating your control.
BOOL LockInPlaceActive(BOOL bLock);
bLock
TRUE if the in-place active state of the control is to be locked; FALSE if it is to be unlocked.
Nonzero if the lock was successful; otherwise 0.
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.
Called by the framework when an ambient property of the container has changed value.
virtual void OnAmbientPropertyChange(DISPID dispid);
dispID
The dispatch ID of the ambient property that changed, or DISPID_UNKNOWN if multiple properties have changed.
Called by the framework when the stock Appearance property value has changed.
virtual void OnAppearanceChanged ();
Override this function if you want notification after this property changes. The default implementation calls InvalidateControl.
Called by the framework when the stock BackColor property value has changed.
virtual void OnBackColorChanged();
Override this function if you want notification after this property changes. The default implementation calls InvalidateControl.
Called by the framework when the stock BorderStyle property value has changed.
virtual void OnBorderStyleChanged();
The default implementation calls InvalidateControl.
Override this function if you want notification after this property changes.
Called by the framework when a mouse button has been clicked or the DoClick stock method has been invoked.
virtual void OnClick(USHORT iButton);
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.
The default implementation calls COleControl::FireClick.
Override this member function to modify or extend the default handling.
Called by the framework when the container has called the control's IOleControl::Close function.
virtual void OnClose(DWORD dwSaveOption);
dwSaveOption
Flag that indicates whether the object should be saved before loading. Valid values are:
-
OLECLOSE_SAVEIFDIRTY -
OLECLOSE_NOSAVE -
OLECLOSE_PROMPTSAVE
By default, OnClose saves the control object if it has been modified and dwSaveOption is either OLECLOSE_SAVEIFDIRTY or OLECLOSE_PROMPTSAVE.
Called by the framework when the container calls the IOleObject::DoVerb member function.
virtual BOOL OnDoVerb(
LONG iVerb,
LPMSG lpMsg,
HWND hWndParent,
LPCRECT lpRect);
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.
Nonzero if call was successful; otherwise 0.
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.
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);
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.
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.
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);
pDC
The device context in which the drawing occurs.
rcBounds
The rectangular area of the control, including the border.
The default implementation calls the OnDraw function.
Causes the control to be UI activated.
virtual BOOL OnEdit(
LPMSG lpMsg,
HWND hWndParent,
LPCRECT lpRect);
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.
Nonzero if the call is successful; otherwise 0.
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:
[!code-cppNVC_MFCAxCtl#5]
Called by the framework when the stock Enabled property value has changed.
virtual void OnEnabledChanged();
Override this function if you want notification after this property changes. The default implementation calls InvalidateControl.
Called by the framework when the container calls the IOleObject::EnumVerbs member function.
virtual BOOL OnEnumVerbs(LPENUMOLEVERB* ppenumOleVerb);
ppenumOleVerb
A pointer to the IEnumOLEVERB object that enumerates the control's verbs.
Nonzero if verbs are available; otherwise 0.
The default implementation enumerates the ON_OLEVERB entries in the message map.
Override this function to change the default way of enumerating verbs.
Called by the framework when an event handler is connected to or disconnected from an OLE control.
virtual void OnEventAdvise(BOOL bAdvise);
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.
Called by the framework when the stock Font property value has changed.
virtual void OnFontChanged();
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.
[!code-cppNVC_MFCAxCtl#6]
Called by the framework when the stock ForeColor property value has changed.
virtual void OnForeColorChanged();
The default implementation calls InvalidateControl.
Override this function if you want notification after this property changes.
Called by the framework after the container calls IOleControl::FreezeEvents.
virtual void OnFreezeEvents(BOOL bFreeze);
bFreeze
TRUE if the control's event handling is frozen; otherwise FALSE.
The default implementation does nothing.
Override this function if you want additional behavior when event handling is frozen or unfrozen.
Called by the framework when the container calls the IViewObject::GetColorSet member function.
virtual BOOL OnGetColorSet(
DVTARGETDEVICE* ptd,
HDC hicTargetDev,
LPLOGPALETTE* ppColorSet);
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.
Nonzero if a valid color set is returned; otherwise 0.
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.
Called by the framework when the control's container has requested information about the control.
virtual void OnGetControlInfo(LPCONTROLINFO pControlInfo);
pControlInfo
Pointer to a CONTROLINFO structure to be filled in.
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.
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);
dispid
The dispatch ID of a property of the control.
strValue
A reference to a CString object through which a string will be returned.
Nonzero if a string has been returned in strValue; otherwise 0.
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.
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();
The handle of the control's menu, or NULL if the control has none. The default implementation returns NULL.
For more information on merging OLE resources, see the article Menus and Resources (OLE).
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);
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.
Nonzero if it successfully returns or adjusts the size; otherwise 0.
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.
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);
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.
Nonzero if elements have been added to pStringArray and pCookieArray.
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.
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);
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.
Nonzero if a value has been returned in lpvarOut; otherwise 0.
Called by the framework in response to a container's IViewObject2::GetExtent request.
virtual BOOL OnGetViewExtent(
DWORD dwDrawAspect,
LONG lindex,
DVTARGETDEVICE* ptd,
LPSIZEL lpsizel);
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.
Nonzero if extent information is successfully returned; otherwise 0.
Override this function if your control uses two-pass drawing, and its opaque and transparent parts have different dimensions.
Called by the framework in response to a container's IViewObjectEx::GetRect request.
virtual BOOL OnGetViewRect(DWORD dwAspect, LPRECTL pRect);
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_CONTENTBounding 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.
Nonzero if the rectangle sized to the object is successfully returned; otherwise 0.
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.
Called by the framework in response to a container's IViewObjectEx::GetViewStatus request.
virtual DWORD OnGetViewStatus();
One of the values of the VIEWSTATUS enumeration if successful; otherwise 0. Possible values are any combination of the following:
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.
Override this function if your control uses two-pass drawing. The default implementation returns VIEWSTATUS_OPAQUE.
Called by the framework when the control is UI deactivated.
virtual void OnHideToolBars();
The implementation should hide all toolbars displayed by OnShowToolbars.
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);
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.
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.
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);
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.
Nonzero if successful; otherwise 0.
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.
Called by the framework after a stock KeyDown event has been processed.
virtual void OnKeyDownEvent(
USHORT nChar,
USHORT nShiftState);
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.
Override this function if your control needs access to the key information after the event has been fired.
Called by the framework after the stock KeyPress event has been fired.
virtual void OnKeyPressEvent(USHORT nChar);
nChar
Contains the virtual key code value of the key pressed. For a list of standard virtual key codes, see Winuser.h
Note that the nChar value may have been modified by the container.
Override this function if you want notification after this event occurs.
Called by the framework after a stock KeyDown event has been processed.
virtual void OnKeyUpEvent(
USHORT nChar,
USHORT nShiftState);
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.
Override this function if your control needs access to the key information after the event has been fired.
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);
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.
Nonzero if a class ID has been returned in lpclsid; otherwise 0.
Override this function to provide a way to invoke your control's property pages from the container's property browser.
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);
pMsg
Pointer to the Windows message generated by a mnemonic key press.
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);
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.
Nonzero if the call is successful; otherwise 0.
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.
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);
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
ptlLocis 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
ptlLocis 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
ptlLocis within the image of the object.
Nonzero if a hit result is successfully returned; otherwise 0. A hit is an overlap with the OLE control display area.
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.
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);
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.
Nonzero if a hit result is successfully returned; otherwise 0.
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.
Called by the framework to retrieve data in the specified format.
virtual BOOL OnRenderData(
LPFORMATETC lpFormatEtc,
LPSTGMEDIUM lpStgMedium);
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.
Nonzero if successful; otherwise 0.
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.
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);
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.
Nonzero if successful; otherwise 0.
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.
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);
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.
Nonzero if successful; otherwise 0.
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.
Called by the framework when the control's properties should be set to their default values.
virtual void OnResetState();
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.
Called by the framework when the container has called the control's IOleControl::SetClientSite function.
virtual void OnSetClientSite();
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.
Called by the framework to replace the control's data with the specified data.
virtual BOOL OnSetData(
LPFORMATETC lpFormatEtc,
LPSTGMEDIUM lpStgMedium,
BOOL bRelease);
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.
Nonzero if successful; otherwise 0.
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.
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);
lpSizeL
A pointer to the SIZEL structure that uses long integers to represent the width and height of the control, expressed in HIMETRIC units.
Nonzero if the size change was accepted; otherwise 0.
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.
Called by the framework to implement a call to IOleInPlaceObject::SetObjectRects.
virtual BOOL OnSetObjectRects(
LPCRECT lpRectPos,
LPCRECT lpRectClip);
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.
Nonzero if the repositioning was accepted; otherwise 0.
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.
Called by the framework when the control has been UI activated.
virtual void OnShowToolBars();
The default implementation does nothing.
Called by the framework when the stock Caption or Text property value has changed.
virtual void OnTextChanged();
The default implementation calls InvalidateControl.
Override this function if you want notification after this property changes.
Called by the framework in response to a container's IOleInPlaceObjectWindowless::OnWindowMessage request.
virtual BOOL OnWindowlessMessage(
UINT msg,
WPARAM wParam,
LPARAM lParam,
LRESULT* plResult);
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.
Nonzero if successful; otherwise 0.
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.
Translates the coordinates of pPoint into client coordinates.
virtual UINT ParentToClient(
LPCRECT lprcBounds,
LPPOINT pPoint,
BOOL bHitTest = FALSE) const;
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.
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.
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).
Notifies the container that a modal dialog box has been closed.
void PostModalDialog(HWND hWndParent = NULL);
hWndParent
Handle to the parent window of the modal dialog box.
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.
Notifies the container that a modal dialog box is about to be displayed.
void PreModalDialog(HWND hWndParent = NULL);
hWndParent
Handle to the parent window of the modal dialog box.
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.
Destroys and re-creates the control's window.
void RecreateControlWindow();
This may be necessary if you need to change the window's style bits.
Forces a repaint of the OLE control.
void Refresh();
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.
Releases mouse capture.
BOOL ReleaseCapture();
Nonzero if successful; otherwise 0.
If the control currently has the mouse capture, the capture is released. Otherwise, this function has no effect.
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);
pDC
Identifies the container device context to be released.
Nonzero if successful; otherwise 0.
The application must call ReleaseDC for each call to GetDC.
Sets the parent of the control.
virtual void ReparentControlWindow(
HWND hWndOuter,
HWND hWndParent);
hWndOuter
The handle of the control window.
hWndParent
The handle of the new parent window.
Call this function to reset the parent of the control window.
Initializes the state of the COleControl stock properties to their default values.
void ResetStockProps();
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.
[!code-cppNVC_MFCAxCtl#7]
Initializes the version number to specified value.
void ResetVersion(DWORD dwVersionDefault);
dwVersionDefault
The version number to be assigned to the control.
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.
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);
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.
Selects a font into a device context.
CFont* SelectFontObject(
CDC* pDC,
CFontHolder& fontHolder);
pDC
Pointer to a device context object.
fontHolder
Reference to the CFontHolder object representing the font to be selected.
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.
Selects the stock Font property into a device context.
CFont* SelectStockFont(CDC* pDC);
pDC
The device context into which the font will be selected.
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.
Serializes or initializes the state of the display space allotted to the control.
void SerializeExtent(CArchive& ar);
ar
A CArchive object to serialize to or from.
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.
[!code-cppNVC_MFCAxCtl#8]
Serializes or initializes the state of the COleControl stock properties: Appearance, BackColor, BorderStyle, Caption, Enabled, Font, ForeColor, and Text.
void SerializeStockProps(CArchive& ar);
ar
A CArchive object to serialize to or from.
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.
Serializes or initializes the state of a control's version information.
DWORD SerializeVersion(
CArchive& ar,
DWORD dwVersionDefault,
BOOL bConvert = TRUE);
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.
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.
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.
Sets the stock Appearance property value of your control.
void SetAppearance (short sAppearance);
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.
For more about stock properties, see ActiveX Controls: Properties.
Sets the stock BackColor property value of your control.
void SetBackColor(OLE_COLOR dwBackColor);
dwBackColor
An OLE_COLOR value to be used for background drawing of your control.
For more information on using this property and other related properties, see the article ActiveX Controls: Properties.
Sets the stock BorderStyle property value of your control.
void SetBorderStyle(short sBorderStyle);
sBorderStyle
The new border style for the control; 0 indicates no border and 1 indicates a normal border.
The control window will then be re-created and OnBorderStyleChanged called.
Causes the control's container window to take possession of the mouse capture on the control's behalf.
CWnd* SetCapture();
A pointer to the CWnd window object that previously received mouse input.
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).
Sets the size of the OLE control window and notifies the container that the control site is changing.
BOOL SetControlSize(int cx, int cy);
cx
Specifies the new width of the control in pixels.
cy
Specifies the new height of the control in pixels.
Nonzero if the call was successful; otherwise 0.
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.
Sets the stock Enabled property value of your control.
void SetEnabled(BOOL bEnabled);
bEnabled
TRUE if the control is to be enabled; otherwise FALSE.
After setting this property, OnEnabledChange is called.
Causes the control's container window to take possession of the input focus on the control's behalf.
CWnd* SetFocus();
A pointer to the CWnd window object that previously had the input focus, or NULL if there is no such window.
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).
Sets the stock Font property of your control.
void SetFont(LPFONTDISP pFontDisp);
pFontDisp
A pointer to a Font dispatch interface.
Sets the stock ForeColor property value of your control.
void SetForeColor(OLE_COLOR dwForeColor);
dwForeColor
An OLE_COLOR value to be used for foreground drawing of your control.
For more information on using this property and other related properties, see the article ActiveX Controls: Properties.
Called by the framework to initialize the list of data formats supported by the control.
virtual void SetInitialDataFormats();
The default implementation specifies two formats: CF_METAFILEPICT and the persistent property set.
Sets the size of an OLE control when first displayed in a container.
void SetInitialSize(
int cx,
int cy);
cx
The initial width of the OLE control in pixels.
cy
The initial height of the OLE control in pixels.
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.
Changes the modified state of a control.
void SetModifiedFlag(BOOL bModified = TRUE);
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.
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 bModifiedTRUE.
Indicates that an edit request has failed.
void SetNotPermitted();
Call this function when BoundPropertyRequestEdit fails. This function throws an exception of type COleDispScodeException to indicate that the set operation was not permitted.
Prevents modification to a control's property value by the user.
void SetNotSupported();
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.
Sets the coordinates of the control's rectangle relative to the container, expressed in device units.
BOOL SetRectInContainer(LPCRECT lpRect);
lpRect
A pointer to a rectangle containing the control's new coordinates relative to the container.
Nonzero if the call was successful; otherwise 0.
If the control is open, it is resized; otherwise the container's OnPosRectChanged function is called.
Sets the value of your control's stock Caption or Text property.
void SetText(LPCTSTR pszText);
pszText
A pointer to a character string.
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.
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);
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.
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.
Transforms coordinate values between HIMETRIC units and the container's native units.
void TransformCoords(
POINTL* lpptlHimetric,
POINTF* lpptfContainer,
DWORD flags);
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.
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.
Converts a color value from the OLE_COLOR data type to the COLORREF data type.
COLORREF TranslateColor(
OLE_COLOR clrColor,
HPALETTE hpal = NULL);
clrColor
A OLE_COLOR data type. For more information, see the Windows OleTranslateColor function.
hpal
A handle to an optional palette; can be NULL.
An RGB (red, green, blue) 32-bit color value that defines the solid color closest to the clrColor value that the device can represent.
This function is useful to translate the stock ForeColor and BackColor properties to COLORREF types used by CDC member functions.
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();
Nonzero indicates that ambient properties will be valid; otherwise ambient properties will not be valid.
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).
Provides a Windows procedure for a COleControl object.
virtual LRESULT WindowProc(
UINT message,
WPARAM wParam,
LPARAM lParam);
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.
The return value of the message dispatched.
Call this function to dispatch specific messages through the control's message map.
MFC Sample CIRC3
MFC Sample TESTHELP
COlePropertyPage Class
CWnd Class
Hierarchy Chart
CFontHolder Class
CPictureHolder Class