diff options
Diffstat (limited to 'doc')
24 files changed, 1021 insertions, 0 deletions
diff --git a/doc/src/demos/desktopservices.qdoc b/doc/src/demos/desktopservices.qdoc new file mode 100644 index 0000000..71197c2 --- /dev/null +++ b/doc/src/demos/desktopservices.qdoc @@ -0,0 +1,33 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example demos/embedded/desktopservices + \title Embedded Desktop Services Demonstration + + \image embeddeddesktopservices-demo.png +*/ diff --git a/doc/src/demos/embeddedsvgviewer.qdoc b/doc/src/demos/embeddedsvgviewer.qdoc new file mode 100644 index 0000000..fbf15e2 --- /dev/null +++ b/doc/src/demos/embeddedsvgviewer.qdoc @@ -0,0 +1,33 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example demos/embedded/embeddedsvgviewer + \title Embedded SVG Viewer Demonstration + + \image embeddedsvgviewer-demo.png +*/ diff --git a/doc/src/demos/fluidlauncher.qdoc b/doc/src/demos/fluidlauncher.qdoc new file mode 100644 index 0000000..ec57373 --- /dev/null +++ b/doc/src/demos/fluidlauncher.qdoc @@ -0,0 +1,33 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example demos/embedded/fluidlauncher + \title Fluid Launcher Demonstration + + \image fluidlauncher-demo.png +*/ diff --git a/doc/src/demos/weatherinfo.qdoc b/doc/src/demos/weatherinfo.qdoc new file mode 100644 index 0000000..ed759c2 --- /dev/null +++ b/doc/src/demos/weatherinfo.qdoc @@ -0,0 +1,33 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example demos/embedded/weatherinfo + \title Weather Info Demonstration + + \image weatherinfo-demo.png +*/ diff --git a/doc/src/examples/bearercloud.qdoc b/doc/src/examples/bearercloud.qdoc new file mode 100644 index 0000000..ddf145c --- /dev/null +++ b/doc/src/examples/bearercloud.qdoc @@ -0,0 +1,183 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example network/bearercloud + \title Bearer Cloud Example + + The Bearer Cloud example shows how to use the Bearer Management API to monitor the + connectivity state of the local device. + + \image bearercloud-example.png Screenshot of the Bearer Cloud example + + Bearer Management provides the QNetworkConfigurationManager class which can be used to monitor + changes in the available \l {QNetworkConfiguration}{network configurations} and the + QNetworkSession class which is used to \l {QNetworkSession::open()}{open} and + \l {QNetworkSession::close()}{close} a session bringing a network interface up or down if + necessary. + + This example displays all known \l {QNetworkConfiguration}{network configurations} in a cloud + orbiting the local device. There are four orbits representing the four possible + \l {QNetworkConfiguration::StateFlags}{states} that the network configuration can be in. + The closer the orbit the more useful the network configuration is in its current state. + The inner orbit is populated with network configurations that are in the + \l {QNetworkConfiguration::Active}{Active} state. The second orbit is populated with network + configurations that are in the \l {QNetworkConfiguration::Discovered}{Discovered} state. The + third orbit is populated with network configurations that are in the + \l {QNetworkConfiguration::Defined}{Defined} state. Finally the outer orbit is populated by + configurations that are in the \l {QNetworkConfiguration::Undefined}{Undefined} state. + + Hovering the mouse over a network configuration will display information about the network + configuration in a tool tip. + + Double clicking on an Active or Discovered network configuration will + \l {QNetworkSession::close()}{close} or \l {QNetworkSession::open()}{open} a network session, + respectively. + + Lastly you can reorganize the cloud without changing the state of the network configurations by + dragging them around. + + This example consists of two main classes, the BearerCloud and Cloud classes. The Cloud class + represents a single network session and associated network configuration. The BearerCloud + class implements a Graphics View scene and manages the life-cycle of Cloud + objects in response to notification signals from QNetworkConfigurationManager. + + \section1 Setting the scene + + When constructing the scene we first calculate some random offsets using the global qsand() + and qrand() functions. We will use these offsets to scatter the initial position of new Cloud + objects. + + Next we place a text item in the center of the scene to represent the local device and + surround it with four concentric circles to help visualize the orbits. + + Finally we connect up the network configuration notification signals and queue the initial + population of the scene during the next iteration of the event loop. + + \snippet examples/network/bearercloud/bearercloud.cpp 0 + + Populating the scene with the initial list of known network configuration is easy. Iterate + over the list returned by QNetworkConfigurationManager::allConfigurations(), calling our + configurationAdded() slot on each one. + + We finishing off by calling cloudMoved() to ensure that animations are started. + + \snippet examples/network/bearercloud/bearercloud.cpp 1 + + The configurationAdded() slot gets called when a new network configuration is added to the + system. + + It stores the \l {QNetworkConfiguration::identifier()}{identifier} of the network + configuration in the \e {configStates} map, which is used to keep a count of the number of + network configurations in each state. This in turn is used to calculate the initial position + of new Cloud objects. + + Next we create a new Cloud object for this network configuration. Set its initial position + and store it in the \e {configurations} hash. + + The last step is to add it to the scene by calling QGraphicsScene::addItem(). + + \snippet examples/network/bearercloud/bearercloud.cpp 2 + + The configurationRemoved() slot gets called when a network configuration is removed from the + system. + + First we remove all references to the network configuration from the \e {configStates} and + \e {configurations} member variables. + + Next we initiate animation by setting a final scale value on the Cloud object associated with + the removed network configuration. + + Finally we flag the Cloud object to delete itself after it has finished animating. + + \snippet examples/network/bearercloud/bearercloud.cpp 3 + + The Cloud object will take care of most of the work required when a network configuration + changes. All we do in the configurationChanged() slot is update the \e {configStates} member + variable. + + \snippet examples/network/bearercloud/bearercloud.cpp 4 + + + \section1 Responding to changes + + Each network session and associated network configuration known to the system is represented in + the scene as a Cloud object. + + In the Cloud constructor we first initialize member variables. Then we create a new + QNetworkSession object bound to the network configuration. Next we connect the QNetworkSession + signals which we use to monitor it for state changes. + + Next we set some QGraphicsItem properties. The QGraphicsItem::ItemIsMovable flag enables mouse + interaction with the Cloud object. + + The Cloud object consists of an icon and a text caption, these are constructed here. We will + assign values to them later, as these will change as the sessions state changes. + + Next we set the initial animation state and call our newConfigurationActivated() slot to finish + setting up the Cloud object based on the state of network session. + + \snippet examples/network/bearercloud/cloud.cpp 0 + + The newConfigurationActivated() slot is called when a session has successfully roamed from one + access point to another. + + The first thing we do is set the icon, inserting it into a shared SVG renderer cache if it is + not already available. Next we set the text caption to the name of the network configuration. + + We then set the position of the icon and text caption so that they are centered horizontally. + + Finally we call our stateChanged() slot. + + \snippet examples/network/bearercloud/cloud.cpp 1 + + The stateChanged() slot is called when the session state changes. + + In this slot we set lower the opacity of Cloud objects with network sessions that cannot be + \l {QNetworkSession::open()}{opened}, and set a detailed tool tip describing the sessions + state. + + \snippet examples/network/bearercloud/cloud.cpp 2 + + In our reimplementation of the QGraphicsItem::mouseDoubleClickEvent() function we call + QNetworkSession::open() or QNetworkSession::close() to open or close the session in response + to a double left click. + + \snippet examples/network/bearercloud/cloud.cpp 3 + + As we support the user dragging Cloud objects around we need to restart animations when the + position of the Cloud object changes. This is accomplished by reimplementing the + QGraphicsItem::itemChanged() function and calling the cloudMoved() function of the BearerCloud + object. + + \snippet examples/network/bearercloud/cloud.cpp 4 + + The remainder of the code for the Cloud object implements the animations. The + calculateForces() function calculates the new position of the Cloud object based on the + position of all the other Cloud objects in the scene. The new position is set when the + advance() function is called to update the Cloud object for the current animation frame. +*/ diff --git a/doc/src/examples/delayedencoding.qdoc b/doc/src/examples/delayedencoding.qdoc new file mode 100644 index 0000000..665ba15 --- /dev/null +++ b/doc/src/examples/delayedencoding.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example draganddrop/delayedencoding + \title Delayed Encoding Example + + The Delayed Encoding example shows how to delay preparing of data + for drag and drop operations until a drop target is found. + + \image delayedecoding-example.png + + The \gui Export push button is pressed down to start the drag. + The data for the drag and drop operation is not processed until + the user of the application has found a valid drop target. This + removes redundant processing if the operation is aborted. In our + case, we have an SVG image that we wish to send as the \c { + "image/png" } MIME type. It is the conversion from SVG to PNG we + wish to delay - it can be quite expensive. + + The example is implemented in two classes: \c SourceWidget and \c + MimeData. The \c SourceWidget class sets up the GUI and starts the + drag operation on request. The \c MimeData class, which inherits + QMimeData, sends a signal when a drop target is found. This signal + is connected to a slot in \c SourceWidget, which does the + conversion from SVG to PNG. + + \section1 SourceWidget Class Definition + + The \c SourceWidget class starts drag and drop operations and also + does the image conversion. + + \snippet examples/draganddrop/delayedencoding/sourcewidget.h 0 + + The \gui Export push button is connected to the \c startDrag() + slot. The \c createData() slot will be invoked when data for the + drag and drop operation is to be created. + + \section1 SourceWidget Class Implementation + + Let's start our code tour with a look at the \c startDrag() slot. + + \snippet examples/draganddrop/delayedencoding/sourcewidget.cpp 0 + + We emit \c dataRequested() from \c MimeData when the operation has + found a valid drop target. + + We gallop along to \c createData(): + + \snippet examples/draganddrop/delayedencoding/sourcewidget.cpp 1 + + Fortunately, Qt provides QSvgRenderer, which can render the SVG + image to any QPaintDevice. Also, QImage has no problems saving to + the PNG format. + + Finally, we can give the data to \c MimeData. + + \section1 MimeData Class Definition + + The \c MimeData class inherits QMimeData and makes it possible to + delay preparing of the data for a drag and drop operation. + + \snippet examples/draganddrop/delayedencoding/mimedata.h 0 + + We will look closer at \c retrieveData() and \c formats() in the + next section. + + \section1 MimeData Class Implementation + + \snippet examples/draganddrop/delayedencoding/mimedata.cpp 0 + + In the \c formats() function, we return the format of the + data we provide. This is the \c { image/png } MIME type. + + \snippet examples/draganddrop/delayedencoding/mimedata.cpp 1 + + \c retrieveData() is reimplemented from QMimeData and is + called when the data is requested by the drag and drop + operation. Fortunately for us, this happens when the operation + is finishing, i.e., when a drop target has been found. + + We emit the \c dataRequested() signal, which is picked up by + \c SourceWidget. The \c SourceWidget (as already explained) + sets the data on \c MimeData with \l{QMimeData::}{setData()}. + +*/ + diff --git a/doc/src/examples/framebufferobject.qdoc b/doc/src/examples/framebufferobject.qdoc new file mode 100644 index 0000000..eff11a9 --- /dev/null +++ b/doc/src/examples/framebufferobject.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example opengl/framebufferobject + \title Framebuffer Object Example + + The Framebuffer Object example demonstrates how to use the + QGLFramebufferObject class to render into an off-screen buffer and + use the contents as a texture in a QGLWidget. + + \image framebufferobject-example.png +*/ diff --git a/doc/src/examples/svggenerator.qdoc b/doc/src/examples/svggenerator.qdoc new file mode 100644 index 0000000..5b3ea00 --- /dev/null +++ b/doc/src/examples/svggenerator.qdoc @@ -0,0 +1,122 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example painting/svggenerator + \title SVG Generator Example + + The SVG Generator example shows how to add SVG file export to applications. + + \image svggenerator-example.png + + Scalable Vector Graphics (SVG) is an XML-based language for describing + two-dimensional vector graphics. Qt provides classes for rendering and + generating SVG drawings. This example allows the user to create a simple + picture and save it to an SVG file. + + The example consists of two classes: \c Window and \c DisplayWidget. + + The \c Window class contains the application logic and constructs the user + interface from a Qt Designer UI file as described in the + \l{Using a Designer UI File in Your Application#The Multiple Inheritance Approach}{Qt Designer manual}. + It also contains the code to write an SVG file. + + The \c DisplayWidget class performs all the work of painting a picture on + screen. Since we want the SVG to resemble this picture as closely as + possible, we make this code available to the \c Window class so that it can + be used to generate SVG files. + + \section1 The DisplayWidget Class + + The \c DisplayWidget class displays a drawing consisting of a selection of + elements chosen by the user. These are defined using \c Shape and + \c Background enums that are included within the class definition: + + \snippet examples/painting/svggenerator/displaywidget.h DisplayWidget class definition + + Much of this class is used to configure the appearance of the drawing. The + \c paintEvent() and \c paint() functions are most relevant to the purpose + of this example, so we will describe these here and leave the reader to + look at the source code for the example to see how shapes and colors are + handled. + + We reimplement the QWidget::paintEvent() function to display the drawing + on screen: + + \snippet examples/painting/svggenerator/displaywidget.cpp paint event + + Here, we only construct a QPainter object, begin painting on the device + and set a render hint for improved output quality before calling the + \c paint() function to perform the painting itself. When this returns, + we close the painter and return. + + The \c paint() function is designed to be used for different painting + tasks. In this example, we use it to draw on a \c DisplayWidget instance + and on a QSvgGenerator object. We show how the painting is performed to + demonstrate that there is nothing device-specific about the process: + + \snippet examples/painting/svggenerator/displaywidget.cpp paint function + + \section1 The Window Class + + The \c Window class represents the example's window, containing the user + interface, which has been created using Qt Designer: + + \snippet examples/painting/svggenerator/window.h Window class definition + + As with the \c DisplayWidget class, we concentrate on the parts of the code + which are concerned with painting and SVG generation. In the \c Window + class, the \c saveSvg() function is called whenever the \gui{Save As...} + button is clicked; this connection was defined in the \c{window.ui} file + using Qt Designer. + + The start of the \c saveSvg() function performs the task of showing a file + dialog so that the user can specify a SVG file to save the drawing to. + + \snippet examples/painting/svggenerator/window.cpp save SVG + + In the rest of the function, we set up the generator and configure it to + generate output with the appropriate dimensions and write to the + user-specified file. We paint on the QSvgGenerator object in the same way + that we paint on a widget, calling the \c DisplayWidget::paint() function + so that we use exactly the same code that we used to display the drawing. + + The generation process itself begins with the call to the painter's + \l{QPainter::}{begin()} function and ends with call to its + \l{QPainter::}{end()} function. The QSvgGenerator paint device relies on + the explicit use of these functions to ensure that output is written to + the file. + + \section1 Further Reading + + The \l{SVG Viewer Example} shows how to display SVG drawings in an + application, and can be used to show the contents of SVG files created + by this example. + + See the QtSvg module documentation for more information about SVG and Qt's + SVG classes. +*/ diff --git a/doc/src/examples/svgviewer.qdoc b/doc/src/examples/svgviewer.qdoc new file mode 100644 index 0000000..c9ddb08 --- /dev/null +++ b/doc/src/examples/svgviewer.qdoc @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example painting/svgviewer + \title SVG Viewer Example + + The SVG Viewer example shows how to add SVG viewing support to applications. + + \image svgviewer-example.png + + Scalable Vector Graphics (SVG) is an XML-based language for describing two-dimensional + vector graphics. Qt provides classes for rendering and displaying SVG drawings in + widgets and on other paint devices. This example allows the user to load SVG files + and view them in a QGraphicsView using a QGraphicsSvgItem. Based on the selected + renderer the QGraphicsView uses either a QWidget or QGLWidget as its viewport. A + third render mode is also provided, where the QGraphicsView draws indirectly though + a QImage. This allows testing of drawing accuracy and performance for both the + native, raster, and OpenGL paint engines. + + See the QtSvg module documentation for more information about SVG and Qt's SVG classes. +*/ diff --git a/doc/src/examples/systray.qdoc b/doc/src/examples/systray.qdoc new file mode 100644 index 0000000..28ac46e --- /dev/null +++ b/doc/src/examples/systray.qdoc @@ -0,0 +1,183 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example desktop/systray + \title System Tray Icon Example + + + The System Tray Icon example shows how to add an icon with a menu + and popup messages to a desktop environment's system tray. + + \image systemtray-example.png Screenshot of the System Tray Icon. + + Modern operating systems usually provide a special area on the + desktop, called the system tray or notification area, where + long-running applications can display icons and short messages. + + This example consists of one single class, \c Window, providing + the main application window (i.e., an editor for the system tray + icon) and the associated icon. + + \image systemtray-editor.png + + The editor allows the user to choose the preferred icon as well as + set the balloon message's type and duration. The user can also + edit the message's title and body. Finally, the editor provide a + checkbox controlling whether the icon is actually shown in the + system tray, or not. + + \section1 Window Class Definition + + The \c Window class inherits QWidget: + + \snippet examples/desktop/systray/window.h 0 + + We implement several private slots to respond to user + interaction. The other private functions are only convenience + functions provided to simplify the constructor. + + The tray icon is an instance of the QSystemTrayIcon class. To + check whether a system tray is present on the user's desktop, call + the static QSystemTrayIcon::isSystemTrayAvailable() + function. Associated with the icon, we provide a menu containing + the typical \gui minimize, \gui maximize, \gui restore and \gui + quit actions. We reimplement the QWidget::setVisible() function to + update the tray icon's menu whenever the editor's appearance + changes, e.g., when maximizing or minimizing the main application + window. + + Finally, we reimplement QWidget's \l {QWidget::}{closeEvent()} + function to be able to inform the user (when closing the editor + window) that the program will keep running in the system tray + until the user chooses the \gui Quit entry in the icon's context + menu. + + \section1 Window Class Implementation + + When constructing the editor widget, we first create the various + editor elements before we create the actual system tray icon: + + \snippet examples/desktop/systray/window.cpp 0 + + We ensure that the application responds to user input by + connecting most of the editor's input widgets (including the + system tray icon) to the application's private slots. But note the + visibility checkbox; its \l {QCheckBox::}{toggled()} signal is + connected to the \e {icon}'s \l {QSystemTrayIcon::}{setVisible()} + function instead. + + \snippet examples/desktop/systray/window.cpp 3 + + The \c setIcon() slot is triggered whenever the current index in + the icon combobox changes, i.e., whenever the user chooses another + icon in the editor. Note that it is also called when the user + activates the tray icon with the left mouse button, triggering the + icon's \l {QSystemTrayIcon::}{activated()} signal. We will come + back to this signal shortly. + + The QSystemTrayIcon::setIcon() function sets the \l + {QSystemTrayIcon::}{icon} property that holds the actual system + tray icon. On Windows, the system tray icon size is 16x16; on X11, + the preferred size is 22x22. The icon will be scaled to the + appropriate size as necessary. + + Note that on X11, due to a limitation in the system tray + specification, mouse clicks on transparent areas in the icon are + propagated to the system tray. If this behavior is unacceptable, + we suggest using an icon with no transparency. + + \snippet examples/desktop/systray/window.cpp 4 + + Whenever the user activates the system tray icon, it emits its \l + {QSystemTrayIcon::}{activated()} signal passing the triggering + reason as parameter. QSystemTrayIcon provides the \l + {QSystemTrayIcon::}{ActivationReason} enum to describe how the + icon was activated. + + In the constructor, we connected our icon's \l + {QSystemTrayIcon::}{activated()} signal to our custom \c + iconActivated() slot: If the user has clicked the icon using the + left mouse button, this function changes the icon image by + incrementing the icon combobox's current index, triggering the \c + setIcon() slot as mentioned above. If the user activates the icon + using the middle mouse button, it calls the custom \c + showMessage() slot: + + \snippet examples/desktop/systray/window.cpp 5 + + When the \e showMessage() slot is triggered, we first retrieve the + message icon depending on the currently chosen message type. The + QSystemTrayIcon::MessageIcon enum describes the icon that is shown + when a balloon message is displayed. Then we call + QSystemTrayIcon's \l {QSystemTrayIcon::}{showMessage()} function + to show the message with the title, body, and icon for the time + specified in milliseconds. + + Mac OS X users note: The Growl notification system must be + installed for QSystemTrayIcon::showMessage() to display messages. + + QSystemTrayIcon also has the corresponding, \l {QSystemTrayIcon::} + {messageClicked()} signal, which is emitted when the user clicks a + message displayed by \l {QSystemTrayIcon::}{showMessage()}. + + \snippet examples/desktop/systray/window.cpp 6 + + In the constructor, we connected the \l + {QSystemTrayIcon::}{messageClicked()} signal to our custom \c + messageClicked() slot that simply displays a message using the + QMessageBox class. + + QMessageBox provides a modal dialog with a short message, an icon, + and buttons laid out depending on the current style. It supports + four severity levels: "Question", "Information", "Warning" and + "Critical". The easiest way to pop up a message box in Qt is to + call one of the associated static functions, e.g., + QMessageBox::information(). + + As we mentioned earlier, we reimplement a couple of QWidget's + virtual functions: + + \snippet examples/desktop/systray/window.cpp 1 + + Our reimplementation of the QWidget::setVisible() function updates + the tray icon's menu whenever the editor's appearance changes, + e.g., when maximizing or minimizing the main application window, + before calling the base class implementation. + + \snippet examples/desktop/systray/window.cpp 2 + + We have reimplemented the QWidget::closeEvent() event handler to + receive widget close events, showing the above message to the + users when they are closing the editor window. + + In addition to the functions and slots discussed above, we have + also implemented several convenience functions to simplify the + constructor: \c createIconGroupBox(), \c createMessageGroupBox(), + \c createActions() and \c createTrayIcon(). See the \l + {desktop/systray/window.cpp}{window.cpp} file for details. +*/ diff --git a/doc/src/examples/textobject.qdoc b/doc/src/examples/textobject.qdoc new file mode 100644 index 0000000..a2e3de0 --- /dev/null +++ b/doc/src/examples/textobject.qdoc @@ -0,0 +1,156 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \example richtext/textobject + \title Text Object Example + + The Text Object example shows how to insert an SVG file into a + QTextDocument. + + \image textobject-example.png + + A QTextDocument consists of a hierarchy of elements, such as text blocks and + frames. A text object describes the structure or format of one or more of these + elements. For instance, images imported from HTML are implemented using text + objects. Text objects are used by the document's + \l{QAbstractTextDocumentLayout}{layout} to lay out and render (paint) the + document. Each object knows how to paint the elements they govern, and + calculates their size. + + To be able to insert an SVG image into a text document, we create + a text object, and implement painting for that object. This object + can then be \l{QTextCharFormat::setObjectType()}{set} on a + QTextCharFormat. We also register the text object with the layout + of the document, enabling it to draw \l{QTextCharFormat}s governed + by our text object. We can summarize the procedure with the + following steps: + + \list + \o Implement the text object. + \o Register the text object with the layout of the text + document. + \o Set the text object on a QTextCharFormat. + \o Insert a QChar::ObjectReplacementCharacter with that + text char format into the document. + \endlist + + The example consists of the following classes: + + \list + \o \c{SvgTextObject} implements the text object. + \o \c{Window} shows a QTextEdit into which SVG images can be + inserted. + \endlist + + \section1 SvgTextObject Class Definition + + Let's take a look at the header file of \c {SvgTextObject}: + + \snippet examples/richtext/textobject/svgtextobject.h 0 + + A text object is a QObject that implements QTextObjectInterface. + Note that the first class inherited must be QObject, and that + you must use Q_INTERFACES to let Qt know that your class + implements QTextObjectInterface. + + The document layout keeps a collection of text objects stored as + \l{QObject}s, each of which has an associated object type. The + layout casts the QObject for the associated object type into the + QTextObjectInterface. + + The \l{QTextObjectInterface::}{intrinsicSize()} and + \l{QTextObjectInterface::}{drawObject()} functions are then used + to calculate the size of the text object and draw it. + + \section1 SvgTextObject Class Implementation + + We start of by taking a look at the + \l{QTextObjectInterface::}{intrinsicSize()} function: + + \snippet examples/richtext/textobject/svgtextobject.cpp 0 + + \c intrinsicSize() is called by the layout to calculate the size + of the text object. Notice that we have drawn the SVG image on a + QImage. This is because SVG rendering is quite expensive. The + example would lag seriously for large images if we drew them + with a QSvgRenderer each time. + + \snippet examples/richtext/textobject/svgtextobject.cpp 1 + + In \c drawObject(), we paint the SVG image using the QPainter + provided by the layout. + + \section1 Window Class Definition + + The \c Window class is a self-contained window that has a + QTextEdit in which SVG images can be inserted. + + \snippet examples/richtext/textobject/window.h 0 + + The \c insertTextObject() slot inserts an SVG image at the current + cursor position, while \c setupTextObject() creates and registers + the SvgTextObject with the layout of the text edit's document. + + The constructor simply calls \c setupTextObject() and \c + setupGui(), which creates and lays out the widgets of the \c + Window. + + \section1 Window Class Implementation + + We will now take a closer look at the functions that are relevant + to our text object, starting with the \c setupTextObject() + function. + + \snippet examples/richtext/textobject/window.cpp 3 + + \c {SvgTextFormat}'s value is the number of our object type. It is + used to identify object types by the document layout. + + Note that we only create one SvgTextObject instance; it will be + used for all QTextCharFormat's with the \c SvgTextFormat object + type. + + Let's move on to the \c insertTextObject() function: + + \snippet examples/richtext/textobject/window.cpp 1 + + First, the \c .svg file is opened and its contents are read + into the \c svgData array. + + \snippet examples/richtext/textobject/window.cpp 2 + + To speed things up, we buffer the SVG image in a QImage. We use + \l{QTextFormat::}{setProperty()} to store the QImage in the in the + QTextCharFormat. We can retrieve it later with + \l{QTextCharFormat::}{property()}. + + We insert the char format in the standard way - using a + QTextCursor. Notice that we use the special QChar + \l{QChar::}{ObjectReplacementCharacter}. +*/ + diff --git a/doc/src/images/bearercloud-example.png b/doc/src/images/bearercloud-example.png Binary files differnew file mode 100644 index 0000000..aaf69df --- /dev/null +++ b/doc/src/images/bearercloud-example.png diff --git a/doc/src/images/delayedecoding-example.png b/doc/src/images/delayedecoding-example.png Binary files differnew file mode 100644 index 0000000..1cafba6 --- /dev/null +++ b/doc/src/images/delayedecoding-example.png diff --git a/doc/src/images/embeddeddesktopservices-demo.png b/doc/src/images/embeddeddesktopservices-demo.png Binary files differnew file mode 100644 index 0000000..c1408c1 --- /dev/null +++ b/doc/src/images/embeddeddesktopservices-demo.png diff --git a/doc/src/images/embeddedsvgviewer-demo.png b/doc/src/images/embeddedsvgviewer-demo.png Binary files differnew file mode 100644 index 0000000..0b806d6 --- /dev/null +++ b/doc/src/images/embeddedsvgviewer-demo.png diff --git a/doc/src/images/fluidlauncher-demo.png b/doc/src/images/fluidlauncher-demo.png Binary files differnew file mode 100644 index 0000000..1720890 --- /dev/null +++ b/doc/src/images/fluidlauncher-demo.png diff --git a/doc/src/images/framebufferobject-example.png b/doc/src/images/framebufferobject-example.png Binary files differnew file mode 100644 index 0000000..df9b6db --- /dev/null +++ b/doc/src/images/framebufferobject-example.png diff --git a/doc/src/images/svggenerator-example.png b/doc/src/images/svggenerator-example.png Binary files differnew file mode 100644 index 0000000..e7a8e53 --- /dev/null +++ b/doc/src/images/svggenerator-example.png diff --git a/doc/src/images/svgviewer-example.png b/doc/src/images/svgviewer-example.png Binary files differnew file mode 100644 index 0000000..14f1377 --- /dev/null +++ b/doc/src/images/svgviewer-example.png diff --git a/doc/src/images/systemtray-editor.png b/doc/src/images/systemtray-editor.png Binary files differnew file mode 100644 index 0000000..fb15dea --- /dev/null +++ b/doc/src/images/systemtray-editor.png diff --git a/doc/src/images/systemtray-example.png b/doc/src/images/systemtray-example.png Binary files differnew file mode 100644 index 0000000..98b5c81 --- /dev/null +++ b/doc/src/images/systemtray-example.png diff --git a/doc/src/images/textobject-example.png b/doc/src/images/textobject-example.png Binary files differnew file mode 100644 index 0000000..626c102 --- /dev/null +++ b/doc/src/images/textobject-example.png diff --git a/doc/src/images/weatherinfo-demo.png b/doc/src/images/weatherinfo-demo.png Binary files differnew file mode 100644 index 0000000..3183aa4 --- /dev/null +++ b/doc/src/images/weatherinfo-demo.png diff --git a/doc/src/snippets/code/src_svg_qgraphicssvgitem.cpp b/doc/src/snippets/code/src_svg_qgraphicssvgitem.cpp new file mode 100644 index 0000000..ac775fd --- /dev/null +++ b/doc/src/snippets/code/src_svg_qgraphicssvgitem.cpp @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSvgRenderer *renderer = new QSvgRenderer(QLatin1String("SvgCardDeck.svg")); +QGraphicsSvgItem *black = new QGraphicsSvgItem(); +QGraphicsSvgItem *red = new QGraphicsSvgItem(); + +black->setSharedRenderer(renderer); +black->setElementId(QLatin1String("black_joker")); + +red->setSharedRenderer(renderer); +red->setElementId(QLatin1String("red_joker")); +//! [0] |
