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