Using the Ultimate Color Picker Dialogs (UCPD) in your application is straightforward. You copy the needed UCPD files into your project, add the appropriate UCPD unit names to the uses clauses of your application source files, add the appropriate UCPD unit(s) to your project if you want UCPDs to be auto-created, and add code to your application to invoke the dialogs. You will also need to make your license information visible from the About Box. The demo program contains example source code showing how to invoke each of the dialogs from your application. You should familiarize yourself with this demo before reading the rest of this document.
The UCPD files you will need to copy into your project directory depend on which dialog(s) you want to implement in your application.
Files to copy: |
Browser Safe Color |
Hue/Saturation/Luminosity |
Hybrid Color |
| ColorPickerDlgUnit.pas & .dfm | required |
required |
required |
| BSC_ColorPickerDlgUnit.pas & .dfm | required |
required |
required |
| HSL_ColorPickerDlgUnit.pas & .dfm | (not needed) |
required |
(not needed) |
| Hybrid_BSC_HSL_ColorPickerDlgUnit.pas & .dfm | (not needed) |
required |
required |
| LicensesAndCreditsDlgUnit.pas & .dfm | optional* |
optional* |
optional* |
*The License agreement requires license information to be visible to the application's user either directly or indirectly from the About Box. The LicensesAndCreditsDlgUnit is provided as an easy way to meet this requirement. It is permissible to fulfil the requirement with an equivalent dialog of your own design.
As with all dialogs derived from Delphi's TForm, you may specify that a single instance of each of the UCPDs be automatically created when your application starts up. This is done using the IDE's Project/Add To Project Menu. Add the following UCPD unit(s) to your project for each dialog you want auto-created:
Browser Safe Color |
Hue/Saturation/Luminosity |
Hybrid Color |
|
| File to Add to your Project: | BSC_ColorPickerDlgUnit.pas |
HSL_ColorPickerDlgUnit.pas |
Hybrid_BSC_HSL_ColorPickerDlgUnit.pas |
| Auto-Created Dialog Variable | BSC_ColorPickerDlg | HSL_ColorPickerDlg | Hybrid_BSC_HSL_ColorPickerDlg |
Note that the LicensesAndCreditsDlg is never auto-created.
Alternatively dialog instances may be dynamically created and freed in the normal manner.
dlg := TBSC_ColorPickerDlg.Create (Owner);
...
dlg.Free
This approach is useful when multiple instances of the dialogs are needed. In some applications it can be useful to have multiple instances, each of which holds a particular color selection for a specific purpose within the application.
Utilizing UCPD in your application adds the following minimal specifications to your application's specifications.
As described in the License Agreement, you must include your UCPD license information in your application's About Box, or in a sub-dialog which can be invoked from the About Box. The necessary license information (five lines of text) are obtained from the website (www.components.SimpleWebsiteNavigation.com) when you obtain your license.
Although it is not required, you may wish to include the following credit if you use either of the UCPDs with Hue/Saturation/Luminosity Color Maps:
The conversion algorithms for HSL color spaces are from Chapter 17 of the book Fundamentals of Interactive Computer Graphics by Foley and van Dam, Addison-Wesley, 1982.
The LicensesAndCreditsDlgUnit is provided as an easy way of fulfilling this requirement. This unit provides a single function (ShowLicensesAndCredits) which, when invoked, shows a dialog box with the license information in the proper form. The About Box of the Demo program includes a label with a caption set to "Licenses and Credits" and font properties set to underlined and purple to mimic a link on a web page. The OnClick event for this label calls this function with the appropriate parameters.
type
TUCPDLicenseGrade =
(UCPDPersonalLicense,
UCPDSharewareLicense,
UCPDCommercialLicense
);
TUCPDLicenseType =
(UCPDGeneralLicense,
UCPDRecompileLicense
);
procedure ShowLicensesAndCredits
(LicenseNo: integer;
Licensee: string;
UCPDLicenseGrade: TUCPDLicenseGrade;
UCPDLicenseType: TUCPDLicenseType;
ApplicationName: string;
usesHSL: boolean
);
The parameters for the function are filled in as appropriate for the license you purchased from www.components.SimpleWebsiteNavigation.com. The ApplicationName string should be filled in for Recompile Licenses, or should be an empty string for General Licenses. The usesHSL parameter determines whether or not the credit to Foley and van Dam for the HSL color space algorithms is shown (it is recommended that you set this to true if you use either the Hue/Saturation/Luminosity or the Hybrid Color Picker Dialogs in your application). You should test your application to ensure that the license information shown when the dialog is invoked matches the license information in the email from www.components.SimpleWebsiteNavigation.com when your purchased your license.
It is easy to add additional license and credit information to the Licenses and Credits dialog. Open LicensesAndCreditsDlgUnit.dfm, select the TMemo LicensesAndCredits (shown selected above), go to the Object Inspector and invoke the Lines property editor. Add the desired license and credit information after the single dashed line that is already there.
The example above shows result after the addition of credit information for JPEG and PNG components for an application. In this example, the original dashed line was cut and pasted in after each credit to act as a separator. This additional information will be available to the application's user via the scrollbar.
The UCPDs are derived from Delphi's TForm, and TColorPickerDlg is the abstract base class. TBSC_ColorPickerDlg implements the Browser Safe Color picker. THybrid_BSC_HSL_ColorPickerDlg inherits from BSC_ColorPickerDlg and adds the implementation of the Hue/Saturation/Luminosity Color picker. THSL_ColorPickerDlg inherits from THybrid_BSC_HSL_ColorPickerDlg and simply hides the Browser Safe Color picker.
This particular class hierarchy was chosen since THybrid_BSC_HSL_ColorPickerDlg contains a large bitmap resource (the Hue/Saturation image) which is also needed by THSL_ColorPickerDlg. Having TBSC_ColorPickerDlg higher in the hierarchy reduces resource requirements for applications needing only TBSC_ColorPickerDlg.
The UCPDs are derived from TForm and thus provide all of TForm's properties, methods, and events.
The ColorPick property contains the selected color. It may be set prior to dialog invocation to preset the color choice for the user, and it may be read after dialog invocation to determine what color was selected by the user.
The Execute method is used to invoke the dialog. The method returns true if Ok was pressed, false otherwise.
The Execute method of the Hybrid Color Picker Dialog takes a mode parameter that may be used to restrict the user to selecting from Browser Safe Colors only or from Hue/Saturation/Luminosity maps only.
Each of the UCPDs implements an OnColorChange event, which can be utilized to obtain notifications of each color change made by the user while the dialog is active. See the Demo program for an example of how this may be utilized.
The UCPD dialogs properly implement their own Ok and Cancel behaviors: if the user changes the Color selection after a dialog is activated and then the dialog is Canceled, the Color property is reset to what it was before the Dialog was activated.
To assist the application developer in implementing Ok and Cancel behaviors in application dialogs from which UCPD dialogs can be invoked as sub-dialogs, the UCPD dialogs implement the following methods:
To utilize these methods to implement Ok/Cancel behavior in the application dialog, add the following event handlers to the application dialog code:
The application developer may choose to derive custom dialogs from any of the UCPDs. The UpdateDialogPreview virtual method is invoked by the base classes to show the initial color, and then again each time the user changes the selected color. The developer can override this method to implement a custom preview in the derived dialog. See the Demo program for an example of how this might be utilized.
As distributed, all UCPDs are sized to operate on an 800x600 display, and this will be adequate for most applications. The following instructions are provided if you wish make the dialogs smaller to support 640x480 displays, or if your application requires a larger display for other reasons and you would like to make the dialogs larger to match that display size.
The size of the BSC Palettes and the HSL Color Maps are determined by the size of the ColorPickerPanel component in the base dialog (TColorPickerDlg in ColorPickerDlgUnit.pas), and are re-calculated to fit in that panel when each dialog object is activated.
To resize the dialogs at design time, simply resize the ColorPickerPanel component in either the base class (preferred) or the appropriate descendant class and make any other desired changes to the dialog layout. If you are using HSL dialogs, you will also need to regenerate the Hue/Saturation Color Map bitmap that is loaded into the HueSaturationImage component (instructions below). You do not need to resize any of the other components placed inside ColorPickerPanel in any of the descendant dialogs.
The Hue/Saturation Color Map is a bitmap displayed in the HueSaturationImage component of THybrid_BSC_HSL_ColorPickerDlg (in Hybrid_BSC_HSL_ColorPickerDlgUnit.pas). The resource file for this unit contains a bitmap of this Hue/Saturation Color Map that should be sized to match the size of the HueSaturationImage component as calculated when the form is created. If you have not properly resized this bitmap, the discrepancy will be noted when the dialog is activated and an Exception will be thrown: "Hue/Image Bitmap Size Problem - contact program vendor", where "program vendor" is you.
To resize the Hue/Saturation bitmap, first resize the ColorPickerPanel as described above. Then you will then need to write a little special-purpose code to generate a new Hue/Saturation bitmap file, and finally you will use the Delphi IDE to reload this new bitmap file into the HueSaturationImage component.
The HSL dialog code contains a procedure to generate a new hue saturation bitmap file, but you will need to write some special-purpose code to invoke it. It is probably easiest to do this by adding a temporary button to the main form of your application, and then adding the following OnClick event handler for that button (make sure you have Hybrid_BSC_HSL_ColorPickerDlgUnit in your USES list):
procedure TMainForm.TempButtonClick(Sender: TObject);
var temp_dlg: THybrid_BSC_HSL_ColorPickerDlg;
begin
temp_dlg := THybrid_BSC_HSL_ColorPickerDlg.Create (self);
temp_dlg.generate_new_hue_saturation_bitmap ('c:\huesat.bmp');
temp_dlg.Free
end;
After compiling and starting your application, click on the temporary button and check to make sure the new bitmap file (c:\huesat.bmp) has been generated. You may then shut down your application and remove the temporary button and event handler from your code.
Next, from the IDE, you will need to load the new bitmap file into the
HueSaturationImage component. Open Hybrid_BSC_HSL_ColorPickerDlgUnit.pas, and
select the HueSaturationImage component. In the Object Inspector's Properties
Tab, select "Picture" then click on the
button. Press
"Load..." and locate the file you generated above (c:\huesat.bmp).
Press "Ok" then recompile your application.
The BSC dialog works fine in Delphi 2, however there are some minor aesthetic problems with the HSL dialogs when compiled with Delphi2. Although the HSL dialogs will function okay, these aesthetic problems are the reason the HSL dialogs are not advertised as being compatible with Delphi 2. The problem is that Delphi2's TImage component does not implement the Transparent property, and consequently the sliding arrows in the Hue, Saturation, and Luminosity slider bars cover up some of the stuff behind them when they are moved. Also, Delphi2 does not implement assert, so a dummy assert procedure is IFDEF'd in to make it compile.