diff options
Diffstat (limited to 'doc/src/howtos')
| -rw-r--r-- | doc/src/howtos/appicon.qdoc | 6 | ||||
| -rw-r--r-- | doc/src/howtos/developmentsteps.qdoc | 186 | ||||
| -rw-r--r-- | doc/src/howtos/exceptionsafety.qdoc | 5 | ||||
| -rw-r--r-- | doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc | 97 | ||||
| -rw-r--r-- | doc/src/howtos/qmlbestpractices/qmlbestpractices-datatypes.qdoc | 49 | ||||
| -rw-r--r-- | doc/src/howtos/scalabilityintro.qdoc | 324 | ||||
| -rw-r--r-- | doc/src/howtos/unix-signal-handlers.qdoc | 10 |
7 files changed, 667 insertions, 10 deletions
diff --git a/doc/src/howtos/appicon.qdoc b/doc/src/howtos/appicon.qdoc index 86934bc..6d86b22 100644 --- a/doc/src/howtos/appicon.qdoc +++ b/doc/src/howtos/appicon.qdoc @@ -62,7 +62,7 @@ Finally, assuming you are using \c qmake to generate your makefiles, add this line to your \c myapp.pro file: - \snippet doc/src/snippets/code/doc_src_appicon.qdoc 1 + \snippet doc/src/snippets/code/doc_src_appicon.pro 1 Regenerate your makefile and your application. The \c .exe file will now be represented with your icon in Explorer. @@ -96,7 +96,7 @@ if the name of your icon file is \c{myapp.icns}, and your project file is \c{myapp.pro}, add this line to \c{myapp.pro}: - \snippet doc/src/snippets/code/doc_src_appicon.qdoc 2 + \snippet doc/src/snippets/code/doc_src_appicon.pro 2 This will ensure that \c qmake puts your icons in the proper place and creates an \c{Info.plist} entry for the icon. @@ -213,6 +213,6 @@ icon file is \c{myapp.svg}, and your project file is \c{myapp.pro}, add this line to \c{myapp.pro}: - \snippet doc/src/snippets/code/doc_src_appicon.qdoc 5 + \snippet doc/src/snippets/code/doc_src_appicon.pro 5 */ diff --git a/doc/src/howtos/developmentsteps.qdoc b/doc/src/howtos/developmentsteps.qdoc new file mode 100644 index 0000000..e898bf5 --- /dev/null +++ b/doc/src/howtos/developmentsteps.qdoc @@ -0,0 +1,186 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page qtdevelopment-steps.html +\title Qt Development: The Steps from Challenge to Achievement + +\section1 The Challenge + +One day, your boss runs into your cubicle and exclaims to you, "The board blew +millions on a new enterprise HelloWorld application. The new one does not work +and we need a solution quickly before this disaster brings down the company! I'm +putting you in charge of the whole project while I go on vacation -- see you in +2 weeks." + +\section1 Brainstorming Ideas - It is time to play! + +Never one to shy away from a challenge (especially when your job might be on the +line), you first set out try come up with an idea about what your options are. + +You ask around a bit and discover that the broken application was intended to +replace one that has been living on a dusty mainframe for the past 25 years. The +machine is nearing end of life and, rather than invest in replacement hardware +to run a legacy HelloWorld program, the board decided to invest in new software +that could be run on desktops, web, mobile devices and embedded into the +company's main product line -- a pocket size device with a small LCD screen, +which flashes the message "Hello World" every full moon. + +The vendor that was chosen to handle this task was a well known multinational +company that specialized in enterprise CRM/ERP systems. The project missed +several delivery deadlines over a 2 year period, and was 500% over budget. There +was not going to be much margin for error trying to fix the problem, and there +would likely be no budget either. + +You begin researching dozens of possible possible approaches to the problem. One +of the biggest challenges is that there are very few options that will allow you +to create native applications that use the same framework for targeting +\l{qt-creator-configure-target}{multiple platforms}. + +Some years ago you had coded a small desktop application using the Qt framework, +without realizing that it also can be used for targeting the web, mobile devices +and embedded devices. Since that time, Qt has added a new feature called \l{Qt +Quick}, which provides the ability to easily design applications with intuitive, +modern-looking, fluid user interfaces. + +\section1 Creating an Objective + +You quickly realize that you might need two, three, or more interfaces for your +application -- one for each of the target platforms you are aiming for. +Thankfully Qt has options well suited for each of them. + +For your mobile application the choice seems obvious enough. The new Qt Quick +technology looks very promising, but you do not know QML; the declarative +language that helps define the interface in a Qt Quick program. You still want +to give it a try, but worry that you might not have something complete before +your boss returns from vacation in two weeks. You also wonder if Qt Quick is +applicable to desktop and embedded targets -- and then of course there is the +need for something targeting the web. You decide to give Qt Quick a try first +and \l{QML Examples and Demos}{see where it takes you}. + +\section1 Developing Plans + +One thing you realize after reading up on \l{Qt Quick} is that things are very +different from the desktop when designing an interface. Qt Quick doesn't contain +ready made UI 'chrome'; the widgets and other design elements that define the +application interface. A new technology, called Qt Quick Components, looks like +a promising solution, but the components will only be available at a later date. +For now you'll have to come up with something on your own -- but you are keen to +give your design skills a work out, and learning to use Qt Quick seems to be a +great way to do it. + +Not knowing a better place to start, you begin by taking a cue from web design +and plan a wireframe, which helps +\l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-visual-editor.html}{define the application layout}, +content and user interaction. You decide on breaking the field of the screen +space into three roughly equal size parts. There will be one section across the +top, which will span the width of the screen, and two sections in the lower +have, which will be approximately as tall as the top section is wide (when in +portrait mode). + +The top section will be a simple text representation of the phrase "Hello World" +in English. In the lower left you would like to place some kind of audio +playback feature that repeats back the phrase in the top section of the screen. +Finally, in the lower right hand side of the screen will be four links to +similar views for additional languages -- Mandarin Chinese, Brazilian +Portuguese, Arabic, and Russian. When the user clicks one of the links the text +at the top is then translated, and the playback corresponds to the appropriate +language. + +While the wireframe is effective in dealing with one part of the design +challenge, it does not cover visual aspects other than layout and content. This +means that you still need to define colours, white space, and typography (among +other things). This is where a style guide would come in handy, if your company +already had one that is. In the absence of one you decide to again get some +inspiration from the web, and you mimic some of the company's website design +into your application -- a sans-serif font for white text on a blue field across +the top, black text on white for the bottom two sections, and a small company +logo to the left of the "Hello World" message. + + +\section1 Execution: The Coding Begins! + +At long last you sit down to \l{qt-technologies}{implement} your plans and +designs. The first few steps go according to plan, and creating the basic layout +and text goes fairly smoothly -- but you run into a few challenges quite +quickly: + +Devising a user friendly interface to audio playback is not as intuitive as you +first thought. Since there exist a ready made component for +\l{http://doc.qt.nokia.com/qtmobility-1.1.0/qml-multimedia.html}{multimedia}, +you remove the bottom left field and now have the screen split in two. You add +textual links for each of the five target languages, and when the user clicks +one of them the message text changes and the appropriate audio plays back. It is +a small sacrifice to make for now, and you are sure there is a solution to be +found once you have become more proficient with QML. + +The next challenge you run into is that \l{qt-deployment}{deploying} the +application to a Symbian phone is not as clearly understood as you expected. +Again you are sure there is something you are missing, but for the time being +you manually copy the .sis file to the "Installs" directory on the phone +(connected to the development machine by USB) and then install it through the +Application Manager. + +When you finally manage to install the application on the device you notice +something that looks rather peculiar, and something you had not thought of. When +the phone is turned into landscape mode, your text remains at the same absolute +coordinates as when it was in portrait mode. You had not realized you needed to +anchor it in order to achieve the centering you wanted. There was an +\l{qt-testing}{easy fix} for this, but you were glad you saw this earlier rather +than later. + + +\section1 Innovating + +After the ups and downs of learning to develop a basic application +using Qt Quick, you start to see greater possibilities for using Qt technologies +for your current and future projects: + +\list +\o Extending HTML5 based applications that tie Javascript to a Qt C++ back end +using \l{Qt WebKit} +\o An \l{qt-rendering-painting-system}{OpenGL} based UI for embedded platforms +\o \l{Gestures Programming}{Touch} screen support +\o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/location-overview.html}{Location} based applications +\o \l{qt-technologies}{Much, much more} +\endlist + + +\section1 The Achievement + +After your boss returned from vacation you presented him with the finished Qt +Quick application, demonstrating it on both a mobile device as well as desktop +(it happened to work well on both with little modification). You also provided +him a presentation that detailed your road map for taking things to the next +level -- targeting other platforms, such as the web, as well as improving on the +existing application you just completed. + +Even though the final product did not turn out the way you originally planned, +your boss was still sufficiently impressed. Not only was the go ahead given for +future projects, but ramping up a small team of developers and designers was +also suggested to help support your efforts. + +*/ diff --git a/doc/src/howtos/exceptionsafety.qdoc b/doc/src/howtos/exceptionsafety.qdoc index c4b5ebc..b3795d6 100644 --- a/doc/src/howtos/exceptionsafety.qdoc +++ b/doc/src/howtos/exceptionsafety.qdoc @@ -100,8 +100,9 @@ if any allocation fails. Allocations can fail if the system runs out of memory or doesn't have enough continuous memory to allocate the requested size. - Exceptions to that rule are documented. As an example, \l QImage::create() - returns false if not enough memory exists instead of throwing an exception. + Exceptions to that rule are documented. As an example, QImage constructors will + create a \l{QImage::isNull()}{null} image if not enough memory exists instead + of throwing an exception. \section1 Recovering from exceptions diff --git a/doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc b/doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc new file mode 100644 index 0000000..246c4e4 --- /dev/null +++ b/doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc @@ -0,0 +1,97 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qml-best-practices-coding.html +\ingroup qml-best-practices +\contentspage QML Best Practices Guides +\previouspage QML Best Practices Guides +\startpage QML Best Practices Guides +\title QML Best Practices: Coding Conventions + +\brief QML Coding Conventions and Importing Files + +There are many different ways to code using QML. These are a set of +guidelines to help your code look better and consistent. + +\section1 Coding Conventions + +The official QML Coding Conventions may be found at +\l {QML Coding Conventions}. This is the recommended convention that will be +used throughout the QML documentation. + +In addition, Qt's official code style may be found at the \l {Qt Coding Style}. + +\section1 Importing Files into QML + +To import items such as directories, use the "import" keyword, similar to +the way the \c {import QtQuick 1.0} statement is used. + +\snippet doc/src/snippets/declarative/imports/best-practices.qml imports + +To facilitate the import of QML components, it is best to begin the QML +file with an uppercase character. This way, the user can simply declare the +component using the file name as the component name. For example, if a QML +component is in a file named \c Button.qml, then the user may import the +component by declaring a \c {Button {}}. Note that this method only works if +the QML files are in the same directory. + +It is also possible to import QML files which have file names that begin in +lower case or files in a different directory by using a \c qmldir file. + +A \c qmldir file tells your QML application which QML components, plugins, +or directories to import. The \c qmldir file must reside in an imported +directory. By using the \c qmldir file, users may import any QML file and assign any +valid QML component name to the component. + +For more information, read the section on +\l{qml-loading-components}{Loading a Component}. + +\section1 Commenting Code + +Commenting code allows others to read the source code better. As well, comments +allow the programmer to think about his or her code; a confusing comment may +mean the code is confusing. + +Similar to JavaScript or C++, there are two ways of commenting QML code: +\list +\o Single line comments start with \c{//} and finish at the end of the line +\o Multiline comments start with \c{/*} and finish with *\/ +\endlist + +\section1 Group Properties + +Many QML properties are \l{attached-properties}{attached} or +\l {qml-grouped-properties}{group} properties. For convenience, you may treat +them as another element when dealing with multiple properties belonging to the +same group. + +\snippet doc/src/snippets/declarative/bestpractices/group.qml not grouped +Treating groups of properties as a block can ease confusion and help relate the +properties with other properties. +\snippet doc/src/snippets/declarative/bestpractices/group.qml grouped +*/ diff --git a/doc/src/howtos/qmlbestpractices/qmlbestpractices-datatypes.qdoc b/doc/src/howtos/qmlbestpractices/qmlbestpractices-datatypes.qdoc new file mode 100644 index 0000000..0f6d74b --- /dev/null +++ b/doc/src/howtos/qmlbestpractices/qmlbestpractices-datatypes.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! + \page qml-best-practices-datatypes.html + \ingroup qml-best-practices + \contentspage QML Best Practices Guides + \previouspage QML Best Practices Guides + \startpage QML Best Practices Guides + \title QML Best Practices: Data Types + + \brief Using Basic Data Types and Custom Types in QML + + QML supports many basic data types, Qt data types, and custom data types. + + \section1 Basic Data Types + + \section1 Qt Data Types + + \section1 Exporting Qt Types to QML + + Programmers may create C++ data structures and expose them to QML, making + data accessible from QML. + + \section2 Using QStringLists in QML +*/ diff --git a/doc/src/howtos/scalabilityintro.qdoc b/doc/src/howtos/scalabilityintro.qdoc new file mode 100644 index 0000000..5b4e58b --- /dev/null +++ b/doc/src/howtos/scalabilityintro.qdoc @@ -0,0 +1,324 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Scalability + \page scalability.html + \preliminary + + \omit preliminary docs for next SDK release \endomit + \omit Somewhere I need to mention applications with more than + one page (top-level layouts). \endomit + + A scalable application is an application that can run on more than + one form factor. In particular, it can cope with different screen + sizes, DPI, and aspect ratios. You need to consider scalability + when: + + \list + \o your application will be deployed to more than one device + handset, or more than one device form factor. + \o your application will be deployed for a long period of time, + so that new device handsets might appear on the market after + your initial deployment. + \endlist + + This document discusses how scalable applications can be created. + + \section1 Developing Scalable UIs + + This section shows the basics of how we advice scalable + applications to be implemented using QML. We recommend that you + follow these techniques: + + \list + \o Create separate top-level layout + definitions for each form factor. + \o Keep the layouts small and let components + scale relative to their immediate parent. + \o Define device independent measurements, such as dp + (device independent pixels), and use + these to scale components and for layout measurement. + \o Define layouts in a + proportional way using the built-in layout features of QML. + \endlist + + Using small top-level layouts makes your codebase smaller and + easier to maintain. Also, components that scales relative to their + parent are more reusable. The layouts should be children of the + application's root item. You can change between them by, for + instance, using the opacity property of Item; that is, if your + application has more tham one top-level layout. Such a top-level + layout is also often referred to as a page, i.e., a layout that + uses the entire screen. For instance, an organizer application + will typically have separate pages for showing the calender and + editing todo items. + + You should define the measurements separate from the UI, for + instance by using a JavaScript object that you fill in with a + script on application start up. + + QML provides several ways of laying out components, e.g, using + anchor based layout, the more classic Grid; Column; and Row + elements, and by setting the dimensions of Items directly. When + laying out components in scalable applications, you should + generally prefer using anchors and set width and height based on + parent size where possible. Layouts are not only relevant to + top-level layouts; components often contain child Items. + + The following sections describe in more detail the different + aspects of scalability that should be considered in order to + achieve the desired level of flexibility within your application. + + \section1 Implementing the Top-Level Layouts + + As mentioned, each application should use separate top-level + layout QML definitions to support separate layout configurations / + form factors. + + Consider an application that has to be deployed to at least two + devices, which both have very different screen sizes and DPI + values. The two form factors of the application will share many + common components and attributes, and will most likely connect to + the same data model. + + Therefore, the top-level definitions should be quite + straightforward and short, with the majority of the functionality + refactored into contained Components. It is important to try to + avoid unnecessary duplication between these top-level definitions, + in order to improve maintainability. + + There are some patterns that you might consider when designing + your top level layouts: + + \list + \o In some cases, the contents of an entire page in a smaller + handset could form a component element of a layout in a + larger device. Therefore, consider making that a separate + component (i.e. defined in a separate QML file), and in the + smaller handset, the Page will simply contain an instance of + that component. On the larger device, there may be enough + space to show two separate items. For example, in an email + viewer, if the screen is large enough, it may be possible to + show the email list view, and the email reader view side by + side. + \o In some cases, the contents of a view might be quite similar + on all screen sizes, but with an expanded content area. In + this case, it may be possible to re-use the same layout + definition, if defined appropriately using anchors. + \endlist + + The \l{Loader} component can be used to load separate QML files + based on some criteria, such as Device Profile (configuration of + screen pixel resolution and DPI density). In the case of form + factor, this information will not change during the application's + lifetime, therefore there is no issue with memory usage or + performance. + + \section1 Defining Measurements + + When you are defining the measurements within an application or + component layout, there are a number aspects to consider: + + \list + \o The layout structure, the high-level relationship between + items. Which item is the parent? How are the items arranged + relatively on the screen? Are they in a grid or column? + \o The layout measurements. How big is an item, or a margin + inside the edge of an item, or an anchor between items? + \o The implicit size of contained items. Some child items will + require a certain amount of space, such as a button + containing a text. That may also depend on the current + platform and style. How do you ensure that you leave enough + space, and what happens if your children change size? + \endlist + + These aspects combine together to resolve the final layout for a + given Device Profile. However, although there are dependencies + between them, it is important to manage and control the different + aspects separately. + + It is strongly recommended that Layout measurements should be + stored in a separate place from the component layout structure + definition files. The reason for this is that layout structure, + for a given form factor, can be re-used for different Device + Profiles. However, measurements will almost always vary between + Device Profiles or Device Categories. + + If the opposite approach (complete duplication of entire QML + files) was taken, then all of the layout states and structure + definitions would be duplicated between the copied QML files, and + only the measurement values would change. + + The main benefit of using separate measurement definition files + are: + + \list + \o To reduce the amount of duplication, and hence increase + maintainability. + \o It becomes much easier to change the layout structure, + perhaps due to subsequent specification changes. In that + case, the layout structure can be modified once, and many or + all of the layout measurements would remain unchanged. + \o It becomes much easier to add support for additional Device + Profiles, simply by adding another measurement definition + file. + \endlist + + \section1 Using QML's Layout Features + + For a given form factor, top-level Layouts structure definitions, + or component layout structure definitions, should in general be + defined in a proportional way using a combination of + + \list + \o \l{Item::anchors.top}{anchors} within an Item + \o \l{Row} / \l{Column} / \l{Grid} + \o simple javascript expressions such as width: Math.round(parent.width / 3.0). + \endlist + + These basic building blocks, along with the powerful evaluation + capabilities of javascript expressions within every QML binding, + are designed to allow the majority of the layout structure + definition to be defined in a Device Profile independent way. + + There are some limitations of the basic grid type layouts. They + are designed to accommodate a number of Items, but use the current + sizes of those items. There is a similar issue with the basic + anchor type layout. In particular, it can be difficult to spread a + number of child items proportionately across an area of their + container. + + By combining the features of the layout managers with simple + javascript expressions, a richer variety of designs can be + expressed, without having to resort to additional layout + measurement parameters or measurement values. + + Here are some things not to do with layouts: + + \list + \o Don't define complex javascript functions that are regularly + evaluated. This will cause poor performance, particularly + during animated transitions. + \o Don't define all of your layouts using x, y, width and + height. Reserve this for items that cannot easily be defined + using anchors (anchors are evaluated in a more efficient + way). + \o Don't make assumptions about the container size, or about + the size of child items. Try to make flexible layout + definitions that can absorb changes in the available space. + \endlist + + \section1 Orientation Switches + + Application top-level page definitions, and reusable component + definitions, should use one QML layout definition for the layout + structure. This single definition should include the layout design + for separate Device Orientations and Aspect Ratios. The reason for + this is that performance during an orientation switch is critical, + and it is therefore a good idea to ensure that all of the + components needed by both orientations are loaded when the + orientation changes. + + On the contrary, you should perform thorough tests if you choose + to use a \l{Loader} to load additional QML that is needed in separate + orientations, as this will affect the performance of the + orientation change. + + In order to enable layout animations between the orientations, the + anchor definitions must reside within the same containing + component. Therefore the structure of a page or a component + should consist of a common set of child components, a common set + of anchor definitions, and a collection of states (defined in a + StateGroup) representing the different aspect ratios supported by + the component. (However note that orientation change animations + are not possible on Symbian due to compatibility support for S60 + applications). + + If a component contained within a page needs to be + hosted in numerous different form factor definitions, then the + layout states of the view should depend on the aspect ratio of the + page (its immediate container). Similarly, different instances of + a component might be situated within numerous different containers + in a UI, and so its layout states should be determined by the + aspect ratio of its parent. The conclusion is that layout states + should always follow the aspect ratio of the direct container (not + the "orientation" of the current device screen). + + Within each layout \l{State}, you should define the relationships + between items using native QML layout definitions. See below for + more information. During transitions between the states (triggered + by the top level orientation change), in the case of anchor + layouts, AnchorAnimation elements can be used to control the + transitions. In some cases, you can also use a NumberAnimation on + e.g. the width of an item. Remember to avoid complex javascript + calculations during each frame of animation. Using simple anchor + definitions and anchor animations can help with this in the + majority of cases. + + There are a few additional cases to consider: + + \list + \o What if you have a single page that looks completely + different between landscape and portrait, i.e. all of the + child items are different? For each page, have two child + components, with separate layout definitions, and make one + or other of the items have zero opacity in each state. You + can use a cross-fade animation by simply applying a + NumberAnimation transition to the opacity. + \o What if you have a single page that shares 30% or more of + the same layout contents between portrait and landscape? In + that case, consider having one component with landscape and + portrait states, and a collection of separate child items + whose opacity (or position) depends on the orientation + state. This will enable you to use layout animations for the + items that are shared between the orientations, whilst the + other items are either faded in/out, or animated on/off + screen. + \o What if you have two pages on a handheld device that need to + be on screen at the same time, for example on a larger form + factor device? In this case, notice that your view component + will no longer be occupying the full screen. Therefore it's + important to remember in all components (in particular, list + delegate items) should depend on the size of the containing + component width, not on the screen width. It may be + necessary to set the width in a Component.onCompleted() + handler in this case, to ensure that the list item delegate + has been constructed before the value is set. + \o What if the two orientations take up too much memory to have + them both in memory at once? Use a \l{Loader} if necessary, if + you cannot keep both versions of the view in memory at once, + but beware performance on the cross-fade animation during + layout switch. One solution could be to have two "splash + screen" items that are children of the Page, then you cross + fade between those during rotation. Then you can use a + \l{Loader} to load another child component that loads the actual + model data to another child Item, and cross-fade to that + when the \l{Loader} has completed. + \endlist + */ + diff --git a/doc/src/howtos/unix-signal-handlers.qdoc b/doc/src/howtos/unix-signal-handlers.qdoc index 2fa558e..20beb38 100644 --- a/doc/src/howtos/unix-signal-handlers.qdoc +++ b/doc/src/howtos/unix-signal-handlers.qdoc @@ -59,7 +59,7 @@ sigaction(2) man pages before plowing through the following code snippets. - \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc 0 + \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.cpp 0 In the MyDaemon constructor, use the socketpair(2) function to initialize each file descriptor pair, and then create the @@ -68,24 +68,24 @@ appropriate slot function, which effectively converts the Unix signal to the QSocketNotifier::activated() signal. - \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc 1 + \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.cpp 1 Somewhere else in your startup code, you install your Unix signal handlers with sigaction(2). - \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc 2 + \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.cpp 2 In your Unix signal handlers, you write a byte to the \e write end of a socket pair and return. This will cause the corresponding QSocketNotifier to emit its activated() signal, which will in turn cause the appropriate Qt slot function to run. - \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc 3 + \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.cpp 3 In the slot functions connected to the QSocketNotifier::activated() signals, you \e read the byte. Now you are safely back in Qt with your signal, and you can do all the Qt stuff you weren'tr allowed to do in the Unix signal handler. - \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.qdoc 4 + \snippet doc/src/snippets/code/doc_src_unix-signal-handlers.cpp 4 */ |