Qt Reference Documentation

QML KeyNavigation Element

The KeyNavigation attached property supports key navigation by arrow keys. More...

  • List of all members, including inherited members
  • Properties

    Detailed Description

    It is common in key-based UIs to use arrow keys to navigate between focused items. The KeyNavigation property provides a convenient way of specifying which item will gain focus when an arrow key is pressed. The following example provides key navigation for a 2x2 grid of items.

     Grid {
         columns: 2
         width: 100; height: 100
         Rectangle {
             id: item1
             focus: true
             width: 50; height: 50
             color: focus ? "red" : "lightgray"
             KeyNavigation.right: item2
             KeyNavigation.down: item3
         Rectangle {
             id: item2
             width: 50; height: 50
             color: focus ? "red" : "lightgray"
             KeyNavigation.left: item1
             KeyNavigation.down: item4
         Rectangle {
             id: item3
             width: 50; height: 50
             color: focus ? "red" : "lightgray"
             KeyNavigation.right: item4
             KeyNavigation.up: item1
         Rectangle {
             id: item4
             width: 50; height: 50
             color: focus ? "red" : "lightgray"
             KeyNavigation.left: item3
             KeyNavigation.up: item2

    By default KeyNavigation receives key events after the item it is attached to. If the item accepts an arrow key event, the KeyNavigation attached property will not receive an event for that key. Setting the priority property to KeyNavigation.BeforeItem allows handling of the key events before normal item processing.

    If an item has been set for a direction and the KeyNavigation attached property receives the corresponding key press and release events, the events will be accepted by KeyNavigation and will not propagate any further.

    See also Keys attached property.

    Property Documentation

    left : Item

    right : Item

    up : Item

    down : Item

    These properties hold the item to assign focus to when Key_Left, Key_Right, Key_Up or Key_Down are pressed.

    priority : enumeration

    This property determines whether the keys are processed before or after the attached item's own key handling.

    • KeyNavigation.BeforeItem - process the key events before normal item key processing. If the event is accepted it will not be passed on to the item.
    • KeyNavigation.AfterItem (default) - process the key events after normal item key handling. If the item accepts the key event it will not be handled by the KeyNavigation attached property handler.


    Thank you for giving your feedback.

    Make sure it is related to this specific page. For more general bugs and requests, please use the Qt Bug Tracker.

    [0]; s.parentNode.insertBefore(ga, s); })();