Update copyright headers
[qt:qt.git] / doc / src / platforms / emb-running.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \page qt-embedded-running.html
30
31     \title Running Qt for Embedded Linux Applications
32     \ingroup qt-embedded-linux
33
34     A \l{Qt for Embedded Linux} application requires a server application to be
35     running, or to be the server application itself. Any \l{Qt for Embedded Linux}
36     application can be the server application by constructing the QApplication
37     object with the QApplication::GuiServer type, or by running the application
38     with the \c -qws command line option.
39
40     Applications can run using both single and multiple displays, and
41     various command line options are available.
42
43     Note that this document assumes that you either are using the
44     \l{The Virtual Framebuffer} or that you are running \l{Qt for Embedded Linux}
45     using the \l {The VNC Protocol and Qt for Embedded Linux}{VNC} protocol,
46     \e or that you have the Linux framebuffer configured
47     correctly and that no server process is running. (To test that the
48     Linux framebuffer is set up correctly, use the program provided by
49     the \l {Testing the Linux Framebuffer} document.)
50
51     \tableofcontents
52
53     \section1 Using a Single Display
54
55     To run the application using a single display, change to a Linux
56     console and select an application to run, e.g. \l {Text
57     Edit}{demos/textedit}.  Run the application with the \c -qws
58     option:
59
60     \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 0
61
62     \table 100%
63     \row
64     \o
65     Provided that the environment variables are adjusted properly
66     during the \l {Installing Qt for Embedded Linux}{installation process}, you
67     should see the \l {Text Edit} demo appear.
68
69     It might be that the hardware drivers must be specified explicitly
70     to make everything work properly. For more information, please
71     consult the following documentation:
72
73     \list
74         \o \l{Qt for Embedded Linux Pointer Handling}{Pointer Handling}
75         \o \l{Qt for Embedded Linux Character Input}{Character Input}
76         \o \l{Qt for Embedded Linux Display Management}{Display Management}
77     \endlist
78
79     \o
80     \inlineimage qt-embedded-runningapplication.png
81     \endtable
82
83     Additional applications can be run as clients, i.e., by running
84     these applications \e without the \c -qws option they will connect
85     to the existing server as clients. You can exit the server
86     application at any time using \gui{Ctrl+Alt+Backspace}.
87
88     \section1 Using Multiple Displays
89
90     Qt for Embedded Linux also allows multiple displays to be used
91     simultaneously. There are two ways of achieving this: Either run
92     multiple Qt for Embedded Linux server processes, or use the
93     ready-made \c Multi screen driver.
94
95     When running multiple server processes, the screen driver (and
96     display number) must be specified for each process using the \c
97     -display command line option or by setting the QWS_DISPLAY
98     environment variable. For example:
99
100     \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 1
101
102     See the \l {Qt for Embedded Linux Display Management}{display management}
103     documentation for more details on how to specify a screen
104     driver. Note that you must also specify the display (i.e., server
105     process) when starting client applications:
106
107     \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 2
108
109     There is no way of moving a client from one display to another
110     when running multiple server processes. Using the \c Multi screen
111     driver, on the other hand, applications can easiliy be moved
112     between the various screens.
113
114     The \c Multi screen driver can be specified just like any other
115     screen driver by using the \c -display command line option or by
116     setting the QWS_DISPLAY environment variable. For example:
117
118     \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 3
119
120     See the \l {Qt for Embedded Linux Display Management}{display management}
121     documentation for details regarding arguments.
122
123     \section1 Command Line Options
124
125     \table 100%
126     \header
127     \o Option \o Description
128     \row
129     \o \bold -fn <font>
130     \o
131     Defines the application font. For example:
132     \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 4
133     The font should be specified using an X logical font description.
134     \row
135     \o \bold -bg <color>
136     \o
137     Sets the default application background color. For example:
138     \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 5
139     The color-name must be one of the names recognized by the QColor constructor.
140     \row
141     \o \bold -btn <color> \o
142     Sets the default button color. For example:
143     \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 6
144     The color-name must be one of the names recognized by the QColor constructor.
145     \row
146     \o \bold -fg <color> \o
147     Sets the default application foreground color. For example:
148     \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 7
149     The color-name must be one of the names recognized by the QColor constructor.
150     \row
151     \o \bold -name <objectname> \o
152     Sets the application name, i.e. the application object's object name. For example:
153     \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 8
154     \row
155     \o \bold -title <title> \o
156     Sets the application's title. For example:
157     \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 9
158     \row
159     \o \bold -geometry <width>x<height>+<Xoffset>+<Yoffset> \o
160     Sets the client geometry of the first window that is shown. For example:
161     \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 10
162     \row
163     \o \bold -keyboard \o
164     Enables the keyboard.
165
166     See also: \l {Qt for Embedded Linux Character Input}.
167     \row
168     \o \bold -nokeyboard \o
169     Disables the keyboard.
170     \row
171     \o \bold -mouse \o
172     Enables the mouse cursor.
173
174     See also: \l {Qt for Embedded Linux Pointer Handling}.
175     \row
176     \o \bold -nomouse \o
177     Disables the mouse cursor.
178     \row
179     \o \bold -qws \o
180     Runs the application as a server application, i.e. constructs a
181     QApplication object of the QApplication::GuiServer type.
182     \row
183     \o \bold -display \o
184     Specifies the screen driver.
185
186     See also: \l {Qt for Embedded Linux Display Management}.
187     \row
188     \o \bold -decoration <style>\o
189     Sets the application decoration. For example:
190     \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 11
191     The supported styles are \c windows, \c default and \c styled.
192
193     See also QDecoration.
194
195     \endtable
196 */