source: trunk/examples/objects/api/python/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: 9.7 KB
Line 
1Rappture.Number
2
3constructors/destructors
4    Rappture.Number()
5    Rappture.Number(name, units, val[, min, max, label, desc])
6    Rappture.Number(const Number& o)
7
8methods
9    n.name([val])
10    n.path([val])
11    n.label([val])
12    n.desc([val])
13    n.hints([val])
14    n.color([val])
15    n.def([val])
16    n.cur([val])
17    n.min([val])
18    n.max([val])
19    n.units([u])
20    n.property(key[, val])
21    n.propremove(key)
22
23    n.convert(to)
24    n.value(units)
25    n.vvalue([...])
26    n.random()
27    n.diff(o)
28
29    n.addPreset(label, desc, val[, units])
30    n.delPreset(label)
31
32    n.configure(as, c)
33    n.dump(as, c)
34
35    n.outcome()
36
37    n.is()
38
39---------------------------------------
40Rappture.Number([name, units, val[, min, max, label, desc]])
41    Purpose: construct a number object
42    Input Arguments: 0, 3 or 7
43        1. name - object's name
44        2. units - object's units
45        3. val - default value
46        4. min - minimum accepted value
47        5. max - maximum accepted value
48        6. label - object's label
49        7. desc - object's description
50    Return Value: a newly created number object
51    Notes: input arguments are used to construct the number object
52    Code Example:
53
54Rappture.Number(o)
55    Purpose: construct a number object based on number object o
56    Input Arguments: 1
57        1. o - number object to copy
58    Return Value: a newly created number object
59    Notes: None
60    Code Example:
61
62
63n.name([val])
64    Purpose: get/set the id name of the object
65    Input Arguments: at most 1
66        1. val - new id name
67    Return Value: the name of the object
68    Notes: if no name is set, None will be returned
69           the id name is used to identify this object from
70           all other objects and should be unique
71           val, if provided, is used to set the object name
72    Code Example:
73
74n.path([val])
75    Purpose: get/set the path of the object
76    Input Arguments: at most 1
77        1. val - new path
78    Return Value: path of the object
79    Notes: if no path is set, None will be returned
80           the path tells where this object sits in the
81           hierarchy of objects.
82           val, if provided, is used to set the object path
83    Code Example:
84
85n.label([val])
86    Purpose: get/set the label of the object
87    Input Arguments: at most 1
88        1. val - new label
89    Return Value: label of the object
90    Notes: if no label is set, None will be returned
91           the label is used by the graphical user interface.
92           val, if provided, is used to set the object label
93    Code Example:
94
95n.desc([val])
96    Purpose: get/set the description of the object
97    Input Arguments: at most 1
98        1. const char *val - new description
99    Return Value: description of the object
100    Notes: if no description is set, None will be returned
101           the description is used by the graphical user
102           interface to describe what type of data is being
103           requested and how the input is used.
104           val, if provided, is used to set the object description
105    Code Example:
106
107n.hints([val])
108    Purpose: get/set the hints of the object
109    Input Arguments: at most 1
110        1. val - new hints
111    Return Value: hints of the object
112    Notes: if no hints are set, None will be returned
113           the hints are used by the graphical user interface
114           val, if provided, is used to set the object hints
115    Code Example:
116
117n.color([val])
118    Purpose: get/set the color of the object
119    Input Arguments: at most 1
120        1. const char *val - new color
121    Return Value: color of the object
122    Notes: if no color is set, None will be returned
123           the color is used by the graphical user interface
124           val, if provided, is used to set the object color
125    Code Example:
126
127n.def([val])
128    Purpose: get/set the default value
129    Input Arguments: at most 1
130        1. val - new default value
131    Return Value: default value of the object
132    Notes: if no default is set, None will be returned
133           val, if provided, is used to set the object default value
134    Code Example:
135
136n.cur([val])
137    Purpose: get/set the current value
138    Input Arguments: at most 1
139        1. val - new current value
140    Return Value: current value of the object
141    Notes: if no current is set, None will be returned
142           val, if provided, is used to set the object current value
143    Code Example:
144
145n.min([val])
146    Purpose: get/set the minimum accepted value of this object
147    Input Arguments: at most 1
148        1. double val - new minimum accepted value
149    Return Value: the minimum value this object will accept.
150    Notes: if no min is set, None will be returned
151           val, if provided, is used to set the object min
152    Code Example:
153
154n.max([val])
155    Purpose: get/set the maximum accepted value of this object
156    Input Arguments: 1
157        1. val - new maximum accepted value
158    Return Value: the maximum value this object will accept.
159    Notes: if no max is set, None will be returned
160           val, if provided, is used to set the object max
161    Code Example:
162
163n.units([val])
164    Purpose: get/set the units of this object
165    Input Arguments: 1
166        1. const char *val - new units
167    Return Value: the string representing the object's units
168    Notes: if no units are set, None will be returned
169           val, if provided, is used to set the object units
170    Code Example:
171
172n.property(key[, val])
173    Purpose: get/set a generic property in the property database
174    Input Arguments: at most 2
175        1. const char *key - property name
176        2. const void *val - property value
177    Return Value: value of the property
178    Notes: A copy val is stored in the property database
179    Code Example:
180
181n.propremove(key)
182    Purpose: remove a property from the property database
183    Input Arguments: 1
184        1. key - property name
185    Return Value: value of the property
186    Notes: None
187    Code Example:
188
189n.convert(to)
190    Purpose: convert the def and cur values to "to" units
191    Input Arguments: 1
192        1. to - string of units to convert to
193    Return Value: Outcome object
194    Notes: the values stored in the object are changed
195    Code Example:
196
197n.value(to)
198    Purpose: return the value of the object with units of "to"
199    Input Arguments: 1
200        1. to - string of units to convert to
201    Return Value: value of the object
202    Notes: cur() is used as the base value. if cur was not set
203            by the user (cur() == None), def() is used.
204            if def was not set (def() == None), 0.0 is used
205            as the value.
206    Code Example:
207
208n.vvalue([...])
209    Purpose: return the value of the object after applying a
210                varying number of hints about how the value
211                should be configured
212    Input Arguments:
213        1. variable number of hints
214    Return Value: value of the object after applying hints.
215    Notes: vvalue will parse out the recognisable hints from
216                va_list arg. Values stored in the object are
217                not changed. Hint strings should have the form
218                hintKey=hintVal and be comma separated
219    Code Example:
220
221n.random()
222    Purpose: populate the object with a random value
223    Input Arguments: 0
224    Return Value: None
225    Notes: the current value of this object will be populated
226           with a random value that fits within the min and
227           max if they were specified.
228    Code Example:
229
230n.diff(o)
231    Purpose: return a list showing the differences between
232             this object and Rappture Object o
233    Input Arguments: 1
234        1. o - Rappture Object to diff against
235    Return Value: list of differences between objects
236    Notes: None
237    Code Example:
238
239n.addPreset(label, desc, val[, units])
240    Purpose: add a preset to this object
241    Input Arguments: 3 or 4
242        1. label - label of the preset
243        2. desc - description of the preset
244        3. val - value of the preset, possibly with units
245        4. units - units of the preset
246    Return Value: None
247    Notes: presets are stored in the object in the same order
248                in which they are created
249    Code Example:
250
251n.delPreset(label)
252    Purpose: delete the preset labeled "label" from this object
253    Input Arguments: 1
254        1. const char *label - label of the preset
255    Return Value: None
256    Notes: preset is removed from the object
257    Code Example:
258
259n.configure(as, c)
260    Purpose: configure the object based on the data in "c".
261                use "as" to determine the type of data in "c".
262    Input Arguments: 2
263        1. as - type of data stored in "c".
264                valid values include:
265                    RPCONFIG_XML
266                    RPCONFIG_TREE
267        2. c - data to configure the object from.
268               if as is...     then c should be...
269               RPCONFIG_XML    const char *xmltext
270               RPCONFIG_TREE   RP_ParserXML *object
271    Return Value: None
272    Notes: object is configured based on values in "c"
273    Code Example:
274
275n.dump(as, c)
276    Purpose: dump the object values based to the object "c".
277                use "as" to determine how to dump the data.
278    Input Arguments: 2
279        1. as - type of data stored in "c".
280                valid values include:
281                    RPCONFIG_XML
282                    RPCONFIG_TREE
283        2. c - data to configure the object from.
284               if as is...     then c should be...
285               RPCONFIG_XML    ClientDataXml *object
286               RPCONFIG_TREE   RP_ParserXML *object
287    Return Value: None
288    Notes: None
289    Code Example:
290
291n.outcome()
292    Purpose: return the status of this object as an Outcome.
293    Input Arguments: 0
294    Return Value: status of the object as an Outcome
295    Notes: None
296    Code Example:
297
298n.is()
299    Purpose: return an integer tag describing the object.
300    Input Arguments: 0
301    Return Value: integer tag unique to all number objects
302    Notes: None
303    Code Example:
Note: See TracBrowser for help on using the repository browser.