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