source: branches/1.3/examples/objects/api/cpp/choice @ 3721

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