StripChart.xml revision 421c997b 
1<sect1 id="StripChart_Widget">
2<title>StripChart Widget</title>
3<!-- .XS -->
4<!-- 	StripChart Widget -->
5<!-- .XE -->
6<!-- .IN "StripChart widget" "" "@DEF@" -->
7<literallayout class="monospaced">
8<!-- .TA 2.0i -->
9<!-- .ta 2.0i -->
10<!-- .sp -->
11Application Header file	&lt;Xaw/StripChart.h&gt;
12<!-- .IN "StripChart.h" "" -->
13Class Header file	&lt;Xaw/StripCharP.h&gt;
14<!-- .IN "StripCharP.h" "" -->
15Class		stripChartWidgetClass
16<!-- .IN "stripChartWidgetClass" "" -->
17Class Name	StripChart
18<!-- .IN "StripChart widget" "class name" -->
19Superclass	Simple
20<!-- .sp -->
21</literallayout>
22<para>
23<!-- .LP -->
24The StripChart widget is used to provide a roughly real
25time graphical chart of a single value.  For example,
26it is used by the common client program <function>xload</function>
27to provide a graph of processor load.  The StripChart
28reads data from an application, and updates the chart
29at the <function>update</function> interval specified.
30</para>
31<sect2 id='StripChart::Resources'>
32<title>Resources</title>
33<para>
34<!-- .LP -->
35When creating a StripChart widget instance, the following resources are
36retrieved from the argument list or from the resource database:
37</para>
38<para>
39<!-- .LP -->
40<!-- .IN "StripChart widget" "resources" -->
41<informaltable>
42  <tgroup cols='5' align='center'>
43  <colspec colname='c1'/>
44  <colspec colname='c2'/>
45  <colspec colname='c3'/>
46  <colspec colname='c4'/>
47  <colspec colname='c5'/>
48  <thead>
49    <row>
50      <entry>Name</entry>
51      <entry>Class</entry>
52      <entry>Type</entry>
53      <entry>Notes</entry>
54      <entry>Default Value</entry>
55    </row>
56  </thead>
57  <tbody>
58    <row>
59      <entry>accelerators</entry>
60      <entry>Accelerators</entry>
61      <entry>AcceleratorTable</entry>
62      <entry></entry>
63      <entry>NULL</entry>
64    </row>
65    <row>
66      <entry>ancestorSensitive</entry>
67      <entry>AncestorSensitive</entry>
68      <entry>Boolean</entry>
69      <entry>D</entry>
70      <entry>True</entry>
71    </row>
72    <row>
73      <entry>background</entry>
74      <entry>Background</entry>
75      <entry>Pixel</entry>
76      <entry></entry>
77      <entry>XtDefaultBackground</entry>
78    </row>
79    <row>
80      <entry>backgroundPixmap</entry>
81      <entry>Pixmap</entry>
82      <entry>Pixmap</entry>
83      <entry></entry>
84      <entry>XtUnspecifiedPixmap</entry>
85    </row>
86    <row>
87      <entry>borderColor</entry>
88      <entry>BorderColor</entry>
89      <entry>Pixel</entry>
90      <entry></entry>
91      <entry>XtDefaultForeground</entry>
92    </row>
93    <row>
94      <entry>borderPixmap</entry>
95      <entry>Pixmap</entry>
96      <entry>Pixmap</entry>
97      <entry></entry>
98      <entry>XtUnspecifiedPixmap</entry>
99    </row>
100    <row>
101      <entry>borderWidth</entry>
102      <entry>BorderWidth</entry>
103      <entry>Dimension</entry>
104      <entry></entry>
105      <entry>1</entry>
106    </row>
107    <row>
108      <entry>colormap</entry>
109      <entry>Colormap</entry>
110      <entry>Colormap</entry>
111      <entry></entry>
112      <entry>Parent's Colormap</entry>
113    </row>
114    <row>
115      <entry>cursor</entry>
116      <entry>Cursor</entry>
117      <entry>Cursor</entry>
118      <entry></entry>
119      <entry>None</entry>
120    </row>
121    <row>
122      <entry>cursorName</entry>
123      <entry>Cursor</entry>
124      <entry>String</entry>
125      <entry></entry>
126      <entry>NULL</entry>
127    </row>
128    <row>
129      <entry>depth</entry>
130      <entry>Depth</entry>
131      <entry>int</entry>
132      <entry>C</entry>
133      <entry>Parent's Depth</entry>
134    </row>
135    <row>
136      <entry>destroyCallback</entry>
137      <entry>Callback</entry>
138      <entry>XtCallbackList</entry>
139      <entry></entry>
140      <entry>NULL</entry>
141    </row>
142    <row>
143      <entry>foreground</entry>
144      <entry>Foreground</entry>
145      <entry>Pixel</entry>
146      <entry></entry>
147      <entry>XtDefaultForeground</entry>
148    </row>
149    <row>
150      <entry>getValue</entry>
151      <entry>Callback</entry>
152      <entry>XtCallbackList</entry>
153      <entry></entry>
154      <entry>NULL</entry>
155    </row>
156    <row>
157      <entry>height</entry>
158      <entry>Height</entry>
159      <entry>Dimension</entry>
160      <entry></entry>
161      <entry>120</entry>
162    </row>
163    <row>
164      <entry>highlight</entry>
165      <entry>Foreground</entry>
166      <entry>Pixel</entry>
167      <entry></entry>
168      <entry>XtDefaultForeground</entry>
169    </row>
170    <row>
171      <entry>insensitiveBorder</entry>
172      <entry>Insensitive</entry>
173      <entry>Pixmap</entry>
174      <entry></entry>
175      <entry>GreyPixmap</entry>
176    </row>
177    <row>
178      <entry>international</entry>
179      <entry>International</entry>
180      <entry>Boolean</entry>
181      <entry>C</entry>
182      <entry>False</entry>
183    </row>
184    <row>
185      <entry>jumpScroll</entry>
186      <entry>JumpScroll</entry>
187      <entry>int</entry>
188      <entry>A</entry>
189      <entry>half the width of the widget</entry>
190    </row>
191    <row>
192      <entry>mappedWhenManaged</entry>
193      <entry>MappedWhenManaged</entry>
194      <entry>Boolean</entry>
195      <entry></entry>
196      <entry>True</entry>
197    </row>
198    <row>
199      <entry>minScale</entry>
200      <entry>Scale</entry>
201      <entry>int</entry>
202      <entry></entry>
203      <entry>1</entry>
204    </row>
205    <row>
206      <entry>pointerColor</entry>
207      <entry>Foreground</entry>
208      <entry>Pixel</entry>
209      <entry></entry>
210      <entry>XtDefaultForeground</entry>
211    </row>
212    <row>
213      <entry>pointerColorBackground</entry>
214      <entry>Background</entry>
215      <entry>Pixel</entry>
216      <entry></entry>
217      <entry>XtDefaultBackground</entry>
218    </row>
219    <row>
220      <entry>screen</entry>
221      <entry>Screen</entry>
222      <entry>Pointer</entry>
223      <entry>R</entry>
224      <entry>Parent's Screen</entry>
225    </row>
226    <row>
227      <entry>sensitive</entry>
228      <entry>Sensitive</entry>
229      <entry>Boolean</entry>
230      <entry></entry>
231      <entry>True</entry>
232    </row>
233    <row>
234      <entry>translations</entry>
235      <entry>Translations</entry>
236      <entry>TranslationTable</entry>
237      <entry></entry>
238      <entry>NULL</entry>
239    </row>
240    <row>
241      <entry>update</entry>
242      <entry>Interval</entry>
243      <entry>int</entry>
244      <entry></entry>
245      <entry>10</entry>
246    </row>
247    <row>
248      <entry>width</entry>
249      <entry>Width</entry>
250      <entry>Dimension</entry>
251      <entry></entry>
252      <entry>120</entry>
253    </row>
254    <row>
255      <entry>x</entry>
256      <entry>Position</entry>
257      <entry>Position</entry>
258      <entry></entry>
259      <entry>0</entry>
260    </row>
261    <row>
262      <entry>y</entry>
263      <entry>Position</entry>
264      <entry>Position</entry>
265      <entry></entry>
266      <entry>0</entry>
267    </row>
268  </tbody>
269  </tgroup>
270</informaltable>
271<!-- .Ac -->
272<!-- .As -->
273<!-- .Bg -->
274<!-- .Gp -->
275<!-- .Bc -->
276<!-- .Bp -->
277<!-- .Bw -->
278<!-- .Cm -->
279<!-- .Cu -->
280<!-- .Cn -->
281<!-- .Dp -->
282<!-- .Dc -->
283<variablelist>
284  <varlistentry>
285    <term>
286      <function>foreground</function>
287    </term>
288    <listitem>
289      <para>
290A pixel value which indexes the widget's colormap to derive the color
291that will be used to draw the graph.
292      </para>
293    </listitem>
294  </varlistentry>
295  <varlistentry>
296    <term>
297      <function>getValue</function>
298    </term>
299    <listitem>
300      <para>
301A list of callback functions to call every <function>update</function> seconds.
302This list should contain one function, which returns the
303value to be graphed by the StripChart widget.  The following
304section describes the procedural interface.  Behavior when this list has
305more than one function is undefined.
306<!-- .Hw -->
307      </para>
308    </listitem>
309  </varlistentry>
310  <varlistentry>
311    <term>
312      <function>highlight</function>
313    </term>
314    <listitem>
315      <para>
316A pixel value which indexes the widget's colormap to derive the color
317that will be used to draw the scale lines on the graph.
318<!-- .Ib -->
319<!-- .Ix -->
320      </para>
321    </listitem>
322  </varlistentry>
323  <varlistentry>
324    <term>
325      <function>jumpScroll</function>
326    </term>
327    <listitem>
328      <para>
329When the graph reaches the right edge of the window it must be
330scrolled to the left.  This resource specifies the number of pixels
331it will jump.  Smooth scrolling can be achieved by setting this resource
332to 1.
333<!-- .Mm -->
334      </para>
335    </listitem>
336  </varlistentry>
337  <varlistentry>
338    <term>
339      <function>minScale</function>
340    </term>
341    <listitem>
342      <para>
343The minimum scale for the graph.  The number of divisions on the graph
344will always be greater than or equal to this value.
345<!-- .Pf -->
346<!-- .Pb -->
347<!-- .Sc -->
348<!-- .Se -->
349<!-- .Tr -->
350      </para>
351    </listitem>
352  </varlistentry>
353  <varlistentry>
354    <term>
355      <function>update</function>
356    </term>
357    <listitem>
358      <para>
359The number of seconds between graph updates.  Each update is
360represented on the graph as a 1 pixel wide line.  Every <function>update</function> seconds
361the <function>getValue</function> procedure will be used to get a new graph point,
362and this point will be added to the right end of the StripChart.
363<!-- .Xy -->
364    </para>
365  </listitem>
366  </varlistentry>
367</variablelist>
368</para>
369</sect2>
370<sect2 id="Getting_the_StripChart_Value">
371<title>Getting the StripChart Value</title>
372<!-- .IN "StripChart widget" "getting the value" -->
373<para>
374<!-- .LP -->
375The StripChart widget will call the application routine passed to it
376as the <function>getValue</function> callback function every <function>update</function> seconds to
377obtain another point for the StripChart graph.
378</para>
379<para>
380<!-- .LP -->
381The calling interface for the <function>getValue</function> callback is:
382<!-- .IN "StripChart widget" "getValue callback" "@DEF@" -->
383<funcsynopsis>
384<funcprototype>
385  <funcdef><function> void</function>(*getValueProc)</funcdef>
386  <paramdef>Widget<parameter> w</parameter></paramdef>
387  <paramdef>XtPointer<parameter> client_data</parameter></paramdef>
388  <paramdef>XtPointer<parameter> value</parameter></paramdef>
389</funcprototype>
390</funcsynopsis>
391<!-- .FN -->
392<variablelist>
393  <varlistentry>
394    <term>
395      <emphasis remap='I'>w</emphasis>
396    </term>
397    <listitem>
398      <para>
399Specifies the StripChart widget.
400      </para>
401    </listitem>
402  </varlistentry>
403  <varlistentry>
404    <term>
405      <emphasis remap='I'>client_data</emphasis>
406    </term>
407    <listitem>
408      <para>
409Specifies the client data.
410      </para>
411    </listitem>
412  </varlistentry>
413  <varlistentry>
414    <term>
415      <emphasis remap='I'>value</emphasis>
416    </term>
417    <listitem>
418      <para>
419Returns a pointer to a double.  The application should set the address
420pointed to by this argument to a double containing the value to be
421graphed on the StripChart.
422    </para>
423  </listitem>
424  </varlistentry>
425</variablelist>
426</para>
427<para>
428<!-- .LP -->
429This function is used by the StripChart to call an application routine.
430The routine will pass the value to be graphed back to the the StripChart
431in the <function>value</function> field of this routine.
432
433</para>
434</sect2>
435</sect1>
436