IViewObject::GetColorSet
Returns the
logical palette that the object will use for drawing in its IViewObject::Draw method with the
corresponding parameters.
HRESULT GetColorSet(
|
DWORD dwAspect, |
//How the
object is to be represented |
|
LONG lindex, |
//Part of the
object of interest in the draw operation |
|
void * pvAspect, |
//Always
NULL |
|
DVTARGETDEVICE * ptd, |
//Pointer to
target device in a structure |
|
HDC hicTargetDev, |
//Information
context for the target device |
|
LOGPALETTE ** ppColorSet |
//Indirect
pointer to a structure |
|
); |
|
Parameters
dwAspect
[in]
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.
See the DVASPECT enumeration for more information.
lindex
[in] Portion
of the object that is of interest for the draw operation. Its interpretation
varies with dwAspect. See the DVASPECT enumeration for more
information.
pvAspect
[in] Pointer
to additional information about the view of the object specified in dwAspect.
Since none of the current aspects support additional information, pvAspect
must always be NULL.
ptd
[in] Pointer
to the DVTARGETDEVICE
structure that describes the device for which the object is to be rendered. If
NULL, the view should be rendered for the default target device (typically the
display). A value other than NULL is interpreted in conjunction with hicTargetDev
and hdcDraw. For example, if hdcDraw specifies a printer as the
device context, ptd points to a structure describing that printer
device. The data may actually be printed if hicTargetDev is a valid
value or it may be displayed in print preview mode if hicTargetDev is
NULL.
hicTargetDev
[in]
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 hicTargetDev parameter.
ppColorSet
[out]
Indirect pointer to where a LOGPALETTE structure is returned. The LOGPALETTE
structure contains the set of colors that would be used if IViewObject::Draw were called with the same
parameters for dwAspect, lindex, pvAspect, ptd, and
hicTargetDev. A NULL pointer to the LOGPALETTE structure means
that the object does not use a palette.
Return Values
This method
supports the standard return values E_INVALIDARG and E_UNEXPECTED, as well as
the following:
S_OK
The set of
colors was returned successfully.
S_FALSE
Set of colors
is empty or the object will not give out the information.
OLE_E_BLANK
No
presentation data for object.
DV_E_LINDEX
Invalid value
for lindex; currently only -1 is supported.
DV_E_DVASPECT
Invalid value
for dwAspect.
Remarks
The
IViewObject::GetColorSet method recursively queries any nested objects and
returns a color set that represents the union of all colors requested. The
color set eventually percolates to the top-level container that owns the window
frame. This container can call IViewObject::GetColorSet on each of its
embedded objects to obtain all the colors needed to draw the embedded objects.
The container can use the color sets obtained in conjunction with other colors
it needs for itself to set the overall color palette.
The OLE-provided
implementation of IViewObject::GetColorSet looks at the data it has on
hand to draw the picture. If CF_DIB is the drawing format, the palette found in
the bitmap is used. For a regular bitmap, no color information is returned. If
the drawing format is a metafile, the object handler enumerates the metafile
looking for a CreatePalette metafile record. If one is found, the handler uses
it as the color set.
Note to Implementers
Object
applications that rely on the default handler for drawing and that use metafiles
for doing so should provide a SetPaletteEntries record when they generate their
metafiles. If a SetPaletteEntries record is not found, the default object
handler returns S_FALSE.
See Also