1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License")
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.jguiraffe.gui.builder.components;
17
18
19 /**
20 * <p>
21 * Definition of an interface for a component that manages the tool tips of UI
22 * elements.
23 * </p>
24 * <p>
25 * Each UI element can be associated with a tool tip that is displayed when the
26 * mouse cursor is placed over the element. The tag handler classes for creating
27 * UI element provide corresponding options.
28 * </p>
29 * <p>
30 * Assigning a tool tip text to an element is standard functionality. However,
31 * sometimes the texts for tool tips must be dynamically adapted depending on
32 * the current status of the element. For instance, an input element contains
33 * invalid data, and the tool tip is to be extended to display the validation
34 * messages, too. Or the tool tip of a disabled button should display additional
35 * information why this button cannot be pressed currently.
36 * </p>
37 * <p>
38 * This interface provides functionality for dealing with tool tips for
39 * components that can change dynamically. The basic idea is that each
40 * component's tool tip consists of two parts:
41 * <ul>
42 * <li>a static part describing the functionality of this component</li>
43 * <li>and a dynamic part containing information related to the current state of
44 * the component.</li>
45 * </ul>
46 * Both parts are optional. Typically the static part remains constant while the
47 * dynamic part may change, but this is not a requirement. This interface
48 * defines methods to query and to set both parts of the tool tip for a given
49 * component. Components can be specified as native objects or by their name
50 * (the latter requires that a concrete implementation has access to a component
51 * store).
52 * </p>
53 *
54 * @author Oliver Heger
55 * @version $Id: ToolTipManager.java 205 2012-01-29 18:29:57Z oheger $
56 */
57 public interface ToolTipManager
58 {
59 /**
60 * Returns the tool tip of the specified component.
61 *
62 * @param component the component in question
63 * @return the tool tip of this component (can be <b>null</b>)
64 */
65 String getToolTip(Object component);
66
67 /**
68 * Sets the tool tip of the specified component. This is the static part of
69 * the component's tool tip.
70 *
71 * @param component the component in question
72 * @param tip the static tool tip for this component
73 */
74 void setToolTip(Object component, String tip);
75
76 /**
77 * Returns the tool tip for the component with the specified name. If the
78 * name cannot be resolved, an exception is thrown.
79 *
80 * @param componentName the name of the component in question
81 * @return the tool tip of this component (can be <b>null</b>)
82 * @throws net.sf.jguiraffe.gui.builder.utils.GUIRuntimeException if the
83 * component cannot be resolved
84 */
85 String getToolTip(String componentName);
86
87 /**
88 * Sets the tool tip of the component with the given name. This is the
89 * static part of the component's tool tip. If the name cannot be resolved,
90 * an exception is thrown.
91 *
92 * @param componentName the name of the component in question
93 * @param tip the static tool tip for this component
94 * @throws net.sf.jguiraffe.gui.builder.utils.GUIRuntimeException if the
95 * component name cannot be resolved
96 */
97 void setToolTip(String componentName, String tip);
98
99 /**
100 * Returns the additional (dynamic) tool tip for the specified component.
101 *
102 * @param component the component in question
103 * @return the additional (dynamic) tool tip of this component (can be
104 * <b>null</b>)
105 */
106 String getAdditionalToolTip(Object component);
107
108 /**
109 * Sets the additional (dynamic) tool tip for the specified component. The
110 * actual tool tip of this component is constructed from the static part
111 * (set through the {@link #setToolTip(Object, String)} method) and this
112 * part.
113 *
114 * @param component the component in question
115 * @param tip the additional (dynamic) tool tip for this component
116 */
117 void setAdditionalToolTip(Object component, String tip);
118
119 /**
120 * Returns the additional (dynamic) tool tip for the component with the
121 * given name. If the name cannot be resolved, an exception is thrown.
122 *
123 * @param componentName the name of the component in question
124 * @return the additional (dynamic) tool tip of this component
125 * @throws net.sf.jguiraffe.gui.builder.utils.GUIRuntimeException if the
126 * component name cannot be resolved
127 */
128 String getAdditionalToolTip(String componentName);
129
130 /**
131 * Sets the additional (dynamic) tool tip for the component with the given
132 * name. This works like {@link #setAdditionalToolTip(Object, String)}, but
133 * the component is specified using its name. If the name cannot be
134 * resolved, an exception is thrown.
135 *
136 * @param componentName the name of the component in question
137 * @param tip the additional (dynamic) tool tip
138 * @throws net.sf.jguiraffe.gui.builder.utils.GUIRuntimeException if the
139 * component name cannot be resolved
140 */
141 void setAdditionalToolTip(String componentName, String tip);
142 }