Userdata design
From Emergent
Contents |
User Data System
Overview
User Data is the name given to the system that enables "extra" data to be associated with particular objects or data items in emergent/temt. User Data can be used for any of the following purposes:
- storing view information, such as window sizes and positions
- storing format and other display information for things like DataTable columns
- storing labels, captions, and other annotations to figures, graphs, etc.
- associating new data items at runtime with existing classes, for scripting
The User Data system can support both simple data types (int, float, String, etc.) as well as strongly-typed values (ex. 3d coordinates, etc.)
The system also supports Schema, which enables the available data values to be queried, and includes default values and user-friendly descriptions.
The User Data API is defined on taBase; however User Data is only implemented by default for taOBase-descendant classes. Other taBase-descendant classes can support User Data if storage is provided.
Data Keys
User Data is set and retrieved via simple string keys. For example, a label on a graph might be accessed using the key "label".
Simple Values
The User Data system has special support for simple scalar values (any scalar type that can be stored in a Variant). The functions for setting and getting simple values are the easiest to use, and so simple values should be used wherever possible.
Getting/Setting Simple Values
The following functions are provided on taBase for getting and setting simple values.
const Variant GetUserValue(key) const const Xxx GetUserValueAsXxx(key) const [various strongly typed versions]
Gets a simple value; if the instance does not have the value, the default (if any) will be returned. If there is no default, then a _nilVariant or equivalent is returned.
bool HasUserValue(key) const
Returns 'true' if the data item exists in the instance -- this is helpful, for example, to decide whether to display it or not in a given context. Only the instance is checked, not the default.
void SetUserValue(const Variant&, key)
If the data item exists for the key, its value is updated with 'value'; if it doesn't exist, a new simple data item is created and added to the User Data for the item.
Strongly-typed Values
The User Data system fully supports strongly-typed values -- this enables custom user data to be defined and manipulated.
Creating a Strongly-typed Class
Custom user data objects must be subclasses of UserDataItemBase (which is itself a subclass of taBase.) The following example shows the (skeleton) definition of a class that stores a label caption along with a 3D position for that label. This class will be used as an example for the remainder of this section. Strongly-typed User Data classes are taBase objects -- a custom macro is provided to declare all the "boilerplate code" for the class. (The class automatically handles InitLinks/CutLinks.)
class UserData_Label: public UserDataItemBase {
public:
TDCoord coord;
String text;
USERDATA_FUNS(UserData_Label, UserData);
private:
void Initialize(); // your initialize code, if any
void Destroy(); // your destroy code, if any
};
That's all there is to it!
Getting/Setting Strongly-typed Values
TBD
Schema
Schema is a collection of UserData objects that get initialized and/or loaded at system startup, and provide default values and descriptive text for users.
Schema serves the following purposes:
- provides a definite list, for any object type, of the kinds of User Data it supports (both simple and strongly-typed)
- supplies default values for all supported keys/types -- this enables clients of a particular key to obtain a sensible default, whether the item exists or not
- supports runtime browsing of available keys, particularly keys that might be of special interest to the user, such as general annotations
No special additional classes are required for schema -- schema always uses an instance of its corresponding object.
For advanced users, the defaults provided by the program can be overridden, and the result saved to a file that is read at startup. This provides a powerful mechanism for users to control a wide variety of default values in the system.
Initializing Schema (Simple Data)
UserDataItem provides a constructor that can be used to create static items of UserData that are associated with a class.
