Users Guide

About Events in VisionPro

VisionPro objects fire, or raise, events to let your application know that something has happened or that the state of an object has changed. In order to be notified when an event occurs, your application uses event handlers. VisionPro objects call your event handlers when the events fire.

This topic describes the kinds of events that VisionPro classes can fire and how you should write your event handlers. You can learn more about events in Handling and Raising Events in the .NET Framework Developer's Guide.

The following table summarizes the types of events that VisionPro uses.

Table 1. Event types
Event Type Description
Changed Events

Changed events are fired whenever the state of a VisionPro object changes. Changed event parameters include detailed information about how the object has changed.

Tool Events

Tool events are fired by VisionPro tools at well-defined times during the execution of the tool.

Acquisition Events

Acquisition events are fired by the acquisition system to indicate the progress of an acquisition. You can use these events to determine when it is safe to move a part out of the camera's field of view.

Collection Events

VisionPro contains many collection classes. These collection classes fire specific events when items are added, changed, moved, or removed from a collection.

Interactive Shape Events

VisionPro graphic shape objects (circles, lines, rectangles, and so on) fire events when users manipulate them. These events include standard changed events as well as special events related to user dragging of shapes.

Coordinate Space Tree Events

The VisionPro coordinate space tree objects fire special events to indicate specific changes in a coordinate space tree such as the addition or deletion of a space or a change in a space's transformation.

Display Events

The display control fires several special events to indicate certain user actions such as clicking, double clicking, or dragging shapes.

Changed Events

The most common type of event fired by a VisionPro object is a changed event. Changed events are used by VisionPro objects to indicate that the state of the object has changed. For example, when you change the brightness of an ICogAcqFifo it fires a Changed event that you can handle if you want to do something in response to the change or ignore if you do not.

VisionPro Object State

A VisionPro object's state is made up of all of the attributes of that object. Much of an object's state is contained in its various properties. An object's state also includes items that are returned by an object's methods (such as result graphics).

Each part of an object's state (each individual piece of information that you can obtain by calling a property getter function or a method) has a unique state flag. State flags are read-only bit flags that VisionPro passes to an event handler so that it can determine what changed. The name of the field corresponds to affected state item. State flags are defined as fields within a class, such as the fields of CogCircle, or as fields in a class of their own, such as CogAcqFifoStateFlags. Typically, state flags that pertain to a single class are defined within a class, and state flags the pertain to several interfaces and classes are defined in their own class.

State Change

Whenever the state of a VisionPro object changes, that object fires a Changed event which invokes a changed event handler that you define. Following the .NET convention for event handlers, the first argument is the object that raised the event, and the second argument is an object that describes the change. In the case of changed events in VisionPro, this is a CogChangedEventArgs object. It has a StateFlags field what tells your application what it needs to know about the new state of the object.

The value of the StateFlags field of a CogChangedEventArgs is set to the bitwise OR of every state flag that corresponds to a changed state item.

Using Changed Events

How you use changed events depends in large part on why you are using changed events. A typical example is to use a changed event to acquire a new image whenever certain acquisition FIFO properties change. There are two steps in writing a changed event handler.

First, associate a changed event handler with the changed event:

myAcqFifo.Changed += new CogChangedEventHandler(myAcqFifo_Changed);

Second, write the event handler itself:

private void myAcqFifo_Changed(object sender, CogChangedEventArgs e) {
    int tNum;

    if ( (e.StateFlags & CogAcqFifoStateFlags.SfBrightness) != 0)
        System.Console.WriteLine("Brightness changed");
    if ( (e.StateFlags & CogAcqFifoStateFlags.SfContrast) != 0)
        System.Console.WriteLine("Contrast changed");

    cogDisplay1.Image = ((ICogAcqFifo) sender).Acquire(out tNum);
}

When your event handler is executes, you can examine the changed event argument to determine how the state has changed. You can also cast the sender argument to the appropriate type to examine the object that raised the event.

Note: If you are using QuickBuild and using your own changed event handler, bear in mind that QuickBuild may change properties (such as triggering) that may invoke your changed even handler. Your changed event handler must be able to handle this case.

