unreal.ScriptableModularBehaviorTool

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

Bases: ScriptableInteractiveTool

A Scriptable tool base blueprint class which provides support for user defined mouse interaction behaviors

C++ Source:

  • Plugin: ScriptableToolsFramework

  • Module: ScriptableToolsFramework

  • File: ScriptableModularBehaviorTool.h

Editor Properties: (see get_editor_property/set_editor_property)

  • custom_icon_path (str): [Read-Write] deprecated: Use ToolIconTexture instead.

  • custom_tool_builder_class (type(Class)): [Read-Write]

  • group_tags (ScriptableToolGroupSet): [Read-Write] Tool Tagging Support

  • 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_icon_texture (Texture2D): [Read-Write]

  • 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_startup_requirements (ScriptableToolStartupRequirements): [Read-Write]

  • tool_target_tool_builder_class (type(Class)): [Read-Write]

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

add_click_drag_behavior(can_begin_click_drag_sequence, on_click_press, on_click_drag, on_click_release, on_terminate_drag_sequence, capture_check, capture_priority=100, mouse_button=ScriptableToolMouseButton.LEFT_BUTTON, update_modifiers_during_drag=False) → None

Implements a standard “button-click-drag”-style input behavior.

The state machine works as follows:

  1. on input-device-button-press, call CanBeginClickDragSequence to determine if capture should begin

  2. on input-device-move, call OnClickDrag

  3. on input-device-button-release, call OnClickRelease

If a ForceEndCapture occurs we call OnTerminateDragSequence

Parameters:
add_double_click_behavior(if_hit_by_click, on_hit_by_click, capture_check, capture_priority=100, mouse_button=ScriptableToolMouseButton.LEFT_BUTTON, hit_test_on_release=True) → None

Implements a standard “button-click”-style input behavior The state machine works as follows:

  1. on input-device-button-press, hit-test the target. If hit, begin capture

  2. on input-device-button-release, hit-test the target. If hit, call OnHitByClick(). If not hit, ignore click.

The second hit-test is required to allow the click to be “cancelled” by moving away from the target. This is standard GUI behavior. You can disable this second hit test using the HitTestOnRelease property. This is strongly discouraged.

Parameters:
add_mouse_hover_behavior(begin_hover_sequence_hit_test, on_begin_hover, on_update_hover, on_end_hover, hover_capture_check, capture_priority=100) → None
Parameters:
add_mouse_wheel_behavior(test_should_respond_to_mouse_wheel, on_mouse_wheel_scroll_up, on_mouse_wheel_scroll_down, capture_check, capture_priority=100) → None
Parameters:

  • test_should_respond_to_mouse_wheel (TestShouldRespondToMouseWheelDelegate) – The result’s bHit property determines whether the mouse wheel action will be captured. (Perhaps the mouse wheel only does something when mousing over some part of a mesh)

  • on_mouse_wheel_scroll_up (OnMouseWheelScrollUpDelegate) – CurrentPos device position/ray at point where mouse wheel is engaged

  • on_mouse_wheel_scroll_down (OnMouseWheelScrollDownDelegate) – CurrentPos device position/ray at point where mouse wheel is engaged

  • capture_check (MouseBehaviorModiferCheckDelegate) – Only enable capture if returns true

  • capture_priority (int32) – The priority is used to resolve situations where multiple behaviors want the same capture

add_multi_click_sequence_behavior(on_begin_sequence_preview, can_begin_click_sequence, on_begin_click_sequence, on_next_sequence_preview, on_next_sequence_click, on_terminate_click_sequence, request_abort_click_sequence, capture_check, hover_capture_check, capture_priority=100, mouse_button=ScriptableToolMouseButton.LEFT_BUTTON) → None

MultiClickSequenceBehavior implements a generic multi-click-sequence input behavior. For example this behavior could be used to implement a multi-click polygon-drawing interaction.

The internal state machine works as follows:

  1. on input-device-button-press, check if target wants to begin sequence. If so, begin capture.

  2. on button release, check if target wants to continue or terminate sequence

    1. if terminate, release capture

    2. if continue, do nothing (capture continues between presses)

The target will receive “preview” notifications (basically hover) during updates where there is not a release. This can be used to (eg) update a rubber-band selection end point

