Color Picker Manager Reference April 1, 2003 MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS Apple Computer, Inc. MANUAL IS SOLD ªAS IS,º AND YOU, THE © 2003, 2004 Apple Computer, Inc. PURCHASER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. All rights reserved. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, No part of this publication may be OR CONSEQUENTIAL DAMAGES reproduced, stored in a retrieval system, or RESULTING FROM ANY DEFECT OR INACCURACY IN THIS MANUAL, even if transmitted, in any form or by any means, advised of the possibility of such damages. mechanical, electronic, photocopying, THE WARRANTY AND REMEDIES SET recording, or otherwise, without prior FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, written permission of Apple Computer, Inc., EXPRESS OR IMPLIED. No Apple dealer, agent, with the following exceptions: Any person or employee is authorized to make any is hereby authorized to store documentation modification, extension, or addition to this warranty. on a single computer for personal use only Some states do not allow the exclusion or and to print copies of documentation for limitation of implied warranties or liability for personal use provided that the incidental or consequential damages, so the above limitation or exclusion may not apply to documentation contains Apple’s copyright you. This warranty gives you specific legal notice. rights, and you may also have other rights which vary from state to state. The Apple logo is a trademark of Apple Computer, Inc. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Carbon, ColorSync, Mac, Mac OS, and QuickDraw are trademarks of Apple Computer, Inc., registered in the United States and other countries. Simultaneously published in the United States and Canada. Even though Apple has reviewed this manual, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS MANUAL, ITS QUALITY, ACCURACY, Contents Chapter 1 Color Picker Manager Reference 7 Color Picker Manager Functions 7 Converting Between SmallFract and Fixed Values 7 Converting Colors Among Color Models 8 Using the Standard Color Picker Dialog Box 11 Working With Universal Procedure Pointers 13 Color Picker Manager Callbacks 17 Changing Colors in a Document 17 Handling Application-Directed Events in a Color Picker 18 Color Picker Manager Data Types 19 CMYColor 19 ColorChangedUPP 19 ColorPickerInfo (Old) 19 HSLColor 21 HSVColor 22 NColorChangedUPP 22 NColorPickerInfo 22 NPMColor 23 PickerMenuItemInfo 24 PMColor 24 SmallFract 25 UserEventUPP 25 Color Picker Manager Constants 25 Color Picker Result Codes 29 Appendix A Unsupported Functions 31 Document Revision History 33 Index 35 3 © 2003, 2004 Apple Computer, Inc. All Rights Reserved. CONTENTS 4 © 2003, 2004 Apple Computer, Inc. All Rights Reserved. Tables Appendix A Unsupported Functions 31 Table A-1 Porting notes for unsupported Color Pickedr functions 32 Document Revision History 33 Table RH-1 Document revision history 33 5 © 2003, 2004 Apple Computer, Inc. All Rights Reserved. TABLES 6 © 2003, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Color Picker Manager Reference Framework: Carbon/Carbon.h Header: ColorPicker.h Using Color Picker Manager functions, your application can use the standard user interface for soliciting color choices from users. Your application can use these functions to display, respond to events within, and close a color picker dialog box. The Color Picker Manager provides standard color pickers (which allow users to select colors from ranges of colors) and a standard dialog box allowing users to interact with the color picker. Your application can also create its own color pickers and dialog boxes to work with the Color Picker Manager. Carbon supports the Color Picker Manager functions that most applications rely on, GetColor, PickColor, and NPickColor. In addition, Carbon will support all the functions described as supported in "Technote 1100: Color Picker 2.1." That same Technote specifies certain functions from earlier versions of the Color Picker Manager that are no longer supported by the Mac OS; Carbon will not support these functions. In addition, many of the functions that start with the word "Picker", such as PickerInit, PickerGetProfile, and PickerItemHit, are no longer supported. These routines provided low-level access to the Color Picker Manager that was rarely used. Color Picker Manager Functions Converting Between SmallFract and Fixed Values Fix2SmallFract Converts a fixed integer to a SmallFract value. SmallFract Fix2SmallFract ( Fixed f ); Color Picker Manager Functions 7 © 2003, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Color Picker Manager Reference Parameter Descriptions f The value of type Fixed to be converted to a SmallFract value. function result A SmallFract converted from the fixed integer value specified in the f parameter. See page for a description of the SmallFract data type. Discussion A SmallFract value can represent a value between 0 and 65,535. Introduced by the original Color Picker Package, SmallFract values are used in CMYColor, HSLColor, and HSVColor structures. They can be assigned directly to and from integers. Availability Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later. Header: ColorPicker.h Carbon Porting Notes SmallFract2Fix Converts a SmallFract value to a fixed integer. Fixed SmallFract2Fix ( SmallFract s ); Parameter Descriptions s The value of type SmallFract to be converted into a fixed integer. function result A fixed integer converted from the SmallFract value specified in the s parameter. Availability Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later. Header: ColorPicker.h Converting Colors Among Color Models CMY2RGB Converts a CMY color to its equivalent RGB color. void CMY2RGB ( const CMYColor * cColor, RGBColor * rColor ); 8 Color Picker Manager Functions © 2003, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Color Picker Manager Reference Parameter Descriptions cColor A pointer to a CMYColor structure to be converted. rColor A pointer to an RGBColor structure for the converted color. Availability Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later. Header: ColorPicker.h Carbon Porting Notes HSL2RGB Converts an HSL color to an RGB color. void HSL2RGB ( const HSLColor * hColor, RGBColor * rColor ); Parameter Descriptions hColor A pointer to the HSLColor structure to be converted. rColor A pointer to an RGBColor structure for the converted color. Availability Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later. Header: ColorPicker.h Carbon Porting Notes HSV2RGB Converts an HSV color to an RGB color. void HSV2RGB ( const HSVColor * hColor, RGBColor * rColor ); Parameter Descriptions hColor A pointer to the HSVColor structure to be converted. Color Picker Manager Functions 9 © 2003, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Color Picker Manager Reference rColor A pointer to an RGBColor structure for the converted color. Availability Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later. Header: ColorPicker.h Carbon Porting Notes RGB2CMY Converts an RGB color to a CMY color. void RGB2CMY ( const RGBColor * rColor, CMYColor * cColor ); Parameter Descriptions rColor A pointer to an RGBColor structure to be converted. cColor A pointer to a CMYColor structure for the converted color. Availability Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later. Header: ColorPicker.h Carbon Porting Notes RGB2HSL Converts an RGB color to an HSL color. void RGB2HSL ( const RGBColor * rColor, HSLColor * hColor ); Parameter Descriptions rColor A pointer to the RGBColor structure to be converted. hColor A pointer to an HSLColor structure for the converted color. 10 Color Picker Manager Functions © 2003, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Color Picker Manager Reference Availability Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later. Header: ColorPicker.h Carbon Porting Notes RGB2HSV Converts an RGB color to an HSV color. void RGB2HSV ( const RGBColor * rColor, HSVColor * hColor ); Parameter Descriptions rColor A pointer to the RGBColor structure to be converted. hColor A pointer to an HSVColor structure for the converted color. Availability Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later. Header: ColorPicker.h Carbon Porting Notes Using the Standard Color Picker Dialog Box NPickColor Displays the Color Picker dialog. OSErr NPickColor ( NColorPickerInfo * theColorInfo ); Parameter Descriptions theColorInfo A pointer to a color picker parameter (NColorPickerInfo) data structure. On input, you specify information such as the location of the dialog. On output, the data structure specifies information such as whether the user changed the color. function result A result code. See ªColor Picker Result Codesº (page 29). Color Picker Manager Functions 11 © 2003, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Color Picker Manager Reference Discussion The NPickColor function displays the standard dialog for color pickers.