projects / OpenSPARC-T2-DV / blame
| Commit | Line | Data |
|---|---|---|
| 86530b38 AT |
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 |