diff options
Diffstat (limited to 'examples/widgets/doc/elidedlabel.qdoc')
| -rw-r--r-- | examples/widgets/doc/elidedlabel.qdoc | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/examples/widgets/doc/elidedlabel.qdoc b/examples/widgets/doc/elidedlabel.qdoc new file mode 100644 index 0000000000..2ce469d85f --- /dev/null +++ b/examples/widgets/doc/elidedlabel.qdoc @@ -0,0 +1,162 @@ +/**************************************************************************** +** +** 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/elidedlabel + \group all-examples + \title Elided Label Example + + This example creates a widget similar to QLabel, that elides the last + visible line, if the text is too long to fit the widget's geometry. + + \image elidedlabel-example.png Elided Label example on XPressMusic 5800 + + When text of varying length has to be displayed in a uniformly sized + area, for instance within a list or grid view where all list items have the + same size, it can be useful to give the user a visual clue when not all + text is visible. QLabel can elide text that doesn't fit within it, but only + in one line. The \c ElidedLabel widget shown in this example word wraps its + text by its width, and elides the last visible line if some text is left + out. \c TestWidget gives control to the features of \c ElidedWidget and + forms the example application. + + + \section1 ElidedLabel Class Definition + + Like QLabel, \c ElidedLabel inherits from QFrame. Here's the definition of + the \c ElidedLabel class: + + + \snippet widgets/elidedlabel/elidedlabel.h 0 + + The \c isElided property depends the font, text content and geometry of the + widget. Whenever any of these change, the \c elisionChanged() signal might + trigger. We cache the current elision value in \c elided, so that it + doesn't have to be recomputed every time it's asked for. + + + \section1 ElidedLabel Class Implementation + + Except for initializing the member variables, the constructor sets the size + policy to be horizontally expanding, since it's meant to fill the width of + its container and grow vertically. + + \snippet widgets/elidedlabel/elidedlabel.cpp 0 + + Changing the \c content require a repaint of the widget. + + \snippet widgets/elidedlabel/elidedlabel.cpp 1 + + QTextLayout is used in the \c paintEvent() to divide the \c content into + lines, that wrap on word boundaries. Each line, except the last visible + one, is drawn \c lineSpacing pixels below the previous one. The \c draw() + method of QTextLine will draw the line using the coordinate point as the + top left corner. + + \snippet widgets/elidedlabel/elidedlabel.cpp 2 + + Unfortunately, QTextLayout does not elide text, so the last visible line + has to be treated differently. This last line is elided if it is too wide. + The \c drawText() method of QPainter draws the text starting from the base + line, which is \c ascecnt() pixels below the last drawn line. + + Finally, one more line is created to see if everything fit on this line. + + \snippet widgets/elidedlabel/elidedlabel.cpp 3 + + If the text was elided and wasn't before or vice versa, cache it in + \c elided and emit the change. + + \snippet widgets/elidedlabel/elidedlabel.cpp 4 + + + \section1 TestWidget Class Definition + + \c TestWidget is a QWidget and is the main window of the example. It + contains an \c ElidedLabel which can be resized with two QSlider widgets. + + \snippet widgets/elidedlabel/testwidget.h 0 + + \section1 TestWidget Class Implementation + + The constructor initializes the whole widget. Strings of different length + are stored in \c textSamples. The user is able to switch between these. + + \snippet widgets/elidedlabel/testwidget.cpp 0 + + An \c ElidedLabel is created to contain the first of the sample strings. + The frame is made visible to make it easier to see the actual size of the + widget. + + \snippet widgets/elidedlabel/testwidget.cpp 1 + + The buttons and the elision label are created. By connecting the + \c elisionChanged() signal to the \c setVisible() slot of the \c label, + it will act as an indicator to when the text is elided or not. This signal + could, for instance, be used to make a "More" button visible, or similar. + + \snippet widgets/elidedlabel/testwidget.cpp 2 + + The \c widthSlider and \c heightSlider specify the size of the + \c elidedText. Since the y-axis is inverted, the \c heightSlider has to be + inverted to act appropriately. + + \snippet widgets/elidedlabel/testwidget.cpp 3 + + The components are all stored in a QGridLayout, which is made the layout of + the \c TestWidget. + + \snippet widgets/elidedlabel/testwidget.cpp 4 + + On the Maemo platform, windows are stuck in landscape mode by default. With + this attribute set, the window manager is aware that this window can be + rotated. + + \snippet widgets/elidedlabel/testwidget.cpp 5 + + The \c widthSlider and \c heightSlider have the exact same length as the + dimensions of the \c elidedText. The maximum value for both of them is + thus their lengths, and each tick indicates one pixel. + + \snippet widgets/elidedlabel/testwidget.cpp 6 + + The \c switchText() slot simply cycles through all the available sample + texts. + + \snippet widgets/elidedlabel/testwidget.cpp 7 + + These slots set the width and height of the \c elided text, in response to + changes in the sliders. + + \section1 The \c main() Function + + The \c main() function creates an instance of \c TestWidget fullscreen and + enters the message loop. + + \snippet widgets/elidedlabel/main.cpp 0 +*/ + |