| Customize Help
| Save Settings

MgraInteractive


Function Map
Syntax
Description
Parameters
- ContextGraId
Table: For specifying the 2D graphics context
- ListGraId
- GraphicType
- InitFlag
Table: For specifying optional behavior when defining the graphic
- CreationMode
Parameter Associations
Table: For defining the graphic interactively
Table: For ending user interaction
Compilation information
Synopsis
Change the state of interactivity of graphics in a 2D graphics list.
Syntax
void MgraInteractive(
MIL_ID ContextGraId, //in
MIL_ID ListGraId, //in
MIL_INT64 GraphicType, //in
MIL_INT64 InitFlag, //in
MIL_INT64 CreationMode //in
)
Description

This function changes the state of interactivity (M_INTERACTIVE_GRAPHIC_STATE) of graphics in a 2D graphics list. It is primarily used to change the state of interactivity of the graphics such that a user can interactively add a graphic of the specified type to the 2D graphics list (M_STATE_WAITING_FOR_CREATION). In addition, the function can end any interactive manipulations occurring in the display and return to an idle state (M_STATE_IDLE).

When in the waiting for creation state (GraphicType set to an M_GRAPHIC_TYPE_... value), the user is expected to define a graphic interactively in the display. Note, however, that MgraInteractive() is asynchronous and only changes the state of interactivity; it will not wait for the user to define the graphic. You should have your application wait for the user to finish defining the graphic, before calling further functions; to do so, hook a function to the change in state of interactivity using MgraHookFunction() with M_INTERACTIVE_GRAPHIC_STATE_MODIFIED. When the user begins defining the graphic, the state of interactivity of the 2D graphics list (MgraInquireList() or MgraGetHookInfo() with M_INTERACTIVE_GRAPHIC_STATE) changes to M_STATE_BEING_CREATED. After a user has defined the graphic interactively, the state of interactivity returns to M_STATE_IDLE and you can continue your application from that moment.

This function is especially useful if your application uses toolbars for a graphical user interface. For example, you can use another API to create a toolbar, with one of its buttons calling MgraInteractive() with M_GRAPHIC_TYPE_RECT. After clicking on the toolbar button, the user can define a rectangle in the display to specify where to perform processing or analysis in the image.

Unlike most other functions that modify a MIL object, you can call this function concurrently from multiple threads on the same MIL 2D graphics list (ListGraId) without using an M_MUTEX object, as long as all the other parameters of the concurrent calls do not also share data.

For more information, see Chapter 26: Generating graphics.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see which MIL system’s documentation you should use in its place and any possible differences.
Parameters
This function is not supported on the selected boards.
This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.
Parameters
ContextGraId

Specifies the identifier of the 2D graphics context. This parameter must be set to one of the following values:

function map For specifying the 2D graphics context
Click to summarizeValue Description
Click to summarize M_DEFAULT

Specifies to use the default 2D graphics context of the current MIL application context.

Note that there is a different default 2D graphics context for each thread.

(summarize)
Click to summarize M_NULL

Specifies a 2D graphics context is not necessary; you should use this setting only when GraphicType is set to M_CANCEL or M_STOP.
Click to summarize MIL 2D graphics context identifier

Specifies a valid 2D graphics context identifier, which you have allocated using MgraAlloc().
ListGraId

Specifies the identifier of a valid 2D graphics list whose state of interactivity must be changed. You must have allocated the 2D graphics list using MgraAllocList().

GraphicType

Specifies the type of graphic to define interactively and add to the 2D graphics list, or specifies to cancel or stop the 2D graphics list's state of interactivity.

See the Parameter associations section for possible values that can be specified.

InitFlag

Specifies optional behavior when defining the graphic in the display. If this behavior is not required or supported, set this parameter to M_DEFAULT. This parameter can be set to one or a combination of the following values. If the value is not supported for the graphic you are defining, MIL generates an error.

function map For specifying optional behavior when defining the graphic
Click to summarizeValue Description
Click to summarize M_FILLED

Specifies that the graphic is filled (MgraControlList() with M_FILLED set to M_TRUE).

This setting only applies to arcs (M_GRAPHIC_TYPE_ARC), polygons (M_GRAPHIC_TYPE_POLYGON), and rectangles (M_GRAPHIC_TYPE_RECT).

INQ(summarize)
Click to summarize M_ROTATE_AROUND_CORNER

Specifies that the rectangle's position is set to its corner (MgraControlList() with M_POSITION_TYPE set to M_CORNER_AND_DIMENSION). If not specified, the rectangle's position is set to its center by default.

