OLE Logo Palette Behaviour for OLE Controls

Last updated Feb 29th, 1996

Palette management guidelines for OLE Controls and OLE Control containers.


NOTE: THIS DOCUMENT IS AN EARLY RELEASE OF THE FINAL SPECIFICATION. IT IS MEANT TO SPECIFY AND ACCOMPANY SOFTWARE THAT IS STILL IN DEVELOPMENT. SOME OF THE INFORMATION IN THIS DOCUMENTATION MAY BE INACCURATE OR MAY NOT BE AN ACCURATE REPRESENTATION OF THE FUNCTIONALITY OF THE FINAL SPECIFICATION OR SOFTWARE. MICROSOFT ASSUMES NO RESPONSIBILITY FOR ANY DAMAGES THAT MIGHT OCCUR EITHER DIRECTLY OR INDIRECTLY FROM THESE INACCURACIES. MICROSOFT MAY HAVE TRADEMARKS, COPYRIGHTS, PATENTS OR PENDING PATENT APPLICATIONS, OR OTHER INTELLECTUAL PROPERTY RIGHTS COVERING SUBJECT MATTER IN THIS DOCUMENT. THE FURNISHING OF THIS DOCUMENT DOES NOT GIVE YOU A LICENSE TO THESE TRADEMARKS, COPYRIGHTS, PATENTS, OR OTHER INTELLECTUAL PROPERTY RIGHTS.

Introduction

This document specifies palette behaviour and palette management guidelines for implementors of OLE Controls and OLE Control containers. The specific behaviour of Microsoft Internet Explorer 3.0 as an OLE Control container is also described.

The reader is assumed to have a good understanding of the Windows palette manager and OLE controls.

Container controlled palette

With more than one control on a page or form, it is up to the container to choose a common palette. Anything else would result in chaos as each control realized its palette while painting. The display would flicker madly and most controls would look awful.

How the container chooses the common palette is up to the implementor of the container. Microsoft Internet Explorer 3.0 will either use an author supplied palette or a default halftone palette. Some containers may use the UI active object's palette, others may compute the palette at runtime.

Ambient palette property

The container makes its palette available as an ambient property: DISPID_AMBIENT_PALETTE. This property is defined in OLE Controls 96 and will be implemented by Microsoft Internet Explorer 3.0 and other Microsoft OLE containers. Controls can receive notification of changes to this property by implementing: IOleControl::OnAmbientPropertyChange()

Containers should realize the ambient palette before calling this function or IViewObject2::Draw().

Older containers that do not implement this property will typically iterate through their controls, forwarding the WM_QUERYNEWPALETTE message until a control returns TRUE (indicating it has realized a palette).

Containers that implement DISPID_AMBIENT_PALETTE should never send WM_QUERYNEWPALETTE to their controls.

Palette change notification

Palette aware controls that wish to be notified of changes to the ambient palette should implement IOleControl::OnAmbientPropertyChange() and handle DISPID_AMBIENT_PALETTE and DISPID_UNKNOWN. The DISPID_UNKNOWN change can be sent when more than one property changes. When this happens, controls should explicitly check for a changed palette.

Existing containers that do not define an ambient palette will send WM_PALETTECHANGED messages. Controls are encouraged to handle this message as well.

IViewObject2::GetColorSet()

All palette aware controls should implement IViewObject2::GetColorSet(). Containers can use the return value to determine if a control is palette aware.

E_NOTIMPLThe control is not palette aware
S_FALSEThe control is palette aware but does not have a palette at this time.
S_OKThe control is palette aware and has returned its palette to the container.

It should be noted that the container does not have to call IViewObject2::GetColorSet(). The container may determine it's palette independently of its controls.

Realizing the palette

Current OLE guidelines allow the UI active object to realize its own palette in the foreground. Under the new guidelines, this is no longer the case.

Controls should only realize their palette in the foreground when receiving WM_QUERYNEWPALETTE message. In every other situation, the control must realize its palette in the background. Containers that implement DISPID_AMBIENT_PALETTE will never send this message.

PDC Implementation

The pre-release version of Microsoft Internet Explorere 3.0 distributed at the PDC does not implement DISPID_AMBIENT_PALETTE. This feature will be implemented before the final release. Even without this property, controls should only realize their palettes in the background.

Summary