1 /*
2 * Copyright (c) 2003-2008 by Cosylab d. d.
3 *
4 * This file is part of CosyBeans.
5 *
6 * CosyBeans 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 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. If not, see <http://www.gnu.org/licenses/>.
18 */
19
20 package com.cosylab.gui.displayers;
21
22 import java.util.BitSet;
23
24 import com.cosylab.util.BitCondition;
25
26
27 /**
28 * A specialization of <code>Displayer</code> interface for patterns. A pattern
29 * is Java primitive <code>long</code> type that is interpreted in its binary
30 * form as a bit-pattern. In order to distinguish significant and
31 * insignificant bits, a bit-mask known as resolution is used. The total
32 * number of bits set to 1 in the bitmask determine the number of bits this
33 * displayer has to render. In order to render these bits properly, the
34 * adapter delivers the following data items:
35 *
36 * <ul>
37 * <li>
38 * <b>String[] bitDescriptions</b>. For each bit in the resolution bit mask
39 * which is set to 1, this array contains a description of maximum one line
40 * length.
41 * </li>
42 * <li>
43 * <b>Condition[] conditionWhenSet</b>. For each bit in the resolution bit
44 * mask, which is set to 1, this array contains hints to the displayer
45 * about how the bit should be rendered if it is set to 1.
46 * </li>
47 * <li>
48 * <b>Condition[] conditionWhenCleared</b>. For each bit in the resolution bit
49 * mask, which is set to 1, this array contains hints to the displayer about
50 * how the bit should be rendered if the bit is set to 0.
51 * </li>
52 * <li>
53 * <b>String format</b>. The C-style formatting string that specifies how the
54 * whole value should be rendered. It may, for example, direct the displayer
55 * to display the value in binary or hex mode.
56 * </li>
57 * </ul>
58 *
59 *
60 * @author <a href="mailto:igor.kriznar@cosylab.com">Igor Kriznar</a>
61 * @version $id$
62 */
63 public interface PatternDisplayer extends Displayer, PatternConsumer
64 {
65 /**
66 * Returns the value currently displayed by the displayer. The value is
67 * interpreted as a bit-field.
68 *
69 * @return BitSet bit value
70 */
71 public BitSet getValue();
72
73 /**
74 * Sets the value to be displayed by the displayer. This method is invoked
75 * by adapter. The value is interpreted as a bit field as described in
76 * the class documentation.
77 *
78 * @param value the value to be displayed.
79 */
80 public void setValue(BitSet value);
81
82 /**
83 * Returns an array of Strings, equal in length to the total number of
84 * significant bits, determined in the <code>resolution</code>. For each
85 * significant bit, this array contains a (maximum) one line description.
86 *
87 * @return String[] an array of descriptions
88 */
89 public String[] getBitDescriptions();
90
91 /**
92 * Sets the array of descriptions to be used by the displayer. This method
93 * will be usually called by the adapter or user during design time.
94 *
95 * @param value the new array of bit descriptions
96 *
97 * @see #getBitDescriptions
98 */
99 public void setBitDescriptions(String[] value);
100
101 /**
102 * Returns the array of <code>Condition</code> objects that carry
103 * information on how each significant bit should be rendered when its
104 * value is 0.
105 *
106 * @return BitCondition[] an array of rendering hints for cleared bits
107 */
108 public BitCondition[] getConditionWhenCleared();
109
110 /**
111 * Sets the rendering hints for the cleared bits. This method will be
112 * usually called by the adapter or during design time.
113 *
114 * @param BitCondition[] an array of rendering hints for cleared bits.
115 *
116 * @see #getConditionWhenCleared
117 */
118 public void setConditionWhenCleared(BitCondition[] value);
119
120 /**
121 * Returns an array of <code>Condition</code> objects that carry
122 * information on how each significant bit should be rendered when its
123 * value is 1.
124 *
125 * @return Condition[] an array of rendering hints for set bits
126 */
127 public BitCondition[] getConditionWhenSet();
128
129 /**
130 * Sets the array of rendering hitns for set bits. This method will be
131 * usually called by the adapter or user during design time.
132 *
133 * @param value the rendering hints
134 *
135 * @see #getConditionWhenSet
136 */
137 public void setConditionWhenSet(BitCondition[] value);
138
139 /**
140 * Returns the C-style format specification used when the <code>long</code>
141 * bit field must be output to string format.
142 *
143 * @return String C-style printf format specification
144 */
145 public String getFormat();
146
147 /**
148 * Sets the format specification used by this displayer to render its value
149 * into one string.
150 *
151 * @param String a new C-style format specification
152 *
153 * @see #getFormat
154 */
155 public void setFormat(String value);
156
157 /**
158 * Returns the resolution bit mask determining which bits in the
159 * <code>value</code> are significant. The total number of ones in the
160 * binary representation of the bit-mask is the number of significant
161 * bits. The value to be rendered is obtained by doing a bitwise and on
162 * the resolution and the value.
163 *
164 * @return BitSet the bit-mask for this displayer
165 */
166 public BitSet getBitMask();
167
168 /**
169 * Sets the bit-mask for this displayer.
170 *
171 * @param BitSet the new bit-mask for this displayer
172 *
173 * @see #getBitMask
174 */
175 public void setBitMask(BitSet value);
176 }
177
178 /* __oOo__ */