This setting only applies to rectangles (M_GRAPHIC_TYPE_RECT).

INQ(summarize)
Click to summarize M_SECTOR

Specifies that the arc is drawn as a sector (MgraControlList() with M_ARC_STYLE set to M_SECTOR).

This setting only applies to arcs (M_GRAPHIC_TYPE_ARC).

INQ(summarize)
Click to summarize M_SQUARE_ASPECT_RATIO

Specifies that the graphic has a 1:1 (square) aspect ratio (MgraControlList() with M_CONSTRAIN_ASPECT_RATIO set to 1.0).

This setting only applies to arcs (M_GRAPHIC_TYPE_ARC) and rectangles (M_GRAPHIC_TYPE_RECT) that are not oriented (M_GRAPHIC_TYPE_RECT with M_ORIENTED_RECT).

INQ(summarize)
CreationMode

Specifies how to interactively define the graphic.

See the Parameter associations section for possible values that can be specified.

Parameter associations

The tables below list possible values for the GraphicType and CreationMode parameters.

The following GraphicType and corresponding CreationMode parameter settings let you define the graphic interactively. Specifically, the following values change the 2D graphics list's state of interactivity (MgraInquireList() with M_INTERACTIVE_GRAPHIC_STATE) to M_STATE_WAITING_FOR_CREATION, allowing you to add a graphic to the 2D graphics list by defining the graphic interactively in the display.

function map For defining the graphic interactively
Click to summarizeGraphicType Description
CreationMode
Click to summarize M_GRAPHIC_TYPE_ARC

Adds an arc to the 2D graphics list by defining the arc interactively in the display. In addition to defining an arc, you can use this value to define a circle or an ellipse (which are extensions of the arc mechanism).

(summarize)
Click to summarize M_DEFAULT

Specifies the legacy default behavior; instead of M_DEFAULT, MIL recommends using M_AXIS_ALIGNED_ELLIPSE.

Do not specify M_DEFAULT unless required for backward compatibility. M_DEFAULT ignores 2D graphics list settings (MgraControlList()) related to whether resizing is with respect to the center (M_FIXED_CENTER) or the corner (M_FIXED_CORNER) of the selection box. M_DEFAULT requires you to click on the ellipse center in the display, and drag both ellipse radii with the mouse (this can be considered a legacy version of an axis-aligned ellipse). MIL adds the ellipse to the 2D graphics list on the first mouse-down event.

(summarize)
Click to summarize M_ARC_THREE_POINTS

Specifies to define a circular arc. This requires three clicks in the display. The first and third clicks determine the arc's start angle and end angle (not necessarily in this order); the second click establishes the position of the arc. MIL adds the arc to the 2D graphics list on the first mouse-move event after the second mouse-up event. MIL does not allow the three clicks to form a straight line.

(summarize)
Click to summarize M_AXIS_ALIGNED_ELLIPSE

Specifies to define an axis-aligned ellipse. This requires you to click on one corner of the ellipse bounding box in the display, and then drag the mouse to the opposite corner. MIL adds the ellipse to the 2D graphics list on the first mouse-down event.

Instead of defining a corner of the ellipse bounding box, the first click can define the ellipse center. This can be the default behavior (MgraControlList() with M_MODE_RESIZE set to M_FIXED_CENTER), or the behavior when resizing while pressing the Alt (M_MODE_RESIZE_ALT), Ctrl (M_MODE_RESIZE_CTRL), or Shift (M_MODE_RESIZE_SHIFT) key.

You can use M_AXIS_ALIGNED_ELLIPSE to define a circle (which is a special type of ellipse), by setting the InitFlag parameter to M_SQUARE_ASPECT_RATIO. You can also call MgraControlList() with M_SQUARE_ASPECT_RATIO as a combination value for M_MODE_RESIZE to specify this as the default behavior, or the behavior when pressing the Alt (M_MODE_RESIZE_ALT), Ctrl (M_MODE_RESIZE_CTRL), or Shift (M_MODE_RESIZE_SHIFT) key.

(summarize)
Click to summarize M_CIRCLE

Specifies to define a circle. This requires you to click on a point on the circle's circumference in the display, and then drag the mouse to the diametrically opposite point. MIL adds the circle to the 2D graphics list on the first mouse-down event.

Instead of defining a point on the circle's circumference, the first click can define the circle's center. This can be the default behavior (MgraControlList() with M_MODE_RESIZE set to M_FIXED_CENTER), or the behavior when resizing while pressing the Alt (M_MODE_RESIZE_ALT), Ctrl (M_MODE_RESIZE_CTRL), or Shift (M_MODE_RESIZE_SHIFT) key.

