COLORMATCHSETUP

[This is preliminary documentation and subject to change.]

The COLORMATCHSETUP structure contains information that the SetupColorMatching function uses to initialize the Color Management dialog box. After the user closes the dialog box, SetupColorMatching returns information about the user's selection in this structure.

Structure

typedef struct _tagCOLORMATCHSETUP {
    DWORD   dwSize;
    DWORD   dwVersion;
    DWORD   dwFlags; 
    HWND    hwndOwner;
    PCTSTR  pSourceName; 
    PCTSTR  pDisplayName; 
    PCTSTR  pPrinterName;
    DWORD   dwRenderIntent; 
    DWORD   dwProofingIntent;
    PTSTR   pMonitorProfile; 
    DWORD   ccMonitorProfile;
    PTSTR   pPrinterProfile; 
    DWORD   ccPrinterProfile;
    PTSTR   pTargetProfile; 
    DWORD   ccTargetProfile;
    DLGPROC lpfnHook; 
    LPARAM  lParam;
    PCMSCALLBACKA lpfnApplyCallback;
    LPARAM        lParamApplyCallback; 
 
} COLORMATCHSETUP;

Members

dwSize

Size of the structure. Should be set to sizeof(COLORMATCHSETUP).

dwVersion

Version of the COLORMATCHSETUP structure. This should be set to COLOR_MATCH_VERSION.

dwFlags

A set of bit flags used to initialize the dialog box. If set to 0 on entry, all controls assume their default states.

When the dialog box returns, these flags are set to indicate the user's input.

This member can be set using a combination of the following flags.

Flag Meaning

CMS_DISABLEICM If set on entry, this flag indicates that the "Enable Color Management" check box is cleared, disabling all other controls. If set on exit, it means that the user does not wish color management performed.

CMS_ENABLEPROOFING If set on entry, this flag indicates that the Proofing controls are to be enabled, and the Proofing check box is checked. If set on exit, it means that the user wishes to do color management for a different target device than the selected printer.

CMS_SETRENDERINTENT If set on entry, this flag indicates that the dwRenderIntent member contains the value to use to initialize the Rendering Intent control. Otherwise, the control defaults to Perceptual rendering. This flag is set on exit if ICM is enabled.

CMS_SETPROOFINTENT Ignored unless CMS_ENABLEPROOFING is also set. If set on entry, and CMS_ENABLEPROOFING is also set, this flag indicates that the dwProofingIntent member is to be used to initialize the Target Rendering Intent control. Otherwise, the control defaults to Perceptual rendering. This flag is set on exit if proofing is enabled.

CMS_SETMONITORPROFILE If set on entry, this flag indicates that the color management profile named in the pMonitorProfile member is to be the initial selection in the monitor profile control. If the specified profile is not associated with the monitor, this flag is ignored, and the default profile for the monitor is used.

CMS_SETPRINTERPROFILE If set on entry, this flag indicates that the color management profile named in the pPrinterProfile member is to be the initial selection in the printer profile control. If the specified profile is not associated with the printer, this flag is ignored, and the default profile for the printer is used.

CMS_SETTARGETPROFILE If set on entry, this flag indicates that the color profile named in the pTargetProfile member is to be the initial selection in the target profile control. If the specified profile is not installed, this flag is ignored, and the default profile for the printer is used. If the printer has no default profile, then the first profile in alphabetical order will be displayed.

CMS_USEHOOK This flag specifies that the lpfnHook member contains the address of a hook procedure, and the lParam member contains a value to be passed to the hook procedure when the WM_INITDIALOG message is sent.

CMS_MONITOROVERFLOW This flag is set on exit if color management is to be enabled and the buffer size given in ccMonitorProfile is insufficient for the selected profile name. GetLastError returns ERROR_INSUFFICIENT_BUFFER in such a case.

CMS_PRINTERROVERFLOW This flag is set on exit if color management is to be enabled and the buffer size given in ccPrinterProfile is insufficient for the selected profile name. GetLastError returns ERROR_INSUFFICIENT_BUFFER in such a case.

CMS_TARGETOVERFLOW This flag is set on exit if proofing is to be enabled and the buffer size given in ccTargetProfile is insufficient for the selected profile name. GetLastError returns ERROR_INSUFFICIENT_BUFFER in such a case.

CMS_USEAPPLYCALLBACK If set on entry, this flag indicates that the SetupColorMatching function should call the function ApplyCallbackFunction. The address of the callback function is contained in lpfnApplyCallback.

hwndOwner

The window handle for the owner of the dialog box, or NULL if the dialog box has no owner.

pSourceName

Pointer to an application-specified string which describes the source profile of the item for which color management is to be performed. If this is NULL, the Image Source control displays the name of the Windows default color profile.

pDisplayName

Points to a string naming the monitor to be used for color management. If this is not the name of a valid monitor, the first enumerated monitor is used.

pPrinterName

Points to a string naming the printer on which the image is to be rendered. If this is not a valid printer name, the default printer is used and named in the dialog.

dwRenderIntent

