Vvidget Code Reference Manual

Vvidget Code > API > iOS > Embedded > Event Qualifiers

The Event Qualifiers are defined by the classes shown below.

VvidgetCodeLineGraphEventQualifierThe event qualifier for a line graph.
VvidgetCodeGroupEventQualifierThe event qualifier for a group graphic.
VvidgetCodeBarChartEventQualifierThe event qualifier for a bar or column chart.
VvidgetCodePieChartEventQualifierThe event qualifier for a pie chart.
VvidgetCodePerspectiveScatterChartEventQualifierThe event qualifier for a perspective scatter chart.
VvidgetCodePerspectiveSurfaceChartEventQualifierThe 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.


Linkage

Add the Event Qualifier functionality to your project by adding all the headers in /Library/Vvidget/ios/include to your project and one of the libraries referenced below for a specific build Configuration.

Definition:/Library/Vvidget/ios/include/VvidgetCode*EventQualifier.h
Device Implementation:/Library/Vvidget/ios/lib/device/libVvidget.a
Simulator Implementation:/Library/Vvidget/ios/lib/simulator/libVvidget.a


VvidgetCodeEventQualifier Method Definitions

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 touch.

- (double)get_VC_hit_x_value

Returns the x-value coordinate hit by the touch. 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 touch. 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.


VvidgetCodeLineGraphEventQualifier Method Definitions

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 touch.

- (unsigned)get_VC_vertex_hit_index

Returns the vertex (data point) index hit by the touch.


VvidgetCodeGroupEventQualifier Method Definitions

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 touch. See Maps for an example use.

- (NSString *)get_VC_hit_description

Returns the description of the graphic element in the group hit by the touch. See Maps for an example use.


VvidgetCodePerspectiveScatterChartEventQualifier Method Definitions

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 touch.

- (unsigned)get_VC_vertex_hit_index

Returns the vertex (data point) index hit by the touch.


VvidgetCodePerspectiveSurfaceChartEventQualifier Method Definitions

The following defines each method that is used with an object (instance) of the VvidgetCodePerspectiveSurfaceChartEventQualifier type, a subclass of VvidgetCodeEventQualifier.

- (unsigned)get_VC_cell_hit_index

Returns the cell index hit by the touch.

- (double)get_VC_hit_3d_x_value

Returns the x-value on the surface that is hit by the touch.

- (double)get_VC_hit_3d_y_value

Returns the y-value on the surface that is hit by the touch.

- (double)get_VC_hit_3d_z_value

Returns the z-value on the surface that is hit by the touch.


VvidgetCodeEventQualifier Target Method Protocol

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.

unsigned data_index = [event_qualifier get_VC_data_graphic_hit_index];

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

NOTE: hovering does not make sense on a iOS touch device thus this method is never called.

- (void)VC_perform_data_graphic_unhover

NOTE: hovering does not make sense on a iOS touch device thus this method is never called.


Actual Use

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.




© Copyright 1993-2011 by VVimaging, Inc. (VVI); All Rights Reserved. Please email support@vvi.com with any comments you have concerning this documentation. See Legal for trademark and legal information.