(summarize)
Click to summarize M_GRAPHIC_TYPE_DOT

Adds a dot to the 2D graphics list by defining the dot interactively in the display.

(summarize)
Click to summarize M_DEFAULT

Specifies to define a dot. This requires you to click on the position in the display at which to place the dot. MIL adds the dot to the 2D graphics list on the mouse-down event.

(summarize)
Click to summarize M_GRAPHIC_TYPE_LINE

Adds a line to the 2D graphics list by defining the line interactively in the display.

(summarize)
Click to summarize M_DEFAULT

Specifies to define a line. This requires you to click on the line's start point in the display, and then drag the mouse to the line's end point. MIL adds the line to the 2D graphics list on the first mouse-down event.

Instead of defining the line's start point, the first click can define the line's center. This can be the default behavior (MgraControlList() with M_MODE_RESIZE set to M_FIXED_CENTER, or the behavior when resizing while pressing the Alt (M_MODE_RESIZE_ALT), Ctrl (M_MODE_RESIZE_CTRL), or Shift (M_MODE_RESIZE_SHIFT) key.

When creating the line, its end point can be seen as its angle of rotation. You can use MgraControlList() to specify the default rotation (orientation) behavior (M_MODE_ROTATE), or the rotation (orientation) behavior while pressing the Alt (M_MODE_ROTATE_ALT), Ctrl (M_MODE_ROTATE_CTRL), or Shift (M_MODE_ROTATE_SHIFT) key.

(summarize)
Click to summarize M_GRAPHIC_TYPE_POLYGON

Adds a polygon to the 2D graphics list by defining the polygon interactively in the display.

(summarize)
Click to summarize M_DEFAULT

Specifies to define a polygon. This requires you to left-click each polygon vertex in the display, except for the last vertex, which you must define with a right-click. MIL adds the polygon to the 2D graphics list on the first mouse-down event.

By default, creating a polygon while pressing the Alt key snaps the next polygon segment to 15° angles. You can call MgraControlList() with M_MODE_ROTATE... to change this behavior.

(summarize)
Click to summarize M_GRAPHIC_TYPE_POLYLINE

Adds a polyline to the 2D graphics list by defining the polyline interactively in the display.

(summarize)
Click to summarize M_DEFAULT

Specifies to define a polyline. This requires you to left-click each polyline vertex in the display, except for the last vertex, which you must define with a right-click. MIL adds the polyline to the 2D graphics list on the first mouse-down event.

By default, creating a polyline while pressing the Alt key snaps the next polyline segment to 15° angles. You can call MgraControlList() with M_MODE_ROTATE... to change this behavior.

(summarize)
Click to summarize M_GRAPHIC_TYPE_RECT

Adds a rectangle to the 2D graphics list by defining the rectangle interactively in the display. By default, you define the rectangle according to its center. This default behavior is established using MgraControlList() with M_POSITION_TYPE set to M_CENTER_AND_DIMENSION. To define the rectangle according to its top-left corner, set the InitFlag parameter (MgraInteractive()) to M_ROTATE_AROUND_CORNER. This is equivalent to setting M_POSITION_TYPE to M_CORNER_AND_DIMENSION.

(summarize)
Click to summarize M_DEFAULT

Specifies the legacy default behavior; instead of M_DEFAULT, MIL recommends using M_AXIS_ALIGNED_RECT.

Do not specify M_DEFAULT unless required for backward compatibility. M_DEFAULT ignores 2D graphics list settings (MgraControlList()) related to whether resizing is with respect to the center (M_FIXED_CENTER) or the corner (M_FIXED_CORNER) of the selection box. You also cannot use M_DEFAULT with M_ROTATE_AROUND_CORNER. M_DEFAULT requires you to click on a rectangle corner in the display, and then drag the mouse to the opposite corner (this can be considered a legacy version of an axis-aligned rectangle). MIL adds the rectangle to the 2D graphics list on the first mouse-down event.

(summarize)
Click to summarize M_AXIS_ALIGNED_RECT

Specifies to define an axis-aligned rectangle. This requires you to click on a rectangle corner in the display, and then drag the mouse to the opposite corner. MIL adds the rectangle to the 2D graphics list on the first mouse-down event. Instead of defining a rectangle corner, the first click can define the rectangle center. This can be the default behavior (MgraControlList() with M_MODE_RESIZE set to M_FIXED_CENTER), or the behavior when resizing while pressing the Alt (M_MODE_RESIZE_ALT), Ctrl (M_MODE_RESIZE_CTRL), or Shift (M_MODE_RESIZE_SHIFT) key.

You can use M_AXIS_ALIGNED_RECT to define a square (which is a special type of rectangle), by setting the InitFlag parameter to M_SQUARE_ASPECT_RATIO. You can also call MgraControlList() with M_SQUARE_ASPECT_RATIO as a combination value for M_MODE_RESIZE to specify this as the default behavior, or the behavior when pressing the Alt (M_MODE_RESIZE_ALT), Ctrl (M_MODE_RESIZE_CTRL), or Shift (M_MODE_RESIZE_SHIFT) key.

(summarize)
Click to summarize M_ORIENTED_RECT

Specifies to define an oriented rectangle. This requires three clicks in the display. By default, the first click defines a fixed corner of the rectangle, the second click defines its width (a line extending to the fixed corner), and the third click defines its height on one side of the width line. MIL adds the rectangle to the 2D graphics list on the first mouse-up event.

Instead of defining the rectangle's width using a fixed corner, the first two clicks can define the width symmetrically on both sides of a center point; that is, the first click represents the fixed center of the width line, and the second click extends the width line equally on both sides of the fixed center. This can be the default behavior (MgraControlList() with M_MODE_RESIZE set to M_FIXED_CENTER), or the behavior when pressing the Alt (M_MODE_RESIZE_ALT), Ctrl (M_MODE_RESIZE_CTRL), or Shift (M_MODE_RESIZE_SHIFT) key.

Instead of defining the rectangle's height on one side of the width line, the third click can define the height symmetrically on both sides; that is, moving your mouse above or below the width line (established by the first two clicks) adjusts the height equally on the other side until the third click. This can be the default behavior (MgraControlList() with M_MODE_RESIZE_SECONDARY_DIMENSION), or the behavior when pressing the Alt (M_MODE_RESIZE_SECONDARY_DIMENSION_ALT), Ctrl (M_MODE_RESIZE_SECONDARY_DIMENSION_CTRL), or Shift (M_MODE_RESIZE_SECONDARY_DIMENSION_SHIFT) key.

You can use M_ORIENTED_RECT to define a square (which is special type of rectangle), by setting the InitFlag parameter to M_SQUARE_ASPECT_RATIO. You can also call MgraControlList() with M_SQUARE_ASPECT_RATIO as a combination value for M_MODE_RESIZE to specify this as the default behavior, or the behavior when pressing the Alt (M_MODE_RESIZE_ALT), Ctrl (M_MODE_RESIZE_CTRL), or Shift (M_MODE_RESIZE_SHIFT) key.

(summarize)

The following GraphicType and corresponding CreationMode parameter settings change the 2D graphics list's state of interactivity to idle (M_STATE_IDLE) and will cancel or stop any user manipulations in progress.

function map For ending user interaction
Click to summarizeGraphicType Description
CreationMode
Click to summarize M_CANCEL

Changes the 2D graphics list's state of interactivity to idle (M_STATE_IDLE) and cancels any user manipulations in progress. A cancel operation will stop any user manipulation in progress and undo any changes that occurred. If, for example, a user was rotating a graphic with the rotate handle, canceling will stop the user from rotating it further and return the graphic to the angle it was set to before the user started manipulating it. If a user is interactively defining a graphic to add to the 2D graphics list, canceling will stop the defining process and not add any graphic to the list.

(summarize)
Click to summarize M_DEFAULT

Specifies that this parameter is not required.
Click to summarize M_STOP

Changes the 2D graphics list's state of interactivity to idle (M_STATE_IDLE) and stops any user manipulations in progress. A stop operation ends any user manipulations in progress and leaves any changes made to the graphic. If, for example, a user was rotating a graphic with the rotate handle, stopping will prevent the user from rotating it further and leave the graphic at that angle. If a user is interactively defining a graphic to add to the 2D graphics list, stopping will prevent the user from defining it further and adds the graphic to the list with the current dimensions.

(summarize)
Click to summarize M_DEFAULT

Specifies to ignore this parameter is not required.
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
DEFAULT NULL FILLED ROTATE AROUND CORNER SECTOR SQUARE ASPECT RATIO GRAPHIC TYPE ARC DEFAULT ARC THREE POINTS AXIS ALIGNED ELLIPSE CIRCLE GRAPHIC TYPE DOT DEFAULT GRAPHIC TYPE LINE DEFAULT GRAPHIC TYPE POLYGON DEFAULT GRAPHIC TYPE POLYLINE DEFAULT GRAPHIC TYPE RECT DEFAULT AXIS ALIGNED RECT ORIENTED RECT CANCEL DEFAULT STOP DEFAULT