Data Label Object Reference

DataLabel Object

Overview

The DataLabel object can be used to define a label for the data in a group. The label object is an array of text strings that automatically appears in an appropriate context in any view of the group. For example, a label associated with a data series might contain a character string corresponding to each data pair in the series. These strings would appear as row annotation in a table view.

DataLabel objects are created automatically when the user performs a drag-and-drop. If the drag-and-drop begins inside an EditTable object, the column heading becomes the name of the data object, and the row annotation becomes a label array. For instance, if the user selects three columns for drag-and-drop, this will automatically create three DataSampled objects (one for each column), with a DataLabel object containing the annotation for each row.

For a Chart, DataLabel objects are used to annotate the axes. For a Table, DataLabel objects provide row or column annotation. The data label has an orientation which specifies which axis (when attached to a chart) it corresponds to. If you specify more than one DataLabel for a specific orientation, the chart manager will try to merge those labels based on the range information.

Example

The following example shows a typical code structure used to define a DataLabel object.

static String x_labels[] = {"Houston","Dallas","San Antonio", "Austin"};
...
XtVaCreateWidget("Cities", (WidgetClass)xintDataLabelObjectClass, edit,
                 XmNlabelStrings, x_labels,
                 XmNlabelCount, sizeof(x_labels)/sizeof(String),
                 XmNlabelOrientation, XintLABEL_X,
                 XmNdataGroup, data_group, 
                 NULL);

Inherited Resources and Behavior

The DataLabel object class does not inherit behavior and resources from any other object class.

The class pointer is xintDataLabelObjectClass.
The class name is XintDataLabel.
The header file is included as <Xint/DataLabel.h>.

The following resources are defined by the DataLabel object class. These resources must be set as part of the object creation function XintCreateDataLabel discussed later in this section.
Name	Type	Default	Access
XmNcopyData	Boolean	True	CSG
XmNdataGroup	Object	NULL	CSG
XmNlabelCount	int	0	CSG
XmNlabelOrientation	int	XintLABEL_X	CSG
XmNlabelPositionArray	float *	NULL	CSG
XmNlabelStrings	char **	NULL	CSG
XmNlastViewDestroy	Boolean	True	CSG
XmNsampledRange	XintRange *	NULL	CSG
XmNupdateCallback	XtCallbackList	NULL	C

Resource Value Description
XintLABEL_X (default) Label is associated with the X axis (column annotation).
XintLABEL_Y Label is associated with the Y axis (row annotation).
XintLABEL_Z Label is associated with the Z axis.

Resource Value	Description
XintLABEL_X (default)	Label is associated with the X axis (column annotation).
XintLABEL_Y	Label is associated with the Y axis (row annotation).
XintLABEL_Z	Label is associated with the Z axis.

XmNlabelPositionArray

This resource specifies an array, of size XmNlabelCount, used to position the labels along a chart axis. This resource should only be used if the increment between the labels is not constant. Use resource XmNsampledRange otherwise.

XmNlabelStrings

This is the text of the label, or the name of a pre-defined array containing a series of character strings to be used as labels.

XmNlastViewDestroy

Specifies whether or not to automatically destroy this data object when there are no more views connected to the data. If this data object is inserted into a DataGroup, you only need to set this resource for the DataGroup object.

XmNsampledRange

Specifies the start and increment for positioning the labels. For example, if the label orientation is specified as X, this resource would define the start (position of the first label) and the increment (how far apart are the labels) in the X direction. If this resource is not specified, the start is assumed to be 0 and the increment 1. This resource is helpful to position the annotation on the axis. Use resource XmNlabelPositionArray to position labels at a non constant interval.

This resource is specified as a pointer to a data structure of type XintRange, which takes the following form:

   typedef struct {
                   float start;
                   float increment;
   } XintRange;

where:

Member Description
start Minimum value.
increment Increment.

Member	Description
start	Minimum value.
increment	Increment.

XmNupdateCallback

This resource allows you to attach a callback to the Label object that is invoked each time the data has changed. See the following section for more information on this callback.

Callback

Callback XmNupdateCallback provides notification of changes in a DataLabel object. This notification can be used to ensure that updates to one view are properly reflected in all other views. The callback structure takes the following form:

   typedef struct {
                   int        reason;
                   XEvent     *event;
                   Object     object;
   } XintDataLabelUpdateCallbackStruct;

