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

assistant: # KeyMapItems(bpy_struct)

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

*class* bpy.types.KeyMapItems(*bpy_struct*)
:   Collection of keymap items

    new(*idname*, *type*, *value*, *\**, *any=False*, *shift=0*, *ctrl=0*, *alt=0*, *oskey=0*, *hyper=0*, *key_modifier='NONE'*, *direction='ANY'*, *repeat=False*, *head=False*)
    :   new

        Parameters:
        :   - **idname** (*string**,* *(**never None**)*) – Operator Identifier
            - **type** (enum in [Event Type Items](bpy_types_enum_items/event_type_items.html#rna-enum-event-type-items)) – Type
            - **value** (enum in [Event Value Items](bpy_types_enum_items/event_value_items.html#rna-enum-event-value-items)) – Value
            - **any** (*boolean**,* *(**optional**)*) – Any
            - **shift** (*int in* *[**-1**,* *1**]**,* *(**optional**)*) – Shift
            - **ctrl** (*int in* *[**-1**,* *1**]**,* *(**optional**)*) – Ctrl
            - **alt** (*int in* *[**-1**,* *1**]**,* *(**optional**)*) – Alt
            - **oskey** (*int in* *[**-1**,* *1**]**,* *(**optional**)*) – OS Key
            - **hyper** (*int in* *[**-1**,* *1**]**,* *(**optional**)*) – Hyper
            - **key_modifier** (enum in [Event Type Items](bpy_types_enum_items/event_type_items.html#rna-enum-event-type-items), (optional)) – Key Modifier
            - **direction** (enum in [Event Direction Items](bpy_types_enum_items/event_direction_items.html#rna-enum-event-direction-items), (optional)) – Direction
            - **repeat** (*boolean**,* *(**optional**)*) – Repeat, When set, accept key-repeat events
            - **head** (*boolean**,* *(**optional**)*) – At Head, Force item to be added at start (not end) of key map so that it doesn’t get blocked by an existing key map item

        Returns:
        :   Item, Added key map item

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

    new_modal(*propvalue*, *type*, *value*, *\**, *any=False*, *shift=0*, *ctrl=0*, *alt=0*, *oskey=0*, *hyper=0*, *key_modifier='NONE'*, *direction='ANY'*, *repeat=False*)
    :   new_modal

        Parameters:
        :   - **propvalue** (*string**,* *(**never None**)*) – Property Value
            - **type** (enum in [Event Type Items](bpy_types_enum_items/event_type_items.html#rna-enum-event-type-items)) – Type
            - **value** (enum in [Event Value Items](bpy_types_enum_items/event_value_items.html#rna-enum-event-value-items)) – Value
            - **any** (*boolean**,* *(**optional**)*) – Any
            - **shift** (*int in* *[**-1**,* *1**]**,* *(**optional**)*) – Shift
            - **ctrl** (*int in* *[**-1**,* *1**]**,* *(**optional**)*) – Ctrl
            - **alt** (*int in* *[**-1**,* *1**]**,* *(**optional**)*) – Alt
            - **oskey** (*int in* *[**-1**,* *1**]**,* *(**optional**)*) – OS Key
            - **hyper** (*int in* *[**-1**,* *1**]**,* *(**optional**)*) – Hyper
            - **key_modifier** (enum in [Event Type Items](bpy_types_enum_items/event_type_items.html#rna-enum-event-type-items), (optional)) – Key Modifier
            - **direction** (enum in [Event Direction Items](bpy_types_enum_items/event_direction_items.html#rna-enum-event-direction-items), (optional)) – Direction
            - **repeat** (*boolean**,* *(**optional**)*) – Repeat, When set, accept key-repeat events

        Returns:
        :   Item, Added key map item

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

    new_from_item(*item*, *\**, *head=False*)
    :   new_from_item

        Parameters:
        :   - **item** ([`KeyMapItem`](bpy.types.KeyMapItem.html#bpy.types.KeyMapItem "bpy.types.KeyMapItem"), (never None)) – Item, Item to use as a reference
            - **head** (*boolean**,* *(**optional**)*) – At Head

        Returns:
        :   Item, Added key map item

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

    remove(*item*)
    :   remove

        Parameters:
        :   **item** ([`KeyMapItem`](bpy.types.KeyMapItem.html#bpy.types.KeyMapItem "bpy.types.KeyMapItem"), (never None)) – Item

    from_id(*id*)
    :   from_id

        Parameters:
        :   **id** (*int in* *[**-inf**,* *inf**]*) – id, ID of the item

        Returns:
        :   Item

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

    find_from_operator(*idname*, *\**, *properties=None*, *include={'ACTIONZONE', 'KEYBOARD', 'MOUSE', 'NDOF'}*, *exclude={}*)
    :   find_from_operator

        Parameters:
        :   - **idname** (*string**,* *(**never None**)*) – Operator Identifier
            - **include** (enum set in [Event Type Mask Items](bpy_types_enum_items/event_type_mask_items.html#rna-enum-event-type-mask-items), (optional)) – Include
            - **exclude** (enum set in [Event Type Mask Items](bpy_types_enum_items/event_type_mask_items.html#rna-enum-event-type-mask-items), (optional)) – Exclude

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

    find_match(*keymap*, *item*)
    :   find_match

        Parameters:
        :   - **keymap** ([`KeyMap`](bpy.types.KeyMap.html#bpy.types.KeyMap "bpy.types.KeyMap")) – The matching keymap
            - **item** ([`KeyMapItem`](bpy.types.KeyMapItem.html#bpy.types.KeyMapItem "bpy.types.KeyMapItem")) – The matching keymap item

        Returns:
        :   The keymap item from this keymap which matches the keymap item from the arguments passed in

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

    match_event(*event*)
    :   match_event

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

    *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