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

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

updates for the rappture objects, object examples, and object apis. small fix for rpunits c interface to check string length. there should probably be more of these checks in the c interface, but units should also be rewritten. added folders to separate out octave2 and octave3 app-fermi examples

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