Flag	Meaning
CMS_DISABLEICM	If set on entry, this flag indicates that the "Enable Color Management" check box is cleared, disabling all other controls. If set on exit, it means that the user does not wish color management performed.
CMS_ENABLEPROOFING	If set on entry, this flag indicates that the Proofing controls are to be enabled, and the Proofing check box is checked. If set on exit, it means that the user wishes to do color management for a different target device than the selected printer.
CMS_SETRENDERINTENT	If set on entry, this flag indicates that the dwRenderIntent member contains the value to use to initialize the Rendering Intent control. Otherwise, the control defaults to Perceptual rendering. This flag is set on exit if ICM is enabled.
CMS_SETPROOFINTENT	Ignored unless CMS_ENABLEPROOFING is also set. If set on entry, and CMS_ENABLEPROOFING is also set, this flag indicates that the dwProofingIntent member is to be used to initialize the Target Rendering Intent control. Otherwise, the control defaults to Perceptual rendering. This flag is set on exit if proofing is enabled.
CMS_SETMONITORPROFILE	If set on entry, this flag indicates that the color management profile named in the pMonitorProfile member is to be the initial selection in the monitor profile control. If the specified profile is not associated with the monitor, this flag is ignored, and the default profile for the monitor is used.
CMS_SETPRINTERPROFILE	If set on entry, this flag indicates that the color management profile named in the pPrinterProfile member is to be the initial selection in the printer profile control. If the specified profile is not associated with the printer, this flag is ignored, and the default profile for the printer is used.
CMS_SETTARGETPROFILE	If set on entry, this flag indicates that the color profile named in the pTargetProfile member is to be the initial selection in the target profile control. If the specified profile is not installed, this flag is ignored, and the default profile for the printer is used. If the printer has no default profile, then the first profile in alphabetical order will be displayed.
CMS_USEHOOK	This flag specifies that the lpfnHook member contains the address of a hook procedure, and the lParam member contains a value to be passed to the hook procedure when the WM_INITDIALOG message is sent.
CMS_MONITOROVERFLOW	This flag is set on exit if color management is to be enabled and the buffer size given in ccMonitorProfile is insufficient for the selected profile name. GetLastError returns ERROR_INSUFFICIENT_BUFFER in such a case.
CMS_PRINTERROVERFLOW	This flag is set on exit if color management is to be enabled and the buffer size given in ccPrinterProfile is insufficient for the selected profile name. GetLastError returns ERROR_INSUFFICIENT_BUFFER in such a case.
CMS_TARGETOVERFLOW	This flag is set on exit if proofing is to be enabled and the buffer size given in ccTargetProfile is insufficient for the selected profile name. GetLastError returns ERROR_INSUFFICIENT_BUFFER in such a case.
CMS_USEAPPLYCALLBACK	If set on entry, this flag indicates that the SetupColorMatching function should call the function ApplyCallbackFunction. The address of the callback function is contained in lpfnApplyCallback.

The type of color management desired. Valid values are:

INTENT_PERCEPTUAL
INTENT_SATURATION
INTENT_RELATIVE_COLORIMETRIC
INTENT_ABSOLUTE_COLORIMETRIC

For more information, see Rendering Intents.

dwProofingIntent

The type of color management desired for the proofed image. Valid values are:

INTENT_PERCEPTUAL
INTENT_SATURATION
INTENT_RELATIVE_COLORIMETRIC
INTENT_ABSOLUTE_COLORIMETRIC

For more information, see Rendering Intents.

pMonitorProfile

Pointer to a buffer in which to place the name of the user-selected monitor profile. If the CMS_SETMONITORPROFILE flag is used, this flag can also be used to select a profile other than the monitor default when the dialog is first displayed.

ccMonitorProfile

The size of the buffer pointed to by the pMonitorProfile member, in characters. If the buffer is not large enough to hold the selected name, the name is truncated to this size, and ERROR_INSUFFICIENT_BUFFER is returned. A buffer of MAX_PATH size always works.

pPrinterProfile

Points to a buffer in which to place the name of the user-selected printer profile. If the CMS_SETPRINTERPROFILE flag is used, this flag can also be used to select a profile other than the printer default when the dialog is first displayed.

ccPrinterProfile

The size of the buffer pointed to by the pPrinterProfile member, in characters. If the buffer is not large enough to hold the selected name, the name is truncated to this size, and ERROR_INSUFFICIENT_BUFFER is returned. A buffer of MAX_PATH size always works.

pTargetProfile

Points to a buffer in which to place the name of the user-selected target profile for proofing. If the CMS_SETTARGETPROFILE flag is used, this flag can also be used to select a profile other than the printer default when the dialog is first displayed.

ccTargetProfile

The size of the buffer pointed to by the pTargetProfile member, in characters. If the buffer is not large enough to hold the selected name, the name is truncated to this size, and ERROR_INSUFFICIENT_BUFFER is returned. A buffer of MAX_PATH size always works.

lpfnHook

If the CMS_USEHOOK flag is set, this member is the address of a dialog procedure (see DialogProc) that can filter or handle messages for the dialog. The hook procedure receives no messages issued before WM_INITDIALOG. It is called on the WM_INITDIALOG message after the system-provided dialog procedure has processed the message. On all other messages, the hook procedure receives the message before the system-provided procedure. If the hook procedure returns TRUE to these messages, the system-provided procedure is not called.

The hook procedure may call the EndDialog function.

lParam

If the CMS_USEHOOK flag is set, this member is passed to the application-provided hook procedure as the lParam parameter when the WM_INITDIALOG message is processed.

lpfnApplyCallback

Contains a pointer to a callback function that is invoked when the Apply button of the Color Management dialog box is selected. If no callback function is provided, this member should be set to NULL.

lParamApplyCallback

Contains a value that will be passed to the function ApplyCallbackFunction through its lParam parameter. The meaning and content of the value is specified by the application.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Requires Windows 98.
  Windows CE: Unsupported.
  Header: Declared in icm.h.
  Unicode: Defined as Unicode and ANSI structures.