If you have multiple DataLabel or other objects in a group, this callback must be registered separately for each individual data object. If you prefer to control updates at the group level, you should register this callback only once for the DataGroup object and use the XintDataGroupUpdateCallbackStruct discussed earlier in this manual.

The following ordered table describes the members of structure XintDataLabelUpdateCallbackStruct:

Data Type Member Description
int reason Indicates why callback was invoked (see table below).
XEvent * event Standard member in Motif callback structure; not used in this context (will always be NULL).
Object object ID of the updated object.

Data Type	Member	Description
int	reason	Indicates why callback was invoked (see table below).
XEvent *	event	Standard member in Motif callback structure; not used in this context (will always be NULL).
Object	object	ID of the updated object.

Member reason provides information explaining why and how the update occurred. Possible values for member reason are:

Reason Description
XintCR_DATA_UPDATE
XintCR_DATA_BATCH Label has been changed, no more information is available.

Reason	Description
XintCR_DATA_UPDATE XintCR_DATA_BATCH	Label has been changed, no more information is available.

Functions

The following functions are defined for creating and manipulating DataLabel objects.

Function Name Description
XintCreateDataLabel Creates a DataLabel object.
XintDataLabelExtend Extends the labels.
XintDataLabelReplace Replaces the labels.
XintDataLabelShift Shifts the labels.

Function Name	Description
XintCreateDataLabel	Creates a DataLabel object.
XintDataLabelExtend	Extends the labels.
XintDataLabelReplace	Replaces the labels.
XintDataLabelShift	Shifts the labels.

XintCreateDataLabel

This function is used to create a data label and define all resources for it.

     Object XintCreateDataLabel (...)

Widget parent Parent of the new data label.
char * name Name of new data label object.
ArgList arglist List of resource settings for the new object.
Cardinal argcount Number of resources being set in arglist.

XintDataLabelExtend

This function adds more labels to the end of a data label array. The function returns False if there is a bad argument, if the function cannot be performed, or if resource XmNcopyData is false.

     Boolean XintDataLabelExtend (...)

Object object Object ID of the label array to be extended.
String * string_array Array of strings to be added to the original label array.
float * pos_array Array of positions to be added to the original position array (Specify NULL if you are not using this field).
int count Number of values being added.

XintDataLabelReplace

This function replaces a range of labels in the label array. The function returns False if there is a bad argument.

     Boolean XintDataLabelReplace(...)

Object object Object ID of the label array to be replaced.
String * string_array Array of new strings to be used to replace existing labels.
float * pos_array Array of positions to be used to replace existing positions (Specify NULL if you are not using this field).
int start Index of first value to be replaced (starts at 0).
int count Number of values being replaced.

XintDataLabelShift

This function shifts the labels contained in a DataLabel object by discarding a specified number of values at the beginning of the existing array, and adding an equal number of values to the end of the existing array.. The function returns False if argument count is bigger than the number of labels.

     Boolean XintDataLabelShift(...)

Object object Object ID of the label array to be shifted.
String * string_array Array of new strings to be appended at the end of the list of labels.
float * pos_array Array of positions to be used to be appended at the end of the position list (Specify NULL if you are not using this field).
int count Number of values to be discarded at the front and appended to the end of the existing array.

Macros

Macro XintIsDataLabel returns True if the specified object is a DataLabel object.

     Boolean XintIsDataLabel (Object object)

Widget	parent	Parent of the new data label.
char *	name	Name of new data label object.
ArgList	arglist	List of resource settings for the new object.
Cardinal	argcount	Number of resources being set in arglist.

Object	object	Object ID of the label array to be extended.
String *	string_array	Array of strings to be added to the original label array.
float *	pos_array	Array of positions to be added to the original position array (Specify NULL if you are not using this field).
int	count	Number of values being added.

Object	object	Object ID of the label array to be replaced.
String *	string_array	Array of new strings to be used to replace existing labels.
float *	pos_array	Array of positions to be used to replace existing positions (Specify NULL if you are not using this field).
int	start	Index of first value to be replaced (starts at 0).
int	count	Number of values being replaced.

Object	object	Object ID of the label array to be shifted.
String *	string_array	Array of new strings to be appended at the end of the list of labels.
float *	pos_array	Array of positions to be used to be appended at the end of the position list (Specify NULL if you are not using this field).
int	count	Number of values to be discarded at the front and appended to the end of the existing array.