summaryrefslogtreecommitdiffstats
path: root/doc/src/examples/elidedlabel.qdoc
blob: 9a5b47668ed41222ef4ea18f97aca226951521c9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
/****************************************************************************
**
** 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$
** 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

    \brief The Elided Label 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 examples/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 examples/widgets/elidedlabel/elidedlabel.cpp 0

    Changing the \c content require a repaint of the widget.

    \snippet examples/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 examples/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 examples/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 examples/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 examples/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 examples/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 examples/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 examples/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 examples/widgets/elidedlabel/testwidget.cpp 3

    The components are all stored in a QGridLayout, which is made the layout of
    the \c TestWidget.

    \snippet examples/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 examples/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 examples/widgets/elidedlabel/testwidget.cpp 6

    The \c switchText() slot simply cycles through all the available sample
    texts.

    \snippet examples/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 examples/widgets/elidedlabel/main.cpp 0
*/