doc/src/examples/elidedlabel.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example widgets/elidedlabel
  30     \group all-examples
  31     \title Elided Label Example
  32
  33     \brief The Elided Label example creates a widget similar to QLabel, that elides the last
  34     visible line, if the text is too long to fit the widget's geometry.
  35
  36     \image elidedlabel-example.png Elided Label example on XPressMusic 5800
  37
  38     When text of varying length has to be displayed in a uniformly sized
  39     area, for instance within a list or grid view where all list items have the
  40     same size, it can be useful to give the user a visual clue when not all
  41     text is visible. QLabel can elide text that doesn't fit within it, but only
  42     in one line. The \c ElidedLabel widget shown in this example word wraps its
  43     text by its width, and elides the last visible line if some text is left
  44     out. \c TestWidget gives control to the features of \c ElidedWidget and
  45     forms the example application.
  46
  47
  48     \section1 ElidedLabel Class Definition
  49
  50     Like QLabel, \c ElidedLabel inherits from QFrame. Here's the definition of
  51     the \c ElidedLabel class:
  52
  53
  54     \snippet examples/widgets/elidedlabel/elidedlabel.h 0
  55
  56     The \c isElided property depends the font, text content and geometry of the
  57     widget. Whenever any of these change, the \c elisionChanged() signal might
  58     trigger. We cache the current elision value in \c elided, so that it
  59     doesn't have to be recomputed every time it's asked for.
  60
  61
  62     \section1 ElidedLabel Class Implementation
  63
  64     Except for initializing the member variables, the constructor sets the size
  65     policy to be horizontally expanding, since it's meant to fill the width of
  66     its container and grow vertically.
  67
  68     \snippet examples/widgets/elidedlabel/elidedlabel.cpp 0
  69
  70     Changing the \c content require a repaint of the widget.
  71
  72     \snippet examples/widgets/elidedlabel/elidedlabel.cpp 1
  73
  74     QTextLayout is used in the \c paintEvent() to divide the \c content into
  75     lines, that wrap on word boundaries. Each line, except the last visible
  76     one, is drawn \c lineSpacing pixels below the previous one. The \c draw()
  77     method of QTextLine will draw the line using the coordinate point as the
  78     top left corner.
  79
  80     \snippet examples/widgets/elidedlabel/elidedlabel.cpp 2
  81
  82     Unfortunately, QTextLayout does not elide text, so the last visible line
  83     has to be treated differently. This last line is elided if it is too wide.
  84     The \c drawText() method of QPainter draws the text starting from the base
  85     line, which is \c ascecnt() pixels below the last drawn line.
  86
  87     Finally, one more line is created to see if everything fit on this line.
  88
  89     \snippet examples/widgets/elidedlabel/elidedlabel.cpp 3
  90
  91     If the text was elided and wasn't before or vice versa, cache it in
  92     \c elided and emit the change.
  93
  94     \snippet examples/widgets/elidedlabel/elidedlabel.cpp 4
  95
  96
  97     \section1 TestWidget Class Definition
  98
  99     \c TestWidget is a QWidget and is the main window of the example. It
 100     contains an \c ElidedLabel which can be resized with two QSlider widgets.
 101
 102     \snippet examples/widgets/elidedlabel/testwidget.h 0
 103
 104     \section1 TestWidget Class Implementation
 105
 106     The constructor initializes the whole widget. Strings of different length
 107     are stored in \c textSamples. The user is able to switch between these.
 108
 109     \snippet examples/widgets/elidedlabel/testwidget.cpp 0
 110
 111     An \c ElidedLabel is created to contain the first of the sample strings.
 112     The frame is made visible to make it easier to see the actual size of the
 113     widget.
 114
 115     \snippet examples/widgets/elidedlabel/testwidget.cpp 1
 116
 117     The buttons and the elision label are created. By connecting the
 118     \c elisionChanged() signal to the \c setVisible() slot of the \c label,
 119     it will act as an indicator to when the text is elided or not. This signal
 120     could, for instance, be used to make a "More" button visible, or similar.
 121
 122     \snippet examples/widgets/elidedlabel/testwidget.cpp 2
 123
 124     The \c widthSlider and \c heightSlider specify the size of the
 125     \c elidedText. Since the y-axis is inverted, the \c heightSlider has to be
 126     inverted to act appropriately.
 127
 128     \snippet examples/widgets/elidedlabel/testwidget.cpp 3
 129
 130     The components are all stored in a QGridLayout, which is made the layout of
 131     the \c TestWidget.
 132
 133     \snippet examples/widgets/elidedlabel/testwidget.cpp 4
 134
 135     On the Maemo platform, windows are stuck in landscape mode by default. With
 136     this attribute set, the window manager is aware that this window can be
 137     rotated.
 138
 139     \snippet examples/widgets/elidedlabel/testwidget.cpp 5
 140
 141     The \c widthSlider and \c heightSlider have the exact same length as the
 142     dimensions of the \c elidedText. The maximum value for both of them is
 143     thus their lengths, and each tick indicates one pixel.
 144
 145     \snippet examples/widgets/elidedlabel/testwidget.cpp 6
 146
 147     The \c switchText() slot simply cycles through all the available sample
 148     texts.
 149
 150     \snippet examples/widgets/elidedlabel/testwidget.cpp 7
 151
 152     These slots set the width and height of the \c elided text, in response to
 153     changes in the sliders.
 154
 155     \section1 The \c main() Function
 156
 157     The \c main() function creates an instance of \c TestWidget fullscreen and
 158     enters the message loop.
 159
 160     \snippet examples/widgets/elidedlabel/main.cpp 0
 161 */
 162