source: trunk/examples/objects/api/cpp/number @ 1581

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

updates for the rappture objects, object examples, and object apis. small fix for rpunits c interface to check string length. there should probably be more of these checks in the c interface, but units should also be rewritten. added folders to separate out octave2 and octave3 app-fermi examples

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