README
1NAME
2 ColourChooser - Perl/Tk module providing a Colour selection dialogue
3 box.
4
5SYNOPSIS
6 use Tk::ColourChooser ;
7
8 my $col_dialog = $Window->ColourChooser ;
9 my $colour = $col_dialog->Show ;
10 if( $colour ) {
11 # They pressed OK and the colour chosen is in $colour - could be
12 # transparent which is 'None' unless -transparent is set.
13 }
14 else {
15 # They cancelled.
16 }
17
18 # May optionally have the colour initialised.
19 my $col_dialog = $Window->ColourChooser( -colour => 'green' ) ;
20 my $col_dialog = $Window->ColourChooser( -colour => '#0A057C' ) ;
21
22 # The title may also be overridden; and we can insist that only hex values
23 # are returned rather than colour names. We can disallow transparent.
24 my $col_dialog = $Window->ColourChooser(
25 -language => 'en', # Or 'de' or 'fr'.
26 -title => 'Select a colour',
27 -colour => '0A057C',
28 -transparent => 0,
29 -hexonly => 1,
30 -showhex => 1,
31 ) ;
32
33DESCRIPTION
34 ColourChooser is a dialogue box which allows the user to pick a colour
35 from the list in rgb.txt (supplied with X Windows), or to create a
36 colour by setting RGB (red, green, blue) values with slider controls.
37
38 You can scroll through all the named colours by using the <Down> and
39 <Up> arrow keys on the keyboard or by clicking the mouse on the
40 scrollbar and then clicking the colour list.
41
42 Options
43 "-language" This is optional. Default is `en'. This option allows you to
44 set the language for the title and labels. Valid values are "en"
45 (english), "de" (german), "fr" (french) and "english" (for backward
46 compatibility) which is also the default. Translations are by Babelfish.
47 Other languages will be added if people provide translations.
48 "-title" This is optional and allows you to set the title. Default is
49 'Colour Chooser' in the "-language" specified.
50 "-colour" This is optional and allows you to specify the colour that is
51 shown when the dialogue is invoked. It may be specified as a colour name
52 from rgb.txt or as a six digit hex number with an optional leading hash,
53 i.e. as 'HHHHHH' or '#HHHHHH'. Default is 'black'.
54 "-hexonly" This is optional. If set to 1 it forces the ColourChooser to
55 only return colours as hex numbers in Tk format ('#HHHHHH'); if set to 0
56 it returns colours as names if they are named in rgb.txt, and as hex
57 numbers if they have no name. Transparent is always returned as 'None'
58 however. Default is 0.
59 "-transparent" This is optional. If set to 0 it stops ColourChooser
60 offering the Transparent button so that only valid colours may be chosen
61 - or cancel. Default is 1.
62 "-showhex" This is optional. If set to 1 it shows the hex value of the
63 colour in the title bar. Default is 0.
64
65 The user has three options:
66
67 OK
68 Pressing OK will return the selected colour, as a name if it has one or
69 as an RGB value if it doesn't. (Colours which do not have names are
70 listed as 'Unnamed' in the colour list box.) If the "-hexonly" option
71 has been specified the colour is always returned as a Tk colour hex
72 value, i.e. in the form '#HHHHHH' except if Transparent is chosen in
73 which case 'None' is returned.
74
75 OK is pressed by a mouse click or <Return> or <o> or <Control-o> or
76 <Alt-o>.
77
78 Transparent
79 Pressing Transparent will return the string 'None' which is xpm's name
80 for transparent.
81
82 Transparent is pressed by a mouse click or <t> or <Control-t> or
83 <Alt-t>.
84
85 Cancel
86 Pressing Cancel will return an empty string.
87
88 Cancel is pressed by a mouse click or <Escape> or <c> or <Control-c> or
89 <Alt-c>. (Note that if the language is not english then the letter to
90 press will be the first letter of the translation of the word 'Cancel'.
91
92INSTALLATION
93 ColourChooser.pm should be placed in any Tk directory in any lib
94 directory in Perl's %INC path, for example, '/usr/lib/perl5/Tk'.
95
96 ColourChooser looks for the file rgb.txt on your system - if it can't
97 find it you will only be able to specify colours by RGB value. Or you
98 can set the environment variable RGB_TEXT to the filename.
99
100METHODS
101 Populate
102 Inherited from Tk::Toplevel
103
104 Show
105 Inherited from Tk::Toplevel
106
107BUGS
108 Does almost no error checking.
109
110 Can be slow to load because rgb.txt is large; however we now load a
111 single instance of the colour names when the module is first used and
112 these names are then shared.
113
114 If you scroll the list by keyboard or use the mouse to move the colour
115 sliders the colour updates as you go; but if you use the mouse on the
116 scrollbar you must click the colour name box for the colour to update. I
117 don't know why this is and any advice on how to fix it would be welcome.
118
119AUTHOR
120 Tina Mueller
121
122ORIGINAL AUTHOR
123 This module was developed by Mark Summerfield <summer@perlpress.com>
124 until version 1.50.
125
126 The code draws from Stephen O. Lidie's work.
127
128COPYRIGHT
129 Copyright (c) Mark Summerfield 1999-2000. All Rights Reserved.
130
131 This module may be used/distributed/modified under the LGPL.
132
133