Object Selection

Object selection functions let add-ons read the objects selected by the user, and optionally change that selection when the add-on is explicitly acting as a selection tool.

Selection is one of the main ways users tell an add-on what they want to inspect, compare, or analyze.

For example, a dogfight analysis add-on can read the two aircraft selected in a viewport, then display geometry, distance, angles, or scoring information for that pair.

Why selection is viewport-aware

Tacview 2 can display several viewports at the same time.

Each viewport can show different layers, camera views, charts, or analysis tools. Because of that, selection can also be specific to a viewport.

This is not meant to make add-ons more complicated. It lets users build flexible workspaces.

For example, a user could open several viewports and use the same add-on to analyze different object pairs at the same time. Each viewport can keep its own selection, and each add-on instance can react to the objects selected in that viewport.

A well-programmed add-on should therefore use the selection from the viewport it is displayed in. This lets the same tool work naturally in one viewport, two viewports, or as many viewports as the user needs.

Global, local, and linked selection

Tacview supports several selection behaviors.

A selection may be global, local to one viewport, or linked to one of the globally selected objects.

This behavior is defined by the user interface and the viewport layout. It is not normally something an add-on needs to decide.

In most cases, an add-on should simply read the selection for the viewport it belongs to. Tacview and the user interface will decide whether that selection is local, global, or linked.

This keeps add-ons simple while still giving users a lot of freedom.

Practical rule

If your add-on displays something in a viewport, pass that viewport handle when reading selection.

This makes the add-on follow the selection visible in that viewport.

Only read the global selection directly when your add-on is not related to a specific viewport, or when you are debugging or prototyping.

Strict selection helpers

Use strict selection helpers when your add-on should react only to objects explicitly selected by the user.

These are the best choice for tools where the user must clearly understand which objects are being analyzed.

• GetSelectedObjectCount()

• GetSelectedObject()

• GetFirstSelectedObject()

Use GetSelectedObjectCount() and GetSelectedObject() when you need to enumerate the selection, such as when analyzing exactly two selected aircraft.

Use GetFirstSelectedObject() when your add-on only needs one valid selected object.

Object of interest helper

Use GetFirstObjectOfInterest() when your add-on needs a useful reference object, even when nothing is explicitly selected.

This helper first tries to use the first valid selected object for the viewport. If no selected object is available, Tacview tries to choose the most appropriate object at the current playback time.

This can be useful for cameras, quick information panels, and tools that should remain helpful without forcing the user to select an object first.

However, it is less strict than using the selection directly. If your add-on must be driven only by the user's explicit selection, use GetFirstSelectedObject() instead.

Selection information

Use GetSelectionInfo() when your add-on needs more information about the current selection than just object handles.

This can be useful for advanced panels or tools that need to understand how the selection is represented by the user interface.

Changing selection

Some add-ons may need to change the selection explicitly.

Use these functions only when your add-on is intentionally acting as a selection tool or navigation helper:

• SelectObjectByHandle()

• SelectObjectById()

• SelectObjectByPilot()

• SelectObjectByCallSign()

• DeselectObject()

• DeselectAllObjects()

Most add-ons should not modify the user's selection. Reading selection is usually enough.

Typical workflow: analyze selected objects

A common add-on pattern is:

local viewportHandle = GetViewportHandle(layerHandle)
local selectedObjectCount = GetSelectedObjectCount(viewportHandle)

if selectedObjectCount == 2 then

	local firstObjectHandle = GetSelectedObject(viewportHandle, 0)
	local secondObjectHandle = GetSelectedObject(viewportHandle, 1)

	local firstObjectTransform = GetObjectTransform(firstObjectHandle)
	local secondObjectTransform = GetObjectTransform(secondObjectHandle)

	if firstObjectTransform ~= nil and secondObjectTransform ~= nil then

		local distance = Distance(firstObjectTransform, secondObjectTransform)

		-- Display analysis for the two selected objects.

	end
end

This pattern keeps the add-on focused on the user's current viewport. It also allows the same add-on to work correctly in several viewports at the same time.

Typical workflow: follow the best available object

Some tools do not need a strict selection. They just need a good object to use as a reference.

local viewportHandle = GetViewportHandle(layerHandle)
local objectHandle = GetFirstObjectOfInterest(viewportHandle)

if objectHandle ~= nil then

	local transform = GetObjectTransform(objectHandle)

	if transform ~= nil then

		-- Use this object as a camera or display reference.

	end
end

This is convenient for tools that should remain useful even before the user selects anything.