1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\page qtquick-positioning-righttoleft.html
6\title Right-to-left User Interfaces
7\brief switching text flow and layout
10This chapter discusses different approaches and options available for implementing right-to-left
11language support for Qt Quick applications. Some common right-to-left languages include Arabic, Hebrew,
12Persian and Urdu. Most changes include making sure that text translated to right-to-left languages
13is properly aligned to the right, and horizontally ordered content in views, lists and grids flows
14correctly from the right to left.
16In right-to-left language speaking cultures, people naturally scan and read graphic elements and text
17from the right to left. The general rule of thumb is that content (like photos, videos and maps) is not
18mirrored, but positioning of the content (like application layouts and the flow of visual elements) is
19mirrored. For example, photos shown in chronological order should flow from right to left, the
20low end range of the horizontal sliders should be located at the right side of the slider, and
21text lines should be aligned to the right side of the available text area. The location of visual
22elements should not be mirrored when the position is related to a content; for example, when a
23position marker is shown to indicate a location on a map. Also, there are some special cases you may
24need to take into account where right-to-left language speakers are used to left-to-right
25positioning, for example when using number dialers in phones and media play, pause, rewind and
26forward buttons in music players.
28\section1 Text Alignment
30(This applies to the \l Text, \l TextInput and \l TextEdit types.)
32When the horizontal alignment of a text item is not explicitly set, the text element is
33automatically aligned to the natural reading direction of the text. By default left-to-right text
34like English is aligned to the left side of the text area, and right-to-left text like Arabic is
35aligned to the right side of the text area. The alignment of a text element with empty text takes
36its alignment cue from \l QInputMethod::inputDirection(), which is based on the active
39This default locale-based alignment can be overridden by setting the \c horizontalAlignment
40property for the text element, or by enabling layout mirroring using the \l LayoutMirroring attached
41property, which causes any explicit left and right horizontal alignments to be mirrored.
42Note that when \l LayoutMirroring is set, the \c horizontalAlignment property value remains unchanged;
43the effective alignment of the text element that takes the mirroring into account can be read from the
44\c effectiveHorizontalAlignment property.
46\snippet qml/righttoleft.qml 0
48\section1 Layout Direction of Positioners and Views
50(This applies to the \l Row, \l Grid, \l Flow, \l ListView and \l GridView types.)
52Types used for horizontal positioning and model views have the \c layoutDirection
53property for controlling the horizontal direction of the layouts. Setting \c layoutDirection to
54\c Qt.RightToLeft causes items to be laid out from the right to left. By default Qt Quick follows
55the left-to-right layout direction.
57The horizontal layout direction can also be reversed through the \l LayoutMirroring attached property.
58This causes the effective \c layoutDirection of positioners and views to be mirrored. Note the actual value
59of the \c layoutDirection property will remain unchanged; the effective layout direction of positioners and
60views that takes the mirroring into account can be read from the \c effectiveLayoutDirection property.
62\snippet qml/righttoleft.qml 1
64\section1 Layout Mirroring
66The attached property \l LayoutMirroring is provided as a convenience for easily implementing right-to-left
67support for existing left-to-right Qt Quick applications. It mirrors the behavior of \l {anchor-layout}
68{Item anchors}, the layout direction of \l{Item Positioners}{positioners} and
69\l{qtquick-modelviewsdata-modelview.html}{model views}, and the explicit text alignment of QML text types.
71You can enable layout mirroring for a particular \l Item:
73\snippet qml/righttoleft.qml 2
75Or set all child types to also inherit the layout direction:
77\snippet qml/righttoleft.qml 3
79Applying mirroring in this manner does not change the actual value of the relevant anchor,
80\c layoutDirection or \c horizontalAlignment properties. The separate read-only property
81\c effectiveLayoutDirection can be used to query the effective layout
82direction of positioners and model views that takes the mirroring into account. Similarly the \l Text,
83\l TextInput and \l TextEdit types have gained the read-only property \c effectiveHorizontalAlignment
84for querying the effective visual alignment of text. For anchors, the read only
85\l {Item::anchors.top}{anchors.mirrored} property reflects whether anchors have been mirrored.
87Note that application layouts and animations that are defined using \l {Item::}{x} property values (as
88opposed to anchors or positioner types) are not affected by the \l LayoutMirroring attached property.
89Therefore, adding right-to-left support to these types of layouts may require some code changes to your application,
90especially in views that rely on both the anchors and x coordinate-based positioning. Here is one way to use
91the \l LayoutMirroring attached property to apply mirroring to an item that is positioned using \l {Item::}{x}
94\snippet qml/righttoleft.qml 4
96Not all layouts should necessarily be mirrored. There are cases where a visual type is positioned to
97the right side of the screen for improved one-handed use, because most people are right-handed, and not
98because of the reading direction. In the case that a child type should not be affected by mirroring,
99set the \l {LayoutMirroring::enabled}{LayoutMirroring.enabled} property for that type to false.
101Qt Quick is designed for developing animated, fluid user interfaces. When mirroring your application, remember to test that
102the animations and transitions continue to work as expected. If you do not have the resources to add
103right-to-left support for your application, it may be better to just keep the application layouts left
104aligned and just make sure that text is translated and aligned properly.
106\section1 Mirroring Icons
108(This applies to \l Image, \l BorderImage and \l AnimatedImage types.)
110Most images do not need to be mirrored, but some directional icons, such as arrows, may need to be mirrored.
111The painting of these icons can be mirrored with a dedicated \c mirror property:
113\snippet qml/righttoleft.qml 5
115\section1 Default Layout Direction
117Use the \l {QtQml::Qt::application}{Qt.application.layoutDirection} property
118to query the active layout direction of the application. It inherits
119QGuiApplication::layoutDirection(), which determines the layout direction from
120the active language translation file.
122To define the layout direction for a particular locale, declare the dedicated
123string literal \c QT_LAYOUT_DIRECTION in the context \c QGuiApplication as
124either \c LTR or \c RTL.
126First, introduce this line somewhere in your QML source code:
129qsTr("QT_LAYOUT_DIRECTION","QGuiApplication");
132Then use \l {Using lupdate} to generate the translation source file.
134This appends the following declaration to the translation file, where you can
135enter either \c LTR or \c RTL as the translation for the locale.
139 <name>QGuiApplication</name>
141 <location filename="myapp.qml" line="33"/>
142 <source>QT_LAYOUT_DIRECTION</source>
143 <translation type="unfinished">RTL</translation>
148Next, add the following bindings to the root QML component of your application:
150LayoutMirroring.enabled: Qt.application.layoutDirection === Qt.RightToLeft
151LayoutMirroring.childrenInherit: true
154The first binding ensures that the UI will be mirrored appropriately when a
155right-to-left locale is set. The second binding ensures that child items of the
156root component will also respect mirroring.
158You can test that the layout direction works as expected by running your Qt Quick application with
159the compiled translation file:
162qml myapp.qml -translation myapp.qm
165You can test your application in right-to-left layout direction by calling the
166static function \l QGuiApplication::setLayoutDirection():
169QGuiApplication app(argc, argv);
170app.setLayoutDirection(Qt::RightToLeft);