Class StatusDataModel
Defined in File status-data-model.h
Class Documentation
-
class StatusDataModel
StatusDataModel is a central data model containing individual items for display in a user-defined manner. For example, the HUD layer in the GPA Framework will display items defined in this data model in a way that makes sense for that particular presentation. Other systems may display the data items contained in the model in whatever form is suitable for that presentation medium.
Items in the data model have a textual label, and an ItemState. It is up to the data view to present the state in whatever form applies to that view; the data model makes no assumption nor imposes any specification in this regard. Therefore the state values can be assumed to be "tri-state". For example, (STATE_RED, STATE_YELLOW, STATE_GREEN) may be displayed as ("Stopped", "Starting", "Running"), or ("No", "Unknown", "No"), or these states may drive 2- or 3-state visual widgets such as checkboxes. The user of this data model should not feel obligated to interpret the state value names literally, in other words.
Items that are transient in nature have a state of STATE_TRANSIENT. In this state, no other states are assumed, and the item may be set to timeout after a number of milliseconds.
"Permanent" stateless items can be created without ever setting a specific state; the default state for items is STATE_NOT_SET, and views can display these as simple text messages with no additional state decoration or indication.
Public Types
-
enum ItemState
The generic states known to the data model.
Values:
-
enumerator STATE_NOT_SET
Item state not set.
-
enumerator STATE_RED
Example: "No", "False", "Stopped", etc.
-
enumerator STATE_YELLOW
Example: "Pending", "Starting", "Unknown".
-
enumerator STATE_GREEN
Example: "Yes", "True", "Running", etc.
-
enumerator STATE_TRANSIENT
Item is transient (no other state is assumed to apply), useful for transient text messages that timeout.
-
enumerator STATE_NOT_SET
-
typedef uint64_t ItemHandle
Items in the data model are accessed and manipulated via opaque handles. This allows the user to cache and use handles without having to handle lifetime management. Accessing destroyed items is handled internally (such manipulation is effectively a no-operation).
Public Functions
-
virtual ~StatusDataModel()
-
virtual ItemHandle CreateStatusDataItem(char const *label) = 0
Obtain a handle to a new data status item. A new item is always created; no attempt is made to check if a similar item already exists.
- Parameters
label -- Text associated with the item; text is UTF8-encoded.
- Returns
Handle to the newly-created item.
-
virtual void DestroyStatusDataItem(ItemHandle item) = 0
Destroy a previously-created status item. Behavior is undefined if the item handle was not originally obtained via the CreateStatusDataItem() method.
- Parameters
item -- Handle to the item to destroy.
-
virtual void SetStatusDataItemLabel(ItemHandle item, char const *label) = 0
Set the label text on an existing status data item.
Note
Behavior is undefined if the item was previously destroyed.
- Parameters
item -- Handle to target item.
label -- Text to set on the item; text is UTF8-encoded.
-
virtual void SetStatusDataItemState(ItemHandle item, ItemState state) = 0
Set the ItemState on an existing status data item.
Note
Behavior is undefined if the item was previously destroyed.
- Parameters
item -- Handle to target item.
state -- State to set on the item.
-
virtual void SetStatusDataItemTimeout(ItemHandle item, uint64_t timeoutMS) = 0
Define a timeout for STATE_TRANSIENT items. Ignored otherwise. Data model views are not obligated to observe this value, but it is recommended. Value is in milliseconds.
- Parameters
item -- Handle to target item.
timeoutMS -- Number of milliseconds the ietm should live in the view.
-
virtual uint32_t GetStatusDataItemCount() = 0
Get the number of active (not destroyed, not timed-out) data items currently defined in the model. a View may use this method to obtain the number of data items available for display.
- Returns
Number of data items currently defined in the model.
-
virtual ItemHandle GetStatusDataItem(uint32_t index) const = 0
Get a handle to the status data item at index.
- Parameters
index -- Zero-based index of the item handle to obtain. See GetStatusDataItemCount().
- Returns
ItemHandle to the target item, or HANDLE_INVALID if the index is out of bounds or the item has since been destroyed or timed out.
-
virtual char const *GetStatusDataItemLabel(ItemHandle item) const = 0
Get the label text associated with the data item handle.
- Parameters
item -- Handle to target item.
- Returns
Item label string; text is UTF8-encoded.
-
virtual ItemState GetStatusDataItemState(ItemHandle item) const = 0
Get the state value associated with the data item handle.
- Parameters
item -- Handle to target item.
- Returns
ItemState value.
-
virtual uint64_t GetStatusDataItemTimeout(ItemHandle item) const = 0
Get the timeout (in milliseconds) for a STATE_TRANSIENT data item.
- Parameters
item -- Handle to target item.
- Returns
Number of milliseconds the item should live in the view.
-
enum ItemState