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

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

examples of using a view in tcl and c, update tcl and c view apis

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