| 1 | |
| 2 | <html> |
| 3 | <head> |
| 4 | <meta name="description" content="Pmw - a toolkit for building high-level compound widgets in Python"> |
| 5 | <meta name="content" content="python, megawidget, mega widget, compound widget, gui, tkinter"> |
| 6 | <title>Pmw.Color reference manual</title> |
| 7 | </head> |
| 8 | |
| 9 | <body bgcolor="#ffffff" text="#000000" link="#0000ee" |
| 10 | vlink="551a8b" alink="ff0000"> |
| 11 | |
| 12 | <h1 ALIGN="CENTER">Pmw.Color</h1> |
| 13 | |
| 14 | <dl> |
| 15 | <dt> <h3>Name</h3></dt><dd> |
| 16 | <p>Pmw.Color - |
| 17 | contains functions for handling colors and color schemes</p> |
| 18 | <p></p> |
| 19 | |
| 20 | |
| 21 | |
| 22 | </dd> |
| 23 | <dt> <h3>Description</h3></dt><dd> |
| 24 | <p> |
| 25 | This module is a set of functions for manipulating colors and for |
| 26 | modifying the color scheme of an application or a widget. Many of |
| 27 | the functions in this module take or return colors. These values |
| 28 | may represent colors in the following ways:</p> |
| 29 | <dl><dt><strong>name</strong></dt><dd>a standard color name, eg <code>'orange'</code> or <code>'#ffa500'</code><p></p> |
| 30 | |
| 31 | </dd> |
| 32 | <dt><strong>rgb</strong></dt><dd>a 3-element sequence of red, green and blue intensities |
| 33 | each between 0.0 (dark) and 1.0 (light), eg <code>[1.0, 0.6, 0.0]</code>.<p></p> |
| 34 | |
| 35 | </dd> |
| 36 | <dt><strong>hsi</strong></dt><dd>a 3-element sequence (<em>hue</em>, <em>saturation</em>, |
| 37 | <em>intensity</em>). The value of <em>hue</em> is between 0.0 and <strong>2pi</strong> |
| 38 | (6.28318) giving a range of colors covering, in order, red, |
| 39 | orange, yellow green, cyan, blue, magenta and back to red. |
| 40 | The value of <em>saturation</em> is between 0.0 (grey) and 1.0 |
| 41 | (brilliant) and the value of <em>intensity</em> is between 0.0 (dark) |
| 42 | and 1.0 (bright).<p></p> |
| 43 | |
| 44 | </dd></dl> |
| 45 | |
| 46 | <p> As used in these functions, the <strong>brightness</strong> of a color is the |
| 47 | perceived grey level of the color as registered by the human eye. |
| 48 | For example, even though the colors red, blue and yellow have the |
| 49 | same intensity (1.0), they have different brightnesses, 0.299, |
| 50 | 0.114 and 0.886 respectively, reflecting the different way these |
| 51 | colors appear to the eye. The brightness of a color is a value |
| 52 | between 0.0 (dark) and 1.0 (bright).</p> |
| 53 | |
| 54 | <p> A <strong>color scheme</strong> is a set of colors defined for each of the |
| 55 | default color options in the Tk option database. Color schemes |
| 56 | can be used in two ways. Firstly, using <code>Pmw.Color.setscheme()</code>, |
| 57 | the Tk option database can be set to the values in the color |
| 58 | scheme. This will not have any effect on currently existing |
| 59 | widgets, but any new widgets created after setting the options |
| 60 | will have these colors as their defaults. Secondly, using |
| 61 | <code>Pmw.Color.changecolor()</code> the color scheme can be used to change |
| 62 | the colors of a widget and all its child widgets.</p> |
| 63 | |
| 64 | <p> A color scheme is specified by defining one or more color options |
| 65 | (one of the defined options must be <code>background</code>). Not all |
| 66 | options need be specified - if any options are not defined, they |
| 67 | are calculated from the other colors. These are the options used |
| 68 | by a color scheme, together with their values if not specified:</p> |
| 69 | <dl><dd><pre> background: (must be specified) |
| 70 | foreground: black |
| 71 | activeForeground: same as foreground |
| 72 | insertBackground: same as foreground |
| 73 | selectForeground: same as foreground |
| 74 | highlightColor: same as foreground |
| 75 | disabledForeground: between fg and bg but closer to bg |
| 76 | highlightBackground: same as background |
| 77 | activeBackground: a little lighter that bg |
| 78 | selectBackground: a little darker that bg |
| 79 | troughColor: a little darker that bg |
| 80 | selectColor: yellow</pre></dd></dl> |
| 81 | |
| 82 | |
| 83 | <p> There are many functions in this module. As well as |
| 84 | <code>Pmw.Color.setscheme()</code> and <code>Pmw.Color.changecolor()</code>, some of the |
| 85 | most useful are <code>Pmw.Color.spectrum()</code>, |
| 86 | <code>Pmw.Color.changebrightness()</code> and |
| 87 | <code>Pmw.Color.getdefaultpalette()</code>.</p> |
| 88 | |
| 89 | <p></p> |
| 90 | |
| 91 | |
| 92 | </dd> |
| 93 | <dt> <h3>Functions</h3></dt><dd> |
| 94 | The following functions are available.<p></p> |
| 95 | <dl> |
| 96 | <dt> <strong>Pmw.Color.average</strong>(<em>rgb1</em>, <em>rgb2</em>, <em>fraction</em>)</dt><dd> |
| 97 | |
| 98 | Return an <strong>rgb</strong> color <em>fraction</em> of the way "between" the colors |
| 99 | <em>rgb1</em> and <em>rgb2</em>, where <em>fraction</em> must be between <strong>0.0</strong> and |
| 100 | <strong>1.0</strong>. If <em>fraction</em> is close to <strong>0.0</strong>, then the color returned |
| 101 | will be close to <em>rgb1</em>. If it is close to <strong>1.0</strong>, then the color |
| 102 | returned will be close to <em>rgb2</em>. If it is near <strong>0.5</strong>, then the |
| 103 | color returned will be half way between the two colors.</p> |
| 104 | |
| 105 | <p></p> |
| 106 | |
| 107 | |
| 108 | </dd> |
| 109 | <dt> <strong>Pmw.Color.bhi2saturation</strong>(<em>brightness</em>, <em>hue</em>, <em>intensity</em>)</dt><dd> |
| 110 | |
| 111 | Return the saturation of the color represented by <em>brightness</em>, |
| 112 | <em>hue</em> and <em>intensity</em>.</p> |
| 113 | |
| 114 | <p></p> |
| 115 | |
| 116 | |
| 117 | </dd> |
| 118 | <dt> <strong>Pmw.Color.bordercolors</strong>(<em>root</em>, <em>colorName</em>)</dt><dd> |
| 119 | |
| 120 | Return a tuple <code>(light, dark)</code> of color names that can be used as |
| 121 | the light and dark border shadows on a widget where the background |
| 122 | is <em>colorName</em>. This is the same method that Tk uses for shadows |
| 123 | when drawing reliefs on widget borders. The <em>root</em> argument is |
| 124 | only used to query Tk for the <strong>rgb</strong> values of <em>colorName</em>.</p> |
| 125 | |
| 126 | <p></p> |
| 127 | |
| 128 | |
| 129 | </dd> |
| 130 | <dt> <strong>Pmw.Color.changebrightness</strong>(<em>root</em>, <em>colorName</em>, <em>brightness</em>)</dt><dd> |
| 131 | |
| 132 | Find the hue of the color <em>colorName</em> and return a color of this |
| 133 | hue with the required <em>brightness</em>. If <em>brightness</em> is <strong>None</strong>, |
| 134 | return the name of color with the given hue and with saturation |
| 135 | and intensity both <strong>1.0</strong>. The <em>root</em> argument is only used to |
| 136 | query Tk for the <strong>rgb</strong> values of <em>colorName</em>.</p> |
| 137 | |
| 138 | <p></p> |
| 139 | |
| 140 | |
| 141 | </dd> |
| 142 | <dt> <strong>Pmw.Color.changecolor</strong>(<em>widget</em>, <em>background</em> = <strong>None</strong>, **<em>kw</em>)</dt><dd> |
| 143 | |
| 144 | Change the color of <em>widget</em> and all its child widgets according |
| 145 | to the color scheme specified by the other arguments. This is done |
| 146 | by modifying all of the color options of existing widgets that |
| 147 | have the default value. The color options are the lower case |
| 148 | versions of those described in the <strong>color scheme</strong> section. Any |
| 149 | options which are different to the previous color scheme (or the |
| 150 | defaults, if this is the first call) are not changed.</p> |
| 151 | |
| 152 | <p> For example to change a widget to have a red color scheme with a |
| 153 | white foreground:</p> |
| 154 | |
| 155 | <dl><dd><pre> Pmw.Color.changecolor(widget, |
| 156 | background = 'red3', foreground = 'white')</pre></dd></dl> |
| 157 | |
| 158 | <p> The colors of widgets created after this call will not be |
| 159 | affected.</p> |
| 160 | |
| 161 | <p> Note that <em>widget</em> must be a Tk widget or toplevel. To change the |
| 162 | color of a Pmw megawidget, use it's <strong>hull</strong> component. For example:</p> |
| 163 | |
| 164 | <dl><dd><pre> widget = megawidget.component('hull') |
| 165 | Pmw.Color.changecolor(widget, background = 'red3')</pre></dd></dl> |
| 166 | |
| 167 | <p></p> |
| 168 | |
| 169 | |
| 170 | </dd> |
| 171 | <dt> <strong>Pmw.Color.correct</strong>(<em>rgb</em>, <em>correction</em>)</dt><dd> |
| 172 | |
| 173 | Return the "corrected" value of <em>rgb</em>. This can be used to |
| 174 | correct for dull monitors. If <em>correction</em> is less than <strong>1.0</strong>, |
| 175 | the color is dulled. If <em>correction</em> is greater than <strong>1.0</strong>, the |
| 176 | color is brightened.</p> |
| 177 | |
| 178 | <p></p> |
| 179 | |
| 180 | |
| 181 | </dd> |
| 182 | <dt> <strong>Pmw.Color.getdefaultpalette</strong>(<em>root</em>)</dt><dd> |
| 183 | |
| 184 | Return a dictionary of the default values of the color options |
| 185 | described in the <strong>color scheme</strong> section.</p> |
| 186 | |
| 187 | <p> To do this, a few widgets are created as children of <em>root</em>, their |
| 188 | defaults are queried, and then the widgets are destroyed. (Tk |
| 189 | supplies no other way to get widget default values.)</p> |
| 190 | |
| 191 | <p> Note that <em>root</em> must be a Tk widget or toplevel. To use a Pmw |
| 192 | megawidget as the root, use it's <strong>hull</strong> component. For example:</p> |
| 193 | |
| 194 | <dl><dd><pre> root = megawidget.component('hull') |
| 195 | Pmw.Color.getdefaultpalette(root)</pre></dd></dl> |
| 196 | |
| 197 | <p></p> |
| 198 | |
| 199 | |
| 200 | </dd> |
| 201 | <dt> <strong>Pmw.Color.hsi2rgb</strong>(<em>hue</em>, <em>saturation</em>, <em>intensity</em>)</dt><dd> |
| 202 | |
| 203 | Return the <strong>rgb</strong> representation of the color represented by <em>hue</em>, |
| 204 | <em>saturation</em> and <em>intensity</em>.</p> |
| 205 | |
| 206 | <p></p> |
| 207 | |
| 208 | |
| 209 | </dd> |
| 210 | <dt> <strong>Pmw.Color.hue2name</strong>(<em>hue</em>, <em>brightness</em> = <strong>None</strong>)</dt><dd> |
| 211 | |
| 212 | Return the name of the color with the specified <em>hue</em> and |
| 213 | <em>brightness</em>. If <em>hue</em> is <strong>None</strong>, return a grey of the requested |
| 214 | brightness. Otherwise, the value of <em>hue</em> should be as described |
| 215 | above. If <em>brightness</em> is <strong>None</strong>, return the name of color with |
| 216 | the given hue and with saturation and intensity both <strong>1.0</strong>.</p> |
| 217 | |
| 218 | <p></p> |
| 219 | |
| 220 | |
| 221 | </dd> |
| 222 | <dt> <strong>Pmw.Color.name2rgb</strong>(<em>root</em>, <em>colorName</em>, <em>asInt</em> = <strong>0</strong>)</dt><dd> |
| 223 | |
| 224 | Return <em>colorName</em> as an <strong>rgb</strong> value. If <em>asInt</em> is true, then |
| 225 | the elements of the return sequence are in the range <strong>0</strong> to |
| 226 | <strong>65535</strong> rather than <strong>0.0</strong> to <strong>1.0</strong>. The <em>root</em> argument is only |
| 227 | used to query Tk for the <strong>rgb</strong> values of <em>colorName</em>.</p> |
| 228 | |
| 229 | <p></p> |
| 230 | |
| 231 | |
| 232 | </dd> |
| 233 | <dt> <strong>Pmw.Color.rgb2brightness</strong>(<em>rgb</em>)</dt><dd> |
| 234 | |
| 235 | Return the brightness of the color represented by <em>rgb</em>.</p> |
| 236 | |
| 237 | <p></p> |
| 238 | |
| 239 | |
| 240 | </dd> |
| 241 | <dt> <strong>Pmw.Color.rgb2hsi</strong>(<em>rgb</em>)</dt><dd> |
| 242 | |
| 243 | Return a tuple (<em>hue</em>, <em>saturation</em>, <em>intensity</em>) corresponding to |
| 244 | the color specified by the <em>rgb</em> sequence.</p> |
| 245 | |
| 246 | <p></p> |
| 247 | |
| 248 | |
| 249 | </dd> |
| 250 | <dt> <strong>Pmw.Color.rgb2name</strong>(<em>rgb</em>)</dt><dd> |
| 251 | |
| 252 | Return the name of the color represented by <em>rgb</em> as a string of |
| 253 | the form <code>'#RRGGBB'</code> suitable for use with Tk color functions.</p> |
| 254 | |
| 255 | <p></p> |
| 256 | |
| 257 | |
| 258 | </dd> |
| 259 | <dt> <strong>Pmw.Color.setscheme</strong>(<em>root</em>, <em>background</em> = <strong>None</strong>, **<em>kw</em>)</dt><dd> |
| 260 | |
| 261 | Set the color scheme for the application by setting default colors |
| 262 | (in the Tk option database of the root window of <em>root</em>) according |
| 263 | to the color scheme specified by the other arguments. This will |
| 264 | affect the initial colours of all widgets created after the call |
| 265 | to this function.</p> |
| 266 | |
| 267 | <p> For example to initialise an application to have a red color |
| 268 | scheme with a white foreground:</p> |
| 269 | |
| 270 | <dl><dd><pre> Pmw.Color.setscheme(root, |
| 271 | background = 'red3', foreground = 'white')</pre></dd></dl> |
| 272 | |
| 273 | <p> This function does not modify the colors of already existing |
| 274 | widgets. Use <strong>Pmw.Color.changecolor()</strong> to do this.</p> |
| 275 | |
| 276 | <p> Note that <em>root</em> must be a Tk widget or toplevel. To use the Tk |
| 277 | option database of the root window of a Pmw megawidget, use the |
| 278 | megawidget's <strong>hull</strong> component. For example:</p> |
| 279 | |
| 280 | <dl><dd><pre> root = megawidget.component('hull') |
| 281 | Pmw.Color.setscheme(root, background = 'red3')</pre></dd></dl> |
| 282 | |
| 283 | <p></p> |
| 284 | |
| 285 | |
| 286 | </dd> |
| 287 | <dt> <strong>Pmw.Color.spectrum</strong>(<em>numColors</em>, <em>correction</em> = <strong>1.0</strong>, <em>saturation</em> = <strong>1.0</strong>, <em>intensity</em> = <strong>1.0</strong>, <em>extraOrange</em> = <strong>1</strong>, <em>returnHues</em> = <strong>0</strong>)</dt><dd> |
| 288 | |
| 289 | Return a list of <em>numColors</em> different colors making up a |
| 290 | <em>spectrum</em>. If <em>extraOrange</em> is false, the colors are evenly |
| 291 | spaced by hue from one end of the spectrum (red) to the other |
| 292 | (magenta). If <em>extraOrange</em> is true, the hues are not quite |
| 293 | evenly spaced - the hues around orange are emphasised, thus |
| 294 | preventing the spectrum from appearing to have to many <em>cool</em> |
| 295 | hues. </p> |
| 296 | |
| 297 | <p> If <em>returnHues</em> is false, the return values are the names of the |
| 298 | colors represented by the hues together with <em>saturation</em> and |
| 299 | <em>intensity</em> and corrected by <em>correction</em>.</p> |
| 300 | |
| 301 | <p> If <em>returnHues</em> is true, the return values are hues.</p> |
| 302 | |
| 303 | <p></p> |
| 304 | |
| 305 | |
| 306 | </dd> |
| 307 | </dl> |
| 308 | </dd></dl> |
| 309 | |
| 310 | <center><P ALIGN="CENTER"> |
| 311 | <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5> |
| 312 | </p></center> |
| 313 | |
| 314 | |
| 315 | <font size=-1> |
| 316 | <center><P ALIGN="CENTER"> |
| 317 | Pmw 1.2 - |
| 318 | 5 Aug 2003 |
| 319 | - <a href="index.html">Home</a> |
| 320 | <br>Manual page last reviewed: 25 May 2002 |
| 321 | </p></center> |
| 322 | </font> |
| 323 | |
| 324 | </body> |
| 325 | </html> |
| 326 | |