Vvidget Code > API > Mac OS X > Embedded > Event Qualifiers
The Event Qualifiers are defined by the classes shown below.
VvidgetCodeLineGraphEventQualifier | The event qualifier for a line graph. |
VvidgetCodeGroupEventQualifier | The event qualifier for a group graphic. |
VvidgetCodeBarChartEventQualifier | The event qualifier for a bar or column chart. |
VvidgetCodePieChartEventQualifier | The event qualifier for a pie chart. |
VvidgetCodePerspectiveScatterChartEventQualifier | The event qualifier for a perspective scatter chart. |
VvidgetCodePerspectiveSurfaceChartEventQualifier | The event qualifier for a perspective surface chart. |
Once associated with a dictionary parser the event qualifier process events and callback upon a target which must implement the target method protocol defined below.
Add the Event Qualifiers functionality to your project by adding all the headers in /Library/Vvidget/macosx/include to your project and one of the frameworks referenced below.
| Definition: | /Library/Vvidget/macosx/include/VvidgetCode*EventQualifier.h |
| Shared Frameworks: | /Library/Frameworks/Vvidget_*.framework |
| Embedded Frameworks: | /Library/Vvidget/EmbeddedFrameworks/Vvidget_*.framework |
If you use the Embedded Frameworks then you will need to add a build copy phase to your project to copy the Vvidget Frameworks into your application bundle. See Deploy for details.
The following defines each method that is used with an object (instance) of the VvidgetCodeEventQualifier type.
- (unsigned)get_VC_data_graphic_hit_index
| Returns the index of the data graphic (a line, wedge or bar) hit by the mouse. |
- (double)get_VC_hit_x_value
| Returns the x-value coordinate hit by the mouse. Notice that the x-value is Indigenous coordinates meaning that if the graphic is on a graph then the x-value is in units of the graph's x-coordinates. For example: for a polar graph the x-value is theta in degrees. |
- (double)get_VC_hit_y_value
| Returns the y-value coordinate hit by the mouse. Notice that the y-value is Indigenous coordinates meaning that if the graphic is on a graph then the y-value is in units of the graph's y-coordinates. For example: for a polar graph the y-value is radius which is a unitless value. |
- (void)set_VC_target:(id)the_target
| Sets the target of the receiver to the_target. the_target must implement the event qualifier target protocol as shown below. |
- (BOOL)VC_is_valid_index:(id)the_index
| If the_index is valid then this method returns YES, otherwise it returns NO. A return of YES indicates that the index represents a hit component, otherwise the component was not hit. |
The following defines each method that is used with an object (instance) of the VvidgetCodeLineGraphEventQualifier type, a subclass of VvidgetCodeEventQualifier.
- (unsigned)get_VC_segment_hit_index
| Returns the segment index hit by the mouse. |
- (unsigned)get_VC_vertex_hit_index
| Returns the vertex (data point) index hit by the mouse. |
The following defines each method that is used with an object (instance) of the VvidgetCodeGroupEventQualifier type, a subclass of VvidgetCodeEventQualifier.
- (NSString *)get_VC_hit_name
| Returns the name of the graphic element in the group hit by the mouse. See Maps for an example use. |
- (NSString *)get_VC_hit_description
| Returns the description of the graphic element in the group hit by the mouse. See Maps for an example use. |
The following defines each method that is used with an object (instance) of the VvidgetCodePerspectiveScatterChartEventQualifier type, a subclass of VvidgetCodeEventQualifier.
- (unsigned)get_VC_segment_hit_index
| Returns the segment index hit by the mouse. |
- (unsigned)get_VC_vertex_hit_index
| Returns the vertex (data point) index hit by the mouse. |
The following defines each method that is used with an object (instance) of the VvidgetCodeLineGraphEventQualifier type, a subclass of VvidgetCodeEventQualifier.
- (unsigned)get_VC_cell_hit_index
| Returns the cell index hit by the mouse. |
- (double)get_VC_hit_3d_x_value
| Returns the x-value on the surface that is hit by the mouse. |
- (double)get_VC_hit_3d_y_value
| Returns the y-value on the surface that is hit by the mouse. |
- (double)get_VC_hit_3d_z_value
| Returns the z-value on the surface that is hit by the mouse. |
The following defines each method that must be implemented by the target of an event qualifier.
- (void)VC_perform_data_graphic_hit
|
This method is called when a data graphic was hit. It is incumbent upon the receiver to use the callback methods of the event qualifier for processing. For example.
queries (calls back upon) event_qualifier to retrieve the index of the data graphic hit. From this index you can determine the data set hit by performing your own lookup based upon the sequence that you loaded data (via the key data_I for example). |
- (void)VC_perform_data_graphic_unhit
| This method is called when a data graphic was unhit. This gives the target the opportunity to undo whatever processing was done in a hit method. You need to implement this method, but its body can be empty. |
- (void)VC_perform_data_graphic_hover
| This method is called when a data graphic was hovered, meaning the cursor is currently over the graphic but the mouse button was not pressed. |
- (void)VC_perform_data_graphic_unhover
| This method is called when a data graphic was unhovered. This gives the target the opportunity to undo whatever processing was done in a hit method. You need to implement this method, but its body can be empty. |
The following is a complete calling sequence of a line graph event qualifier and installs the event qualifier into the view for processing by the controller.
event_qualifier = [[VvidgetCodeLineGraphEventQualifier alloc] init];
[event_qualifier set_VC_target:my_target];
[dictionary_parser VC_associate_with_event_qualifier:event_qualifier];
Given the above, the object my_target must implement the following methods.
- (void)VC_perform_data_graphic_hit
{
unsigned data_index, segment_index, vertex_index;
CGPoint hit_point;
data_index = [event_qualifier get_VC_data_graphic_hit_index];
segment_index = [event_qualifier get_VC_segment_hit_index];
vertex_index = [event_qualifier get_VC_vertex_hit_index];
if([VvidgetCodeEventQualifier VC_is_valid_index:vertex_index])
{
hit_point = [self EX_point_for_curve_index:(data_index - 1) point_index:(vertex_index - 1)];
printf("Hit curve %d at point %d with x = %g , y = %g\n", data_index, vertex_index, hit_point.x, hit_point.y);
}
else if([VvidgetCodeEventQualifier VC_is_valid_index:segment_index])
{
printf("Hit curve %d at segment %d\n", data_index, segment_index);
}
else
{
printf("Hit curve %d\n", data_index);
}
return;
}
- (void)VC_perform_data_graphic_unhit
{
unsigned data_index, segment_index, vertex_index;
CGPoint hit_point;
data_index = [event_qualifier get_VC_data_graphic_hit_index];
segment_index = [event_qualifier get_VC_segment_hit_index];
vertex_index = [event_qualifier get_VC_vertex_hit_index];
if([VvidgetCodeEventQualifier VC_is_valid_index:vertex_index])
{
hit_point = [self EX_point_for_curve_index:(data_index - 1) point_index:(vertex_index - 1)];
printf("Hovering over curve %d at point %d with x = %g , y = %g\n", data_index, vertex_index, hit_point.x, hit_point.y);
}
else if([VvidgetCodeEventQualifier VC_is_valid_index:segment_index])
{
printf("Hovering over curve %d at segment %d\n", data_index, segment_index);
}
else
{
printf("Hovering over curve %d\n", data_index);
}
return;
}
- (void)VC_perform_data_graphic_hover
{
unsigned data_index, segment_index, vertex_index;
CGPoint hit_point;
data_index = [event_qualifier get_VC_data_graphic_hit_index];
segment_index = [event_qualifier get_VC_segment_hit_index];
vertex_index = [event_qualifier get_VC_vertex_hit_index];
if([VvidgetCodeEventQualifier VC_is_valid_index:vertex_index])
{
hit_point = [self EX_point_for_curve_index:(data_index - 1) point_index:(vertex_index - 1)];
printf("Hovering over curve %d at point %d with x = %g , y = %g\n", data_index, vertex_index, hit_point.x, hit_point.y);
}
else if([VvidgetCodeEventQualifier VC_is_valid_index:segment_index])
{
printf("Hovering over curve %d at segment %d\n", data_index, segment_index);
}
else
{
printf("Hovering over curve %d\n", data_index);
}
return;
}
- (void)VC_perform_data_graphic_unhover
{
printf("Not over a graphic\n");
return;
}
The methods above refer to the following method, which is roughed in to demonstrate a method which returns a data point value based upon curve and point index.
- (CGPoint)EX_point_for_curve_index:(unsigned)a_curve_index point_index:(unsigned)a_point_index
{
/* Assign the data value from a_curve_index and a_point_index. */
CGPoint a_point;
a_point.x = fx(a_curve_index, a_point_index); // example
a_point.y = fy(a_curve_index, a_point_index); // example
return a_point;
}
| Please help improve this documentation. If a section is hard to understand, there is a typo, you would like a new section added, or you detect any other improvement that can be made then please email support@vvi.com with your information. |