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