source: trunk/SRC/Documentation/idldoc_assistant_output/Colors/getcolor.html @ 163

Last change on this file since 163 was 163, checked in by navarro, 18 years ago

header improvements : type of parameters and keywords, default values, spell checking + idldoc assistant (IDL online_help)
File size: 10.5 KB
Line 
1
2
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4  <head>
5    <title>getcolor.pro (SAXO Documentation Assistant)</title>
6  </head>
7
8  <body text="#000000" bgcolor="#FFFFFF">
9
10   
11<!-- Navbar template takes a structure with the following fields:
12       overview_href :
13       overview_selected :
14       dir_overview_href :
15       dir_overview_selected :
16       categories_href :
17       categories_selected :
18       index_href :
19       index_selected :
20       search_href :
21       search_selected :
22       file_selected :
23       source_href :
24       source_selected :
25       help_href :
26       help_selected :
27       etc_selected :
28
29       prev_file_href :
30       next_file_href :
31
32       view_single_page_href :
33       view_frames_href :
34
35       summary_fields_href :
36       summary_routine_href :
37       details_routine_href :
38
39       title :
40       subtitle :
41       user :
42-->
43
44
45<table border="0" cellpadding="0" cellspacing="0" width="98%" bgcolor="#F0F0FF" valign="bottom">
46  <tr>
47    <td width="10%">
48<a href="colorbar.html"><img src="./../prev.gif" border="0" alt="Previous"></a></td>
49    <td width="80%" align="center" valign="center">
50<font size=-1><i>SAXO Documentation Assistant</i>: <a href="./../home.html">Overview</a></font></td>
51    <td width="10%" align="right">
52<a href="lct.html"><img src="./../next.gif" border="0" alt="Next"></a></td>
53  </tr>
54</table>
55
56
57    <h1><font size="-2">Colors/</font></h1>
58    <h2>getcolor.pro</h2>
59
60    <dl>
61    </dl>
62
63     
64 The original purpose of this function was to enable the
65 user to specify one of the 16 colors supported by the
66 McIDAS color map by name. Over time, however, the function
67 has become a general purpose function for handling and
68 supporting drawing colors in a device-independent way.
69 In particular, I have been looking for ways to write color
70 handling code that will work transparently on both 8-bit and
71 24-bit machines. On 24-bit machines, the code should work the
72 same where color decomposition is turned on or off.
73
74 (The 16 supported colors in GETCOLOR come from the McIDAS color
75 table offered on the IDL newsgroup by Liam Gumley.)
76
77
78   
79
80     
81      <a name="#_getcolor"></a>
82
83      <h2>getcolor  <font size="-1" color="#006633"> Graphics, Color
84</font></h2>
85
86      <p><font face="Courier"><i>result = </i>getcolor(<i>[<a href="#_getcolor_keyword_thisColor">thisColor</a>][, <a href="#_getcolor_keyword_index">index</a>]</i>, <a href="#_getcolor_keyword_TRUE">TRUE</a>=<i>TRUE</i>, <a href="#_getcolor_keyword_NAMES">NAMES</a>=<i>NAMES</i>, <a href="#_getcolor_keyword_LOAD">LOAD</a>=<i>LOAD</i>, <a href="#_getcolor_keyword_START">START</a>=<i>START</i>)</font></p>
87
88   
89
90
91    <h3>Return value</h3>
92 If no positional parameter is present, then the return value is either a 16-by-3
93 byte array containing the RGB values of all 16 colors or it is a 16-element
94 long integer array containing color values that can be decomposed into colors.
95 The 16-by-3 array is appropriate for loading color tables with the TVLCT command:
96
97           Device, Decomposed=0
98           colors = GetColor()
99           TVLCT, colors, 100
100
101 If  function is called with just this single input parameter,
102 the return value is either a 1-by-3 array containing the RGB values of
103 that particular color, or a 24-bit integer that can be "decomposed" into
104 that particular color, depending upon the state of the TRUE keyword and
105 upon whether color decomposition is turned on or off. The state of color
106 decomposition can ONLY be determined if the program is being run in
107 IDL 5.2 or higher.
108
109 If index parameter is passed, then the return value of the function is the
110 index number and not the color triple. (If color decomposition is turned
111 on AND the user specifies an index parameter, the color is loaded in the
112 color table at the proper index, but a 24-bit value is returned to the
113 user in IDL 5.2 and higher.)
114
115
116
117   
118    <h3>Parameters</h3>
119   
120
121    <a name="#_getcolor_keyword_thisColor"></a>
122    <h4>thisColor&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
123      <font size="-1" color="#006633">in</font>
124     
125      <font size="-1" color="#006633">optional</font>
126     
127     
128     
129     
130     
131    </h4>
132
133     
134 A string with the "name" of the color. Valid names are:
135           black
136           magenta
137           cyan
138           yellow
139           green
140           red
141           blue
142           navy
143           gold
144           pink
145           aqua
146           orchid
147           gray
148           sky
149           beige
150           white
151
152 The color YELLOW is returned if the color name can't be resolved.
153 Case is unimportant.
154
155
156   
157
158    <a name="#_getcolor_keyword_index"></a>
159    <h4>index&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
160      <font size="-1" color="#006633">in</font>
161     
162      <font size="-1" color="#006633">optional</font>
163     
164     
165     
166     
167     
168    </h4>
169
170     
171 The color table index where the specified color should be loaded.
172
173   
174   
175
176   
177    <h3>Keywords</h3>
178
179   
180    <a name="#_getcolor_keyword_TRUE"></a>
181    <h4>TRUE&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
182     
183     
184     
185     
186     
187     
188     
189     
190    </h4>
191
192     
193 If this keyword is set, the specified color triple is returned
194 as a 24-bit integer equivalent. The lowest 8 bits correspond to
195 the red value; the middle 8 bits to the green value; and the
196 highest 8 bits correspond to the blue value. In IDL 5.2 and higher,
197 if color decomposition is turned on, it is as though this keyword
198 were set.
199
200   
201    <a name="#_getcolor_keyword_NAMES"></a>
202    <h4>NAMES&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
203     
204     
205     
206     
207     
208     
209     
210     
211    </h4>
212
213     
214 If this keyword is set, the return value of the function is
215 a 16-element string array containing the names of the colors.
216 These names would be appropriate, for example, in building
217 a list widget with the names of the colors. If the NAMES
218 keyword is set, the COLOR and INDEX parameters are ignored.
219
220 listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16)
221
222   
223    <a name="#_getcolor_keyword_LOAD"></a>
224    <h4>LOAD&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
225     
226     
227     
228     
229     
230     
231     
232     
233    </h4>
234
235     
236 If this keyword is set, all 16 colors are automatically loaded
237 starting at the color index specified by the START keyword.
238 Note that setting this keyword means that the return value of the
239 function will be a structure, with each field of the structure
240 corresponding to a color name. The value of each field will be
241 an index number (set by the START keyword) corresponding to the
242 associated color, or a 24-bit long integer value that creates the
243 color on a true-color device. What you have as the field values is
244 determined by the TRUE keyword or whether color decomposition is on
245 or off in the absence of the TRUE keyword. It will either be a 1-by-3
246 byte array or a long integer value.
247
248   
249    <a name="#_getcolor_keyword_START"></a>
250    <h4>START&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
251     
252     
253     
254     
255     
256     
257      <font size="-1" color="#006633">default:</font> <font size="-1" color="#006633"><i>!D.TABLE_SIZE - 17</i></font>
258     
259    </h4>
260
261   
262 The starting color index number if the LOAD keyword is set. This keyword
263 value is ignored unless the LOAD keyword is also set. The keyword is also
264 ignored if the TRUE keyword is set or if color decomposition in on in
265 IDL 5.2 and higher.
266
267   
268   
269
270    <h3>Examples</h3> 
271 To load a yellow color in color index 100 and plot in yellow, type:
272
273      IDL> yellow = GETCOLOR('yellow', 100)
274      IDL> PLOT, data, COLOR=yellow
275
276 or,
277
278      IDL> PLOT, data, COLOR=GETCOLOR('yellow', 100)
279
280 To do the same thing on a 24-bit color system with decomposed color on, type:
281
282      IDL> PLOT, data, COLOR=GETCOLOR('yellow', /TRUE)
283
284 or in IDL 5.2 and higher,
285
286      IDL> DEVICE, Decomposed=1
287      IDL> PLOT, data, COLOR=GETCOLOR('yellow')
288
289 To load all 16 colors into the current color table, starting at
290 color index 200, type:
291
292      IDL> TVLCT, GETCOLOR(), 200
293
294 To add the color names to a list widget:
295
296      IDL> listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16)
297
298 To load all 16 colors and have the color indices returned in a structure:
299
300      IDL> DEVICE, Decomposed=0
301      IDL> colors = GetColor(/Load, Start=1)
302      IDL> HELP, colors, /Structure
303      PLOT, data, COLOR=colors.yellow
304
305 To get the direct color values as 24-bit integers in color structure fields:
306
307      IDL> DEVICE, Decomposed=1
308      IDL> colors = GetColor(/Load)
309      IDL> PLOT, data, COLOR=colors.yellow
310
311 Note that the START keyword value is ignored if on a 24-bit device,
312 so it is possible to write completely device-independent code by
313 writing code like this:
314
315      IDL> colors = GetColor(/Load)
316      IDL> PLOT, data, Color=colors.yellow;           IDL> DEVICE, Decomposed=0
317      IDL> colors = GetColor(/Load, Start=1)
318      IDL> HELP, colors, /Structure
319      PLOT, data, COLOR=colors.yellow
320
321 To get the direct color values as 24-bit integers in color structure fields:
322
323      IDL> DEVICE, Decomposed=1
324      IDL> colors = GetColor(/Load)
325      IDL> PLOT, data, COLOR=colors.yellow
326
327 Note that the START keyword value is ignored if on a 24-bit device,
328 so it is possible to write completely device-independent code by
329 writing code like this:
330
331      IDL> colors = GetColor(/Load)
332      IDL> PLOT, data, Color=colors.yellow
333
334    <h3>Version history</h3>
335   
336    <h4>Version</h4> $Id: getcolor.pro 137 2006-07-12 09:33:44Z smasson $
337    <h4>History</h4> 
338 Written by: David Fanning, 10 February 96.
339 Fixed a bug in which N_ELEMENTS was spelled wrong. 7 Dec 96. DWF
340 Added the McIDAS colors to the program. 24 Feb 99. DWF
341 Added the INDEX parameter to the program 8 Mar 99. DWF
342 Added the NAMES keyword at insistence of Martin Schultz. 10 Mar 99. DWF
343 Reordered the colors so black is first and white is last. 7 June 99. DWF
344 Added automatic recognition of DECOMPOSED=1 state. 7 June 99. DWF
345 Added LOAD AND START keywords. 7 June 99. DWF.
346
347   
348
349    <h3>Known issues</h3>
350   
351   
352   
353    <h4>Restrictions</h4> 
354 The TRUE keyword causes the START keyword to be ignored.
355 The NAMES keyword causes the COLOR, INDEX, START, and TRUE parameters to be
356 ignored.
357 The COLOR parameter is ignored if the LOAD keyword is used.
358 On systems where it is possible to tell the state of color decomposition
359 (i.e., IDL 5.2 and higher), a 24-bit value (or values) is automatically
360 returned if color decomposition is ON.
361
362
363   
364   
365   
366   
367   
368   
369   
370
371    <font size="-3"><p>&nbsp;</p></font>
372    <hr size="1" color="#CCCCCC"/>
373     
374
375   
376
377    <p><font color="gray" size="-3">&nbsp;&nbsp;Produced by IDLdoc 2.0 on Tue Aug 29 14:49:07 2006.</font></p>
378
379  </body>
380</html>
Note: See TracBrowser for help on using the repository browser.