source: trunk/examples/objects/api/tcl/view @ 1645

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

adding api for view, updating tcl app-fermi object example with view interface

File size: 23.6 KB
Line 
1Rappture::View
2
3constructors/destructors
4    Rappture::View <name> -rows <rows> -cols <cols>
5
6methods
7    name ?<val>?
8    path ?<val>?
9    label ?<val>?
10    desc ?<val>?
11    hints ?<val>?
12    property <key> ?<val>?
13    propremove <key>
14
15    plot    <name> -at "row,col" -table <table> {"x1" "y1" "s1" ...}
16    volume  <name> -at "row,col" -table <table> {"x1" "y1" "z1" "d1" ...}
17    surface <name> -at "row,col" -table <table> {"x1" "y1" "d1" ...}
18    image   <object> -at "row,col"
19    note    <object> -at "row,col"
20
21    vvalue ?<hints>?
22    random
23    diff <o>
24    configure -as <as> <c>
25    dump -as <as>
26    outcome
27    is
28
29---------------------------------------
30Rappture::View <name> -rows <rows> -cols <cols>
31    Purpose: construct a view for displaying data
32    Input Arguments: 1 manditory, 2 optional
33        1. name - name of the view
34        2. rows - number of rows in the view, default is 1
35        3. cols - number of columns in the view, default is 1
36    Return Value: a newly created, empty view object
37    Notes: None
38    Code Example:
39    {{{
40        set v [Rappture::View "fdfplots" -rows 2 -cols 1]
41    }}}
42
43name ?<val>?
44    Purpose: get/set the id name of the object
45    Input Arguments: at most 1
46        1. val - new id name
47    Return Value: the name of the object
48    Notes: if no name is set, an empty string will be returned
49           the id name is used to identify this object from
50           all other objects and should be unique
51           val, if provided, is used to set the object name
52    Code Example:
53    {{{
54        set p [Rappture::Plot]
55        $p name
56        # ""
57        $p name "fdfactor"
58        $p name
59        # "fdfactor"
60    }}}
61
62path ?<val>?
63    Purpose: get/set the path of the object
64    Input Arguments: at most 1
65        1. val - new path
66    Return Value: path of the object
67    Notes: if no path is set, an empty string will be returned
68           the path tells where this object sits in the
69           hierarchy of objects.
70           val, if provided, is used to set the object path
71    Code Example:
72    {{{
73        set p [Rappture::Plot]
74        $p path
75        # ""
76        $p path "output"
77        $p path
78        # "output"
79    }}}
80
81label ?<val>?
82    Purpose: get/set the label of the object
83    Input Arguments: at most 1
84        1. val - new label
85    Return Value: label of the object
86    Notes: if no label is set, an empty string will be returned
87           the label is used by the graphical user interface.
88           val, if provided, is used to set the object label
89    Code Example:
90    {{{
91        set p [Rappture::Plot]
92        $p label
93        # ""
94        $p label "Fermi-Dirac Factor"
95        $p label
96        # "Fermi-Dirac Factor"
97    }}}
98
99desc ?<val>?
100    Purpose: get/set the description of the object
101    Input Arguments: at most 1
102        1. val - new description
103    Return Value: description of the object
104    Notes: if no description is set, an empty string will be returned
105           the description is used by the graphical user
106           interface to describe what type of data is being
107           requested and how the input is used.
108           val, if provided, is used to set the object description
109    Code Example:
110    {{{
111        set p [Rappture::Plot]
112        $p desc
113        # ""
114        $p desc "A plot of the Fermi-Dirac Factor"
115        $p desc
116        # "A plot of the Fermi-Dirac Factor"
117    }}}
118
119hints ?<val>?
120    Purpose: get/set the hints of the object
121    Input Arguments: at most 1
122        1. val - new hints
123    Return Value: hints of the object
124    Notes: if no hints are set, an empty string will be returned
125           the hints are used by the graphical user interface
126           val, if provided, is used to set the object hints
127    Code Example:
128    {{{
129        set p [Rappture::Plot]
130        $p hints
131        # ""
132        $p hints "no hints"
133        $p hints
134        # "no hints"
135    }}}
136
137property <key> ?<val>?
138    Purpose: get/set a generic property in the property database
139    Input Arguments: at most 2
140        1. key - property name
141        2. val - property value
142    Return Value: value of the property
143    Notes: A copy val is stored in the property database
144    Code Example:
145    {{{
146        set p [Rappture::Plot]
147        $p property "name"
148        # ""
149        $p property "name" "fdfactor"
150        # "fdfactor"
151        $p name
152        # "fdfactor"
153    }}}
154
155propremove <key>
156    Purpose: remove a property from the property database
157    Input Arguments: 1
158        1. key - property name
159    Return Value: value of the property
160    Notes: None
161    Code Example:
162    {{{
163        set p [Rappture::Plot]
164        $p name "fdfactor"
165        $p property "name"
166        # "fdfactor"
167        $p propremove "name"
168        # "fdfactor"
169        $p property "name"
170        # ""
171    }}}
172
173plot <name> -at "row,col" -table <table> {"x1" "y1" "s1" "x2" "y2" "s2" ...}
174    Purpose: populate a view object with a plot
175    Input Arguments: 2 required, 2 optional
176        1. name - name of the plot
177        2. -at - position of the plot within the view, row and column number
178        3. -table - name of the table holding the data.
179        4. {"x1" "y1" "s1" ...} - x and y column names, followed by the style
180    Return Value: None
181    Notes: plots can be grouped together by specifying
182           multiple x,y pairs within the list of columns
183           from the last argument. eg:
184           {"x1" "y1" "s1" "x2" "y2" "s2"}
185    Code Example:
186    {{{
187        set results [Rappture::Table "dataTable"]
188        $results column "Xvals" "X Values"
189        $results column "Squared" "X Squared"
190        $results column "Cubed" "X Cubed"
191
192        # create a view with two curves grouped on a single plot
193        # 1) x vs x^2
194        # 2) x vs x^3
195        set v1 [Rappture::View fdfview1]
196        $v1 plot "fdfPlot1" -table "dataTable" \
197            {"Xvals" "Squared" "g:o" "Xvals" "Cubed" "b-o"}
198
199        # create a view with two plots, one stacked on top of the other
200        # 1) x vs x^2
201        # 2) x vs x^3
202        set v2 [Rappture::View fdfview2 -rows 2 -cols 1]
203        $v2 plot "fdfPlot2" -at "1,1" -table "dataTable" \
204            {"Xvals" "Squared" "g:o"}
205        $v2 plot "fdfPlot3" -at "2,1" -table "dataTable" \
206            {"Xvals" "Cubed" "b-o"}
207
208        # create a view with two plots side by side
209        # 1) x vs x^2   2) x vs x^3
210        set v3 [Rappture::View fdfview3 -rows 1 -cols 2]
211        $v3 plot "fdfPlot4" -at "1,1" -table "dataTable" \
212            {"Xvals" "Squared" "g:o"}
213        $v3 plot "fdfPlot5" -at "1,2" -table "dataTable" \
214            {"Xvals" "Cubed" "b-o"}
215    }}}
216
217volume  <name> -at "row,col" -table <table> {"x1" "y1" "z1" "d1",...}
218    Purpose: populate a view object with a volume
219    Input Arguments: 2 required, 2 optional
220        1. name - name of the volume
221        2. -at - position of the plot within the view, row and column number
222        3. -table - name of the table holding the data.
223        4. {"x1" "y1" "z1" "d1",...} - x, y, z, and data column names
224    Return Value: None
225    Notes: volumes can be grouped together by specifying
226           multiple x,y,z triplets within the list of columns
227           from the last argument. eg:
228           {"x1" "y1" "z1" "d1" "x2" "y2" "z2" "d2"}
229    ToDo:
230        1. how to specify transfer function ranges
231        2. how to specify uni rect grid instead of explicit points
232            - three values in the coords columns is assumed to be
233              the min, max, and step for that direction of the
234              uniform rectangular grid?
235    Code Example:
236    {{{
237        set results [Rappture::Table "dataTable"]
238        $results column "Xcoords" "X coordinates"
239        $results column "Ycoords" "Y coordinates"
240        $results column "Zcoords" "Z coordinates"
241        $results column "Data1" "Data Set #1"
242        $results column "Data2" "Data Set #2"
243
244        # create a view with two volumes in a single visualization window
245        set v1 [Rappture::View fdfview1]
246        $v1 volume "fdfVol1" -table "dataTable" \
247            {"Xcoords" "Ycoords" "Zcoords" "Data1" \
248             "Xcoords" "Ycoords" "Zcoords" "Data2"}
249
250        # create a view with two volumes in different visualization windows
251        # one stacked on top of the other
252        set v2 [Rappture::View fdfview2 -rows 2 -cols 1]
253        $v2 volume "fdfVol2" -at "1,1" -table "dataTable" \
254            {"Xcoords" "Ycoords" "Zcoords" "Data1"}
255        $v2 volume "fdfVol3" -at "2,1" -table "dataTable" \
256            {"Xcoords" "Ycoords" "Zcoords" "Data2"}
257
258        # create a view with two volumes in different visualization windows
259        # side by side
260        set v3 [Rappture::View fdfview3 -rows 1 -cols 2]
261        $v3 volume "fdfVol4" -at "1,1" -table "dataTable" \
262            {"Xcoords" "Ycoords" "Zcoords" "Data1"}
263        $v3 volume "fdfVol5" -at "1,2" -table "dataTable" \
264            {"Xcoords" "Ycoords" "Zcoords" "Data2"}
265    }}}
266
267surface <name> -at "row,col" -table <table> {"x1" "y1" "d1" ...}
268    Purpose: populate a view object with a surface plot
269    Input Arguments: 2 required, 2 optional
270        1. name - name of the volume
271        2. -at - position of the plot within the view, row and column number
272        3. -table - name of the table holding the data.
273        4. {"x1" "y1" "d1",...} - x, y, and data column names
274    Return Value: None
275    Notes: surface plots can be grouped together by specifying
276           multiple x,y pairs within the list of columns
277           from the last argument. eg:
278           {"x1" "y1" "d1" "x2" "y2" "d2"}
279    ToDo:
280        1. how to specify transfer function ranges
281        2. how to specify uni rect grid instead of explicit points
282            - three values in the coords columns is assumed to be
283              the min, max, and step for that direction of the
284              uniform rectangular grid?
285    Code Example:
286    {{{
287        set results [Rappture::Table "dataTable"]
288        $results column "Xcoords" "X coordinates"
289        $results column "Ycoords" "Y coordinates"
290        $results column "Data1" "Data Set #1"
291        $results column "Data2" "Data Set #2"
292
293        # create a view with two surface plots in a single visualization window
294        set v1 [Rappture::View fdfview1]
295        $v1 surface "fdfSurf1" -table "dataTable" \
296            {"Xcoords" "Ycoords" "Data1" \
297             "Xcoords" "Ycoords" "Data2"}
298
299        # create a view with two volumes in different visualization windows
300        # one stacked on top of the other
301        set v2 [Rappture::View fdfview2 -rows 2 -cols 1]
302        $v2 surface "fdfSurf2" -at "1,1" -table "dataTable" \
303            {"Xcoords" "Ycoords" "Data1"}
304        $v2 surface "fdfSurf3" -at "2,1" -table "dataTable" \
305            {"Xcoords" "Ycoords" "Data2"}
306
307        # create a view with two volumes in different visualization windows
308        # side by side
309        set v3 [Rappture::View fdfview3 -rows 1 -cols 2]
310        $v3 surface "fdfSurf4" -at "1,1" -table "dataTable" \
311            {"Xcoords" "Ycoords" "Data1"}
312        $v3 surface "fdfSurf5" -at "1,2" -table "dataTable" \
313            {"Xcoords" "Ycoords" "Data2"}
314    }}}
315
316image <object> -at "row,col"
317    Purpose: populate a view object with an image
318    Input Arguments: 1 required, 1 optional
319        1. object - object representing the image
320        2. -at - position of the image within the view, row and column number
321    Return Value: None
322    Code Example:
323    {{{
324        set i1 [Rappture::Image "image1" -label "ilabel1" -desc "idesc1"]
325        set i2 [Rappture::Image "image2" -label "ilabel2" -desc "idesc2"]
326
327        # create a view with two images in different windows
328        # one stacked on top of the other
329        set v1 [Rappture::View fdfview1 -rows 2 -cols 1]
330        $v1 image $i1 -at "1,1"
331        $v1 image $i2 -at "2,1"
332
333        # create a view with two images in different windows
334        # side by side
335        set v2 [Rappture::View fdfview2 -rows 1 -cols 2]
336        $v2 image $i1 -at "1,1"
337        $v2 image $i2 -at "1,2"
338    }}}
339
340note <object> -at "row,col"
341    Purpose: populate a view object with a note
342    Input Arguments: 1 required, 1 optional
343        1. object - object representing the note
344        2. -at - position of the note within the view, row and column number
345    Return Value: None
346    Code Example:
347    {{{
348        set i1 [Rappture::Note "note1" -label "nlabel1" -desc "ndesc1"]
349        set i2 [Rappture::Note "note2" -label "nlabel2" -desc "ndesc2"]
350
351        # create a view with two notes in different windows
352        # one stacked on top of the other
353        set v1 [Rappture::View fdfview1 -rows 2 -cols 1]
354        $v1 note $n1 -at "1,1"
355        $v1 note $n2 -at "2,1"
356
357        # create a view with two notes in different windows
358        # side by side
359        set v2 [Rappture::View fdfview2 -rows 1 -cols 2]
360        $v2 note $i1 -at "1,1"
361        $v2 note $i2 -at "1,2"
362    }}}
363
364vvalue ?<hints>?
365    Purpose: return the value of the object after applying a
366             varying number of hints about how the value
367             should be configured
368    Input Arguments: variable numbber
369        1. variable number of hints
370    Return Value: value of the object
371    Notes: vvalue will parse out the recognisable hints from
372           va_list arg. Values stored in the object are
373           not changed. Hints should be of the form
374           hintKey=hintVal
375    Code Example:
376    {{{
377        for {set i 0} {$i < 10} {incr i} {
378            lappend x $i
379            lappend y1 [expr pow($i,2)]
380            lappend y2 [expr pow($i,3)]
381        }
382
383        set p [Rappture::Plot]
384        $p add $x $y1 -format "g:o" -name "xsquared"
385        $p add $x $y2 -format "b-o" -name "xcubed"
386        puts [$p vvalue]
387        # [ [ [1 2 3 4 5 6 7 8 9 10] \
388        #     [1 4 9 16 25 36 49 64 81 100] ] \
389        #   [ [1 2 3 4 5 6 7 8 9 10] \
390        #     [1 8 27 64 125 216 343 512 729 1000] ] ]
391
392    }}}
393
394random
395    Purpose: populate the object with a random value
396    Input Arguments: 0
397    Return Value: None
398    Notes: the current value of this object will be populated
399           with a random value that fits within the min and
400           max if they were specified.
401    Code Example:
402    {{{
403        set p [Rappture::Plot]
404        $p random
405        # plot is filed with random data
406        puts [$p vvalue]
407        # [ [ [1 2 3 4 5 6 7 8 9 10] \
408        #     [1 2 3 4 5 6 7 8 9 10] ] \
409        #   [ [1 2 3 4 5 6 7 8 9 10] \
410        #     [1 4 9 16 25 36 49 64 81 100] ] \
411        #   [ [1 2 3 4 5 6 7 8 9 10] \
412        #     [1 8 27 64 125 216 343 512 729 1000] ] ]
413        puts [$p count]
414        # 3
415
416    }}}
417
418diff <o>
419    Purpose: return a list showing the differences between
420             this object and Rappture Object o
421    Input Arguments: 1
422        1. o - Rappture Object to diff against
423    Return Value: list of differences between objects
424    Notes: None
425    Code Example:
426    {{{
427        set p1 [Rappture::Plot]
428        $p1 random
429        # plot is filed with random data
430        puts [$p vvalue]
431        # [ [ [1 2 3 4 5 6 7 8 9 10] \
432        #     [1 4 9 16 25 36 49 64 81 100] ] ]
433
434        set p2 [Rappture::Plot]
435        $p2 random
436        # plot is filed with random data
437        puts [$p vvalue]
438        # [ [ [1 2 3 4 5 6 7 8 9 10] \
439        #     [1 8 27 64 125 216 343 512 729 1000] ] ]
440
441        set diffs [$p1 diff $p2]
442
443        foreach {ctype prop oVal nVal} $diffs {
444            puts "$ctype $prop $oval $nVal"
445        }
446        # c name temperature Ef
447        # c units K eV
448        # c def 300 4.5
449        # c min 0 0
450        # c max 500 10
451        # c label "Ambiant Temperature" "Fermi Level"
452        # c desc "Temperature of the environment" "Energy at center of distribution"
453        #
454        # Note that this function will find a difference in the
455        # minimum values even though they are numerically equal.
456        # This is because the objects have different units that
457        # are not compatible. If compatible units were found,
458        # n2's values would have been converted to n1's units
459        # for each comparison.
460
461
462    }}}
463
464configure -as <as> <c>
465    Purpose: configure the object based on the data in "c".
466             use "as" to determine the type of data in "c".
467    Input Arguments: 2
468        1. as - type of data stored in "c".
469                valid values include:
470                    RPCONFIG_XML
471                    RPCONFIG_TREE
472        2. c - data to configure the object from.
473               if as is...     then c should be...
474               RPCONFIG_XML    const char *xmltext
475               RPCONFIG_TREE   RP_ParserXML *object
476    Return Value: None
477    Notes: object is configured based on values in "c"
478    Code Example:
479    {{{
480        set p [Rappture.Plot]
481        set xmldata {
482            <?xml version="1.0">
483            <curve id="xsquared">
484                <about>
485                    <group>auto34</group>
486                    <label>x squared</label>
487                    <description>x values are squared</description>
488                    <type></type>
489                    <format>g:o</format>
490                </about>
491                <xaxis>
492                    <label>x values</label>
493                    <description>values being squared</description>
494                    <units></units>
495                    <scale>linear</scale>
496                </xaxis>
497                <yaxis>
498                    <label>y values</label>
499                    <description>squared values</description>
500                    <units></units>
501                    <scale>linear</scale>
502                </yaxis>
503                <component>
504                    <xy>         1         1
505                 2         4
506                 3         9
507                 4        16
508                 5        25
509                 6        36
510                 7        49
511                 8        64
512                 9        81
513                10       100
514                    </xy>
515                </component>
516            </curve>
517            <curve id="xcubed">
518                <about>
519                    <group>auto34</group>
520                    <label>x cubed</label>
521                    <description>x values are cubed</description>
522                    <type></type>
523                    <format>b-o</format>
524                </about>
525                <xaxis>
526                    <label>x values</label>
527                    <description>values being cubed</description>
528                    <units></units>
529                    <scale>linear</scale>
530                </xaxis>
531                <yaxis>
532                    <label>y values</label>
533                    <description>cubed values</description>
534                    <units></units>
535                    <scale>linear</scale>
536                </yaxis>
537                <component>
538                    <xy>         1         1
539                 2         8
540                 3        27
541                 4        64
542                 5       125
543                 6       216
544                 7       343
545                 8       512
546                 9       729
547                10      1000
548                    </xy>
549                </component>
550            </curve>
551        }
552
553        $p configure -as RPCONFIG_XML $xmldata
554        puts [$p vvalue]
555        # [ [ [1 2 3 4 5 6 7 8 9 10] \
556        #     [1 4 9 16 25 36 49 64 81 100] ] \
557        #   [ [1 2 3 4 5 6 7 8 9 10] \
558        #     [1 8 27 64 125 216 343 512 729 1000] ] ]
559
560        for {set cur 0} {$cur < [$p count]} {incr cur} {
561            set c [$p getNthCurve $cur]
562            puts [$c name]
563            puts [$c label]
564            puts [$c desc]
565            puts [$c format]
566            for {set axisCnt 0} {$axisCnt < [$c dims]} {incr axisCnt} {
567                set axis [$c getNthAxis $axisCnt]
568                puts [$axis label]
569                puts [$axis desc]
570                puts [$axis units]
571                puts [$axis scale]
572                puts [$axis data]
573            }
574        }
575        # xsquared
576        # x squared
577        # x values are squared
578        # g:o
579        # xaxis
580        # x values
581        # values being squared
582        #
583        # linear
584        # [1 2 3 4 5 6 7 8 9 10]
585        # yaxis
586        # y values
587        # squared values
588        #
589        # linear
590        # [1 4 9 16 25 36 49 64 81 100]
591        # xcubed
592        # x cubed
593        # x values are cubed
594        # b-o
595        # xaxis
596        # x values
597        # values being cubed
598        #
599        # linear
600        # [1 2 3 4 5 6 7 8 9 10]
601        # yaxis
602        # y values
603        # cubed values
604        #
605        # linear
606        # [1 8 27 64 125 216 343 512 729 1000]
607
608    }}}
609
610dump -as <as>
611    Purpose: dump the object values.
612             use "as" to determine how to dump the data.
613    Input Arguments: 2
614        1. as - type of data to be returned.
615                valid values include:
616                    RPCONFIG_XML
617                    RPCONFIG_TREE
618    Return Value:
619               if as is...     then return the following...
620               RPCONFIG_XML    ClientDataXml *object
621               RPCONFIG_TREE   RP_ParserXML *object
622    Notes: None
623    Code Example:
624    {{{
625        for {set i 0} {$i < 10} {incr i} {
626            lappend x $i
627            lappend y1 [expr pow($i,2)]
628            lappend y2 [expr pow($i,3)]
629        }
630
631        set p [Rappture::Plot]
632        $p add $x $y1 -format "g:o" -name "xsquared"
633        $p add $x $y2 -format "b-o" -name "xcubed"
634        puts [$p dump -as RPCONFIG_XML]
635        # <curve id="xsquared">
636        #     <about>
637        #         <group>auto34</group>
638        #         <label></label>
639        #         <description></description>
640        #         <type>(null)</type>
641        #         <format>g:o</format>
642        #     </about>
643        #     <xaxis>
644        #         <label></label>
645        #         <description></description>
646        #         <units></units>
647        #         <scale>linear</scale>
648        #     </xaxis>
649        #     <yaxis>
650        #         <label></label>
651        #         <description></description>
652        #         <units></units>
653        #         <scale>linear</scale>
654        #     </yaxis>
655        #     <component>
656        #         <xy>         1         1
657        #      2         4
658        #      3         9
659        #      4        16
660        #      5        25
661        #      6        36
662        #      7        49
663        #      8        64
664        #      9        81
665        #     10       100
666        #         </xy>
667        #     </component>
668        # </curve>
669        # <curve id="xcubed">
670        #     <about>
671        #         <group>auto34</group>
672        #         <label></label>
673        #         <description></description>
674        #         <type>(null)</type>
675        #         <format>b-o</format>
676        #     </about>
677        #     <xaxis>
678        #         <label></label>
679        #         <description></description>
680        #         <units></units>
681        #         <scale>linear</scale>
682        #     </xaxis>
683        #     <yaxis>
684        #         <label></label>
685        #         <description></description>
686        #         <units></units>
687        #         <scale>linear</scale>
688        #     </yaxis>
689        #     <component>
690        #         <xy>         1         1
691        #      2         8
692        #      3        27
693        #      4        64
694        #      5       125
695        #      6       216
696        #      7       343
697        #      8       512
698        #      9       729
699        #     10      1000
700        #         </xy>
701        #     </component>
702        # </curve>
703
704    }}}
705
706outcome
707    Purpose: return the status of this object as an Outcome.
708    Input Arguments: 0
709    Return Value: status of the object as an Outcome
710    Notes: None
711    Code Example:
712    {{{
713        set p [Rappture::Plot]
714        set out [$p outcome]
715        if ([$out value] != 0) {
716            puts stderr [$out context]
717            puts stderr [$out remark]
718        }
719    }}}
720
721
722is
723    Purpose: return an integer tag describing the object.
724    Input Arguments: 0
725    Return Value: integer tag unique to all number objects
726    Notes: None
727    Code Example:
Note: See TracBrowser for help on using the repository browser.