source: trunk/examples/objects/api/python/number @ 1619

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

updating python objects api with example code, fixes for tcl objects api

File size: 16.6 KB
Line 
1Rappture.Number
2
3constructors/destructors
4    Rappture.Number()
5    Rappture.Number(name, units, val[, min, max, label, desc])
6    Rappture.Number(numObj)
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    n.convert(to)
23    n.value(units)
24    n.vvalue([...])
25    n.random()
26    n.diff(o)
27    n.addPreset(label, desc, val[, units])
28    n.delPreset(label)
29    n.configure(as, c)
30    n.dump(as, c)
31    n.outcome()
32    n.is()
33
34---------------------------------------
35Rappture.Number([name, units, val[, min, max, label, desc]])
36    Purpose: construct a number object
37    Input Arguments: 0, 3 or 7
38        1. name - object's name
39        2. units - object's units
40        3. val - default value
41        4. min - minimum accepted value
42        5. max - maximum accepted value
43        6. label - object's label
44        7. desc - object's description
45    Return Value: a newly created number object
46    Notes: input arguments are used to construct the number object
47    Code Example:
48    {{{
49        n1 = Rappture.Number()
50        n2 = Rappture.Number("temperature","K",300)
51        n3 = Rappture.Number("temperature",units="K",300,min=0,max=500,
52                                 label="Ambiant Temperature",
53                                 desc="Temperature of the environment")
54    }}}
55
56Rappture.Number(numObj)
57    Purpose: construct a number object based on number object numObj
58    Input Arguments: 1
59        1. numObj - number object to copy
60    Return Value: a newly created number object
61    Notes: None
62    Code Example:
63    {{{
64        n1 = Rappture.Number()
65        n2 = Rappture.Number(n1)
66    }}}
67
68
69n.name([val])
70    Purpose: get/set the id name of the object
71    Input Arguments: at most 1
72        1. val - new id name
73    Return Value: the name of the object
74    Notes: if no name is set, None will be returned
75           the id name is used to identify this object from
76           all other objects and should be unique
77           val, if provided, is used to set the object name
78    Code Example:
79    {{{
80        n = Rappture.Number()
81        n.name()
82        # ""
83        n.name("temperature")
84        n.name()
85        # "temperature"
86    }}}
87
88n.path([val])
89    Purpose: get/set the path of the object
90    Input Arguments: at most 1
91        1. val - new path
92    Return Value: path of the object
93    Notes: if no path is set, None will be returned
94           the path tells where this object sits in the
95           hierarchy of objects.
96           val, if provided, is used to set the object path
97    Code Example:
98    {{{
99        n = Rappture.Number()
100        n.path()
101        # ""
102        n.path("input")
103        n.path()
104        # "input"
105    }}}
106
107n.label([val])
108    Purpose: get/set the label of the object
109    Input Arguments: at most 1
110        1. val - new label
111    Return Value: label of the object
112    Notes: if no label is set, None will be returned
113           the label is used by the graphical user interface.
114           val, if provided, is used to set the object label
115    Code Example:
116    {{{
117        n = Rappture.Number()
118        n.label()
119        # ""
120        n.label("Ambiant temperature")
121        n.label()
122        # "Ambiant temperature"
123    }}}
124
125n.desc([val])
126    Purpose: get/set the description of the object
127    Input Arguments: at most 1
128        1. val - new description
129    Return Value: description of the object
130    Notes: if no description is set, None will be returned
131           the description is used by the graphical user
132           interface to describe what type of data is being
133           requested and how the input is used.
134           val, if provided, is used to set the object description
135    Code Example:
136    {{{
137        n = Rappture.Number()
138        n.desc()
139        # ""
140        n.desc("Temperature of the environment")
141        n.desc()
142        # "Temperature of the environment"
143    }}}
144
145n.hints([val])
146    Purpose: get/set the hints of the object
147    Input Arguments: at most 1
148        1. val - new hints
149    Return Value: hints of the object
150    Notes: if no hints are set, None will be returned
151           the hints are used by the graphical user interface
152           val, if provided, is used to set the object hints
153    Code Example:
154    {{{
155        n = Rappture.Number()
156        n.hints()
157        # ""
158        n.hints("none")
159        n.hints()
160        # "none"
161    }}}
162
163n.color([val])
164    Purpose: get/set the color of the object
165    Input Arguments: at most 1
166        1. val - new color
167    Return Value: color of the object
168    Notes: if no color is set, None will be returned
169           the color is used by the graphical user interface
170           val, if provided, is used to set the object color
171    Code Example:
172    {{{
173        n = Rappture.Number()
174        n.color()
175        # ""
176        n.color("none")
177        n.color()
178        # "none"
179    }}}
180
181n.def([val])
182    Purpose: get/set the default value
183    Input Arguments: at most 1
184        1. val - new default value
185    Return Value: default value of the object
186    Notes: if no default is set, None will be returned
187           val, if provided, is used to set the object default value
188    Code Example:
189    {{{
190        n = Rappture.Number()
191        n.def()
192        # ""
193        n.def(300)
194        n.def()
195        # 300
196    }}}
197
198n.cur([val])
199    Purpose: get/set the current value
200    Input Arguments: at most 1
201        1. val - new current value
202    Return Value: current value of the object
203    Notes: if no current is set, None will be returned
204           val, if provided, is used to set the object current value
205    Code Example:
206    {{{
207        n = Rappture.Number()
208        n.cur()
209        # ""
210        n.cur(450)
211        n.cur()
212        # 450
213    }}}
214
215n.min([val])
216    Purpose: get/set the minimum accepted value of this object
217    Input Arguments: at most 1
218        1. double val - new minimum accepted value
219    Return Value: the minimum value this object will accept.
220    Notes: if no min is set, None will be returned
221           val, if provided, is used to set the object min
222    Code Example:
223    {{{
224        n Rappture.Number()
225        n.min()
226        # ""
227        n.min(0)
228        n.min()
229        # 0
230    }}}
231
232n.max([val])
233    Purpose: get/set the maximum accepted value of this object
234    Input Arguments: 1
235        1. val - new maximum accepted value
236    Return Value: the maximum value this object will accept.
237    Notes: if no max is set, None will be returned
238           val, if provided, is used to set the object max
239    Code Example:
240    {{{
241        n = Rappture.Number()
242        n.max()
243        # ""
244        n.max(500)
245        n.max()
246        # 500
247    }}}
248
249n.units([val])
250    Purpose: get/set the units of this object
251    Input Arguments: 1
252        1. val - new units
253    Return Value: the string representing the object's units
254    Notes: if no units are set, None will be returned
255           val, if provided, is used to set the object units
256    Code Example:
257    {{{
258        n = Rappture.Number()
259        n.units()
260        # ""
261        n.units("K")
262        n.units()
263        # "K"
264    }}}
265
266n.property(key[, val])
267    Purpose: get/set a generic property in the property database
268    Input Arguments: at most 2
269        1. key - property name
270        2. val - property value
271    Return Value: value of the property
272    Notes: A copy val is stored in the property database
273    Code Example:
274    {{{
275        n = Rappture.Number()
276        n.property("units")
277        # ""
278        n.property("units","K")
279        # "K"
280        n.units()
281        # "K"
282    }}}
283
284n.propremove(key)
285    Purpose: remove a property from the property database
286    Input Arguments: 1
287        1. key - property name
288    Return Value: value of the property
289    Notes: None
290    Code Example:
291    {{{
292        n = Rappture.Number("temperature","K",300)
293        n.property("units")
294        # "K"
295        n.propremove("units")
296        # "K"
297        n.property("units")
298        # ""
299    }}}
300
301n.convert(to)
302    Purpose: convert the def and cur values to "to" units
303    Input Arguments: 1
304        1. to - string of units to convert to
305    Return Value: Outcome object
306    Notes: the values stored in the object are changed
307    Code Example:
308    {{{
309        n = Rappture.Number("temperature","K",300)
310        n.min("0K")
311        n.max("500K")
312        n.cur(450)
313        out = n.convert("F")
314        if (out.value() != 0) {
315            sys.stderr.write(out.context())
316            sys.stderr.write(out.remark())
317        }
318        n.min()
319        # -459.67
320        n.max()
321        # 440.33
322        n.def()
323        # 80.33
324        n.cur()
325        # 350.33
326    }}}
327
328n.value(to)
329    Purpose: return the value of the object with units of "to"
330    Input Arguments: 1
331        1. to - string of units to convert to
332    Return Value: value of the object
333    Notes: cur() is used as the base value. if cur was not set
334            by the user (cur() == None), def() is used.
335            if def was not set (def() == None), 0.0 is used
336            as the value.
337    Code Example:
338    {{{
339        n = Rappture.Number()
340        n.value()
341        # 0
342        n.def(300)
343        n.value()
344        # 300
345        n.cur(450)
346        n.value()
347        # 450
348        n.value("F")
349        # 350.33
350    }}}
351
352n.vvalue([...])
353    Purpose: return the value of the object after applying a
354                varying number of hints about how the value
355                should be configured
356    Input Arguments:
357        1. variable number of hints
358    Return Value: value of the object after applying hints.
359    Notes: vvalue will parse out the recognisable hints from
360                va_list arg. Values stored in the object are
361                not changed. Hint strings should have the form
362                hintKey=hintVal and be comma separated
363    Code Example:
364    {{{
365        n = Rappture.Number()
366        n.cur(450)
367        n.vvalue()
368        # 450
369        n.vvalue("units=F")
370        # 350.33
371    }}}
372
373n.random()
374    Purpose: populate the object with a random value
375    Input Arguments: 0
376    Return Value: None
377    Notes: the current value of this object will be populated
378           with a random value that fits within the min and
379           max if they were specified.
380    Code Example:
381    {{{
382        n = Rappture.Number()
383        n.random()
384        n.cur()
385        # 1042.34
386        # should be something more like:
387        # n.configure(min=-30,max=30)
388        # n.random()
389        n.min(-30)
390        n.max(30)
391        n.random()
392        n.cur()
393        # 16.89
394    }}}
395
396n.diff(o)
397    Purpose: return a list showing the differences between
398             this object and Rappture Object o
399    Input Arguments: 1
400        1. o - Rappture Object to diff against
401    Return Value: list of differences between objects
402    Notes: None
403    Code Example:
404    {{{
405        n1 = Rappture.Number("temperature","K",300,"0K","500K",
406                                 "Ambiant Temperature",
407                                 "Temperature of the environment")
408        n2 = Rappture.Number("Ef","eV","4.5eV","0eV","10eV",
409                                 "Fermi Level",
410                                 "Energy at center of distribution")
411        diffs = n1.diff(n2)
412        # diffs is a list of tuples or list of lists
413
414        for ctype, prop, oVal, nVal in diffs {
415            print ctype, prop, oVal, nVal
416        }
417        # c name temperature Ef
418        # c units K eV
419        # c def 300 4.5
420        # c min 0 0
421        # c max 500 10
422        # c label "Ambiant Temperature" "Fermi Level"
423        # c desc "Temperature of the environment" "Energy at center of distribution"
424        #
425        # Note that this function will find a difference in the
426        # minimum values even though they are numerically equal.
427        # This is because the objects have different units that
428        # are not compatible. If compatible units were found,
429        # n2's values would have been converted to n1's units
430        # for each comparison.
431    }}}
432
433n.addPreset(label, desc, val[, units])
434    Purpose: add a preset to this object
435    Input Arguments: 3 or 4
436        1. label - label of the preset
437        2. desc - description of the preset
438        3. val - value of the preset, possibly with units
439        4. units - units of the preset
440    Return Value: None
441    Notes: presets are stored in the object in the same order
442                in which they are created
443    Code Example:
444    {{{
445        n = Rappture.Number("temperature","K",300,"0K","500K",
446                                "Ambiant Temperature",
447                                "Temperature of the environment"]
448        n.addPreset("Room Temperature","","300K")
449        n.addPreset("Liquid Nitrogen","",77,"K")
450        n.addPreset("Liquid Helium","","4.2K")
451
452        # 3 Presets stored in the Rappture.Number object
453    }}}
454
455n.delPreset(label)
456    Purpose: delete the preset labeled "label" from this object
457    Input Arguments: 1
458        1. label - label of the preset
459    Return Value: None
460    Notes: preset is removed from the object
461    Code Example:
462    {{{
463        n = Rappture.Number("temperature","K",300,"0K","500K",
464                                "Ambiant Temperature",
465                                "Temperature of the environment")
466        n.addPreset("Room Temperature","","300K")
467        n.addPreset("Liquid Nitrogen","",77,"K")
468        n.addPreset("Liquid Helium","","4.2K")
469
470        n.delPreset("Liquid Helium")
471        # 2 Presets stored in the Rappture.Number object
472    }}}
473
474n.configure(as, c)
475    Purpose: configure the object based on the data in "c".
476                use "as" to determine the type of data in "c".
477    Input Arguments: 2
478        1. as - type of data stored in "c".
479                valid values include:
480                    RPCONFIG_XML
481                    RPCONFIG_TREE
482        2. c - data to configure the object from.
483               if as is...     then c should be...
484               RPCONFIG_XML    const char *xmltext
485               RPCONFIG_TREE   RP_ParserXML *object
486    Return Value: None
487    Notes: object is configured based on values in "c"
488    Code Example:
489    {{{
490        n = Rappture.Number()
491        xmldata = """
492            <?xml version="1.0">
493            <number id="temperature">
494                <about>
495                    <label>Ambient temperature</label>
496                    <description>Temperature of the environment.</description>
497                </about>
498                <units>K</units>
499                <min>0K</min>
500                <max>500K</max>
501                <default>300K</default>
502            </number>
503        """
504
505        n.configure(RPCONFIG_XML,xmldata)
506        n.name()
507        # temperature
508        n.label()
509        # Ambient temperature
510        n.desc()
511        # Temperature of the environment.
512        n.units()
513        # K
514        n.min()
515        # 0
516        n.max()
517        # 500
518        n.def()
519        # 300
520    }}}
521
522n.dump(as, c)
523    Purpose: dump the object values based to the object "c".
524                use "as" to determine how to dump the data.
525    Input Arguments: 2
526        1. as - type of data stored in "c".
527                valid values include:
528                    RPCONFIG_XML
529                    RPCONFIG_TREE
530        2. c - data to configure the object from.
531               if as is...     then c should be...
532               RPCONFIG_XML    ClientDataXml *object
533               RPCONFIG_TREE   RP_ParserXML *object
534    Return Value: None
535    Notes: None
536    Code Example:
537    {{{
538        n = Rappture.Number("temperature","K",300,"0K","500K",
539                                "Ambiant Temperature",
540                                "Temperature of the environment")
541        xmldata = n.dump(RPCONFIG_XML)
542        print xmldata
543
544        # <number id="temperature">
545        #     <about>
546        #         <label>Ambient temperature</label>
547        #         <description>Temperature of the environment.</description>
548        #     </about>
549        #     <units>K</units>
550        #     <min>0K</min>
551        #     <max>500K</max>
552        #     <default>300K</default>
553        # </number>
554    }}}
555
556n.outcome()
557    Purpose: return the status of this object as an Outcome.
558    Input Arguments: 0
559    Return Value: status of the object as an Outcome
560    Notes: None
561    Code Example:
562    {{{
563        n = Rappture.Number("temperature","K",300,"0K","500K",
564                                "Ambiant Temperature",
565                                "Temperature of the environment")
566        out = n.outcome()
567        if (out.value() != 0) {
568            sys.stderr.write(out.context())
569            sys.stderr.write(out.remark())
570        }
571    }}}
572
573n.is()
574    Purpose: return an integer tag describing the object.
575    Input Arguments: 0
576    Return Value: integer tag unique to all number objects
577    Notes: None
578    Code Example:
Note: See TracBrowser for help on using the repository browser.