user: Give a detailed overview of Gizmo(bpy_struct): syntax, arguments, return values, common patterns.

assistant: # Gizmo(bpy_struct)

base class — [`bpy_struct`](bpy.types.bpy_struct.html#bpy.types.bpy_struct "bpy.types.bpy_struct")

*class* bpy.types.Gizmo(*bpy_struct*)
:   Collection of gizmos

    alpha
    :   Type:
        :   float in [0, 1], default 0.0

    alpha_highlight
    :   Type:
        :   float in [0, 1], default 0.0

    bl_idname
    :   Type:
        :   string, default “”, (never None)

    color
    :   Type:
        :   [`mathutils.Color`](mathutils.html#mathutils.Color "mathutils.Color") of 3 items in [0, inf], default (0.0, 0.0, 0.0)

    color_highlight
    :   Type:
        :   [`mathutils.Color`](mathutils.html#mathutils.Color "mathutils.Color") of 3 items in [0, inf], default (0.0, 0.0, 0.0)

    group
    :   Gizmo group this gizmo is a member of

        Type:
        :   [`GizmoGroup`](bpy.types.GizmoGroup.html#bpy.types.GizmoGroup "bpy.types.GizmoGroup"), (readonly)

    hide
    :   Type:
        :   boolean, default False

    hide_keymap
    :   Ignore the key-map for this gizmo

        Type:
        :   boolean, default False

    hide_select
    :   Type:
        :   boolean, default False

    is_highlight
    :   Type:
        :   boolean, default False, (readonly)

    is_modal
    :   Type:
        :   boolean, default False, (readonly)

    line_width
    :   Type:
        :   float in [0, inf], default 0.0

    matrix_basis
    :   Type:
        :   [`mathutils.Matrix`](mathutils.html#mathutils.Matrix "mathutils.Matrix") of 4 \* 4 items in [-inf, inf], default ((0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0))

    matrix_offset
    :   Type:
        :   [`mathutils.Matrix`](mathutils.html#mathutils.Matrix "mathutils.Matrix") of 4 \* 4 items in [-inf, inf], default ((0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0))

    matrix_space
    :   Type:
        :   [`mathutils.Matrix`](mathutils.html#mathutils.Matrix "mathutils.Matrix") of 4 \* 4 items in [-inf, inf], default ((0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0))

    matrix_world
    :   Type:
        :   [`mathutils.Matrix`](mathutils.html#mathutils.Matrix "mathutils.Matrix") of 4 \* 4 items in [-inf, inf], default ((0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0)), (readonly)

    properties
    :   Type:
        :   [`GizmoProperties`](bpy.types.GizmoProperties.html#bpy.types.GizmoProperties "bpy.types.GizmoProperties"), (readonly, never None)

    scale_basis
    :   Type:
        :   float in [0, inf], default 0.0

    select
    :   Type:
        :   boolean, default False

    select_bias
    :   Depth bias used for selection

        Type:
        :   float in [-inf, inf], default 0.0

    use_draw_hover
    :   Type:
        :   boolean, default False

    use_draw_modal
    :   Show while dragging

        Type:
        :   boolean, default False

    use_draw_offset_scale
    :   Scale the offset matrix (use to apply screen-space offset)

        Type:
        :   boolean, default False

    use_draw_scale
    :   Use scale when calculating the matrix

        Type:
        :   boolean, default True

    use_draw_value
    :   Show an indicator for the current value while dragging

        Type:
        :   boolean, default False

    use_event_handle_all
    :   When highlighted, do not pass events through to be handled by other keymaps

        Type:
        :   boolean, default False

    use_grab_cursor
    :   Type:
        :   boolean, default False

    use_operator_tool_properties
    :   Merge active tool properties on activation (does not overwrite existing)

        Type:
        :   boolean, default False

    use_select_background
    :   Don’t write into the depth buffer

        Type:
        :   boolean, default False

    use_tooltip
    :   Use tooltips when hovering over this gizmo

        Type:
        :   boolean, default True

    draw(*context*)

    draw_select(*context*, *\**, *select_id=0*)

    test_select(*context*, *location*)
    :   Parameters:
        :   **location** (*int array* *of* *2 items in* *[**-inf**,* *inf**]**,* *(**never None**)*) – Location, Region coordinates

        Returns:
        :   Use -1 to skip this gizmo

        Return type:
        :   int in [-1, inf]

    modal(*context*, *event*, *tweak*)
    :   Parameters:
        :   **tweak** (enum set in {`'PRECISE'`, `'SNAP'`}) – Tweak

        Returns:
        :   result

        Return type:
        :   enum set in [Operator Return Items](bpy_types_enum_items/operator_return_items.html#rna-enum-operator-return-items)

    setup()

    invoke(*context*, *event*)
    :   Returns:
        :   result

        Return type:
        :   enum set in [Operator Return Items](bpy_types_enum_items/operator_return_items.html#rna-enum-operator-return-items)

    exit(*context*, *cancel*)
    :   Parameters:
        :   **cancel** (*boolean*) – Cancel, otherwise confirm

    select_refresh()

    draw_preset_box(*matrix*, *\**, *select_id=-1*)
    :   Draw a box

        Parameters:
        :   - **matrix** ([`mathutils.Matrix`](mathutils.html#mathutils.Matrix "mathutils.Matrix") of 4 \* 4 items in [-inf, inf]) – The matrix to transform
            - **select_id** (*int in* *[**-1**,* *inf**]**,* *(**optional**)*) – ID to use when gizmo is selectable. Use -1 when not selecting.

    draw_preset_arrow(*matrix*, *\**, *axis='POS_Z'*, *select_id=-1*)
    :   Draw a box

        Parameters:
        :   - **matrix** ([`mathutils.Matrix`](mathutils.html#mathutils.Matrix "mathutils.Matrix") of 4 \* 4 items in [-inf, inf]) – The matrix to transform
            - **axis** (enum in [Object Axis Items](bpy_types_enum_items/object_axis_items.html#rna-enum-object-axis-items), (optional)) – Arrow Orientation
            - **select_id** (*int in* *[**-1**,* *inf**]**,* *(**optional**)*) – ID to use when gizmo is selectable. Use -1 when not selecting.

    draw_preset_circle(*matrix*, *\**, *axis='POS_Z'*, *select_id=-1*)
    :   Draw a box

        Parameters:
        :   - **matrix** ([`mathutils.Matrix`](mathutils.html#mathutils.Matrix "mathutils.Matrix") of 4 \* 4 items in [-inf, inf]) – The matrix to transform
            - **axis** (enum in [Object Axis Items](bpy_types_enum_items/object_axis_items.html#rna-enum-object-axis-items), (optional)) – Arrow Orientation
            - **select_id** (*int in* *[**-1**,* *inf**]**,* *(**optional**)*) – ID to use when gizmo is selectable. Use -1 when not selecting.

    target_set_prop(*target*, *data*, *property*, *\**, *index=-1*)
    :   Parameters:
        :   - **target** (*string**,* *(**never None**)*) – Target property
            - **data** ([`AnyType`](bpy.types.AnyType.html#bpy.types.AnyType "bpy.types.AnyType"), (never None)) – Data from which to take property
            - **property** (*string**,* *(**never None**)*) – Identifier of property in data

    target_set_operator(*operator*, *\**, *index=0*)
    :   Operator to run when activating the gizmo (overrides property targets)

        Parameters:
        :   - **operator** (*string**,* *(**never None**)*) – Target operator
            - **index** (*int in* *[**0**,* *255**]**,* *(**optional**)*) – Part index

        Returns:
        :   Operator properties to fill in

        Return type:
        :   [`OperatorProperties`](bpy.types.OperatorProperties.html#bpy.types.OperatorProperties "bpy.types.OperatorProperties")

    target_is_valid(*property*)
    :   Parameters:
        :   **property** (*string**,* *(**never None**)*) – Property identifier

        Return type:
        :   boolean

    draw_custom_shape(*shape*, *\**, *matrix=None*, *select_id=None*)
    :   Draw a shape created form [`Gizmo.draw_custom_shape`](#bpy.types.Gizmo.draw_custom_shape "bpy.types.Gizmo.draw_custom_shape").

        Parameters:
        :   - **shape** (*Any*) – The cached shape to draw.
            - **matrix** ([`mathutils.Matrix`](mathutils.html#mathutils.Matrix "mathutils.Matrix")) – 4x4 matrix, when not given [`Gizmo.matrix_world`](#bpy.types.Gizmo.matrix_world "bpy.types.Gizmo.matrix_world") is used.
            - **select_id** (*int*) – The selection id.
              Only use when drawing within [`Gizmo.draw_select`](#bpy.types.Gizmo.draw_select "bpy.types.Gizmo.draw_select").

    *static* new_custom_shape(*type*, *verts*)
    :   Create a new shape that can be passed to [`Gizmo.draw_custom_shape`](#bpy.types.Gizmo.draw_custom_shape "bpy.types.Gizmo.draw_custom_shape").

        Parameters:
        :   - **type** (*str*) – The type of shape to create in (POINTS, LINES, TRIS, LINE_STRIP).
            - **verts** (*Sequence**[**Sequence**[**float**]**]*) – Sequence of 2D or 3D coordinates.

        Returns:
        :   The newly created shape (the return type make change).

        Return type:
        :   Any

    *classmethod* bl_rna_get_subclass(*id*, *default=None*, */*)
    :   Parameters:
        :   **id** (*str*) – The RNA type identifier.

        Returns:
        :   The RNA type or default when not found.

        Return type:
        :   [`bpy.types.Struct`](bpy.types.Struct.html#bpy.types.Struct "bpy.types.Struct") subclass

    *classmethod* bl_rna_get_subclass_py(*id*, *default=None*, */*)
    :   Parameters:
        :   **id** (*str*) – The RNA type identifier.

        Returns:
        :   The class or default when not found.

        Return type:
        :   type

    target_get_range(target):
    :   Get the range for this target property.

        Parameters:
        :   **target** – Target property name.

        Returns:
        :   The range of this property (min, max).

        Return type:
        :   tuple[float, float]

    target_get_value(target):
    :   Get the value of this target property.

        Parameters:
        :   **target** (*str*) – Target property name.

        Returns:
        :   The value of the target property as a value or array based on the target type.

        Return type:
        :   float | tuple[float, …]

    target_set_handler(target, get, set, range=None):
    :   Assigns callbacks to a gizmos property.

        Parameters:
        :   - **target** (*str*) – Target property name.
            - **get** (*Callable**[**[**]**,* *float* *|* *Sequence**[**float**]**]*) – Function that returns the value for this property (single value or sequence).
            - **set** (*Callable**[**[**tuple**[**float**,* *...**]**]**,* *Any**]*) – Function that takes a single value argument and applies it.
            - **range** (*callable*) – Function that returns a (min, max) tuple for gizmos that use a range. The returned value is not used.

    target_set_value(target):
    :   Set the value of this target property.

        Parameters:
        :   **target** (*str*) – Target property name.