Data Array Access
Chapter 3 detailed the general layout of the Objective Chart data array to be a two-dimensional, grid-like structure with numeric, stylistic, and text data storage. This section lists the functions available for accessing the data array.
To access an individual data object, reference it using its index and group coordinates.
If you reference a data list (group) or data object (index) that has not been created yet, Objective Chart automatically creates the necessary objects for you. Therefore, you can build and initialize your data array in one step. All you need to do is assign values to the groups and indices that you require. The SRGraphData and SRGraphDataList objects are created automatically and transparently. This capability to generate the data array is controlled by the growlist parameter of some of the access functions. Functions without this parameter generally do grow the data list if necessary. As noted below, some functions can not cause the data list to grow. If a non-existing data object is referenced by these functions (or others with growlist set to FALSE), an exception is thrown.
The SRGraph object has two sets of methods for this access. The first uses functions built in to the SRGraph class that allow indirect access to a data item. These functions are:
• SetValue(int index, int group, double value, BOOL bUseDefaultStyle)
Places a value at the specified index and group. If the data object does not exist, one is created for you. If bUseDefaultStyle is TRUE, the m_DefaultDataStyle member of the SRGraph object is copied to the style member of the data object.
• GetValue(int index, int group)
Retrieves a value from a given location. If no data object exists, one is created and a zero value is returned.
• SetText(int index, int group, LPCSTR text)
Places a text string in the default annotation of a given location. If no data object exists, one is created for you.
• GetText(int index, int group)
Retrieves text from a location. If the specified data object does not exist, an exception is generated.
• SetHeader(int group, LPCSTR text)
Places an annotation in the SRGraphDataList object that controls a specific group or series. If no group exists, then one is created.
• GetHeader(int group)
Retrieves an annotation previously set with SetHeader(). If no group exists, an exception is thrown.
Greater control may be exercised over individual items in the data array by using the second set of data access methods. Functions within SRGraph return pointers to individual SRGraphDataList objects. Then functions within those objects give access to the SRGraphData items stored, also via pointers.
SRGraphDataList*
SRGraph::GetGroup(int group, BOOL growlist)
Retrieves a pointer to a specific SRGraphDataList object. The growlist parameter, which defaults to TRUE, allows you to choose whether the group list should grow automatically if a request is made for a group that does not exist. If growlist is FALSE and the group does not exist, an exception is thrown.
SRGraphData*
SRGraphDataList::GetIndex(int index, BOOL growlist)
Retrieves a pointer to the individual data object within a group. The growlist parameter allows you to choose whether the list should grow automatically or not. The default setting grows the list.
These methods are commonly used in the following manner:
MyGraphObject.GetGroup(n)->GetIndex(x)-> SomeDataFunction(...);
SRGraphData*
SRGraph::GetData(int index, int group)
Retrieves a pointer to a data item. It is equivalent to calling the following:
GetGroup(group, TRUE)-> GetIndex(index,TRUE).
MyGraphObject.GetData(x,n)->SomeDataFunction(...);
SRGraphData*
SRGraph::GetSafeData(int index, int group)
Retrieves a pointer to a pre-existing data item— it throws an exception if the specified data item does not exist. GetSafeData() is used extensively within Objective Chart
GetGroup() and GetIndex() are used by the first set of data access functions. The SetXXX functions set the growlist parameter to TRUE, allowing the data list to grow. Therefore, you can build your data array without explicitly creating the data lists (SRGraphDataList) or data items (SRGraphData).
The following code segment builds a data array, including annotations and styles, for plotting two parabolas. For demonstration purposes, a variety of access methods are used.
CString s;
// loop to add 10 data objects (indices)
// to each of two groups
for(int x=0;x<10;x++)
{
// group 0
m_Graph.SetValue(x,0,(double)(50+10*x-5*x**2));
// add annotation – for axis labels or chart tips
s.Format("%d",x);
m_Graph.GetGroup(0)->GetIndex(x)->SetAnnotation(s);
// display with a wiget, no line
m_Graph.GetGroup(0)->GetIndex(x)->GetStyle()->
SetObjectStyle(CX_OBJECT_POINT);
// group 1
m_Graph.SetValue(x,1,(double)(35+15*x-3*x**2));
// represent as a line with no wigets
m_Graph.GetData(x,1)->GetStyle()->
SetObjectStyle(CX_OBJECT_LINE);
}
// set group headers, used by legends
for(int g=0;g<2;g++)
{
s.Format("Group %d",g);
m_Graph.SetHeader(g,s);
}