doc/src/qtquick1/righttoleft.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qml-righttoleft.html
  30 \inqmlmodule QtQuick 1
  31 \title QML Right-to-left User Interfaces
  32
  33 \section1 Overview
  34
  35 This chapter discusses different approaches and options available for implementing right-to-left
  36 language support for Qt Quick applications. Some common right-to-left languages include Arabic, Hebrew,
  37 Persian and Urdu. Most changes include making sure that text translated to right-to-left languages
  38 is properly aligned to the right, and horizontally ordered content in views, lists and grids flows
  39 correctly from the right to left.
  40
  41 In right-to-left language speaking cultures, people naturally scan and read graphic elements and text
  42 from the right to left. The general rule of thumb is that content (like photos, videos and maps) is not
  43 mirrored, but positioning of the content (like application layouts and the flow of visual elements) is
  44 mirrored. For example, photos shown in chronological order should flow from right to left, the
  45 low end range of the horizontal sliders should be located at the right side of the slider, and
  46 text lines should should be aligned to the right side of the available text area. The location of visual
  47 elements should not be mirrored when the position is related to a content; for example, when a
  48 position marker is shown to indicate a location on a map. Also, there are some special cases you may
  49 need to take into account where right-to-left language speakers are used to left-to-right
  50 positioning, for example when using number dialers in phones and media play, pause, rewind and
  51 forward buttons in music players.
  52
  53 \section1 Text Alignment
  54
  55 (This applies to the \l Text, \l TextInput and \l TextEdit elements.)
  56
  57 When the horizontal alignment of a text item is not explicitly set, the text element is
  58 automatically aligned to the natural reading direction of the text. By default left-to-right text
  59 like English is aligned to the left side of the text area, and right-to-left text like Arabic is
  60 aligned to the right side of the text area. The alignment of a text element with empty text takes
  61 its alignment cue from \l QInputPanel::inputDirection(), which is based on the active
  62 system locale.
  63
  64 This default locale-based alignment can be overriden by setting the \c horizontalAlignment
  65 property for the text element, or by enabling layout mirroring using the \l LayoutMirroring attached
  66 property, which causes any explicit left and right horizontal alignments to be mirrored.
  67 Note that when \l LayoutMirroring is set, the \c horizontalAlignment property value remains unchanged;
  68 the effective alignment of the text element that takes the mirroring into account can be read from the
  69 \c effectiveHorizontalAlignment property.
  70
  71 \snippet doc/src/snippets/declarative/righttoleft.qml 0
  72
  73 \section1 Layout direction of positioners and views
  74
  75 (This applies to the \l Row, \l Grid, \l Flow, \l ListView and \l GridView elements.)
  76
  77 From Qt Quick 1.1 onwards, elements used for horizontal positioning and model views have gained a \c layoutDirection
  78 property for controlling the horizontal direction of the layouts. Setting \c layoutDirection to
  79 \c Qt.RightToLeft causes items to be laid out from the right to left. By default Qt Quick follows
  80 the left-to-right layout direction.
  81
  82 The horizontal layout direction can also be reversed through the \l LayoutMirroring attached property.
  83 This causes the effective \c layoutDirection of positioners and views to be mirrored. Note the actual value
  84 of the \c layoutDirection property will remain unchanged; the effective layout direction of positioners and
  85 views that takes the mirroring into account can be read from the \c effectiveLayoutDirection property.
  86
  87 \snippet doc/src/snippets/declarative/righttoleft.qml 1
  88
  89 \section1 Layout mirroring
  90
  91 The attached property \l LayoutMirroring is provided as a convenience for easily implementing right-to-left
  92 support for existing left-to-right Qt Quick applications. It mirrors the behavior of \l {anchor-layout}
  93 {Item anchors}, the layout direction of \l{Using QML Positioner and Repeater Items}{positioners} and
  94 model views, and the explicit text alignment of QML text elements.
  95
  96 You can enable layout mirroring for a particular \l Item:
  97
  98 \snippet doc/src/snippets/declarative/righttoleft.qml 2
  99
 100 Or set all child elements to also inherit the layout direction:
 101
 102 \snippet doc/src/snippets/declarative/righttoleft.qml 3
 103
 104 Applying mirroring in this manner does not change the actual value of the relevant anchor,
 105 \c layoutDirection or \c horizontalAlignment properties. The separate read-only property
 106 \c effectiveLayoutDirection can be used to query the effective layout
 107 direction of positioners and model views that takes the mirroring into account. Similarly the \l Text,
 108 \l TextInput and \l TextEdit elements have gained the read-only property \c effectiveHorizontalAlignment
 109 for querying the effective visual alignment of text. For anchors, the read only
 110 \l {Item::anchors.top}{anchors.mirrored} property reflects whether anchors have been mirrored.
 111
 112 Note that application layouts and animations that are defined using \l {Item::}{x} property values (as
 113 opposed to anchors or positioner elements) are not affected by the \l LayoutMirroring attached property.
 114 Therefore, adding right-to-left support to these types of layouts may require some code changes to your application,
 115 especially in views that rely on both the anchors and x coordinate-based positioning. Here is one way to use
 116 the \l LayoutMirroring attached property to apply mirroring to an item that is positioned using \l {Item::}{x}
 117 coordinates:
 118
 119 \snippet doc/src/snippets/declarative/righttoleft.qml 4
 120
 121 Not all layouts should necessarily be mirrored. There are cases where a visual element is positioned to
 122 the right side of the screen for improved one-handed use, because most people are right-handed, and not
 123 because of the reading direction. In the case that a child element should not be affected by mirroring,
 124 set the \l {LayoutMirroring::enabled}{LayoutMirroring.enabled} property for that element to false.
 125
 126 Qt Quick is designed for developing animated, fluid user interfaces. When mirroring your application, remember to test that
 127 the animations and transitions continue to work as expected. If you do not have the resources to add
 128 right-to-left support for your application, it may be better to just keep the application layouts left
 129 aligned and just make sure that text is translated and aligned properly.
 130
 131 \section1 Mirroring icons
 132
 133 (This applies to \l Image, \l BorderImage and \l AnimatedImage elements.)
 134
 135 Most images do not need to be mirrored, but some directional icons, such as arrows, may need to be mirrored.
 136 The painting of these icons can be mirrored with a dedicated \c mirror property introduced in Qt Quick 1.1:
 137
 138 \snippet doc/src/snippets/declarative/righttoleft.qml 5
 139
 140 \section1 Default layout direction
 141
 142 The \l {QML:Qt::application}{Qt.application.layoutDirection} property can be used to query the active layout direction of the
 143 application. It is based on QApplication::layoutDirection(), which most commonly determines the layout
 144 direction from the active language translation file.
 145
 146 To define the layout direction for a particular locale, declare the dedicated string literal
 147 \c QT_LAYOUT_DIRECTION in context \c QApplication as either "LTR" or "RTL".
 148
 149 You can do this by first introducing this line
 150
 151 \code
 152 QT_TRANSLATE_NOOP("QApplication", "QT_LAYOUT_DIRECTION");
 153 \endcode
 154
 155 somewhere in your QML source code and calling \c lupdate to generate the translation source file.
 156
 157 \code
 158 lupdate myapp.qml -ts myapp.ts
 159 \endcode
 160
 161 This will append the following declaration to the translation file, where you can fill in either "LTR" or
 162 "RTL" as the translation for the locale.
 163
 164 \code
 165 <context>
 166     <name>QApplication</name>
 167     <message>
 168         <location filename="myapp.qml" line="33"/>
 169         <source>QT_LAYOUT_DIRECTION</source>
 170         <translation type="unfinished">RTL</translation>
 171     </message>
 172 </context>
 173 \endcode
 174
 175 You can test that the layout direction works as expected by running your Qt Quick application with
 176 the compiled translation file:
 177
 178 \code
 179 qmlviewer myapp.qml -translation myapp.qm
 180 \endcode
 181
 182 You can test your application in right-to-left layout direction simply by executing qmlviewer with a
 183 command-line parameter "-reverse":
 184
 185 \code
 186 qmlviewer myapp.qml -reverse
 187 \endcode
 188
 189 The layout direction can also be set from C++ by calling the static function \l QApplication::setLayoutDirection():
 190
 191 \code
 192 QApplication app(argc, argv);
 193 app.setLayoutDirection(Qt::RightToLeft);
 194 \endcode
 195
 196 */