1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2000 Ronny Standtke <Ronny.Standtke@gmx.de>
4
5 SPDX-License-Identifier: LGPL-2.0-only
6*/
7
8#ifndef KSQUEEZEDTEXTLABEL_H
9#define KSQUEEZEDTEXTLABEL_H
10
11#include <QLabel>
12#include <kwidgetsaddons_export.h>
13#include <memory>
14
15// TODO KF6:
16// - make more functions virtual (to benefit subclasses of KSqueezedTextLabel)
17// - try to eliminate need for non-virtual-warning (to benefit use as QLabel),
18// see https://phabricator.kde.org/D7164 for some ideas/considerations
19/*!
20 * \class KSqueezedTextLabel
21 * \inmodule KWidgetsAddons
22 *
23 * \brief A replacement for QLabel that squeezes its text into the label.
24 *
25 * If the text is too long to fit into the label it is divided into
26 * remaining left and right parts which are separated by three dots.
27 * Hovering the mouse over the label shows the full text in a tooltip.
28 *
29 * Example:
30 * http://www.kde.org/documentation/index.html could be squeezed to
31 * http://www.kde...ion/index.html
32 *
33 * \image ksqueezedtextlabel.png "KSqueezedTextLabel Widget"
34 *
35 * To change the position of the elision mark to the left or right end
36 * of the text, use setTextElideMode().
37 *
38 * \note Several functions of KSqueezedTextLabel (indicated by a warning
39 * in their description) reimplement non-virtual functions of QLabel.
40 * Therefore, you may need to cast the object to KSqueezedTextLabel in
41 * some situations:
42 * \code
43 * KSqueezedTextLabel* squeezed = new KSqueezedTextLabel("text", parent);
44 * QLabel* label = squeezed;
45 * label->setText("new text"); // this will not work
46 * squeezed->setText("new text"); // works as expected
47 * static_cast<KSqueezedTextLabel*>(label)->setText("new text"); // works as expected
48 * \endcode
49 */
50class KWIDGETSADDONS_EXPORT KSqueezedTextLabel : public QLabel
51{
52 Q_OBJECT
53
54 /*!
55 * \property KSqueezedTextLabel::textElideMode
56 */
57 Q_PROPERTY(Qt::TextElideMode textElideMode READ textElideMode WRITE setTextElideMode)
58
59 /*!
60 * \property KSqueezedTextLabel::indent
61 */
62 Q_PROPERTY(int indent READ indent WRITE setIndent)
63
64 /*!
65 * \property KSqueezedTextLabel::margin
66 */
67 Q_PROPERTY(int margin READ margin WRITE setMargin)
68
69public:
70 /*!
71 * Default constructor.
72 *
73 * \a parent the label's parent object
74 */
75 explicit KSqueezedTextLabel(QWidget *parent = nullptr);
76
77 /*!
78 * \a text the text that will be displayed
79 *
80 * \a parent the label's parent object
81 */
82 explicit KSqueezedTextLabel(const QString &text, QWidget *parent = nullptr);
83
84 ~KSqueezedTextLabel() override;
85
86 /*!
87 * Returnss the label's minimum size, where the horizontal component
88 * will be -1 to indicate the label's ability to shrink its width
89 * by squeezing the text
90 */
91 QSize minimumSizeHint() const override;
92
93 /*!
94 * Returns the label's preferred size, which is wide enough
95 * to display the text without squeezing it
96 */
97 QSize sizeHint() const override;
98
99 /*!
100 * Sets the indentation of the label.
101 *
102 * \a indent the amount of indentation in pixels
103 *
104 * Reimplementation of QLabel::setIndent().
105 *
106 * \warning The corresponding function in the base class is not virtual.
107 * Therefore make sure to call this function on objects of type KSqueezedTextLabel,
108 * as shown in the example in the class description.
109 *
110 * \since 5.39
111 */
112 void setIndent(int indent);
113
114 /*!
115 * Sets the margin of the label.
116 *
117 * \a margin the margin size in pixels
118 *
119 * Reimplementation of QLabel::setMargin().
120 *
121 * \warning The corresponding function in the base class is not virtual.
122 * Therefore make sure to call this function on objects of type KSqueezedTextLabel,
123 * as shown in the example in the class description.
124 *
125 * \since 5.39
126 */
127 void setMargin(int margin);
128
129 virtual void setAlignment(Qt::Alignment);
130
131 /*!
132 * Returns the text elide mode
133 */
134 Qt::TextElideMode textElideMode() const;
135
136 /*!
137 * Sets the text elide mode.
138 *
139 * \a mode The text elide mode.
140 */
141 void setTextElideMode(Qt::TextElideMode mode);
142
143 /*!
144 * Returns the full text set via setText()
145 *
146 * \since 4.4
147 */
148 QString fullText() const;
149
150 /*!
151 * Returns \c true if the text displayed is currently squeezed,
152 * i.e. the original text does not fit inside the space available
153 * and elide mode is set to a value other than Qt::ElideNone.
154 *
155 * \since 5.38
156 */
157 bool isSqueezed() const;
158
159 /*!
160 * Returns the rectangle to squeeze the text into
161 *
162 * Reimplementation of QLabel::contentsRect().
163 *
164 * \warning The corresponding function in the base class is not virtual.
165 * Therefore make sure to call this function on objects of type KSqueezedTextLabel,
166 * as shown in the example in the class description.
167 *
168 * \since 5.39
169 */
170 QRect contentsRect() const;
171
172public Q_SLOTS:
173 /*!
174 * Sets the text.
175 *
176 * \a text The new text.
177 *
178 * Reimplementation of QLabel::setText().
179 *
180 * \warning The corresponding function in the base class is not virtual.
181 * Therefore make sure to call this function on objects of type KSqueezedTextLabel,
182 * as shown in the example in the class description.
183 */
184 void setText(const QString &text);
185
186 /*!
187 * Clears the text.
188 *
189 * Reimplementation of QLabel::clear().
190 *
191 * \warning The corresponding function in the base class is not virtual.
192 * Therefore make sure to call this function on objects of type KSqueezedTextLabel,
193 * as shown in the example in the class description.
194 */
195 void clear();
196
197protected:
198 void mouseReleaseEvent(QMouseEvent *) override;
199
200 void resizeEvent(QResizeEvent *) override;
201
202 void contextMenuEvent(QContextMenuEvent *) override;
203
204 void squeezeTextToLabel();
205
206private:
207 std::unique_ptr<class KSqueezedTextLabelPrivate> const d;
208};
209
210#endif // KSQUEEZEDTEXTLABEL_H
211

source code of kwidgetsaddons/src/ksqueezedtextlabel.h