Picking allows users to select and interact with overlays on the screen, and can be used to create interactive UI elements. Picks are usually executed in response to a mouse click, mouse move, key press, or any combination of these.

The ExecuteOverlayPick method returns information about the overlays that are at a specified pixel. The input is an x and y coordinate. The origin is the top, left corner of the 3D control. In most cases, the input to ExecuteOverlayPick will be the location of the mouse cursor to pick overlays under the cursor.

ExecuteOverlayPick returns a collection of pick results, IAgGxOverlayPickResultCollection. Each pick result, IAgGxOverlayPickResult, represents one overlay that was picked. IAgGxOverlayPickResult provides the overlay that was picked, the location of the pick relative to the overlay, and the location of the pick relative to the screen. If muliple overlays are picked at the given pixel, the collection will contain each of the overlays that were picked, sorted by their z-order. For instance, if a texture overlay is added to a panel overlay and a pick is executed on a pixel of the texture overlay, the first pick result in the collection will contain the texture overlay, and the second pick result in the collection will contain that overlay's parent, the panel overlay. ExecuteOverlayPick is shown in the example below.

CopyC#

IAgGxOverlayPickResultCollection collection = scene.ExecuteOverlayPick(x, y);
if (!collection.Empty)
{
    IAgGxOverlayPickResult pickResult = collection[0];
    IAgGxOverlay overlay = pickResult.Overlay;
    IAgGxOverlayConstantPoint overlayLocation = pickResult.Position;
    IAgGxOverlayConstantPoint screenLocation = pickResult.ScreenPosition;
}

It is sometimes useful when building UI elements with overlays to disable picking on a certain overlay. If an overlay's PickingEnabled property is set to false, the overlay will not be picked during calls to ExecuteOverlayPick, as seen in the example below:

CopyC#

IAgGxOverlayPickResultCollection collection = scene.ExecuteOverlayPick(x, y);
if (!collection.Empty)
{
    IAgGxOverlayPickResult pickResult = collection[0];
    IAgGxOverlay overlay = pickResult.Overlay;
    overlay.PickingEnabled = false;
}
// Collection will not contain the overlay that was picked above
collection = scene.ExecuteOverlayPick(x, y);