| Displaying Images and Overlays |
|
Images are normally displayed in a Multiple Document Interface (MDI) child of the main application window. This "workspace" window is controlled by an instance of the McWindow class. The McWindow instance controlling each MDI image window is an Item in the Application.Windows collection. Window objects may be accessed by name or zero-based index number from this collection.
The McWindow.View property exposes the McView object, an ActiveX control, that is actually doing the image display.
'Example: show the first window's image name
Debug.Print Windows(0).View.ImageToDisplay.Name
The McWindows events most likely to be of interest are the New, Activate and Close events. These three events allow you to track the creation of McWindow instances, when a window becomes the ActiveWindow, and when a window is closed. Most of the other McWindow events are ones that are generated by the enclosed McView object.
Control of the windows display is done via a McView ActiveX control (the McWindow.View property). The ImageToDisplay property exposes the McImage instance that is being displayed in the View. The actual rendering of image data onto a display context is handled by the viewer's Display property, which is a tightly bound McDisplay object instance. The viewer is capable of blending two images, applying an overlay mask based on a third image, panning and scrolling each image independently, and zooming to any magnification. It is also capable of displaying a particular frame of a multi-frame image, as well as displaying a frame sequence at a specified rate. The Display is also responsible for handling cutting, copying and pasting image and display renderings to and from the clipboard, as well as previewing a paste operation (e.g., see EditPasteAoi).
There may be multiple McView objects (owned by multiple McWindow objects) all displaying the same ImageToDisplay. The rendering of the image data in each view may differ from the others in many ways, most typically by different Pan, Scroll and Magnification properties.
The McView object, via its Display engine, is only directly responsible for displaying image data into the display context. Drawing upon the display context and interaction with the window are handled by "overlays" after image display has been completed.
~166.png)  ~240.png)  ~240.png) ~262.png) ~240.png) |
Overlays are McGraphOverlay objects that receive a notification from a McView (or a McDisplay) when it is their turn to draw upon the display surface. The McGraphOverlay collection holds a list of primitive graphical elements, which are all derived from the McGraphObj base class. Objects of the McGraphObj base class type are not createable, instead one of the derived types must be created via the Add method. The best way to get examples of manipulation of these individual graphical objects is to use the Annotation toolbar while recording a macro or looking at the Audit window.
Notice that in the display object model, McGraphOverlay objects do not appear as children of any of the image display components, but rather as descendents of the ImageToDisplay. This is because overlays are notify sinks for the McView events, not properties of the view. McGraphOverlay objects that are descendents of McImage objects are automatically made notify sinks of any McWindow.View for which the image becomes the view's ImageToDisplay. Thus identical overlay drawings (suitably positioned and magnified) will automatically appear on each of multiple views that are displaying the same ImageToDisplay.
Most views have multiple McGraphOverlay objects connected to them as notify sinks (though usually only a few of these overlays will be displaying anything at any one time). These McGraphOverlay objects are completely independent and know nothing of each other. Their order of notification can be altered with the McDisplay.SetNotifyPriority method; the overlay receiving notifications last draws on top of all the others.
A number of predefined McGraphOverlay objects are automatically created as descendent properties of each McImage object. The one you would most likely use directly is the McImage.AnnotationOverlay, which is the overlay upon which all of the Annotation toolbar tools place their graphical objects (and the overlay on which tools that move or edit annotations operate).
'Example: clear all annotations from the ActiveImage
ActiveImage.AnnotationOverlay.RemoveAll
Each instance of the McFeatures-derived objects McRegions, McLines and McPoints can automatically display their features on an overlay created in their own private DisplayOverlays collection. Normally only one such overlay is used for feature display, McFeatures.AutoDisplayOverlay, and you rarely need to access it, because feature display is done for you automatically. Occasionally you may need to access this overlay to hide it or to start some tool to interact with some features (e.g., the McImage.Aoi property is a McRegions).
'Example: hide ActiveImage.Aoi on all images without changing the Aoi
ActiveImage.Aoi.AutoDisplayOverlay.Visible = False
Another image overlay property is the McImage.ImageToolsOverlay, which is an overlay reserved for use by tools that want to draw graphic elements during their interaction with the user.
User interaction with image and/or overlay data could be implemented by directly tracking events such as the MouseMove or MouseDown that are fired by McWindow objects. And when doing development of simple macros for your own use you might wish to use this approach. However, the user can only be interacting with the image for one purpose at a time, and in the general case conflicts are inevitable using this approach (e.g., was that mouse click supposed to indicate the start of an Aoi rectangle, or was it to select an Annotation graph object?).
So there needs to be some cooperative mechanism to indicate which image-interaction "tool" is in charge, and there also need to be mechanisms to find out what the tool is, which overlay is the target of its actions and so on. This cooperative user interaction is mediated by the existance of a single active McGraphToolServer object which is controlled by a single McGraphOverlay object. Only one McGraphToolServer object may be active at one time, and it is always exposed as the McGraphOverlay.ActiveTool property of any overlay instance, not just the one that the tool is targeting (that overlay is available as the McGraphToolServer.ActiveOverlay property); if no tool is active, then the McGraphOverlay.ActiveTool will be Nothing.
A tool is started on an overlay with the McGraphOverlay.SelectTool method, supplying ToolClassName and GraphObjClassName arguments as necessary. The associated McGraphToolServer properties are the ToolClassName and ActiveClassName properties, which correspond to the McGraphOverlay.SelectTool method's ToolClassName and GraphObjClassName arguments, respectively.
There are "built-in" tools to allow the user to interactively create all of the McGraphObj-derived graph object types (e.g., a McGraphObjRect) and a tool to allow users to select, move and edit any McGraphObj object on a particular overlay. The built-in object creation tools have a blank McGraphOverlay.SelectTool method ToolClassName argument, and a GraphObjClassName argument that is the name of the type of object to be created.
'Example: start the built-in tool to create rounded-rectangle annotation objects
ActiveImage.AnnotationOverlay.SelectTool "", "McGraphObjRRect"
The built-in graph object selection tool has a McGraphOverlay.SelectTool method ToolClassName argument of "McGraphToolSelect", and a GraphObjClassName argument that is blank (or missing).
'Example: start the built-in selection tool to select/move/edit annotation objects
ActiveImage.AnnotationOverlay.SelectTool "McGraphToolSelect"
If both the ToolClassName and GraphObjClassName arguments are blank or missing, then any ActiveTool is shut down.
'Example: stop any tool on any overlay
ActiveImage.AnnotationOverlay.SelectTool
The the McGraphOverlay.SelectTool method ToolClassName argument is also allowed to be the ProgID of a COM object exposing the McGraphToolServer class and prepared to handle the McView events. These custom tools handle many sorts of user interactions. Ones supplied with the application include the McPanScrollTool and the McRotateGridTool, for example.
~242.png)