Parameters:

  • on_begin_sequence_preview (OnBeginSequencePreviewDelegate) – Notify Target device position has changed but a click sequence hasn’t begun yet (eg for interactive previews)

  • can_begin_click_sequence (CanBeginClickSequenceDelegate) – Test if target would like to begin sequence based on this click. Gets checked both on mouse down and mouse up.

  • on_begin_click_sequence (OnBeginClickSequenceDelegate) – Notify Target about the first click in the sequence.

  • on_next_sequence_preview (OnNextSequencePreviewDelegate) – Notify Target device position has changed but a click hasn’t occurred yet (eg for interactive previews)

  • on_next_sequence_click (OnNextSequenceClickDelegate) – Notify Target about next click in sqeuence, returns false to terminate sequence

  • on_terminate_click_sequence (OnTerminateClickSequenceDelegate) – Notify Target that click sequence has been explicitly terminated (eg by escape key, cancel tool, etc).

  • request_abort_click_sequence (RequestAbortClickSequenceDelegate) – Target overrides this and returns true if it wants to abort click sequence, checked every update

  • capture_check (MouseBehaviorModiferCheckDelegate) – Only enable capture if returns true

  • hover_capture_check (MouseBehaviorModiferCheckDelegate) – Only enable hover capture if returns true

  • capture_priority (int32) – The priority is used to resolve situations where multiple behaviors want the same capture

  • mouse_button (ScriptableToolMouseButton) – Determines which mouse button the behavior captures on

add_multi_key_input_behavior(on_key_pressed, on_key_released, on_force_end_capture_func_in, keys, require_all_keys, capture_check, capture_priority) → None

AddMultiKeyInputBehavior implements a generic keyboard multi key listener behavior

Parameters:

  • on_key_pressed (OnKeyStateToggleDelegate) – Callback when the target key(s) is pressed. Only triggers once if bRequireAllKeys is true.

  • on_key_released (OnKeyStateToggleDelegate) – Callback when the target key(s) is pressed. Only triggers once if bRequireAllKeys is true.

  • on_force_end_capture_func_in (OnForceEndCaptureDelegate_ScriptableTools) – Callback when capture is ended prematurely, typically due to the viewport losing focus, in which case the release callback will not be called.

  • keys (Array[Key]) – Target keys to watch for

  • require_all_keys (bool) – If true, all target keys must be pressed simultaniously to recieve press/release events. Otherwise, any and all keys can trigger events.

  • capture_check (MouseBehaviorModiferCheckDelegate) – Only enable capture if returns true

  • capture_priority (int32) – The priority is used to resolve situations where multiple behaviors want the same capture

add_single_click_behavior(if_hit_by_click, on_hit_by_click, capture_check, capture_priority=100, mouse_button=ScriptableToolMouseButton.LEFT_BUTTON, hit_test_on_release=True) → None

Implements a standard “button-click”-style input behavior The state machine works as follows:

  1. on input-device-button-press, hit-test the target. If hit, begin capture

  2. on input-device-button-release, hit-test the target. If hit, call OnHitByClick(). If not hit, ignore click.

The second hit-test is required to allow the click to be “cancelled” by moving away from the target. This is standard GUI behavior. You can disable this second hit test using the HitTestOnRelease property. This is strongly discouraged.

Parameters:
add_single_click_or_drag_behavior(if_hit_by_click, on_hit_by_click, can_begin_click_drag_sequence, on_click_press, on_click_drag, on_click_release, on_terminate_drag_sequence, capture_check, capture_priority=100, mouse_button=ScriptableToolMouseButton.LEFT_BUTTON, begin_drag_if_click_target_not_hit=True, click_distance_threshold=5.000000) → None

SingleClickOrDragBehavior is a combination of a SingleClickBehavior and ClickDragBehavior, and allows for the common UI interaction where a click-and-release does one action, but if the mouse is moved, then a drag interaction is started. For example click-to-select is often combined with a drag-marquee-rectangle in this way. This can be directly implemented with a ClickDragBehavior but requires the client to (eg) detect movement thresholds, etc. This class encapsulates all that state/logic.

The ClickDistanceThreshold parameter determines how far the mouse must move (in whatever device units are in use) to switch from a click to drag interaction

The bBeginDragIfClickTargetNotHit parameter determines if the drag interaction will be immediately initiated if the initial ‘click’ mouse-down does not hit a valid clickable target. Defaults to true.

Parameters:
add_single_key_input_behavior(on_key_pressed, on_key_released, on_force_end_capture_func_in, key, capture_check, capture_priority) → None

AddSingleKeyInputBehavior implements a generic keyboard key listener behavior

Parameters:
get_active_modifiers() → ScriptableToolModifierStates
Returns:

a struct containing the current Modifier key states

Return type:

ScriptableToolModifierStates

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