unreal.ScriptableSingleClickTool

class unreal.ScriptableSingleClickTool(outer: Object | None = None, name: Name | str = 'None')

Bases: ScriptableInteractiveTool

UScriptableSingleClickTool is an extension of UScriptableInteractiveTool that supports a “click” interaction, ie button press-down-and-release on an arbitrary Target (defined by the Tool). Note that like a standard GUI click interaction, if the device is moved off the “Target” before the button is released, the click is cancelled. Note that in this context, the Target is defined implicitly by the Tool returning a “hit” for a given input device location, rather than any specific geometry.

Hover is also supported.

Note: Currently these interactions are only supported for mouse devices, or devices remapped to be a mouse by the UInputRouter. Also currently only the left-mouse-button is supported.

C++ Source:

• Plugin: ScriptableToolsFramework

• Module: ScriptableToolsFramework

• File: ScriptableSingleClickTool.h

Editor Properties: (see get_editor_property/set_editor_property)

• custom_icon_path (str): [Read-Write] Relative Path to a custom Icon Image for this Tool. The Image file format must be png or svg.

  The Image file must reside in the same Content folder hierarchy as contains the Tool Class (ie Blueprint asset), i.e. either the Project Content folder or a Plugin Content folder.

  So for example if the Tool BP is in a plugin named MyCustomTools, the icon must be in

  MyProject/Plugins/MyCustomTools/Content/<SubFolders>/MyToolIcon.png,

  and the relative path to use here would be <SubFolders>/MyToolIcon.png

• show_tool_in_editor (bool): [Read-Write] A generic flag to indicate whether this Tool should be shown in the UE Editor. This may be interpreted in different ways

• tool_category (Text): [Read-Write] Category of this Tool, will be used in (eg) Tool Palette Section headers

• tool_long_name (Text): [Read-Write] Long Name of this Tool, will be used in (eg) longer labels like the Accept/Cancel toolbar

• tool_name (Text): [Read-Write] Name of this Tool, will be used in (eg) Toolbars

• tool_shutdown_type (ScriptableToolShutdownType): [Read-Write] Specifies how the user exits this Tool, either Accept/Cancel-style or Complete-style

• tool_tooltip (Text): [Read-Write] Tooltip used for this Tool in (eg) icons/etc

• want_mouse_hover (bool): [Read-Write] Enable Hover support API functions OnHoverHitTest / OnHoverBegin / OnHoverUpdate / OnHoverEnd for Mouse devices. Defaults to disabled.

get_active_modifiers() → ScriptableToolModifierStates

Returns:

a struct containing the current Modifier key states

Return type:

ScriptableToolModifierStates

in_active_hover() → bool

In Active Hover

Return type:

bool

is_alt_down() → bool

Returns:

true if the Alt key is currently held down

Return type:

bool

is_ctrl_down() → bool

Returns:

true if the Ctrl key is currently held down

Return type:

bool

is_shift_down() → bool

Returns:

true if the Shift key is currently held down

Return type:

bool

on_hit_by_click(click_pos, modifiers) → None

OnHitByClick is called when the Tool has indicated it would like to consume a click event (via TestIfHitByClick), and the click was not cancelled or consumed by a nearer object.

Parameters:

• click_pos (InputDeviceRay) – the position of the click, including both a 3D ray from the eye, and (optionally) a 2D mouse position

• modifiers (ScriptableToolModifierStates) – current modifier key/button state

on_hover_begin(hover_pos, modifiers) → None

Begin a sequence of Hover input events

Parameters:

• hover_pos (InputDeviceRay) – the current position of the cursor/device, including both a 3D ray from the eye, and (optionally) a 2D mouse position

• modifiers (ScriptableToolModifierStates) – current modifier key/button state

on_hover_end(modifiers) → None

Indicate that an active captured Hover sequence has ended. The device may no longer be in the viewport, so no position can be provided.

Parameters:

modifiers (ScriptableToolModifierStates) – current modifier key/button state

on_hover_hit_test(hover_pos, modifiers) → InputRayHit

OnHoverHitTest is called to allow the Tool to indicate if it would like to start consuing “hover” input at HoverPos. The Tool can return yes/no and a “hit depth”, which will be used to determine if the Tool is given the active hover input stream. The default OnHoverHitTest implement always captures the hover.

Once the hover is accepted, the OnHoverBegin event will fire, and then a stream of OnHoverUpdate events. If at any point the hover is no longer relevant, OnHoverUpdate should return false. OnHoverEnd will be called at that point, or if the hover is cancelled for any reason (eg mouse goes out of window, button is pressed, etc)

Parameters:

• hover_pos (InputDeviceRay) – the current position of the cursor/device, including both a 3D ray from the eye, and (optionally) a 2D mouse position

• modifiers (ScriptableToolModifierStates) – current modifier key/button state

Returns:

a FInputRayHit indicating a hit (true/false) and the hit depth along the hit-ray (0 for “always consume”)

Return type:

InputRayHit

on_hover_update(hover_pos, modifiers) → bool

Update an active Hover sequence. OnHoverUpdate is only ever called between OnHoverBegin and OnHoverEnd

Parameters:

• hover_pos (InputDeviceRay) – the current position of the cursor/device, including both a 3D ray from the eye, and (optionally) a 2D mouse position

• modifiers (ScriptableToolModifierStates) – current modifier key/button state

Returns:

true to continue hovering, false to stop receiving additional hover events

Return type:

bool

test_if_hit_by_click(click_pos, modifiers) → InputRayHit

TestIfHitByClick is called to allow the Tool to indicate if it would like to consume a potential click at ClickPos. The Tool can return yes/no and a “hit depth”, which will be used to determine if the Tool is given the click (ie if it has the nearest depth), at which point the OnHitByClick event will fire. The default TestIfHitByClick implementation always captures the click (at depth 0).

Note that this function will be called twice for a particular hit - once on mouse-down and once on mouse-up, and if it returns no-hit on mouse-up, the click will be “cancelled”, similar to standard GUI click interactions.

Parameters:

• click_pos (InputDeviceRay) – the position of the click, including both a 3D ray from the eye, and (optionally) a 2D mouse position

• modifiers (ScriptableToolModifierStates) – current modifier key/button state

Returns:

a FInputRayHit indicating a hit (true/false) and the hit depth along the hit-ray (0 for “always consume”)

Return type:

InputRayHit

property want_mouse_hover: bool

[Read-Write] Enable Hover support API functions OnHoverHitTest / OnHoverBegin / OnHoverUpdate / OnHoverEnd for Mouse devices. Defaults to disabled.

Type:

(bool)