<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qdeclarativeitem.cpp -->
<title>Qt 4.8: QML KeyNavigation Element</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li><a href="qdeclarativeelements.html">QML Elements</a></li>
<li>QML KeyNavigation Element</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#properties">Properties</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
</ul>
</div>
<h1 class="title">QML KeyNavigation Element</h1>
<span class="subtitle"></span>
<!-- $$$KeyNavigation-brief -->
<p>The KeyNavigation attached property supports key navigation by arrow keys. <a href="#details">More...</a></p>
<!-- @@@KeyNavigation -->
<p>This element was introduced in Qt 4.7.</p>
<ul>
<li><a href="qml-keynavigation-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="properties"></a>
<h2>Properties</h2>
<ul>
<li class="fn"><b><b><a href="qml-keynavigation.html#backtab-prop">backtab</a></b></b> : Item</li>
<li class="fn"><b><b><a href="qml-keynavigation.html#down-prop">down</a></b></b> : Item</li>
<li class="fn"><b><b><a href="qml-keynavigation.html#left-prop">left</a></b></b> : Item</li>
<li class="fn"><b><b><a href="qml-keynavigation.html#priority-prop">priority</a></b></b> : enumeration</li>
<li class="fn"><b><b><a href="qml-keynavigation.html#right-prop">right</a></b></b> : Item</li>
<li class="fn"><b><b><a href="qml-keynavigation.html#tab-prop">tab</a></b></b> : Item</li>
<li class="fn"><b><b><a href="qml-keynavigation.html#up-prop">up</a></b></b> : Item</li>
</ul>
<!-- $$$KeyNavigation-description -->
<a name="details"></a>
<h2>Detailed Description</h2>
<p>Key-based user interfaces commonly allow the use of arrow keys to navigate between focusable items. The KeyNavigation attached property enables this behavior by providing a convenient way to specify the item that should gain focus when an arrow or tab key is pressed.</p>
<p>The following example provides key navigation for a 2x2 grid of items:</p>
<pre class="qml"> import QtQuick 1.0
<span class="type"><a href="qml-grid.html">Grid</a></span> {
<span class="name">width</span>: <span class="number">100</span>; <span class="name">height</span>: <span class="number">100</span>
<span class="name">columns</span>: <span class="number">2</span>
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">topLeft</span>
<span class="name">width</span>: <span class="number">50</span>; <span class="name">height</span>: <span class="number">50</span>
<span class="name">color</span>: <span class="name">focus</span> ? <span class="string">"red"</span> : <span class="string">"lightgray"</span>
<span class="name">focus</span>: <span class="number">true</span>
<span class="name">KeyNavigation</span>.right: <span class="name">topRight</span>
<span class="name">KeyNavigation</span>.down: <span class="name">bottomLeft</span>
}
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">topRight</span>
<span class="name">width</span>: <span class="number">50</span>; <span class="name">height</span>: <span class="number">50</span>
<span class="name">color</span>: <span class="name">focus</span> ? <span class="string">"red"</span> : <span class="string">"lightgray"</span>
<span class="name">KeyNavigation</span>.left: <span class="name">topLeft</span>
<span class="name">KeyNavigation</span>.down: <span class="name">bottomRight</span>
}
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">bottomLeft</span>
<span class="name">width</span>: <span class="number">50</span>; <span class="name">height</span>: <span class="number">50</span>
<span class="name">color</span>: <span class="name">focus</span> ? <span class="string">"red"</span> : <span class="string">"lightgray"</span>
<span class="name">KeyNavigation</span>.right: <span class="name">bottomRight</span>
<span class="name">KeyNavigation</span>.up: <span class="name">topLeft</span>
}
<span class="type"><a href="qml-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">bottomRight</span>
<span class="name">width</span>: <span class="number">50</span>; <span class="name">height</span>: <span class="number">50</span>
<span class="name">color</span>: <span class="name">focus</span> ? <span class="string">"red"</span> : <span class="string">"lightgray"</span>
<span class="name">KeyNavigation</span>.left: <span class="name">bottomLeft</span>
<span class="name">KeyNavigation</span>.up: <span class="name">topRight</span>
}
}</pre>
<p>The top-left item initially receives focus by setting <a href="qml-item.html#focus-prop">focus</a> to <tt>true</tt>. When an arrow key is pressed, the focus will move to the appropriate item, as defined by the value that has been set for the KeyNavigation <a href="qml-keynavigation.html#left-prop">left</a>, <a href="qml-keynavigation.html#right-prop">right</a>, <a href="qml-keynavigation.html#up-prop">up</a> or <a href="qml-keynavigation.html#down-prop">down</a> properties.</p>
<p>Note that if a KeyNavigation attached property receives the key press and release events for a requested arrow or tab key, the event is accepted and does not propagate any further.</p>
<p>By default, KeyNavigation receives key events after the item to which it is attached. If the item accepts the key event, the KeyNavigation attached property will not receive an event for that key. Setting the <a href="qml-keynavigation.html#priority-prop">priority</a> property to <tt>KeyNavigation.BeforeItem</tt> allows the event to be used for key navigation before the item, rather than after.</p>
<p>If item to which the focus is switching is not enabled or visible, an attempt will be made to skip this item and focus on the next. This is possible if there are a chain of items with the same KeyNavigation handler. If multiple items in a row are not enabled or visible, they will also be skipped.</p>
<p><b>See also </b><a href="qml-keys.html">Keys attached property</a>.</p>
<!-- @@@KeyNavigation -->
<h2>Property Documentation</h2>
<!-- $$$left -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="left-prop"></a><span class="name">left</span> : <span class="type"><a href="qml-item.html">Item</a></span></p></td></tr><tr valign="top" class="even"><td class="tblQmlPropNode"><p><a name="right-prop"></a><span class="name">right</span> : <span class="type"><a href="qml-item.html">Item</a></span></p></td></tr><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="up-prop"></a><span class="name">up</span> : <span class="type"><a href="qml-item.html">Item</a></span></p></td></tr><tr valign="top" class="even"><td class="tblQmlPropNode"><p><a name="down-prop"></a><span class="name">down</span> : <span class="type"><a href="qml-item.html">Item</a></span></p></td></tr><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="tab-prop"></a><span class="name">tab</span> : <span class="type"><a href="qml-item.html">Item</a></span></p></td></tr><tr valign="top" class="even"><td class="tblQmlPropNode"><p><a name="backtab-prop"></a><span class="name">backtab</span> : <span class="type"><a href="qml-item.html">Item</a></span></p></td></tr></table></div><div class="qmldoc"><p>These properties hold the item to assign focus to when the left, right, up or down cursor keys, or the tab key are pressed.</p>
</div></div><!-- @@@left -->
<br/>
<!-- $$$priority -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="priority-prop"></a><span class="name">priority</span> : <span class="type"><a href="qml-enumeration.html">enumeration</a></span></p></td></tr></table></div><div class="qmldoc"><p>This property determines whether the keys are processed before or after the attached item's own key handling.</p>
<ul>
<li><a href="qml-keynavigation.html">KeyNavigation</a>.BeforeItem - process the key events before normal item key processing. If the event is used for key navigation, it will be accepted and will not be passed on to the item.</li>
<li><a href="qml-keynavigation.html">KeyNavigation</a>.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 <a href="qml-keynavigation.html">KeyNavigation</a> attached property handler.</li>
</ul>
</div></div><!-- @@@priority -->
<br/>
<!-- $$$tab -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="tab-prop"></a><span class="name">tab</span> : <span class="type"><a href="qml-item.html">Item</a></span></p></td></tr><tr valign="top" class="even"><td class="tblQmlPropNode"><p><a name="backtab-prop"></a><span class="name">backtab</span> : <span class="type"><a href="qml-item.html">Item</a></span></p></td></tr></table></div><div class="qmldoc"><p>These properties hold the item to assign focus to when the Tab key or Shift+Tab key combination (Backtab) are pressed.</p>
</div></div><!-- @@@tab -->
<br/>
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Digia, Qt and their respective logos are trademarks of Digia Plc
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
