user: How do I use GizmoGroup(bpy_struct) in Blender? Include parameters, examples, warnings and best practices.

assistant: # GizmoGroup(bpy_struct)

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

*class* bpy.types.GizmoGroup(*bpy_struct*)
:   Storage of an operator being executed, or registered after execution

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

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

    bl_options
    :   Options for this operator type

        - `3D`
          3D – Use in 3D viewport.
        - `SCALE`
          Scale – Scale to respect zoom (otherwise zoom independent display size).
        - `DEPTH_3D`
          Depth 3D – Supports culled depth by other objects in the view.
        - `SELECT`
          Select – Supports selection.
        - `PERSISTENT`
          Persistent.
        - `SHOW_MODAL_ALL`
          Show Modal All – Show all while interacting, as well as this group when another is being interacted with.
        - `EXCLUDE_MODAL`
          Exclude Modal – Show all except this group while interacting.
        - `TOOL_INIT`
          Tool Init – Postpone running until tool operator run (when used with a tool).
        - `TOOL_FALLBACK_KEYMAP`
          Use fallback tools keymap – Add fallback tools keymap to this gizmo type.
        - `VR_REDRAWS`
          VR Redraws – The gizmos are made for use with virtual reality sessions and require special redraw management.

        Type:
        :   enum set in {`'3D'`, `'SCALE'`, `'DEPTH_3D'`, `'SELECT'`, `'PERSISTENT'`, `'SHOW_MODAL_ALL'`, `'EXCLUDE_MODAL'`, `'TOOL_INIT'`, `'TOOL_FALLBACK_KEYMAP'`, `'VR_REDRAWS'`}, default set()

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

    bl_region_type
    :   The region where the panel is going to be used in

        Type:
        :   enum in [Region Type Items](bpy_types_enum_items/region_type_items.html#rna-enum-region-type-items), default `'WINDOW'`

    bl_space_type
    :   The space where the panel is going to be used in

        Type:
        :   enum in [Space Type Items](bpy_types_enum_items/space_type_items.html#rna-enum-space-type-items), default `'EMPTY'`

    gizmos
    :   List of gizmos in the Gizmo Map

        Type:
        :   [`Gizmos`](bpy.types.Gizmos.html#bpy.types.Gizmos "bpy.types.Gizmos") [`bpy_prop_collection`](bpy.types.bpy_prop_collection.html#bpy.types.bpy_prop_collection "bpy.types.bpy_prop_collection") of [`Gizmo`](bpy.types.Gizmo.html#bpy.types.Gizmo "bpy.types.Gizmo"), (readonly)

    name
    :   Type:
        :   string, default “”, (readonly, never None)

    *classmethod* poll(*context*)
    :   Test if the gizmo group can be called or not

        Return type:
        :   boolean

    *classmethod* setup_keymap(*keyconfig*)
    :   Initialize keymaps for this gizmo group, use fallback keymap when not present

        Return type:
        :   [`KeyMap`](bpy.types.KeyMap.html#bpy.types.KeyMap "bpy.types.KeyMap"), (never None)

    setup(*context*)
    :   Create gizmos function for the gizmo group

    refresh(*context*)
    :   Refresh data (called on common state changes such as selection)

    draw_prepare(*context*)
    :   Run before each redraw

    invoke_prepare(*context*, *gizmo*)
    :   Run before invoke

    *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