KGantt

kganttdatetimegrid.h
1/*
2 * SPDX-FileCopyrightText: 2001-2015 Klaralvdalens Datakonsult AB. All rights reserved.
3 *
4 * This file is part of the KGantt library.
5 *
6 * SPDX-License-Identifier: GPL-2.0-or-later
7 */
8
9#ifndef KGANTTDATETIMEGRID_H
10#define KGANTTDATETIMEGRID_H
11
12#include "kganttabstractgrid.h"
13
14#include <QDateTime>
15#include <QSet>
16#include <QPair>
17
18namespace KGantt {
19
20 class DateTimeScaleFormatter;
21 class DateTimeTimeLine;
22
23
24 /*!\class KGantt::DateTimeGrid
25 * \ingroup KGantt
26 *
27 * This implementation of AbstractGrid works with QDateTime
28 * and shows days and week numbers in the header
29 */
30 class KGANTT_EXPORT DateTimeGrid : public AbstractGrid
31 {
32 Q_OBJECT
33 KGANTT_DECLARE_PRIVATE_DERIVED( DateTimeGrid )
34 public:
35 enum Scale {
36 ScaleAuto,
37 ScaleHour,
38 ScaleDay,
39 ScaleWeek,
40 ScaleMonth,
41 ScaleUserDefined
42 };
43 enum HeaderType {
44 NoHeader,
45 UpperHeader,
46 LowerHeader
47 };
48
50 ~DateTimeGrid() override;
51
52 /*! \returns The QDateTime used as start date for the grid.
53 *
54 * The default is three days before the current date.
55 */
56 QDateTime startDateTime() const;
57
58 /*! \param dt The start date of the grid. It is used as the beginning of the
59 * horizontal scrollbar in the view.
60 *
61 * Emits gridChanged() after the start date has changed.
62 */
63 void setStartDateTime( const QDateTime& dt );
64
65 /*! \returns The width in pixels for each day in the grid.
66 *
67 * The default is 100 pixels.
68 */
69 qreal dayWidth() const;
70
71 /*! \param w The width in pixels for each day in the grid.
72 *
73 * The signal gridChanged() is emitted after the day width is changed.
74 */
75 void setDayWidth( qreal );
76
77 /*! Maps a given point in time \a dt to an X value in the scene.
78 */
79 qreal mapFromDateTime( const QDateTime& dt) const;
80
81 /*! Maps a given X value \a x in scene coordinates to a point in time.
82 */
83 QDateTime mapToDateTime( qreal x ) const;
84
85 /*! \param ws The start day of the week.
86 *
87 * A solid line is drawn on the grid to mark the beginning of a new week.
88 * Emits gridChanged() after the start day has changed.
89 */
90 void setWeekStart( Qt::DayOfWeek );
91
92 /*! \returns The start day of the week */
93 Qt::DayOfWeek weekStart() const;
94
95 /*! \param fd A set of days to mark as free in the grid.
96 *
97 * Free days are filled with the alternate base brush of the
98 * palette used by the view.
99 * The signal gridChanged() is emitted after the free days are changed.
100 */
101 void setFreeDays( const QSet<Qt::DayOfWeek>& fd );
102
103 /*! \returns The days marked as free in the grid. */
104 QSet<Qt::DayOfWeek> freeDays() const;
105
106 /*! Sets the brush to use to paint free days.
107 */
108 void setFreeDaysBrush(const QBrush brush);
109
110 /*!
111 \returns The brush used to paint free days.
112 */
113 QBrush freeDaysBrush() const;
114
115 /*! \param s The scale to be used to paint the grid.
116 *
117 * The signal gridChanged() is emitted after the scale has changed.
118 * \sa Scale
119 *
120 * Following example demonstrates how to change the format of the header to use
121 * a date-scaling with the header-label displayed with the ISO date-notation.
122 * \code
123 * DateTimeScaleFormatter* formatter = new DateTimeScaleFormatter(DateTimeScaleFormatter::Day, QString::fromLatin1("yyyy-MMMM-dddd"));
124 * grid->setUserDefinedUpperScale( formatter );
125 * grid->setUserDefinedLowerScale( formatter );
126 * grid->setScale( DateTimeGrid::ScaleUserDefined );
127 * \endcode
128 */
129 void setScale( Scale s );
130
131 /*! \returns The scale used to paint the grid.
132 *
133 * The default is ScaleAuto, which means the day scale will be used
134 * as long as the day width is less or equal to 500.
135 * \sa Scale
136 */
137 Scale scale() const;
138
139 /*! Sets the scale formatter for the lower part of the header to the
140 * user defined formatter to \a lower. The DateTimeGrid object takes
141 * ownership of the formatter, which has to be allocated with new.
142 *
143 * You have to set the scale to ScaleUserDefined for this setting to take effect.
144 * \sa DateTimeScaleFormatter
145 */
146 void setUserDefinedLowerScale( DateTimeScaleFormatter* lower );
147
148 /*! Sets the scale formatter for the upper part of the header to the
149 * user defined formatter to \a upper. The DateTimeGrid object takes
150 * ownership of the formatter, which has to be allocated with new.
151 *
152 * You have to set the scale to ScaleUserDefined for this setting to take effect.
153 * \sa DateTimeScaleFormatter
154 */
155 void setUserDefinedUpperScale( DateTimeScaleFormatter* upper );
156
157 /*! \return The DateTimeScaleFormatter being used to render the lower scale.
158 */
159 DateTimeScaleFormatter* userDefinedLowerScale() const;
160
161
162 /*! \return The DateTimeScaleFormatter being used to render the upper scale.
163 */
164 DateTimeScaleFormatter* userDefinedUpperScale() const;
165
166 /*! \returns true if row separators are used. */
167 bool rowSeparators() const;
168
169 /*! \param enable Whether to use row separators or not. */
170 void setRowSeparators( bool enable );
171
172 /*! Sets the brush used to display rows where no data is found.
173 * Default is a red pattern. If set to QBrush() rows with no
174 * information will not be marked.
175 */
176 void setNoInformationBrush( const QBrush& brush );
177
178 /*! \returns the brush used to mark rows with no information.
179 */
180 QBrush noInformationBrush() const;
181
182 /*! \param idx The index to get the Span for.
183 * \returns The start and end pixels, in a Span, of the specified index.
184 */
185 /*reimp*/ Span mapToChart( const QModelIndex& idx ) const override;
186
187 /*! Maps the supplied Span to QDateTimes, and puts them as start time and
188 * end time for the supplied index.
189 *
190 * \param span The span used to map from.
191 * \param idx The index used for setting the start time and end time in the model.
192 * \param constraints A list of hard constraints to match against the start time and
193 * end time mapped from the span.
194 *
195 * \returns true if the start time and time was successfully added to the model, or false
196 * if unsuccessful.
197 * Also returns false if any of the constraints isn't satisfied. That is, if the start time of
198 * the constrained index is before the end time of the dependency index, or the end time of the
199 * constrained index is before the start time of the dependency index.
200 */
201 /*reimp*/ bool mapFromChart( const Span& span, const QModelIndex& idx,
202 const QList<Constraint>& constraints=QList<Constraint>() ) const override;
203
204 /*!
205 * \param value The datetime to get the x value for.
206 * \returns The x value corresponding to \a value or -1.0 if \a value is not a datetime variant.
207 */
208 /*reimp*/ qreal mapToChart( const QVariant& value ) const override;
209
210 /*!
211 * \param x The x value to get the datetime for.
212 * \returns The datetime corresponding to \a x or an invalid datetime if x cannot be mapped.
213 */
214 /*reimp*/ QVariant mapFromChart( qreal x ) const override;
215 /*reimp*/ void paintGrid( QPainter* painter,
216 const QRectF& sceneRect, const QRectF& exposedRect,
217 AbstractRowController* rowController = nullptr,
218 QWidget* widget = nullptr ) override;
219 /*reimp*/ void paintHeader( QPainter* painter,
220 const QRectF& headerRect, const QRectF& exposedRect,
221 qreal offset, QWidget* widget = nullptr ) override;
222
223 /**
224 * @return the timeline control object
225 */
226 DateTimeTimeLine *timeLine() const;
227
228 HeaderType sectionHandleAtPos(int x, int y, const QRect &headerRect) const;
229
230 protected:
231 /*! Paints the hour scale header.
232 * \sa paintHeader()
233 */
234 virtual void paintHourScaleHeader( QPainter* painter,
235 const QRectF& headerRect, const QRectF& exposedRect,
236 qreal offset, QWidget* widget = nullptr );
237
238 /*! Paints the day scale header.
239 * \sa paintHeader()
240 */
241 virtual void paintDayScaleHeader( QPainter* painter,
242 const QRectF& headerRect, const QRectF& exposedRect,
243 qreal offset, QWidget* widget = nullptr );
244
245 /*! Paints the week scale header.
246 * \sa paintHeader()
247 */
248 virtual void paintWeekScaleHeader( QPainter* painter,
249 const QRectF& headerRect, const QRectF& exposedRect,
250 qreal offset, QWidget* widget = nullptr );
251
252 /*! Paints the week scale header.
253 * \sa paintHeader()
254 */
255 virtual void paintMonthScaleHeader( QPainter* painter,
256 const QRectF& headerRect, const QRectF& exposedRect,
257 qreal offset, QWidget* widget = nullptr );
258
259 virtual void paintUserDefinedHeader( QPainter* painter,
260 const QRectF& headerRect, const QRectF& exposedRect,
261 qreal offset, const DateTimeScaleFormatter* formatter,
262 QWidget* widget = nullptr );
263
264
265 /*! Draw the background for a day.
266 */
267 virtual void drawDayBackground(QPainter* painter, const QRectF& rect, const QDate& date);
268
269 /*! Draw the foreground for a day.
270 */
271 virtual void drawDayForeground(QPainter* painter, const QRectF& rect, const QDate& date);
272
273 /** Return the rectangle that represents the date-range.
274 */
275 QRectF computeRect(const QDateTime& from, const QDateTime& to, const QRectF& rect) const;
276
277
278 /** Return a date-range represented by the rectangle.
279 */
280 QPair<QDateTime, QDateTime> dateTimeRange(const QRectF& rect) const;
281
282 /* reimp */ void drawBackground(QPainter* paint, const QRectF& rect) override;
283 /* reimp */ void drawForeground(QPainter* paint, const QRectF& rect) override;
284 };
285
286 /*!\class KGantt::DateTimeScaleFormatter
287 * \ingroup KGantt
288 *
289 * This class formats dates and times used in DateTimeGrid follawing a given format.
290 *
291 * The format follows the format of QDateTime::toString(), with one addition:
292 * "w" is replaced with the week number of the date as number without a leading zero (1-53)
293 * "ww" is replaced with the week number of the date as number with a leading zero (01-53)
294 *
295 * For example:
296 *
297 * \code
298 * // formatter to print the complete date over the current week
299 * // This leads to the first day of the week being printed
300 * DateTimeScaleFormatter formatter = DateTimeScaleFormatter( DateTimeScaleFormatter::Week, "yyyy-MM-dd" );
301 * \endcode
302 *
303 * Optionally, you can set an user defined text alignment flag. The default value is Qt::AlignCenter.
304 * \sa DateTimeScaleFormatter::DateTimeScaleFormatter
305 *
306 * This class even controls the range of the grid sections.
307 * \sa KGanttDateTimeScaleFormatter::Range
308 */
309 class KGANTT_EXPORT DateTimeScaleFormatter
310 {
311 KGANTT_DECLARE_PRIVATE_BASE_POLYMORPHIC( DateTimeScaleFormatter )
312 public:
313 enum Range {
314 Second,
315 Minute,
316 Hour,
317 Day,
318 Week,
319 Month,
320 Year
321 };
322
323 /*! Creates a DateTimeScaleFormatter using \a range and \a format.
324 * The text on the header is aligned following \a alignment.
325 */
326 DateTimeScaleFormatter( Range range, const QString& formatString,
327 Qt::Alignment alignment = Qt::AlignCenter );
328 DateTimeScaleFormatter( Range range, const QString& formatString,
329 const QString& templ, Qt::Alignment alignment = Qt::AlignCenter );
330
331 /*! \returns The format being used for formatting dates and times.
332 */
334 virtual ~DateTimeScaleFormatter();
335
336 DateTimeScaleFormatter& operator=( const DateTimeScaleFormatter& other );
337
338 /*! \returns The format string
339 */
340 QString format() const;
341
342 /*! \returns The range of each item on a DateTimeGrid header.
343 * \sa DateTimeScaleFormatter::Range */
344 Range range() const;
345 Qt::Alignment alignment() const;
346
347 /*! \returns the QDateTime being the begin of the range after the one containing \a datetime
348 * \sa currentRangeBegin
349 */
350 virtual QDateTime nextRangeBegin( const QDateTime& datetime ) const;
351
352 /*! \returns the QDateTime being the begin of the range containing \a datetime
353 * \sa nextRangeBegin
354 */
355 virtual QDateTime currentRangeBegin( const QDateTime& datetime ) const;
356
357 /*! \returns The \a datetime as string respecting the format.
358 */
359 QString format( const QDateTime& datetime ) const;
360 virtual QString text( const QDateTime& datetime ) const;
361 };
362}
363
364
365
366#ifndef QT_NO_DEBUG_STREAM
367QDebug KGANTT_EXPORT operator<<( QDebug dbg, KGantt::DateTimeScaleFormatter::Range );
368#endif
369
370#endif /* KGANTTDATETIMEGRID_H */
371
Abstract baseclass for grids. A grid is used to convert between QModelIndex'es and gantt chart values...
Abstract baseclass for row controllers. A row controller is used by the GraphicsView to nagivate the ...
A class representing a start point and a length.
Global namespace.
typedef Alignment
DayOfWeek
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:02:52 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.