1/* -*- C++ -*-
2 This file is part of the KDE libraries
3 Copyright (C) 2005 Andreas Nicolai <Andreas.Nicolai@gmx.net>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KPLOTAXIS_H
22#define KPLOTAXIS_H
23
24#include <kdeui_export.h>
25
26#include <QtCore/QString>
27#include <QtCore/QList>
28
29/**
30 * @short Axis for KPlotWidget
31 *
32 * Contains all data for drawing an axis including format specification axis labels.
33 *
34 * @author Andreas Nicolai
35 * @version 1.0
36 */
37class KDEUI_EXPORT KPlotAxis {
38public:
39
40 /**
41 * Constructor, constructs an axis with the label @p label.
42 */
43 explicit KPlotAxis( const QString& label = QString() );
44
45 /**
46 * Destructor.
47 */
48 ~KPlotAxis();
49
50 /**
51 * @return whether the axis is visible or not
52 */
53 bool isVisible() const;
54
55 /**
56 * Sets the "visible" property of the axis.
57 * @param visible if true, this axis will be drawn on the KPlotWidget
58 */
59 void setVisible( bool visible );
60
61 /**
62 * @return whether tick labels will be drawn for this axis
63 */
64 bool areTickLabelsShown() const;
65
66 /**
67 * Determine whether tick labels will be drawn for this axis.
68 * @param b if true, tick labels will be drawn.
69 */
70 void setTickLabelsShown( bool b );
71
72 /**
73 * Sets the axis label.
74 * Set the label to an empty string to omit the axis label.
75 * @param label a string describing the data plotted on the axis.
76 */
77 void setLabel( const QString& label );
78
79 /**
80 * @return the label string for this axis
81 */
82 QString label() const;
83
84 /**
85 * @return the ticklabel string for the given value, rendered according
86 * to the current format specification.
87 * @param the value to be rendered as a tick label.
88 * @sa setTickLabelFormat()
89 */
90 QString tickLabel( double value ) const;
91
92 /**
93 * Set the display format for converting the double value of the
94 * tick's position to the QString for the tick label.
95 *
96 * Normally, the format character is one of 'e', 'E', 'f', 'g', or 'G'
97 * (see the documentation for QString::arg(double) for details).
98 *
99 * In addition, it is possible to set the format character to 't';
100 * in this case the tickmark value is interpreted as a time in hours,
101 * and the ticklabel string will be in "hh:mm" clock format.
102 * Note that when the format character is 't', the fieldWidth and prec
103 * values are ignored.
104 *
105 * @param format the format specification character
106 * @param fieldWidth the number of characters in the output string.
107 * If set to 0, the string will be as wide as it needs to be to fully
108 * render the value.
109 * @param precision the number of characters following the decimal point.
110 */
111 void setTickLabelFormat( char format = 'g', int fieldWidth = 0, int precision = -1 );
112
113 /**
114 * @return the field width of the tick labels
115 */
116 int tickLabelWidth() const;
117
118 /**
119 * @return the number format of the tick labels
120 */
121 char tickLabelFormat() const;
122
123 /**
124 * @return the number precision of the tick labels
125 */
126 int tickLabelPrecision() const;
127
128 /**
129 * Determine the positions of major and minor tickmarks for this axis.
130 * @note this function is called by KPlotWidget whenever the plot's
131 * limits are modified.
132 * @param x0 the minimum data coordinate of the axis.
133 * @param length the range covered by the axis, in data units.
134 * @sa majorTickMarks()
135 * @sa minorTickMarks()
136 */
137 void setTickMarks( double x0, double length );
138
139 /**
140 * @return the list of coordinates of the major tickmarks for this axis
141 * @note the positions of tickmarks are automatically computed by setTickMarks().
142 * @sa setTickMarks()
143 * @sa minorTickMarks()
144 */
145 QList< double > majorTickMarks() const;
146
147 /**
148 * @return the list with the minor tickmarks
149 * @note the positions of tickmarks are automatically computed by setTickMarks().
150 * @sa setTickMarks()
151 * @sa majorTickMarks()
152 */
153 QList< double > minorTickMarks() const;
154
155private:
156 class Private;
157 Private * const d;
158
159 Q_DISABLE_COPY( KPlotAxis )
160};
161
162#endif // KPLOTAXIS_H
163