source: trunk/examples/objects/api/c/number @ 1586

Last change on this file since 1586 was 1586, checked in by dkearney, 11 years ago

updating potential apis for c cpp and python. adding random() and diff()
functions to the rappture objects. objects should be able to generate a random
value for itself based on how it was configured. objects should be able to
compare itself with another object and tell us what the differences are.

File size: 20.8 KB
Line 
1Number
2
3    Rp_NumberInit(Rp_Number *num)
4    Rp_NumberInit2(Rp_Number *num, const char *name, const char *units,
5                   double val);
6    Rp_NumberInit3(Rp_Number *num, const char *name, const char *units,
7                   double val, double min, double max, const char *label,
8                   const char *desc);
9    Rp_NumberCopy(const Rp_Number* o);
10    Rp_NumberDestroy(Rp_Number *num);
11
12    const char *Rp_NumberGetName(Rp_Number *num) const;
13    void Rp_NumberSetName(Rp_Number *num, const char *val);
14
15    const char *Rp_NumberGetPath(Rp_Number *num) const;
16    void Rp_NumberSetPath(Rp_Number *num, const char *val);
17
18    const char *Rp_NumberGetLabel(Rp_Number *num) const;
19    void Rp_NumberSetLabel(Rp_Number *num, const char *val);
20
21    const char *Rp_NumberGetDesc(Rp_Number *num) const;
22    void Rp_NumberSetDesc(Rp_Number *num, const char *val);
23
24    const char *Rp_NumberGetHints(Rp_Number *num) const;
25    void Rp_NumberSetHints(Rp_Number *num, const char *val);
26
27    const char *Rp_NumberGetColor(Rp_Number *num) const;
28    void Rp_NumberSetColor(Rp_Number *num, const char *val);
29
30    double Rp_NumberGetDefault(Rp_Number *num) const;
31    void Rp_NumberSetDefault(Rp_Number *num, double val);
32
33    double Rp_NumberGetCurrent(Rp_Number *num) const;
34    void Rp_NumberSetCurrent(Rp_Number *num, double val);
35
36    double Rp_NumberGetMin(Rp_Number *num) const;
37    void Rp_NumberSetMin(Rp_Number *num, double val);
38
39    double Rp_NumberGetMax(Rp_Number *num) const;
40    void Rp_NumberSetMax(Rp_Number *num, double val);
41
42    const char *Rp_NumberGetUnits(Rp_Number *num) const;
43    void Rp_NumberSetUnits(Rp_Number *num, const char *u);
44
45    int Rp_NumberDefaultSet(Rp_Number *num) const;
46    int Rp_NumberCurrentSet(Rp_Number *num) const;
47
48    const void *Rp_NumberGetProperty (Rp_Number *num, const char *key) const;
49    void Rp_NumberSetProperty (Rp_Number *num, const char *key,
50                               const void *val, size_t nbytes);
51
52    const char *Rp_NumberPropStr (Rp_Number *num, const char *key) const;
53    void Rp_NumberPropStr (Rp_Number *num, const char *key, const char *val);
54
55    void Rp_NumberPropRemove (Rp_Number *num, const char *key);
56
57    Outcome& Rp_NumberConvert(Rp_Number *num, const char *to);
58    double Rp_NumberValue(Rp_Number *num, const char *units) const;
59    void Rp_NumberVValue(Rp_Number *num, void *storage, size_t numHints,
60                         va_list arg) const;
61    void Rp_NumberRandom();
62    Rp_Chain *Rp_NumberDiff(const Rp_Object *o);
63
64    void Rp_NumberAddPreset(Rp_Number *num, const char *label,
65                            const char *desc, double val,
66                            const char *units);
67
68    void Rp_NumberAddPreset2(Rp_Number *num, const char *label,
69                             const char *desc, const char *val);
70
71    void Rp_NumberDelPreset(Rp_Number *num, const char *label);
72
73    void Rp_NumberConfigure(Rp_Number *num, size_t as, ClientData c);
74    void Rp_NumberDump(Rp_Number *num, size_t as, ClientData c);
75
76    Outcome *Rp_NumberOutcome(Rp_Number *num) const;
77
78    const int Rp_NumberIs(Rp_Number *num) const;
79
80    void Rp_NumberMinFromStr(Rp_Number *num, const char *val);
81    void Rp_NumberMaxFromStr(Rp_Number *num, const char *val);
82    void Rp_NumberDefaultFromStr(Rp_Number *num, const char *val);
83    void Rp_NumberCurrentFromStr(Rp_Number *num, const char *val);
84
85---------------------------------------
86
87const char *Rp_NumberGetName(Rp_Number *num)
88    Purpose: get the id name of the object
89    Input Arguments: 1
90        1. Rp_Number *num - pointer to Number object
91    Return Value: the id name stored in the object.
92    Notes: if no name is set, NULL will be returned
93            the id name is used to identify this object from
94            all other objects and should be unique
95    Code Example:
96
97void Rp_NumberSetName(Rp_Number *num, const char *val)
98    Purpose: set the id name of the object
99    Input Arguments: 2
100        1. Rp_Number *num - pointer to Number object
101        2. const char *val - new id name
102    Return Value: None
103    Notes: a copy of the memory location val will be stored
104    Code Example:
105
106const char *Rp_NumberGetpath(Rp_Number *num)
107    Purpose: get the path of the object
108    Input Arguments: 1
109        1. Rp_Number *num - pointer to Number object
110    Return Value: the path stored in the object.
111    Notes: if no path is set, NULL will be returned
112            the path tells where this object sits in the
113            hierarchy of objects.
114    Code Example:
115
116void Rp_NumberSetPath(Rp_Number *num, const char *val)
117    Purpose: set the path of the object
118    Input Arguments: 2
119        1. Rp_Number *num - pointer to Number object
120        2. const char *val - new path
121    Return Value: None
122    Notes: a copy of the memory location val will be stored
123    Code Example:
124
125const char *Rp_NumberGetLabel(Rp_Number *num)
126    Purpose: get the label of the object
127    Input Arguments: 1
128        1. Rp_Number *num - pointer to Number object
129    Return Value: the label stored in the object.
130    Notes: if no label is set, NULL will be returned
131            the label is used by the graphical user interface.
132    Code Example:
133
134void Rp_NumberSetLabel(Rp_Number *num, const char *val)
135    Purpose: set the label of the object
136    Input Arguments: 2
137        1. Rp_Number *num - pointer to Number object
138        2. const char *val - new label
139    Return Value: None
140    Notes: a copy of the memory location val will be stored
141    Code Example:
142
143const char *Rp_NumberGetDesc(Rp_Number *num)
144    Purpose: get the description of the object
145    Input Arguments: 1
146        1. Rp_Number *num - pointer to Number object
147    Return Value: the description stored in the object.
148    Notes: if no description is set, NULL will be returned
149            the description is used by the graphical user
150            interface to describe what type of data is being
151            requested and how the input is used.
152    Code Example:
153
154void Rp_NumberSetDesc(Rp_Number *num, const char *val)
155    Purpose: set the description of the object
156    Input Arguments: 2
157        1. Rp_Number *num - pointer to Number object
158        2. const char *val - new description
159    Return Value: None
160    Notes: a copy of the memory location val will be stored
161    Code Example:
162
163const char *Rp_NumberGetHints(Rp_Number *num)
164    Purpose: get the hints of the object
165    Input Arguments: 1
166        1. Rp_Number *num - pointer to Number object
167    Return Value: the hints stored in the object.
168    Notes: if no hints are set, NULL will be returned
169            the hints are used by the graphical user interface
170    Code Example:
171
172void Rp_NumberSetHints(Rp_Number *num, const char *val)
173    Purpose: set the hints of the object
174    Input Arguments: 2
175        1. Rp_Number *num - pointer to Number object
176        2. const char *val - new hints
177    Return Value: None
178    Notes: a copy of the memory location val will be stored
179    Code Example:
180
181double Rp_NumberGetDefault(Rp_Number *num)
182    Purpose: get the default value
183    Input Arguments: 1
184        1. Rp_Number *num - pointer to Number object
185    Return Value: the default value stored in the object.
186    Notes: use the function defset() to see if a valid
187            default value was stored in the object.
188    Code Example:
189
190void Rp_NumberSetDefault(Rp_Number *num, double val)
191    Purpose: set the default value
192    Input Arguments: 2
193        1. Rp_Number *num - pointer to Number object
194        2. double val - new default value
195    Return Value: None
196    Notes: None
197    Code Example:
198
199double Rp_NumberGetCurrent(Rp_Number *num)
200    Purpose: get the current value
201    Input Arguments: 1
202        1. Rp_Number *num - pointer to Number object
203    Return Value: the current value stored in the object.
204    Notes: use the function curset() to see if a valid
205            default value was stored in the object.
206    Code Example:
207
208void Rp_NumerSetCurrent(Rp_Number *num, double val)
209    Purpose: set the current value
210    Input Arguments: 2
211        1. Rp_Number *num - pointer to Number object
212        2. double val - new current value
213    Return Value: None
214    Notes: None
215    Code Example:
216
217double Rp_NumberGetMin(Rp_Number *num)
218    Purpose: get the minimum accepted value of this object
219    Input Arguments: 1
220        1. Rp_Number *num - pointer to Number object
221    Return Value: the minimum value this object will accept.
222    Notes: use the function minset() to see if a valid
223            minimum value was stored in the object.
224    Code Example:
225
226void Rp_NumberSetMin(Rp_Number *num, double val)
227    Purpose: set the minimum accepted value of this object
228    Input Arguments: 2
229        1. Rp_Number *num - pointer to Number object
230        2. double val - new minimum accepted value
231    Return Value: None
232    Notes: None
233    Code Example:
234
235double Rp_NumberGetMax(Rp_Number *num)
236    Purpose: get the maximum accepted value of this object
237    Input Arguments: 1
238        1. Rp_Number *num - pointer to Number object
239    Return Value: the maximum value this object will accept.
240    Notes: use the function maxset() to see if a valid
241            maximum value was stored in the object.
242    Code Example:
243
244void Rp_NumberSetMax(Rp_Number *num, double val)
245    Purpose: set the maximum accepted value of this object
246    Input Arguments: 2
247        1. Rp_Number *num - pointer to Number object
248        2. double val - new maximum accepted value
249    Return Value: None
250    Notes: None
251    Code Example:
252
253const char* Rp_NumberGetUnits(Rp_Number *num)
254    Purpose: get the units of this object
255    Input Arguments: 1
256        1. Rp_Number *num - pointer to Number object
257    Return Value: the string representing the object's units
258    Notes: None
259    Code Example:
260
261void Rp_NumberSetUnits(Rp_Number *num, const char *val)
262    Purpose: set the units of this object
263    Input Arguments: 2
264        1. Rp_Number *num - pointer to Number object
265        2. const char *val - new units
266    Return Value: None
267    Notes: None
268    Code Example:
269
270int Rp_NumberDefaultSet(Rp_Number *num) const
271    Purpose: return whether the default value was set by the user
272    Input Arguments: 1
273        1. Rp_Number *num - pointer to Number object
274    Return Value: 1 if default was set by user, otherwise 0
275    Notes: None
276    Code Example:
277
278int Rp_NumberCurrentSet(Rp_Number *Num) const
279    Purpose: return whether the current value was set by the user
280    Input Arguments: 1
281        1. Rp_Number *num - pointer to Number object
282    Return Value: 1 if current was set by user, otherwise 0
283    Notes: None
284    Code Example:
285
286const void *Rp_NumberGetProperty (Rp_Number *num, const char *key) const;
287    Purpose: get a generic property from the property database
288    Input Arguments: 2
289        1. Rp_Number *num - pointer to Number object
290        2. const char *key - property name
291    Return Value: value of the property
292    Notes: None
293    Code Example:
294
295void Rp_NumberSetProperty (Rp_Number *num, const char *key,
296                           const void *val, size_t nbytes);
297    Purpose: set a generic property in the property database
298    Input Arguments: 4
299        1. Rp_Number *num - pointer to Number object
300        2. const char *key - property name
301        3. const void *val - property value
302        4. size_t nbytes - size (in bytes) of the value
303    Return Value: None
304    Notes: A copy of the memory pointed to by val is stored
305            in the property database
306    Code Example:
307
308const char *Rp_NumberGetPropStr (Rp_Number *num, const char *key) const;
309    Purpose: get a string property from the property database
310    Input Arguments: 2
311        1. Rp_Number *num - pointer to Number object
312        2. const char *key - property name
313    Return Value: value of the property
314    Notes: None
315    Code Example:
316
317void Rp_NumberSetPropStr (Rp_Number *num, const char *key, const char *val);
318    Purpose: set a string property in the property database
319    Input Arguments: 3
320        1. Rp_Number *num - pointer to Number object
321        2. const char *key - property name
322        3. const char *val - property value
323    Return Value: None
324    Notes: A copy of the memory pointed to by val is stored
325            in the property database
326    Code Example:
327
328void Rp_NumberPropRemove (Rp_Number *num, const char *key);
329    Purpose: remove a property from the property database
330    Input Arguments: 2
331        1. Rp_Number *num - pointer to Number object
332        2. const char *key - property name
333    Return Value: value of the property
334    Notes: None
335    Code Example:
336
337Outcome *Rp_NumberConvert(Rp_Number *num, const char *to);
338    Purpose: convert the def and cur values to "to" units
339    Input Arguments: 2
340        1. Rp_Number *num - pointer to Number object
341        2. const char *to - string of units to convert to
342    Return Value: Outcome object
343    Notes: the values stored in the object are changed
344    Code Example:
345
346double Rp_NumberValue(Rp_Number *num, const char *to) const;
347    Purpose: return the value of the object with units of "to"
348    Input Arguments: 2
349        1. Rp_Number *num - pointer to Number object
350        2. const char *to - string of units to convert to
351    Return Value: value of the object
352    Notes: cur() is used as the base value. if cur was not set
353            by the user (curset() == 0), def() is used.
354            if def was not set (defset() == 0), 0.0 is used
355            as the value.
356    Code Example:
357
358void Rp_NumberVValue(Rp_Number *num, void *storage, size_t numHints,
359                     va_list arg) const;
360    Purpose: return the value of the object after applying a
361                varying number of hints about how the value
362                should be configured
363    Input Arguments: 4
364        1. Rp_Number *num - pointer to Number object
365        2. void *storage - the return value
366        3. size_t numHints - number of hints provided
367        4. va_list arg - list of hints specified as a va_list
368    Return Value: None
369    Notes: vvalue will parse out the recognisable hints from
370                va_list arg. Values stored in the object are
371                not changed.
372    Code Example:
373
374void Rp_NumberRandom();
375    Purpose: populate the object with a random value
376    Input Arguments: 0
377    Return Value: None
378    Notes: the current value of this object will be populated
379           with a random value that fits within the min and
380           max if they were specified.
381    Code Example:
382
383Rp_Chain *Rp_NumberDiff(const Rp_Object *o);
384    Purpose: return a linked list showing the differences between
385             this object and Rp_Object *o
386    Input Arguments: 1
387        1. const Rp_Object *o - object to diff against
388    Return Value: list of differences between objects
389    Notes: None
390    Code Example:
391
392void Rp_NumberAddPreset(Rp_Number *num, const char *label, const char *desc,
393                        double val, const char *units);
394    Purpose: add a preset to this object
395    Input Arguments: 5
396        1. Rp_Number *num - pointer to Number object
397        2. const char *label - label of the preset
398        3. const char *desc - description of the preset
399        4. double val - value of the preset
400        5. const char *units - units of the preset
401    Return Value: None
402    Notes: presets are stored in the object in the same order
403                in which they are created
404    Code Example:
405
406void Rp_NumberAddPreset2(Rp_Number *num, const char *label, const char *desc,
407                         const char *val);
408    Purpose: add a preset to this object
409    Input Arguments: 4
410        1. Rp_Number *num - pointer to Number object
411        2. const char *label - label of the preset
412        3. const char *desc - description of the preset
413        4. const char *val - numeric value and units of the preset
414    Return Value: None
415    Notes: presets are stored in the object in the same order
416                in which they are created
417    Code Example:
418
419void Rp_NumberDelPreset(Rp_Number *num, const char *label);
420    Purpose: delete the preset labeled "label" from this object
421    Input Arguments: 1
422        1. Rp_Number *num - pointer to Number object
423        2. const char *label - label of the preset
424    Return Value: None
425    Notes: preset is removed from the object
426    Code Example:
427
428void Rp_NumberConfigure(Rp_Number *num, size_t as, ClientData c);
429    Purpose: configure the object based on the data in "c".
430                use "as" to determine the type of data in "c".
431    Input Arguments: 3
432        1. Rp_Number *num - pointer to Number object
433        2. size_t as - type of data stored in "c".
434                        valid values include:
435                            RPCONFIG_XML
436                            RPCONFIG_TREE
437        3. ClientData c - data to configure the object from.
438                            if as is...     then c should be...
439                            RPCONFIG_XML    const char *xmltext
440                            RPCONFIG_TREE   RP_ParserXML *object
441    Return Value: None
442    Notes: object is configured based on values in "c"
443    Code Example:
444
445void Rp_NumberDump(Rp_Number *num, size_t as, ClientData c);
446    Purpose: dump the object values based to the object "c".
447                use "as" to determine how to dump the data.
448    Input Arguments: 3
449        1. Rp_Number *num - pointer to Number object
450        2. size_t as - type of data stored in "c".
451                        valid values include:
452                            RPCONFIG_XML
453                            RPCONFIG_TREE
454        3. ClientData c - data to configure the object from.
455                            if as is...     then c should be...
456                            RPCONFIG_XML    ClientDataXml *object
457                            RPCONFIG_TREE   RP_ParserXML *object
458    Return Value: None
459    Notes: None
460    Code Example:
461
462void Rp_NumberOutcome(Rp_Number *num) const;
463    Purpose: return the status of this object as an Outcome.
464    Input Arguments: 1
465        1. Rp_Number *num - pointer to Number object
466    Return Value: status of the object as an Outcome
467    Notes: None
468    Code Example:
469
470const int Rp_NumberIs(Rp_Number *num) const;
471    Purpose: return an integer tag describing the object.
472    Input Arguments: 1
473        1. Rp_Number *num - pointer to Number object
474    Return Value: integer tag unique to all number objects
475    Notes: None
476    Code Example:
477
478void Rp_NumberMinFromStr(Rp_Number *num, const char *val);
479    Purpose: populate the min() value from a string.
480    Input Arguments: 2
481        1. Rp_Number *num - pointer to Number object
482        2. const char *val - value and units for the
483                                minimum value
484    Return Value: None
485    Notes: This function tries to parse the string for a value
486            and a units string. if a units string is found and
487            no units have been set for the object, these units
488            become the units for the object. if there are
489            already units for this object, any value found
490            during the split is converted to the object's
491            units before being stored in min().
492    Code Example:
493
494void Rp_NumberMaxFromStr(Rp_Number *num, const char *val);
495    Purpose: populate the max() value from a string.
496    Input Arguments: 2
497        1. Rp_Number *num - pointer to Number object
498        2. const char *val - value and units for the
499                                maximum value
500    Return Value: None
501    Notes: This function tries to parse the string for a value
502            and a units string. if a units string is found and
503            no units have been set for the object, these units
504            become the units for the object. if there are
505            already units for this object, any value found
506            during the split is converted to the object's
507            units before being stored in max().
508    Code Example:
509
510void Rp_NumberDefaultFromStr(Rp_Number *num, const char *val);
511    Purpose: populate the def() value from a string.
512    Input Arguments: 2
513        1. Rp_Number *num - pointer to Number object
514        2. const char *val - value and units for the
515                                default value
516    Return Value: None
517    Notes: This function tries to parse the string for a value
518            and a units string. if a units string is found and
519            no units have been set for the object, these units
520            become the units for the object. if there are
521            already units for this object, any value found
522            during the split is converted to the object's
523            units before being stored in def().
524    Code Example:
525
526void Rp_NumberCurrentFromStr(Rp_Number *num, const char *val);
527    Purpose: populate the cur() value from a string.
528    Input Arguments: 1
529        1. Rp_Number *num - pointer to Number object
530        2. const char *val - value and units for the
531                                current value
532    Return Value: None
533    Notes: This function tries to parse the string for a value
534            and a units string. if a units string is found and
535            no units have been set for the object, these units
536            become the units for the object. if there are
537            already units for this object, any value found
538            during the split is converted to the object's
539            units before being stored in cur().
540    Code Example:
Note: See TracBrowser for help on using the repository browser.