Debian Codegraph @

laf-widget/src/main/java/org/pushingpixels/lafwidget/LafWidget.java

raw
1 /*
2 * Copyright (c) 2005-2010 Laf-Widget Kirill Grouchnikov. All Rights Reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
6 *
7 * o Redistributions of source code must retain the above copyright notice,
8 * this list of conditions and the following disclaimer.
9 *
10 * o Redistributions in binary form must reproduce the above copyright notice,
11 * this list of conditions and the following disclaimer in the documentation
12 * and/or other materials provided with the distribution.
13 *
14 * o Neither the name of Laf-Widget Kirill Grouchnikov nor the names of
15 * its contributors may be used to endorse or promote products derived
16 * from this software without specific prior written permission.
17 *
18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
20 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
22 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
23 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
25 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
26 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
27 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
28 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30 package org.pushingpixels.lafwidget;
31
32 import java.util.Locale;
33
34 import javax.swing.JComponent;
35 import javax.swing.JPasswordField;
36 import javax.swing.UIManager;
37
38 import org.pushingpixels.lafwidget.preview.DefaultPreviewPainter;
39 import org.pushingpixels.lafwidget.preview.PreviewPainter;
40 import org.pushingpixels.lafwidget.tabbed.DefaultTabPreviewPainter;
41 import org.pushingpixels.lafwidget.tabbed.TabHoverPreviewWidget;
42 import org.pushingpixels.lafwidget.tabbed.TabOverviewDialogWidget;
43 import org.pushingpixels.lafwidget.tabbed.TabPreviewPainter;
44 import org.pushingpixels.lafwidget.text.LockBorderWidget;
45 import org.pushingpixels.lafwidget.text.PasswordStrengthChecker;
46
47 /**
48 * Interface for LAF widgets (behavioural traits).
49 *
50 * @author Kirill Grouchnikov
51 */
52 public interface LafWidget<T extends JComponent> {
53 /**
54 * <p>
55 * Client property name for specifying that the {@link LockBorderWidget}
56 * should put a lock icon. This property can be set either on a single
57 * component or globally on {@link UIManager}. The value in both cases
58 * should be either {@link Boolean#TRUE} or {@link Boolean#FALSE}.
59 * </p>
60 *
61 * @since 3.2
62 */
63 public final static String HAS_LOCK_ICON = "lafwidgets.hasLockIcon";
64
65 /**
66 * <p>
67 * Client property name for specifying the preview painter for tabbed pane.
68 * This property can be set on a single tabbed pane. The value should be an
69 * instance of {@link TabPreviewPainter}. Default implementation of this
70 * {@link DefaultTabPreviewPainter}. Tabbed panes that have associated
71 * preview painters, have two widgets installed:
72 * </p>
73 * <ul>
74 * <li>Tab overview dialog from {@link TabOverviewDialogWidget}.</li>
75 * <li>Tab hover preview from {@link TabHoverPreviewWidget}.</li>
76 * </ul>
77 *
78 * <p>
79 * Here is an example of tabbed pane with default tab preview painter
80 * installed:
81 * </p>
82 *
83 * <code>
84 * &nbsp;&nbsp;JTabbedPane jtp = new JTabbedPane();<br>
85 * &nbsp;&nbsp;jtp.putClientProperty(LafWidget.TABBED_PANE_PREVIEW_PAINTER,<br>
86 * &nbsp;&nbsp;&nbsp;&nbsp;new DefaultTabPreviewPainter());
87 * </code>
88 */
89 public final static String TABBED_PANE_PREVIEW_PAINTER = "lafwidgets.tabbedpanePreviewPainter";
90
91 /**
92 * <p>
93 * Client property name for specifying the preview painter for a component.
94 * This property can be set either on a component or globally on
95 * {@link UIManager}. The value in both cases should be an instance of
96 * {@link PreviewPainter}. Default implementation is available in the
97 * {@link DefaultPreviewPainter}.
98 * </p>
99 *
100 * <p>
101 * Here is an example of a scroll pane with default preview painter
102 * installed on the internal component:
103 * </p>
104 *
105 * <code>
106 * JPanel myPanel = new JPanel();<br>
107 * myPanel.putClientProperty(LafWidget.PANE_PREVIEW_PAINTER,<br>
108 * &nbsp;&nbsp;new DefaultPreviewPainter());<br>
109 * JScrollPane jsp = new JScrollPane(myPanel);
110 * </code>
111 */
112 public final static String COMPONENT_PREVIEW_PAINTER = "lafwidgets.componentPreviewPainter";
113
114 /**
115 * <p>
116 * Client property name for specifying password strength checker for a
117 * password field. The value should be an instance of
118 * {@link PasswordStrengthChecker}, otherwise will be ignored. This property
119 * must be set on a specific {@link JPasswordField}. Here is an example:
120 * </p>
121 *
122 * <code>
123 * &nbsp;&nbsp;JPasswordField jpf = new JPasswordField("password", 10);<br>
124 * &nbsp;&nbsp;jpf.putClientProperty(LafWidget.PASSWORD_STRENGTH_CHECKER,<br>
125 * &nbsp;&nbsp;&nbsp;&nbsp;new PasswordStrengthChecker() {<br>
126 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;public PasswordStrength getStrength(char[] password) {<br>
127 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (password == null)<br>
128 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return PasswordStrength.WEAK;<br>
129 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;int length = password.length;<br>
130 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (length < 3)<br>
131 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return PasswordStrength.WEAK;<br>
132 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (length < 6)<br>
133 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return PasswordStrength.MEDIUM;<br>
134 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return PasswordStrength.STRONG;<br>
135 * &nbsp;&nbsp;&nbsp;&nbsp;}<br>
136 * <br>
137 * &nbsp;&nbsp;&nbsp;&nbsp;public String getDescription(PasswordStrength strength) {<br>
138 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (strength == PasswordStrength.WEAK)<br>
139 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return "&lt;html&gt;This password is &lt;b&gt;way&lt;/b&gt; too weak&lt;/html&gt;";<br>
140 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (strength == PasswordStrength.MEDIUM)<br>
141 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return "&lt;html&gt;Come on, you can do&lt;br&gt; a little better than that&lt;/html&gt;";<br>
142 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (strength == PasswordStrength.STRONG)<br>
143 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return "OK";<br>
144 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return null;<br>
145 * &nbsp;&nbsp;&nbsp;&nbsp;}<br>
146 * &nbsp;&nbsp;});
147 * </code>
148 */
149 public final static String PASSWORD_STRENGTH_CHECKER = "lafwidgets.passwordStrengthChecker";
150
151 /**
152 * <p>
153 * Client property name for specifying that the text component contents
154 * should be selected on focus gain. This property can be set either on a
155 * single text component or globally on {@link UIManager}. The value in both
156 * cases should be either {@link Boolean#TRUE} or {@link Boolean#FALSE}.
157 * </p>
158 *
159 * <p>
160 * Here is an example of globally set property (all text components that
161 * don't specify {@link Boolean#FALSE} as a client property will have the
162 * "select all on focus gain" behaviour):
163 * </p>
164 *
165 * <code>
166 * &nbsp;&nbsp;UIManager.put(LafWidget.TEXT_SELECT_ON_FOCUS, Boolean.TRUE);
167 * </code>
168 */
169 public final static String TEXT_SELECT_ON_FOCUS = "lafwidgets.textSelectAllOnFocus";
170
171 /**
172 * <p>
173 * Client property name for specifying that the text component contents
174 * should flip selection on ESCAPE key press. This property can be set on a
175 * single text component. The value should be either {@link Boolean#TRUE} or
176 * {@link Boolean#FALSE}.
177 * </p>
178 *
179 * <p>
180 * Here is an example of this property set on this specific text field:
181 * </p>
182 *
183 * <code>
184 * &nbsp;&nbsp;myTextField.put(LafWidget.TEXT_FLIP_SELECT_ON_ESCAPE, Boolean.TRUE);
185 * </code>
186 */
187 public final static String TEXT_FLIP_SELECT_ON_ESCAPE = "lafwidgets.textFlipSelectOnEscape";
188
189 /**
190 * <p>
191 * Client property name for specifying that the text component should have
192 * the edit context menu (with Cut / Copy / Paste / ... menu items). This
193 * property can be set either on a single text component or globally on
194 * {@link UIManager}. The value in both cases should be either
195 * {@link Boolean#TRUE} or {@link Boolean#FALSE}.
196 * </p>
197 *
198 * <p>
199 * Here is an example of globally set property (all text components that
200 * don't specify {@link Boolean#FALSE} as a client property will have the
201 * the edit context menu):
202 * </p>
203 *
204 * <code>
205 * &nbsp;&nbsp;UIManager.put(LafWidget.TEXT_EDIT_CONTEXT_MENU, Boolean.TRUE);
206 * </code>
207 */
208 public final static String TEXT_EDIT_CONTEXT_MENU = "lafwidgets.textEditContextMenu";
209
210 /**
211 * Client property name for specifying that the tree component should have
212 * automatic drag and drop support. This property can be set either on a
213 * single tree or globally on {@link UIManager}. The value in both cases
214 * should be either {@link Boolean#TRUE} or {@link Boolean#FALSE}.<br>
215 * <br>
216 * Here is an example of globally set property (all trees that don't specify
217 * {@link Boolean#FALSE} as a client property will have the automatic drag
218 * and drop support): <br>
219 * <br>
220 * <code>
221 * &nbsp;&nbsp;UIManager.put(LafWidget.TREE_AUTO_DND_SUPPORT, Boolean.TRUE);
222 * </code>
223 */
224 public final static String TREE_AUTO_DND_SUPPORT = "lafwidgets.treeAutoDnDSupport";
225
226 /**
227 * <p>
228 * Client property name for specifying that a scroll pane should have
229 * auto-scroll support invoked on middle-mouse button click. This property
230 * can be installed on a single scroll pane or globally on {@link UIManager}
231 * , and the value should be either {@link Boolean#TRUE} or
232 * {@link Boolean#FALSE}.
233 * </p>
234 * <p>
235 * Here is an example of a scroll bar that has auto-scroll installed.
236 * </p>
237 * <code>
238 * JScrollPane scrollPane = ...<br>
239 * scrollPane.putClientProperty(LafWidget.AUTO_SCROLL, Boolean.TRUE);
240 * </code>
241 *
242 * @since version 3.4
243 */
244 public final static String AUTO_SCROLL = "lafwidget.scroll.auto";
245
246 /**
247 * <p>
248 * Client property name for specifying that the label lookup for custom
249 * widgets and sub-components installed by various UI delegates should
250 * ignore the global locale (as returned by {@link Locale#getDefault()} and
251 * use the component-specific locale (as returned by
252 * {@link JComponent#getLocale()} instead. This property can be installed
253 * only on a single component, and the value should be either
254 * {@link Boolean#TRUE} or {@link Boolean#FALSE}.
255 * </p>
256 *
257 * <p>
258 * Here is an example of menu bar that will be localized according to its
259 * own locale
260 * </p>
261 * <code>
262 * JMenuBar jmb = ...<br>
263 * jmb.putClientProperty(LafWidget.IGNORE_GLOBAL_LOCALE, Boolean.TRUE);
264 * </code>
265 *
266 * @since version 3.1
267 */
268 public final static String IGNORE_GLOBAL_LOCALE = "lafwidgets.ignoreGlobalLocale";
269
270 /**
271 * Associates a component with <code>this</code> widget.
272 *
273 * @param jcomp
274 * Component.
275 */
276 public void setComponent(T jcomp);
277
278 /**
279 * Returns indication whether <code>this</code> widget requires custom LAF
280 * support. Some widgets such as {@link TabOverviewDialogWidget} or
281 * {@link TabHoverPreviewWidget} require custom implementation based on the
282 * internals of the specific LAF. Relevant functions in the base
283 * {@link LafWidgetSupport} support throw
284 * {@link UnsupportedOperationException}.
285 *
286 * @return <code>true</code> if <code>this</code> widget requires custom LAF
287 * support, <code>false</code> otherwise.
288 */
289 public boolean requiresCustomLafSupport();
290
291 /**
292 * Installs UI on the associated component.
293 */
294 public void installUI();
295
296 /**
297 * Installs default settings for the associated component.
298 */
299 public void installDefaults();
300
301 /**
302 * Installs listeners for the associated component.
303 */
304 public void installListeners();
305
306 /**
307 * Installs components for the associated component.
308 */
309 public void installComponents();
310
311 /**
312 * Uninstalls UI on the associated component.
313 */
314 public void uninstallUI();
315
316 /**
317 * Uninstalls default settings for the associated component.
318 */
319 public void uninstallDefaults();
320
321 /**
322 * Uninstalls listeners for the associated component.
323 */
324 public void uninstallListeners();
325
326 /**
327 * Uninstalls components for the associated component.
328 */
329 public void uninstallComponents();
330 }