Keep in mind that events fired in VisionPro objects that are part of VisionPro tools do not propagate to the tool. If you are working with VisionPro tools and you want to handle changed events from the component objects within the tool, you must set up separate changed event handlers for the component objects.

Suspending Changed Events

If you are making many changes to an object, you may not want to receive a changed event for every property you change. In these cases, you can use SuspendChangedEvent to keep changed events from firing. When you call ResumeAndRaiseChangedEvent, and at least one event would have fired during the time events were suspended, a single changed event fires.

Tool Events

Each VisionPro tool implements the ICogTool interface which includes two tool-related events. All VisionPro tools fire these events under the same conditions. The VisionPro tool group framework makes use of these events to manage the updating of data links between the tools in a tool group. Your application can use these events to help manage the execution of tools and tool groups, and it can use these events to modify the results produced by individual tools during the execution of a tool group.

The following table describes the individual tool events.

Table 2. Tool events
Event Description
Ran

This event is fired after the tool has completed its Run method. Note that the CogToolGroup class uses this event to update data links between tools in the tool group. If your application sinks this event, it may be called before or after the links are updated. If you want to use an event to modify tool results, use the Changed event.

Running

This event is fired as the tool's Run method starts.

Acquisition Events

The VisionPro acquisition system implements three events that fire during the image acquisition process.

The Changed event fires when an acquisition FIFO property is changed.

The Flushed event fires when an acquisition FIFO is flushed.

The MovePart event fires after the camera has integrated the image, but (possibly) before it is available in video memory. When this event fires, it is safe to change the scene visible by the camera. The move part event has two parameters: the ticket of the acquisition request and a trigger sequence number..

The Complete event fires when an acquisition has been completed and the image may be available. (The complete event fires even if an image is not available when the acquisition times out.) The complete event has two parameters: the ticket of the acquisition request that is being completed and a trigger sequence number.

The Overrun event fires when an acquisition fails because, even though the acquisition system was able to obtain the required resources, it was unable to start the acquisition in a timely fashion. Either a trigger was detected but the acquisition system could not start the acquisition, or trigger signals arrived faster than the acquisition system could handle them. The overrun event has two parameters: the ticket that indicates whether a trigger was missed or whether the acquisition was overrun and a trigger sequence number.

Collection Events

Most of VisionPro's collection classes, such as CogGraphicCollection and CogStringCollection, as well as the ones that provide multiple parameters to vision tools, such as CogBlobMeasureCollection and CogCaliperScorers, fire ICogCollectionEvents.

Collection events come in pairs. One fires before an operation, and the other fires after an operation. For example, the Clearing event fires before a collection is cleared, and the Cleared event fires after a collection is cleared. Depending on your application, you may want to handle either or both kinds of events.

The following table lists the collection events.

Table 3. Collection events
Event Description
Changed

Fires when a collection is loaded from a persistence archive.

Clearing

Fires before the entire collection is cleared.

The second argument to the event handler is a EventArgs (no event data).

Cleared

Fires after the entire collection is cleared.

The second argument to the event handler is a EventArgs (no event data).

InsertingItem

Fires before an item is inserted.

The second argument to the event handler is a CogCollectionInsertEventArgs.

InsertedItem

Fires after an item is inserted.

The second argument to the event handler is a CogCollectionInsertEventArgs.

RemovingItem

Fires before an item is removed.

The second argument to the event handler is a CogCollectionRemoveEventArgs.

RemovedItem

Fires after after an item is removed.

The second argument to the event handler is a CogCollectionRemoveEventArgs.

ReplacingItem

Fires before an item is replaced.

The second argument to the event handler is a CogCollectionReplaceEventArgs.

ReplacedItem

Fires after after an item is replaced.

The second argument to the event handler is a CogCollectionReplaceEventArgs.

MovingItem

Fires before an item is moved to a new index.

The second argument to the event handler is a CogCollectionMoveEventArgs.

MovedItem

Fires after after an item is moved to a new index.

The second argument to the event handler is a CogCollectionMoveEventArgs.

Additionally, keyed collections, such as CogStringCollection, fire two additional events when keys change:

Table 4. Keyed collection events
Event Description
KeyChanging

Fires before an item's key is changed.

The second argument to the event handler is a CogCollectionKeyChangeEventArgs.

KeyChanged

Fires after an item's key is changed.

