source: trunk/examples/objects/api/cpp/plot @ 1586

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