diff options
author | Frederik Gladhorn <frederik.gladhorn@digia.com> | 2012-09-19 09:15:38 +0200 |
---|---|---|
committer | The Qt Project <gerrit-noreply@qt-project.org> | 2012-09-21 19:59:16 +0200 |
commit | d1f74b8ddf7a6f26f8b2a689cc728282bc68125c (patch) | |
tree | d3e369cdf317aedde6018ebf8adfb4ba17129e00 /examples/widgets/doc | |
parent | d16c565ca6a55788435c52ad45647eda67854d80 (diff) |
Move examples to proper location.
Change-Id: Ib808f5d99cb8217f8786411b531fa5bc7fa5250a
Reviewed-by: Martin Smith <martin.smith@digia.com>
Diffstat (limited to 'examples/widgets/doc')
-rw-r--r-- | examples/widgets/doc/dropsite.qdoc | 249 | ||||
-rw-r--r-- | examples/widgets/doc/images/dropsite-example.png | bin | 0 -> 118905 bytes | |||
-rw-r--r-- | examples/widgets/doc/images/mousebutton-buttontester.png | bin | 0 -> 14492 bytes | |||
-rw-r--r-- | examples/widgets/doc/images/orientation-landscape-ui.png | bin | 0 -> 18077 bytes | |||
-rw-r--r-- | examples/widgets/doc/images/orientation-landscape.png | bin | 0 -> 46496 bytes | |||
-rw-r--r-- | examples/widgets/doc/images/orientation-portrait-ui.png | bin | 0 -> 9785 bytes | |||
-rw-r--r-- | examples/widgets/doc/images/orientation-portrait.png | bin | 0 -> 17377 bytes | |||
-rw-r--r-- | examples/widgets/doc/mousebuttons.qdoc | 94 | ||||
-rw-r--r-- | examples/widgets/doc/orientation.qdoc | 143 |
9 files changed, 486 insertions, 0 deletions
diff --git a/examples/widgets/doc/dropsite.qdoc b/examples/widgets/doc/dropsite.qdoc new file mode 100644 index 0000000000..6e4b21a9be --- /dev/null +++ b/examples/widgets/doc/dropsite.qdoc @@ -0,0 +1,249 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example draganddrop/dropsite + \title Drop Site Example + + The example shows how to distinguish the various MIME formats available + in a drag and drop operation. + + \image dropsite-example.png Screenshot of the Drop Site example + + The Drop Site example accepts drops from other applications, and displays + the MIME formats provided by the drag object. + + There are two classes, \c DropArea and \c DropSiteWindow, and a \c main() + function in this example. A \c DropArea object is instantiated in + \c DropSiteWindow; a \c DropSiteWindow object is then invoked in the + \c main() function. + + \section1 DropArea Class Definition + + The \c DropArea class is a subclass of QLabel with a public slot, + \c clear(), and a \c changed() signal. + + \snippet draganddrop/dropsite/droparea.h DropArea header part1 + + In addition, \c DropArea also contains a private instance of QLabel and + reimplementations of four \l{QWidget} event handlers: + + \list 1 + \li \l{QWidget::dragEnterEvent()}{dragEnterEvent()} + \li \l{QWidget::dragMoveEvent()}{dragMoveEvent()} + \li \l{QWidget::dragLeaveEvent()}{dragLeaveEvent()} + \li \l{QWidget::dropEvent()}{dropEvent()} + \endlist + + These event handlers are further explained in the implementation of the + \c DropArea class. + + \snippet draganddrop/dropsite/droparea.h DropArea header part2 + + \section1 DropArea Class Implementation + + In the \c DropArea constructor, we set the \l{QWidget::setMinimumSize()} + {minimum size} to 200x200 pixels, the \l{QFrame::setFrameStyle()} + {frame style} to both QFrame::Sunken and QFrame::StyledPanel, and we align + its contents to the center. + + \snippet draganddrop/dropsite/droparea.cpp DropArea constructor + + Also, we enable drop events in \c DropArea by setting the + \l{QWidget::acceptDrops()}{acceptDrops} property to \c true. Then, + we enable the \l{QWidget::autoFillBackground()}{autoFillBackground} + property and invoke the \c clear() function. + + The \l{QWidget::dragEnterEvent()}{dragEnterEvent()} event handler is + called when a drag is in progress and the mouse enters the \c DropArea + object. For the \c DropSite example, when the mouse enters \c DropArea, + we set its text to "<drop content>" and highlight its background. + + \snippet draganddrop/dropsite/droparea.cpp dragEnterEvent() function + + Then, we invoke \l{QDropEvent::acceptProposedAction()} + {acceptProposedAction()} on \a event, setting the drop action to the one + proposed. Lastly, we emit the \c changed() signal, with the data that was + dropped and its MIME type information as a parameter. + + For \l{QWidget::dragMoveEvent()}{dragMoveEvent()}, we just accept the + proposed QDragMoveEvent object, \a event, with + \l{QDropEvent::acceptProposedAction()}{acceptProposedAction()}. + + \snippet draganddrop/dropsite/droparea.cpp dragMoveEvent() function + + The \c DropArea class's implementation of \l{QWidget::dropEvent()} + {dropEvent()} extracts the \a{event}'s mime data and displays it + accordingly. + + \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part1 + + The \c mimeData object can contain one of the following objects: an image, + HTML text, plain text, or a list of URLs. + + \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part2 + + \list + \li If \c mimeData contains an image, we display it in \c DropArea with + \l{QLabel::setPixmap()}{setPixmap()}. + \li If \c mimeData contains HTML, we display it with + \l{QLabel::setText()}{setText()} and set \c{DropArea}'s text format + as Qt::RichText. + \li If \c mimeData contains plain text, we display it with + \l{QLabel::setText()}{setText()} and set \c{DropArea}'s text format + as Qt::PlainText. In the event that \c mimeData contains URLs, we + iterate through the list of URLs to display them on individual + lines. + \li If \c mimeData contains other types of objects, we set + \c{DropArea}'s text, with \l{QLabel::setText()}{setText()} to + "Cannot display data" to inform the user. + \endlist + + We then set \c{DropArea}'s \l{QWidget::backgroundRole()}{backgroundRole} to + QPalette::Dark and we accept \c{event}'s proposed action. + + \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part3 + + The \l{QWidget::dragLeaveEvent()}{dragLeaveEvent()} event handler is + called when a drag is in progress and the mouse leaves the widget. + + \snippet draganddrop/dropsite/droparea.cpp dragLeaveEvent() function + + For \c{DropArea}'s implementation, we clear invoke \c clear() and then + accept the proposed event. + + The \c clear() function sets the text in \c DropArea to "<drop content>" + and sets the \l{QWidget::backgroundRole()}{backgroundRole} to + QPalette::Dark. Lastly, it emits the \c changed() signal. + + \snippet draganddrop/dropsite/droparea.cpp clear() function + + \section1 DropSiteWindow Class Definition + + The \c DropSiteWindow class contains a constructor and a public slot, + \c updateFormatsTable(). + + \snippet draganddrop/dropsite/dropsitewindow.h DropSiteWindow header + + The class also contains a private instance of \c DropArea, \c dropArea, + QLabel, \c abstractLabel, QTableWidget, \c formatsTable, QDialogButtonBox, + \c buttonBox, and two QPushButton objects, \c clearButton and + \c quitButton. + + \section1 DropSiteWindow Class Implementation + + In the constructor of \c DropSiteWindow, we instantiate \c abstractLabel + and set its \l{QLabel::setWordWrap()}{wordWrap} property to \c true. We + also call the \l{QLabel::adjustSize()}{adjustSize()} function to adjust + \c{abstractLabel}'s size according to its contents. + + \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part1 + + Then we instantiate \c dropArea and connect its \c changed() signal to + \c{DropSiteWindow}'s \c updateFormatsTable() slot. + + \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part2 + + We now set up the QTableWidget object, \c formatsTable. Its + horizontal header is set using a QStringList object, \c labels. The number + of columms are set to two and the table is not editable. Also, the + \c{formatTable}'s horizontal header is formatted to ensure that its second + column stretches to occupy additional space available. + + \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part3 + + Two QPushButton objects, \c clearButton and \c quitButton, are instantiated + and added to \c buttonBox - a QDialogButtonBox object. We use + QDialogButtonBox here to ensure that the push buttons are presented in a + layout that conforms to the platform's style. + + \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part4 + + The \l{QPushButton::clicked()}{clicked()} signals for \c quitButton and + \c clearButton are connected to \l{QWidget::close()}{close()} and + \c clear(), respectively. + + For the layout, we use a QVBoxLayout, \c mainLayout, to arrange our widgets + vertically. We also set the window title to "Drop Site" and the minimum + size to 350x500 pixels. + + \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part5 + + We move on to the \c updateFormatsTable() function. This function updates + the \c formatsTable, displaying the MIME formats of the object dropped onto + the \c DropArea object. First, we set \l{QTableWidget}'s + \l{QTableWidget::setRowCount()}{rowCount} property to 0. Then, we validate + to ensure that the QMimeData object passed in is a valid object. + + \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part1 + + Once we are sure that \c mimeData is valid, we iterate through its + supported formats using the \l{The foreach Keyword}{foreach keyword}. + This keyword has the following format: + + \snippet code/doc_src_examples_dropsite.qdoc 0 + + In our example, \c format is the \a variable and the \a container is a + QStringList, obtained from \c mimeData->formats(). + + \note The \l{QMimeData::formats()}{formats()} function returns a + QStringList object, containing all the formats supported by the + \c mimeData. + + \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part2 + + Within each iteration, we create a QTableWidgetItem, \c formatItem and we + set its \l{QTableWidgetItem::setFlags()}{flags} to Qt::ItemIsEnabled, and + its \l{QTableWidgetItem::setTextAlignment()}{text alignment} to Qt::AlignTop + and Qt::AlignLeft. + + A QString object, \c text, is customized to display data according to the + contents of \c format. We invoke {QString}'s \l{QString::simplified()} + {simplified()} function on \c text, to obtain a string that has no + additional space before, after or in between words. + + \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part3 + + If \c format contains a list of URLs, we iterate through them, using spaces + to separate them. On the other hand, if \c format contains an image, we + display the data by converting the text to hexadecimal. + + \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part4 + + Once \c text has been customized to contain the appropriate data, we insert + both \c format and \c text into \c formatsTable with + \l{QTableWidget::setItem()}{setItem()}. Lastly, we invoke + \l{QTableView::resizeColumnToContents()}{resizeColumnToContents()} on + \c{formatsTable}'s first column. + + \section1 The main() Function + + Within the \c main() function, we instantiate \c DropSiteWindow and invoke + its \l{QWidget::show()}{show()} function. + + \snippet draganddrop/dropsite/main.cpp main() function +*/ diff --git a/examples/widgets/doc/images/dropsite-example.png b/examples/widgets/doc/images/dropsite-example.png Binary files differnew file mode 100644 index 0000000000..42b988d733 --- /dev/null +++ b/examples/widgets/doc/images/dropsite-example.png diff --git a/examples/widgets/doc/images/mousebutton-buttontester.png b/examples/widgets/doc/images/mousebutton-buttontester.png Binary files differnew file mode 100644 index 0000000000..82fcb7617f --- /dev/null +++ b/examples/widgets/doc/images/mousebutton-buttontester.png diff --git a/examples/widgets/doc/images/orientation-landscape-ui.png b/examples/widgets/doc/images/orientation-landscape-ui.png Binary files differnew file mode 100644 index 0000000000..c591ff14d2 --- /dev/null +++ b/examples/widgets/doc/images/orientation-landscape-ui.png diff --git a/examples/widgets/doc/images/orientation-landscape.png b/examples/widgets/doc/images/orientation-landscape.png Binary files differnew file mode 100644 index 0000000000..e606804d21 --- /dev/null +++ b/examples/widgets/doc/images/orientation-landscape.png diff --git a/examples/widgets/doc/images/orientation-portrait-ui.png b/examples/widgets/doc/images/orientation-portrait-ui.png Binary files differnew file mode 100644 index 0000000000..304835b93e --- /dev/null +++ b/examples/widgets/doc/images/orientation-portrait-ui.png diff --git a/examples/widgets/doc/images/orientation-portrait.png b/examples/widgets/doc/images/orientation-portrait.png Binary files differnew file mode 100644 index 0000000000..3d778e8d90 --- /dev/null +++ b/examples/widgets/doc/images/orientation-portrait.png diff --git a/examples/widgets/doc/mousebuttons.qdoc b/examples/widgets/doc/mousebuttons.qdoc new file mode 100644 index 0000000000..10d1f9a116 --- /dev/null +++ b/examples/widgets/doc/mousebuttons.qdoc @@ -0,0 +1,94 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2012 Rick Stockton <rickstockton@reno-computerhelp.com> +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/mousebuttons + \title Mouse Button Tester + + \brief The 'Mouse Button Tester' example demonstrates how to reimplement + mouse events within a custom class. You can also use this program to + verify that Qt is actually receiving mouse events from your mouse. + + Many 'gamer' mouse devices are configured with high-numbered "buttons" + sending text shortcuts for certain games. With such a mouse, no mouse + button events occur: The "mouse" sends keystrokes, and the + 'Mouse Button Tester' Window will not see the event. Receiving no event, + it will not repaint the Window with new text describing a button event. + + And so, in addition to it's use as Qt example code, the program may be + useful s a mouse device tester. Note that there is another example + mouse buttons example which provides the same function, written in QML. + + This program (the Widget-based example) consists of three classes, + in addition to the main() parent program: + + \list + \li \c A QPushButton, "Quit". + \li \c ButtonTester. This is derived from Qt's TextArea class, for + purpose of customizing/re-implementing the mouse and wheel event + member functions. + \li \c A simple QVBoxLayout layout. + \endlist + + First we will review the main program, with it's layout and "Quit" + QPushButton. Then we will take a look at the \c ButtonTester class. + + \section1 The Main Program + + Note that the QPushButton, "Quit", is defined directly within the main() + program, rather than another class. This is a correct way of defining a + "Quit" QPushButton: A "Quit" Button defined inside another + class would result in the destructor of that second class being + called twice. This "Quit" Button uses the traditional Signal/Slot + connection to invoke termination of the QApp, which will properly destroy + its child classes before terminating itself. + + The remainder of the main() program is concerned with defining the layout, + and applying a minimum size to the customized ButtonTester. + + \section1 ButtonTester Class Definition + + The \c ButtonTester class inherits from QTextEdit, and listens for + mouse events on all possible Qt::MouseButton values. It also listens for + wheel events from the mouse, and indicates the direction of wheel motion + ("up", down", "left", or "right"). It prints short debug messages into + the Window, and also on the console QDebug() stream, when mouse button + and wheel events occur. Our reimplementation of mousePressEvent(), + mouseReleaseEvent(), mouseDoubleClickEvent(), and wheelEvent() "drive" + the program; the other functions simply convert the Qt::MouseButton + values into text strings. + + You should call the ignore() function on any mouse event (or other event) + which your widget-based classes do not use and consume. This function + assures that Qt will propagate the event through each parent widget, + until it is used or propagated to the Window Manager. (Qt attempts to do + this automatically, but it is better programming practice to explicitly + invoke the function.) + + \image mousebutton-buttontester.png +*/ diff --git a/examples/widgets/doc/orientation.qdoc b/examples/widgets/doc/orientation.qdoc new file mode 100644 index 0000000000..b39bbf981a --- /dev/null +++ b/examples/widgets/doc/orientation.qdoc @@ -0,0 +1,143 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! \example widgets/orientation + \group all-examples + \title Orientation Example + + The example shows a simple way to use different UIs depending on the screen + orientation of a mobile device. + + \image orientation-landscape.png The UI in landscape mode + \image orientation-portrait.png The UI in portrait mode + + The screen on many mobile devices can be viewed in both portrait and + landscape orientation. The orientation can be swiched with the help of a + hardware or software trigger. Due to the often small physical screen size, + user interfaces has to be very simple and compact to stay usable, and + applications usually occupy the whole screen. Designing a user interface + that works equally well in both landscape and portrait mode is not always + possible, however, so making a different layout for each case usually pays + off. + + The example application makes use of two different UI widgets created with + the Qt Designer, one for portrait and one for landscape orientation. The + application has a widget that contains an image and the user is able to + select one of three images for it to show. In addition to the two UIs, the + application consists of a \c MainWindow class. + + \section1 Landscape UI + + If the screen is in landscape mode, the user probably holds the device with + both hands and is ready to give full attention to the application. The + landscape UI looks like this: + + \image orientation-landscape-ui.png The landscape UI + + To the left is a QWidget called \c choiceWidget, which will show the + current image, and to the right are three QRadioButton instances. The + active radio button specifies the image to show. + + \section1 Portrait UI + + When the device is in portrait mode, it usually means that the user holds + it with one hand, and can comfortably use the thumb for small amounts of + input. The layout is simpler, and is focused on consuming content. The + portrait UI looks like this: + + \image orientation-portrait-ui.png The portrait UI + + Similarly, it contains a QWidget, also called \c choiceWidget, that will + show the current image. In contrast to the landscape UI, this one doesn't + provide any controls to change the image. + + \section1 MainWindow Class Definition + + \c MainWindow inherits from QWidget and acts as the top level widget of the + application. + + \snippet widgets/orientation/mainwindow.h 0 + + The \c resizeEvent() method is re-implemented, and used to check which + UI to show. The \c onRadioButtonClicked() slot is connected to the + landscape UI's radio button group and selects the current image. + + \c landscapeWidget and \c portraitWidget will contain the UI layouts. Only + one of them is visible at a time. + + \section1 MainWindow Class Implementation + + In the constructor, the widgets that will hold the UIs are created and set + up. + + \snippet widgets/orientation/mainwindow.cpp 0 + + Since the exit buttons on the layouts are different from each other, both + of them have to have their \c clicked() signal connected to the \c close() + slot of the main widget. The first image is also made current with the call + to \c onRadioButtonClicked(). + + \snippet widgets/orientation/mainwindow.cpp 1 + + On the Maemo platform, windows are stuck in landscape mode by default. The + application has to explicitly say that rotation is supported. + + \snippet widgets/orientation/mainwindow.cpp 2 + + The \c resizeEvent() is called when the main window is first created, and + also whenever the window has been resized. If the window is shown in + full screen, this is an indication that the orientation of the screen has + changed. + + The dimensions of \c landscapeWidget is the transpose of the dimensions of + \c portraitWidget. When the orientation is known, both are set to the + (possibly transposed) size of the window. Depending on the orientation, one + widget is made visible and the other invisible. + + \snippet widgets/orientation/mainwindow.cpp 3 + + When the user selects one of the radio buttons in the landscape UI, the + current image is changed. The image is displayed by specifying the + background style of the choice widget. Since both \c portrait and + \c landscape have a \c choiceWidget of their own, the change has to be + reflected in both instances. + + \snippet widgets/orientation/mainwindow.cpp 4 + + Synchronizing both UIs like this might become unfeasible when there are + many things that can change. In that case it is better to make use of the + \l{Introduction to Model/View Programming}{Model-View-Controller pattern} + more extensively and share the content between both portrait and landscape + widgets. Then an interface for displaying and manipulating it can be tailor + made for both orientations. + + \section1 The \c main() Function + + The main function creates a \c MainWindow instance and shows it full + screen. + \snippet widgets/orientation/main.cpp 0 +*/ |