source: trunk/examples/objects/api/c/plot

Last change on this file was 1586, checked in by dkearney, 14 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: 12.3 KB
Line 
1Plot
2
3    Rp_Plot *Rp_PlotInit(Rp_Library *lib)
4    void Rp_PlotDestroy (Rp_Plot *p);
5
6    const char *Rp_PlotGetName(Rp_Plot *p) const;
7    void Rp_PlotSetName(Rp_Plot *p, const char *val);
8
9    const char *Rp_PlotGetPath(Rp_Plot *p) const;
10    void Rp_PlotSetPath(Rp_Plot *p, const char *val);
11
12    const char *Rp_PlotGetLabel(Rp_Plot *p) const;
13    void Rp_PlotSetLabel(Rp_Plot *p, const char *val);
14
15    const char *Rp_PlotGetDesc(Rp_Plot *p) const;
16    void Rp_PlotSetDesc(Rp_Plot *p, const char *val);
17
18    const char *Rp_PlotGetHints(Rp_Plot *p) const;
19    void Rp_PlotSetHints(Rp_Plot *p, const char *val);
20
21    const char *Rp_PlotGetColor(Rp_Plot *p) const;
22    void Rp_PlotSetColor(Rp_Plot *p, const char *val);
23
24    const void *Rp_PlotGetProperty (Rp_Plot *p, const char *key) const;
25    void Rp_PlotSetProperty (Rp_Plot *p, const char *key, const void *val, size_t nbytes);
26
27    const char *Rp_PlotGetPropStr (Rp_Plot *p, const char *key) const;
28    void Rp_PlotSetPropStr (Rp_Plot *p, const char *key, const char *val);
29
30    void Rp_PlotPropRemove (Rp_Plot *p, const char *key);
31
32    void Rp_PlotAdd (Rp_Plot *p, size_t nPts, double *x, double *y,
33                      const char *fmt, const char *name);
34
35    void Rp_PlotAddCurve (Rp_Plot *p, Curve *c, const char *name);
36
37    size_t Rp_PlotCount(Rp_Plot *p) const;
38
39    Curve *Rp_PlotCurve (Rp_Plot *p, const char* name) const;
40    Curve *Rp_PlotGetNthCurve(Rp_Plot *p, size_t n) const;
41
42    void Rp_PlotVValue(Rp_Plot *p, void *storage, size_t numHints,
43                       va_list arg) const;
44    void Rp_PlotRandom();
45    Rp_Chain *Rp_PlotDiff(Rp_Plot *o);
46
47    void Rp_PlotConfigure(Rp_Plot *p, size_t as, ClientData c);
48    void Rp_PlotDump(Rp_Plot *p, size_t as, ClientData c);
49
50    Outcome *Rp_PlotOutcome(Rp_Plot *p) const;
51
52    const int Rp_PlotIs(Rp_Plot *p) const;
53
54---------------------------------------
55
56const char *Rp_PlotGetName(Rp_Plot *p)
57    Purpose: get the id name of the object
58    Input Arguments: 1
59        1. Rp_Plot *p - pointer to Plot object
60    Return Value: the id name stored in the object.
61    Notes: if no name is set, NULL will be returned
62            the id name is used to identify this object from
63            all other objects and should be unique
64    Code Example:
65
66void Rp_PlotSetName(Rp_Plot *p, const char *val)
67    Purpose: set the id name of the object
68    Input Arguments: 2
69        1. Rp_Plot *p - pointer to Plot object
70        2. const char *val - new id name
71    Return Value: None
72    Notes: a copy of the memory location val will be stored
73    Code Example:
74
75const char *Rp_PlotGetPath(Rp_Plot *p)
76    Purpose: get the path of the object
77    Input Arguments: 1
78        1. Rp_Plot *p - pointer to Plot object
79    Return Value: the path stored in the object.
80    Notes: if no path is set, NULL will be returned
81            the path tells where this object sits in the
82            hierarchy of objects.
83    Code Example:
84
85void Rp_PlotGetPath(Rp_Plot *p, const char *val)
86    Purpose: set the path of the object
87    Input Arguments: 2
88        1. Rp_Plot *p - pointer to Plot object
89        2. const char *val - new path
90    Return Value: None
91    Notes: a copy of the memory location val will be stored
92    Code Example:
93
94const char *Rp_PlotGetLabel(Rp_Plot *p)
95    Purpose: get the label of the object
96    Input Arguments: 1
97        1. Rp_Plot *p - pointer to Plot object
98    Return Value: the label stored in the object.
99    Notes: if no label is set, NULL will be returned
100            the label is used by the graphical user interface.
101    Code Example:
102
103void Rp_PlotSetLabel(Rp_Plot *p, const char *val)
104    Purpose: set the label of the object
105    Input Arguments: 2
106        1. Rp_Plot *p - pointer to Plot object
107        2. const char *val - new label
108    Return Value: None
109    Notes: a copy of the memory location val will be stored
110    Code Example:
111
112const char *Rp_PlotGetDesc(Rp_Plot *p)
113    Purpose: get the description of the object
114    Input Arguments: 1
115        1. Rp_Plot *p - pointer to Plot object
116    Return Value: the description stored in the object.
117    Notes: if no description is set, NULL will be returned
118            the description is used by the graphical user
119            interface to describe what type of data is being
120            requested and how the input is used.
121    Code Example:
122
123void Rp_PlotSetDesc(Rp_Plot *p, const char *val)
124    Purpose: set the description of the object
125    Input Arguments: 2
126        1. Rp_Plot *p - pointer to Plot object
127        2. const char *val - new description
128    Return Value: None
129    Notes: a copy of the memory location val will be stored
130    Code Example:
131
132const char *Rp_PlotGetHints(Rp_Plot *p)
133    Purpose: get the hints of the object
134    Input Arguments: 1
135        1. Rp_Plot *p - pointer to Plot object
136    Return Value: the hints stored in the object.
137    Notes: if no hints are set, NULL will be returned
138            the hints are used by the graphical user interface
139    Code Example:
140
141void Rp_PlotSetHints(Rp_Plot *p, const char *val)
142    Purpose: set the hints of the object
143    Input Arguments: 2
144        1. Rp_Plot *p - pointer to Plot object
145        2. const char *val - new hints
146    Return Value: None
147    Notes: a copy of the memory location val will be stored
148    Code Example:
149
150const void *Rp_PlotGetProperty (Rp_Plot *p, const char *key) const;
151    Purpose: get a generic property from the property database
152    Input Arguments: 2
153        1. Rp_Plot *p - pointer to Plot object
154        2. const char *key - property name
155    Return Value: value of the property
156    Notes: None
157    Code Example:
158
159void Rp_PlotSetProperty (Rp_Plot *p, const char *key, const void *val, size_t nbytes);
160    Purpose: set a generic property in the property database
161    Input Arguments: 4
162        1. Rp_Plot *p - pointer to Plot object
163        2. const char *key - property name
164        3. const void *val - property value
165        4. size_t nbytes - size (in bytes) of the value
166    Return Value: None
167    Notes: A copy of the memory pointed to by val is stored
168            in the property database
169    Code Example:
170
171const char *Rp_PlotGetPropStr (Rp_Plot *p, const char *key) const;
172    Purpose: get a string property from the property database
173    Input Arguments: 2
174        1. Rp_Plot *p - pointer to Plot object
175        2. const char *key - property name
176    Return Value: value of the property
177    Notes: None
178    Code Example:
179
180void Rp_PlotSetPropStr (Rp_Plot *p, const char *key, const char *val);
181    Purpose: set a string property in the property database
182    Input Arguments: 3
183        1. Rp_Plot *p - pointer to Plot object
184        2. const char *key - property name
185        3. const char *val - property value
186    Return Value: None
187    Notes: A copy of the memory pointed to by val is stored
188            in the property database
189    Code Example:
190
191void Rp_PlotPropRemove (Rp_Plot *p, const char *key);
192    Purpose: remove a property from the property database
193    Input Arguments: 1
194        1. Rp_Plot *p - pointer to Plot object
195        2. const char *key - property name
196    Return Value: value of the property
197    Notes: None
198    Code Example:
199
200void Rp_PlotAdd (Rp_Plot *p, size_t nPts, double *x, double *y,
201                 const char *fmt, const char *name);
202    Purpose: add data for an xy curve to the plot
203    Input Arguments: 6
204        1. Rp_Plot *p - pointer to Plot object
205        2. size_t nPts - number of points in the x and y arrays
206        3. double *x - pointer to array representing the x axis
207        4. double *y - pointer to array representing the y axis
208        5. const char *fmt - format of the line
209        6. const char *name - id of the newly created curve
210    Return Value: reference to a Plot object
211    Notes: format can be something like "g:o" to represent
212            green line, dotted line style, circle marker.
213            this follows matlab's formatting rules.
214    Code Example:
215
216void Rp_PlotAddCurve (Rp_Plot *p, Curve *c, const char *name);
217    Purpose: add a Curve object to this Plot object
218    Input Arguments: 3
219        1. Rp_Plot *p - pointer to Plot object
220        2. Curve *c - Curve object to add
221        3. const char *name - id of the Curve object
222    Return Value: reference to a Plot object
223    Notes: Curve object should not be deleted by user?
224    Code Example:
225
226size_t Rp_PlotCount(Rp_Plot *p) const;
227    Purpose: retrieve the number of curves in this Plot object
228    Input Arguments: 1
229        1. Rp_Plot *p - pointer to Plot object
230    Return Value: number of curves stored in the object
231    Notes: None
232    Code Example:
233
234Curve *Rp_PlotCurve (Rp_Plot *p, const char* name) const;
235    Purpose: retrieve the curve with the id matching "name"
236    Input Arguments: 2
237        1. Rp_Plot *p - pointer to Plot object
238        2. const char *name - id to Curve to be retrieved
239    Return Value: pointer to Curve object matching "name" or NULL
240    Notes: None
241    Code Example:
242
243Curve *Rp_PlotGetNthCurve(Rp_Plot *p, size_t n) const;
244    Purpose: return the n'th curve stored in the object
245    Input Arguments: 2
246        1. Rp_Plot *p - pointer to Plot object
247        2. size_t n - number of the curve to retrieve
248    Return Value: pointer to the n'th Curve object stored in
249                    the Plot object or NULL
250    Notes: None
251    Code Example:
252
253void Rp_PlotVValue(Rp_Plot *p, void *storage, size_t numHints, va_list arg) const;
254    Purpose: return the value of the object after applying a
255                varying number of hints about how the value
256                should be configured
257    Input Arguments: 4
258        1. Rp_Plot *p - pointer to Plot object
259        2. void *storage - the return value
260        3. size_t numHints - number of hints provided
261        4. va_list arg - list of hints specified as a va_list
262    Return Value: None
263    Notes: vvalue will parse out the recognisable hints from
264                va_list arg. Values stored in the object are
265                not changed.
266    Code Example:
267
268void Rp_PlotRandom();
269    Purpose: populate the object with a random value
270    Input Arguments: 0
271    Return Value: None
272    Notes: the current value of this object will be populated
273           with a random value that fits within the min and
274           max if they were specified.
275    Code Example:
276
277Rp_Chain *Rp_PlotDiff(const Rp_Object *o);
278    Purpose: return a linked list showing the differences between
279             this object and Rp_Object *o
280    Input Arguments: 1
281        1. const Rp_Object *o - object to diff against
282    Return Value: list of differences between objects
283    Notes: None
284    Code Example:
285
286void Rp_PlotConfigure(Rp_Plot *p, size_t as, ClientData c);
287    Purpose: configure the object based on the data in "c".
288                use "as" to determine the type of data in "c".
289    Input Arguments: 3
290        1. Rp_Plot *p - pointer to Plot object
291        2. size_t as - type of data stored in "c".
292                        valid values include:
293                            RPCONFIG_XML
294                            RPCONFIG_TREE
295        3. ClientData c - data to configure the object from.
296                            if as is...     then c should be...
297                            RPCONFIG_XML    const char *xmltext
298                            RPCONFIG_TREE   RP_ParserXML *object
299    Return Value: None
300    Notes: object is configured based on values in "c"
301    Code Example:
302
303void Rp_PlotDump(Rp_Plot *p, size_t as, ClientData c);
304    Purpose: dump the object values based to the object "c".
305                use "as" to determine how to dump the data.
306    Input Arguments: 3
307        1. Rp_Plot *p - pointer to Plot object
308        2. size_t as - type of data stored in "c".
309                        valid values include:
310                            RPCONFIG_XML
311                            RPCONFIG_TREE
312        3. ClientData c - data to configure the object from.
313                            if as is...     then c should be...
314                            RPCONFIG_XML    ClientDataXml *object
315                            RPCONFIG_TREE   RP_ParserXML *object
316    Return Value: None
317    Notes: None
318    Code Example:
319
320Outcome *Rp_PlotOutcome(Rp_Plot *p) const;
321    Purpose: return the status of this object as an Outcome.
322    Input Arguments: 1
323        1. Rp_Plot *p - pointer to Plot object
324    Return Value: status of the object as an Outcome
325    Notes: None
326    Code Example:
327
328const int Rp_PlotIs(Rp_Plot *p) const;
329    Purpose: return an integer tag describing the object.
330    Input Arguments: 1
331        1. Rp_Plot *p - pointer to Plot object
332    Return Value: integer tag unique to all plot objects
333    Notes: None
334    Code Example:
Note: See TracBrowser for help on using the repository browser.