1 /*
2 * Copyright (c) 2003-2008 by Cosylab d. d.
3 *
4 * This file is part of CosyBeans-Common.
5 *
6 * CosyBeans-Common is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License, or
9 * (at your option) any later version.
10 *
11 * CosyBeans-Common is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with CosyBeans-Common. If not, see <http://www.gnu.org/licenses/>.
18 */
19
20 package com.cosylab.gui.components.range2;
21
22 /**
23 * This interface is a definition of range, a pair of two values denoting
24 * minimum and maximum. Range can be interpreted as a function of two
25 * parameters defined between minimum and maximum.<p>
26 * Two operations are defined on this range, conversion from absolute value
27 * to relative and vice-versa. Absolute values are of the same scale as
28 * minimum and maximum, relative values are defined as an interval between
29 * 0 and 1, where <code>toRelative(getMinimum())</code> returns 0 and
30 * <code>toRelative(getMaximum())</code> returns 1.<p>
31 *
32 * Additionally, each range provides <code>TickCollector</code>, which generates
33 * information used when rendering scale ticks.<p>
34 *
35 * @author <a href="mailto:ales.pucelj@cosylab.com">Ales Pucelj</a>
36 * @version $id$
37 */
38 public interface Range {
39
40 /**
41 * Converts relative value (in 0 to 1 range) to absolute value.<p>
42 * These conditions must be true:
43 * <ul>
44 * <li><code>toAbsolute(0.0) == getMinimum()</code></li>
45 * <li><code>toAbsolute(1.0) == getMaximum()</code></li>
46 * <li><code>toAbsolute(toRelative(x)) == x</code></li>
47 * <li>toAbsolute(x) must always return value between getMinimum() and
48 * getMaximum() for x between 0.0 and 1.0.</li>
49 * </ul>
50 * This method does not need to return correct result for values outside the
51 * 0 to 1 range.
52 *
53 * @param relative value to convert to absolute.
54 * @return Absolute value.
55 */
56 double toAbsolute(double relative, RangedValue ranged);
57
58 /**
59 * Converts absolute value (in <code>getMinimum()</code> to
60 * <code>getMaximum()</code> range) to relative value (0 to 1 range).<p>
61 * These conditions must be true:
62 * <ul>
63 * <li><code>toRelative(getMinimum()) == 0.0</code></li>
64 * <li><code>toRelative(getMaximum()) == 1.0</code></li>
65 * <li><code>toRelative(toAbsolute(x)) == x</code></li>
66 * <li>toRelative must return value between 0 and 1 for all values between
67 * <code>getMinimum()</code> and <code>getMaximum()</code>.
68 * </ul>
69 *
70 * @param absolute value to convert to relative.
71 * @return relative value.
72 */
73 double toRelative(double absolute, RangedValue ranged);
74
75 /**
76 * Checks the value for acceptability. This is acceptance test for each and
77 * every value that is used with this range. Result will be adjusted value
78 * of the parameter.<p>
79 * For some scales i.e. logarithmic, no value can be set below certain
80 * value (0.0 in case of logarithmic). This method will ensure, that
81 * whenever incorrect value is passed, it returns a value that is
82 * acceptable. In case of logarithmic range, return value will never be
83 * less than 0.0.
84 *
85 * @param value to test.
86 * @return acceptable value.
87 */
88 double validate(double value);
89
90 /**
91 * Returns the default TickCaluclator employed by this Range.
92 *
93 * @return
94 */
95 public TickCalculator getDefaultTickCalculator();
96 }