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

Last change on this file since 402 was 402, checked in by smasson, 15 years ago

update documentation
File size: 10.4 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">
84 Graphics, Color
85</font></h2>
86
87      <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>
88
89   
90
91
92    <h3>Return value</h3>
93 If no positional parameter is present, then the return value is either a 16-by-3
94 byte array containing the RGB values of all 16 colors or it is a 16-element
95 long integer array containing color values that can be decomposed into colors.
96 The 16-by-3 array is appropriate for loading color tables with the TVLCT command:
97
98           Device, Decomposed=0
99           colors = GetColor()
100           TVLCT, colors, 100
101
102 If  function is called with just this single input parameter,
103 the return value is either a 1-by-3 array containing the RGB values of
104 that particular color, or a 24-bit integer that can be "decomposed" into
105 that particular color, depending upon the state of the TRUE keyword and
106 upon whether color decomposition is turned on or off. The state of color
107 decomposition can ONLY be determined if the program is being run in
108 IDL 5.2 or higher.
109
110 If index parameter is passed, then the return value of the function is the
111 index number and not the color triple. (If color decomposition is turned
112 on AND the user specifies an index parameter, the color is loaded in the
113 color table at the proper index, but a 24-bit value is returned to the
114 user in IDL 5.2 and higher.)
115
116
117
118   
119    <h3>Parameters</h3>
120   
121
122    <a name="#_getcolor_keyword_thiscolor"></a>
123    <h4>thiscolor&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
124      <font size="-1" color="#006633">in</font>
125     
126      <font size="-1" color="#006633">optional</font>
127     
128     
129     
130     
131     
132    </h4>
133
134   
135 A string with the "name" of the color. Valid names are:
136           black
137           magenta
138           cyan
139           yellow
140           green
141           red
142           blue
143           navy
144           gold
145           pink
146           aqua
147           orchid
148           gray
149           sky
150           beige
151           white
152
153 The color YELLOW is returned if the color name can't be resolved.
154 Case is unimportant.
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><pre>
271
272 To load a yellow color in color index 100 and plot in yellow, type:
273
274   IDL> yellow = GETCOLOR('yellow', 100)
275   IDL> PLOT, data, COLOR=yellow
276
277 or,
278
279   IDL> PLOT, data, COLOR=GETCOLOR('yellow', 100)
280
281 To do the same thing on a 24-bit color system with decomposed color on, type:
282
283   IDL> PLOT, data, COLOR=GETCOLOR('yellow', /TRUE)
284
285 or in IDL 5.2 and higher,
286
287   IDL> DEVICE, Decomposed=1
288   IDL> PLOT, data, COLOR=GETCOLOR('yellow')
289
290 To load all 16 colors into the current color table, starting at
291 color index 200, type:
292
293   IDL> TVLCT, GETCOLOR(), 200
294
295 To add the color names to a list widget:
296
297   IDL> listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16)
298
299 To load all 16 colors and have the color indices returned in a structure:
300
301   IDL> DEVICE, Decomposed=0
302   IDL> colors = GetColor(/Load, Start=1)
303   IDL> HELP, colors, /Structure
304   IDL> PLOT, data, COLOR=colors.yellow
305
306 To get the direct color values as 24-bit integers in color structure fields:
307
308   IDL> DEVICE, Decomposed=1
309   IDL> colors = GetColor(/Load)
310   IDL> PLOT, data, COLOR=colors.yellow
311
312 Note that the START keyword value is ignored if on a 24-bit device,
313 so it is possible to write completely device-independent code by
314 writing code like this:
315
316   IDL> colors = GetColor(/Load)
317   IDL> PLOT, data, Color=colors.yellow;           IDL> DEVICE, Decomposed=0
318   IDL> colors = GetColor(/Load, Start=1)
319   IDL> HELP, colors, /Structure
320   IDL> PLOT, data, COLOR=colors.yellow
321
322 To get the direct color values as 24-bit integers in color structure fields:
323
324   IDL> DEVICE, Decomposed=1
325   IDL> colors = GetColor(/Load)
326   IDL> PLOT, data, COLOR=colors.yellow
327
328 Note that the START keyword value is ignored if on a 24-bit device,
329 so it is possible to write completely device-independent code by
330 writing code like this:
331
332   IDL> colors = GetColor(/Load)
333   IDL> PLOT, data, Color=colors.yellow
334
335    </pre><h3>Version history</h3>
336   
337    <h4>Version</h4>
338 $Id: getcolor.pro 371 2008-08-07 09:32:02Z pinsard $
339
340    <h4>History</h4>
341 Written by: David Fanning, 10 February 96.
342 Fixed a bug in which N_ELEMENTS was spelled wrong. 7 Dec 96. DWF
343 Added the McIDAS colors to the program. 24 Feb 99. DWF
344 Added the INDEX parameter to the program 8 Mar 99. DWF
345 Added the NAMES keyword at insistence of Martin Schultz. 10 Mar 99. DWF
346 Reordered the colors so black is first and white is last. 7 June 99. DWF
347 Added automatic recognition of DECOMPOSED=1 state. 7 June 99. DWF
348 Added LOAD AND START keywords. 7 June 99. DWF.
349
350   
351
352    <h3>Known issues</h3>
353   
354   
355   
356    <h4>Restrictions</h4>
357 The TRUE keyword causes the START keyword to be ignored.
358 The NAMES keyword causes the COLOR, INDEX, START, and TRUE parameters to be
359 ignored.
360 The COLOR parameter is ignored if the LOAD keyword is used.
361 On systems where it is possible to tell the state of color decomposition
362 (i.e., IDL 5.2 and higher), a 24-bit value (or values) is automatically
363 returned if color decomposition is ON.
364
365
366   
367   
368   
369   
370   
371   
372   
373
374    <font size="-3"><p>&nbsp;</p></font>
375    <hr size="1" color="#CCCCCC"/>
376     
377
378   
379
380    <p><font color="gray" size="-3">&nbsp;&nbsp;Produced by IDLdoc 2.0.</font></p>
381
382  </body>
383</html>
Note: See TracBrowser for help on using the repository browser.