KChart

KChartLegend.h
1/*
2 * SPDX-FileCopyrightText: 2001-2015 Klaralvdalens Datakonsult AB. All rights reserved.
3 *
4 * This file is part of the KD Chart library.
5 *
6 * SPDX-License-Identifier: GPL-2.0-or-later
7 */
8
9#ifndef KCHARTLEGEND_H
10#define KCHARTLEGEND_H
11
12#include "KChartAbstractAreaWidget.h"
13#include "KChartPosition.h"
14#include "KChartMarkerAttributes.h"
15
16class QTextTable;
17
18namespace KChart {
19
20class AbstractDiagram;
21typedef QList<AbstractDiagram*> DiagramList;
22typedef QList<const AbstractDiagram*> ConstDiagramList;
23
24/**
25 * @brief Legend defines the interface for the legend drawing class.
26 *
27 * Legend is the class for drawing legends for all kinds of diagrams ("chart types").
28 *
29 * Legend is drawn on chart level, not per diagram, but you can have more than one
30 * legend per chart, using KChart::Chart::addLegend().
31 *
32 * \note Legend is different from all other classes of KChart, since it can be
33 * displayed outside of the Chart's area. If you want to, you can embed the legend
34 * into your own widget, or into another part of a bigger layout, into which you might
35 * have inserted the Chart.
36 *
37 * On the other hand, please note that you MUST call Chart::addLegend to get your
38 * legend positioned into the correct place of your chart - if you want to have
39 * the legend shown inside of the chart (that's probably true for most cases).
40 */
41class KCHART_EXPORT Legend : public AbstractAreaWidget
42{
43 Q_OBJECT
44
45 Q_DISABLE_COPY( Legend )
46 KCHART_DECLARE_PRIVATE_DERIVED_QWIDGET( Legend )
47
48public:
49 explicit Legend( QWidget* parent = nullptr );
50 explicit Legend( KChart::AbstractDiagram* diagram, QWidget* parent = nullptr );
51 ~Legend() override;
52
53
54 enum LegendStyle { MarkersOnly = 0,
55 LinesOnly = 1,
56 MarkersAndLines = 2 };
57
58
59 void setLegendStyle( LegendStyle style );
60 LegendStyle legendStyle() const;
61
62
63
64 /**
65 * Creates an exact copy of this legend.
66 */
67 virtual Legend * clone() const;
68
69 /**
70 * Returns true if both legends have the same settings.
71 */
72 bool compare( const Legend* other ) const;
73
74 void resizeEvent( QResizeEvent * event ) override; // TODO: should be protected
75
76 virtual void paint( QPainter* painter ) override;
77 void paint( QPainter* painter, const QRect &rect);
78 void setVisible( bool visible ) override;
79
80 /**
81 Specifies the reference area for font size of title text,
82 and for font size of the item texts, IF automatic area
83 detection is set.
84
85 \note This parameter is ignored, if the Measure given for
86 setTitleTextAttributes (or setTextAttributes, resp.) is
87 not specifying automatic area detection.
88
89 If no reference area is specified, but automatic area
90 detection is set, then the size of the legend's parent
91 widget will be used.
92
93 \sa KChart::Measure, KChartEnums::MeasureCalculationMode
94 */
95 void setReferenceArea( const QWidget* area );
96 /**
97 Returns the reference area, that is used for font size of title text,
98 and for font size of the item texts, IF automatic area
99 detection is set.
100
101 \sa setReferenceArea
102 */
103 const QWidget* referenceArea() const;
104
105 /**
106 * The first diagram of the legend or 0 if there was none added to the legend.
107 * @return The first diagram of the legend or 0.
108 *
109 * \sa diagrams, addDiagram, removeDiagram, removeDiagrams, replaceDiagram, setDiagram
110 */
111 KChart::AbstractDiagram* diagram() const;
112
113 /**
114 * The list of all diagrams associated with the legend.
115 * @return The list of all diagrams associated with the legend.
116 *
117 * \sa diagram, addDiagram, removeDiagram, removeDiagrams, replaceDiagram, setDiagram
118 */
119 DiagramList diagrams() const;
120
121 /**
122 * @return The list of diagrams associated with this legend.
123 */
124 ConstDiagramList constDiagrams() const;
125
126 /**
127 * Add the given diagram to the legend.
128 * @param newDiagram The diagram to add.
129 *
130 * \sa diagram, diagrams, removeDiagram, removeDiagrams, replaceDiagram, setDiagram
131 */
132 void addDiagram( KChart::AbstractDiagram* newDiagram );
133
134 /**
135 * Removes the diagram from the legend's list of diagrams.
136 *
137 * \sa diagram, diagrams, addDiagram, removeDiagrams, replaceDiagram, setDiagram
138 */
139 void removeDiagram( KChart::AbstractDiagram* oldDiagram );
140
141 /**
142 * Removes all diagrams from the legend's list of diagrams.
143 *
144 * \sa diagram, diagrams, addDiagram, removeDiagram, replaceDiagram, setDiagram
145 */
146 void removeDiagrams();
147
148 /**
149 * Replaces the old diagram, or appends the
150 * new diagram, it there is none yet.
151 *
152 * @param newDiagram The diagram to be used instead of the old one.
153 * If this parameter is zero, the first diagram will just be removed.
154 *
155 * @param oldDiagram The diagram to be removed by the new one. This
156 * diagram will be deleted automatically. If the parameter is omitted,
157 * the very first diagram will be replaced. In case, there was no
158 * diagram yet, the new diagram will just be added.
159 *
160 * \sa diagram, diagrams, addDiagram, removeDiagram, removeDiagrams, setDiagram
161 */
162 void replaceDiagram( KChart::AbstractDiagram* newDiagram,
163 KChart::AbstractDiagram* oldDiagram = nullptr );
164
165 /**
166 * Returns the offset of the first dataset of \c diagram.
167 *
168 */
169 uint dataSetOffset( KChart::AbstractDiagram* diagram );
170
171 /**
172 * @brief A convenience method doing the same as replaceDiagram( newDiagram, 0 );
173 *
174 * Replaces the first diagram by the given diagram.
175 * If the legend's list of diagram is empty the given diagram is added to the list.
176 *
177 * \sa diagram, diagrams, addDiagram, removeDiagram, removeDiagrams, replaceDiagram
178 */
179 void setDiagram( KChart::AbstractDiagram* newDiagram );
180
181 /**
182 * \brief Specify the position of a non-floating legend.
183 *
184 * Use setFloatingPosition to set position and alignment
185 * if your legend is floating.
186 *
187 * \sa setAlignment, setFloatingPosition
188 */
189 void setPosition( Position position );
190
191 /**
192 * Returns the position of a non-floating legend.
193 * \sa setPosition
194 */
195 Position position() const;
196
197 /**
198 * \brief Specify the alignment of a non-floating legend.
199 *
200 * Use setFloatingPosition to set position and alignment
201 * if your legend is floating.
202 *
203 * \sa alignment, setPosition, setFloatingPosition
204 */
205 void setAlignment( Qt::Alignment );
206
207 /**
208 * Returns the alignment of a non-floating legend.
209 * \sa setAlignment
210 */
211 Qt::Alignment alignment() const;
212
213 /**
214 * \brief Specify the alignment of the text elements within the legend
215 *
216 * \sa textAlignment()
217 */
218 void setTextAlignment( Qt::Alignment );
219
220 /**
221 * \brief Returns the alignment used while rendering text elements within the legend.
222 *
223 * \sa setTextAlignment()
224 */
225 Qt::Alignment textAlignment() const;
226
227 /**
228 * \brief Specify the alignment of the legend symbol( alignment of Legend::LinesOnly)
229 * within the legend
230 *
231 * \sa legendSymbolAlignment()
232 */
233 void setLegendSymbolAlignment(Qt::Alignment);
234
235 /**
236 * \brief Returns the alignment used while drawing legend symbol(alignment of Legend::LinesOnly)
237 * within the legend.
238 *
239 * \sa setLegendSymbolAlignment()
240 */
241 Qt::Alignment legendSymbolAlignment() const;
242
243 /**
244 * \brief Specify the position and alignment of a floating legend.
245 *
246 * Use setPosition and setAlignment to set position and alignment
247 * if your legend is non-floating.
248 *
249 * \note When setFloatingPosition is called, the Legend's position value is set to
250 * KChart::Position::Floating automatically.
251 *
252 * If your Chart is pointed to by m_chart, your could have the floating legend
253 * aligned exactly to the chart's coordinate plane's top-right corner
254 * with the following commands:
255\verbatim
256KChart::RelativePosition relativePosition;
257relativePosition.setReferenceArea( m_chart->coordinatePlane() );
258relativePosition.setReferencePosition( Position::NorthEast );
259relativePosition.setAlignment( Qt::AlignTop | Qt::AlignRight );
260relativePosition.setHorizontalPadding(
261 KChart::Measure( -1.0, KChartEnums::MeasureCalculationModeAbsolute ) );
262relativePosition.setVerticalPadding(
263 KChart::Measure( 0.0, KChartEnums::MeasureCalculationModeAbsolute ) );
264m_legend->setFloatingPosition( relativePosition );
265\endverbatim
266 *
267 * To have the legend positioned at a fixed point, measured from the QPainter's top left corner,
268 * you could use the following code code:
269 *
270\verbatim
271KChart::RelativePosition relativePosition;
272relativePosition.setReferencePoints( PositionPoints( QPointF( 0.0, 0.0 ) ) );
273relativePosition.setReferencePosition( Position::NorthWest );
274relativePosition.setAlignment( Qt::AlignTop | Qt::AlignLeft );
275relativePosition.setHorizontalPadding(
276 KChart::Measure( 4.0, KChartEnums::MeasureCalculationModeAbsolute ) );
277relativePosition.setVerticalPadding(
278 KChart::Measure( 4.0, KChartEnums::MeasureCalculationModeAbsolute ) );
279m_legend->setFloatingPosition( relativePosition );
280\endverbatim
281 * Actually that's exactly the code KChart is using as default position for any floating legends,
282 * so if you just say setPosition( KChart::Position::Floating ) without calling setFloatingPosition
283 * your legend will be positioned at point 4/4.
284 *
285 * \sa setPosition, setAlignment
286 */
287 void setFloatingPosition( const RelativePosition& relativePosition );
288
289 /**
290 * Returns the position of a floating legend.
291 * \sa setFloatingPosition
292 */
293 const RelativePosition floatingPosition() const;
294
295 void setOrientation( Qt::Orientation orientation );
296 Qt::Orientation orientation() const;
297
298
299 void setSortOrder( Qt::SortOrder order );
300 Qt::SortOrder sortOrder() const;
301
302 void setShowLines( bool legendShowLines );
303 bool showLines() const;
304
305
306 /**
307 \brief Removes all legend texts that might have been set by setText.
308
309 This resets the Legend to default behaviour: Texts are created automatically.
310 */
311 void resetTexts();
312 void setText( uint dataset, const QString& text );
313 QString text( uint dataset ) const;
314 const QMap<uint,QString> texts() const;
315
316 /**
317 * Sets a list of datasets that are to be hidden in the legend.
318 *
319 * By passing an empty list, you show all datasets.
320 * All datasets are shown by default, which means
321 * that hiddenDatasets() returns an empty list.
322 */
323 void setHiddenDatasets( const QList<uint> hiddenDatasets );
324 const QList<uint> hiddenDatasets() const;
325 void setDatasetHidden( uint dataset, bool hidden );
326 bool datasetIsHidden( uint dataset ) const;
327
328 uint datasetCount() const;
329
330 void setDefaultColors();
331 void setRainbowColors();
332 void setSubduedColors( bool ordered = false );
333
334 void setBrushesFromDiagram( KChart::AbstractDiagram* diagram );
335
336 /**
337 * Note: there is no color() getter method, since setColor
338 * just sets a QBrush with the respective color, so the
339 * brush() getter method is sufficient.
340 */
341 void setColor( uint dataset, const QColor& color );
342
343 void setBrush( uint dataset, const QBrush& brush );
344 QBrush brush( uint dataset ) const;
345 const QMap<uint,QBrush> brushes() const;
346
347 void setPen( uint dataset, const QPen& pen );
348 QPen pen( uint dataset ) const;
349 const QMap<uint,QPen> pens() const;
350
351 /**
352 * Note that any sizes specified via setMarkerAttributes are ignored,
353 * unless you disable the automatic size calculation, by saying
354 * setUseAutomaticMarkerSize( false )
355 */
356 void setMarkerAttributes( uint dataset, const MarkerAttributes& );
357 MarkerAttributes markerAttributes( uint dataset ) const;
358 const QMap<uint, MarkerAttributes> markerAttributes() const;
359
360 /**
361 * This option is on by default, it means that Marker sizes in the Legend
362 * will be the same as the font height used for their respective label texts.
363 *
364 * Set this to false, if you want to specify the marker sizes via setMarkerAttributes
365 * or if you want the Legend to use the same marker sizes as they are used in the Diagrams.
366 */
367 void setUseAutomaticMarkerSize( bool useAutomaticMarkerSize );
368 bool useAutomaticMarkerSize() const;
369
370 void setTextAttributes( const TextAttributes &a );
371 TextAttributes textAttributes() const;
372
373 void setTitleText( const QString& text );
374 QString titleText() const;
375
376 void setTitleTextAttributes( const TextAttributes &a );
377 TextAttributes titleTextAttributes() const;
378
379 void setSpacing( uint space );
380 uint spacing() const;
381
382 // called internally by KChart::Chart, when painting into a custom QPainter
383 void forceRebuild() override;
384
385 QSize minimumSizeHint() const override;
386 QSize sizeHint() const override;
387 bool hasHeightForWidth() const override;
388 int heightForWidth( int width ) const override;
389 void needSizeHint() override;
390 void resizeLayout( const QSize& size ) override;
391
392Q_SIGNALS:
393 void destroyedLegend( KChart::Legend* );
394 /** Emitted upon change of a property of the Legend or any of its components. */
396
397private Q_SLOTS:
398 void emitPositionChanged();
399 void resetDiagram( KChart::AbstractDiagram* );
400 void activateTheLayout();
401 void setNeedRebuild();
402 void buildLegend();
403}; // End of class Legend
404
405}
406
407
408#endif // KCHARTLEGEND_H
An area in the chart with a background, a frame, etc.
AbstractDiagram defines the interface for diagram classes.
Legend defines the interface for the legend drawing class.
void propertiesChanged()
Emitted upon change of a property of the Legend or any of its components.
A set of attributes controlling the appearance of data set markers.
Defines a position, using compass terminology.
Defines relative position information: reference area, position in this area (reference position),...
A set of text attributes.
typedef Alignment
Orientation
SortOrder
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:02:46 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.