NAME

ColourChooser - Perl/Tk module providing a Colour selection dialogue box.

SYNOPSIS

use Tk::ColourChooser ; 

eval {
    my $col_dialog = $Window->ColourChooser ;
    my $colour     = $col_dialog->Show ;
    if( $colour ) {
        # They pressed OK and the colour chosen is in $colour - could be
        # transparent which is 'None' unless -transparent is set.
    }
    else {
        # They cancelled.
    }
}
if( $@ ) {
    # Died because it couldn't find rgb.txt.
}

# May optionally have the colour initialised.
my $col_dialog = $Window->ColourChooser( -colour => 'green' ) ;
my $col_dialog = $Window->ColourChooser( -colour => '#0A057C' ) ;

# The title may also be overridden; and we can insist that only hex values
# are returned rather than colour names. We can disallow transparent.
my $col_dialog = $Window->ColourChooser( 
                    -title       => 'Select a colour',
                    -colour      => '0A057C',
                    -transparent => 0,
                    -hexonly     => 1,
                    ) ;

DESCRIPTION

ColourChooser is a dialogue box which allows the user to pick a colour from the list in rgb.txt (supplied with X Windows), or to create a colour by setting RGB (red, green, blue) values with slider controls.

You can scroll through all the named colours by using the <Down> and <Up> arrow keys on the keyboard.

Options

-colour This is optional and allows you to specify the colour that is shown when the dialogue is invoked. It may be specified as a colour name from rgb.txt or as a six digit hex number with an optional leading hash, i.e. as 'HHHHHH' or '#HHHHHH'. Default is 'black'.

-hexonly This is optional. If set to 1 it forces the ColourChooser to only return colours as hex numbers in Tk format ('#HHHHHH'); if set to 0 it returns colours as names if they are named in rgb.txt, and as hex numbers if they have no name. Transparent is always returned as 'None' however. Default is 0.

-transparent This is optional. If set to 0 it stops ColourChooser offering the Transparent button so that only valid colours may be chosen - or cancel. Default is 1. =back

The user has three options:

OK

Pressing OK will return the selected colour, as a name if it has one or as an RGB value if it doesn't. (Colours which do not have names are listed as 'Unnamed' in the colour list box.) If the -hexonly option has been specified the colour is always returned as a Tk colour hex value, i.e. in the form '#HHHHHH' except if Transparent is chosen in which case 'None' is returned.

OK is pressed by a mouse click or <Return> or <o> or <Control-o> or <Alt-o>.

Transparent

Pressing Transparent will return the string 'None' which is xpm's name for transparent.

Transparent is pressed by a mouse click or <t> or <Control-t> or <Alt-t>.

Cancel

Pressing Cancel will return an empty string.

Cancel is pressed by a mouse click or <Escape> or <c> or <Control-c> or <Alt-c>.

FOR DEVELOPERS

There are two functions that developers can use in their own code to use some of ColourChooser's own functionality. If you have a colour name and want to convert that to hex you can do it thus:

# Load the rgb values, only needed once.
Tk::ColourChooser::read_rgb( $Win ) ; 
    ...
# Now we can do lookups.
my $hex = Tk::ColourChooser::name2hex( $Win, $colour_name ) ;

See pixmaped (pixmaped-gif.pl - _colour2rgb) for an example of this.

INSTALLATION

ColourChooser.pm should be placed in any Tk directory in any lib directory in Perl's %INC path, for example, '/usr/lib/perl5/Tk'.

ColourChooser looks for the file rgb.txt on your system - it won't work if it can't find it!

BUGS

Scrolling with the mouse updates the list box, but not the background colour which shows what the chosen colour looks like. It should behave the same as scrolling with the <Down> and <Up> arrow keys.

ColourChooser does almost no error checking.

ColourChooser is slow to load because rgb.txt is large.

CHANGES

1999/01/29 First version.

1999/02/15 Improved handling of initial colour so that it copes better with the variety of valid colour name inputs.

1999/02/17 If a colour is given as lowercase hex it is now properly recognised.

1999/02/23 Should now be Windows compatible.

AUTHOR

Mark Summerfield. I can be contacted as <mark.summerfield@chest.ac.uk> - please include the word 'colourchooser' in the subject line.

The code draws from Stephen O. Lidie's work.

COPYRIGHT

Copyright (c) Mark Summerfield 1999. All Rights Reserved.

This module may be used/distributed/modified under the same terms as Perl itself.

cpanm Tk::MesgBox

perl -MCPAN -e shell
install Tk::MesgBox