The second argument to the event handler is a CogCollectionKeyChangeEventArgs.

Interactive Shape Events

All of the VisionPro shapes fire changed events when you make a change to their properties. For instance, if you change a circle's CenterX and CenterY properties, two changed events will fire, one for each property (unless you have suspended changed events). If you set the circle's Interactive property and drag it, a changed event fires if its location or radius is changed.

Interactive shapes can also fire events as they are dragged. The Dragging event fires as the shape is being moved or resized with the mouse. The event handler's CogDraggingEventArgs argument provides a DragGraphic property that contains the shape that would result if dragging ended. The event fires when you release the mouse button. The event handler's CogDraggingEventArgs argument provides a DragGraphic property that contains the shape that resulted from dragging the original shape.

Coordinate Space Tree Events

CogCoordinateSpaceTree fires events whenever a change is made to the tree. The following table lists the coordinate space tree events:

Table 5. Coordinate space tree events
Event Description
Changed

Fires when a coordinate space tree is loaded from a persistence archive.

NameChanged

Fires when the name of a coordinate space changes.

The second argument to the event handler is a CogNameChangedEventArgs that provides NewSpaceName and OldSpaceName properties.

SpaceAdded

Fires when a new coordinate space is added to the tree.

The second argument to the event handler is a CogSpaceAddedEventArgs that provides a NewSpaceName property.

SubtreeDeleted

Fires when a subtree has been deleted from a coordinate space tree.

The second argument to the event handler is a CogSubtreeDeletedEventArgs that provides a OldSpaceName property.

SubtreeMoved

Fires when a subtree is moved within a coordinates space tree.

The second argument to the event handler is a CogSubtreeMovedEventArgs that provides NewSpaceName and OldSpaceName properties.

TransformChanged

Fires when a coordinate space's transformation object changes.

The second argument to the event handler is a CogTransformChangedEventArgs that provides a SpaceName property.

TreeAdded

Fires when a new coordinate space tree is added to the tree.

The second argument to the event handler is a CogTreeAddedEventArgs that provides a NewSpaceName property.

Display Events

The CogDisplay control fires events in response to changes in the state of the control and in response to user actions such as mouse clicks and keyboard presses.

The Changed event fires whenever there is a change to the state of the display control itself. For instance, this event fires when you make scroll bars visible or invisible or when you change the display's zoom factor.

The following table lists the events that the Display Control fires in response to mouse actions:

Table 6. Mouse-related events fired by the Display Control
Event Description
Click

Fires when the user clicks and releases the left mouse button in the display control.

The second argument to the event handler is a EventArgs (no event data).

DoubleClick

Fires when the user double-clicks and releases the left mouse button in the display control.

The second argument to the event handler is a EventArgs (no event data).

The DoubleClick event fires if the two clicks take place within the system wide double click time. Other wise, individual Click events fire.

DraggingStopped

Fires when the user stops dragging an object that implements ICogGraphicInteractive

The second argument to the event handler is a EventArgs (no event data).

This event fires in addition to any specific even that the shape might fire.

MouseDown

Fires when the user clicks either mouse button in the display control.

The second argument to the event handler is a MouseEventArgs that provides properties that describe the mouse location and mouse button states.

MouseMove

Fires when the user moves the mouse in the display control.

The second argument to the event handler is a MouseEventArgs that provides properties that describe the mouse location and mouse button states.

MouseUp

Fires when the user releases either mouse button in the display control.

The second argument to the event handler is a MouseEventArgs that provides properties that describe the mouse location and mouse button states.

The following table lists the events that the Display Control fires in response to keyboard actions:

Table 7. Key-related events fired by the Display Control
Event Description
KeyDown

Fires when the user presses a key while the Display Control has input focus.

The second argument to the event handler is a KeyEventArgs that provides properties that describe the keyboard states.

KeyUp

Fires when the user releases a key while the Display Control has input focus.

The second argument to the event handler is a KeyEventArgs that provides properties that describe the keyboard states.

KeyPress

Fires when the user presses a key while the Display Control has input focus. If the key does not have an ASCII value (such as an arrow key) this event does not fire, though KeyDown and KeyUp do.

The second argument to the event handler is a KeyPressEventArgs that provides properties that return the pressed key.