KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > forms > IMessageManager


1 /*******************************************************************************
2  * Copyright (c) 2007 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  ******************************************************************************/

11
12 package org.eclipse.ui.forms;
13
14 import org.eclipse.jface.dialogs.IMessageProvider;
15 import org.eclipse.jface.fieldassist.ControlDecoration;
16 import org.eclipse.swt.widgets.Control;
17 import org.eclipse.ui.forms.widgets.Form;
18
19 /**
20  * This interface provides for managing typed messages in a form. Typed messages
21  * are messages associated with a type that indicates their severity (error,
22  * warning, information). The interface is responsible for:
23  * <ul>
24  * <li>Bridging the concept of typed messages and control decorations</li>
25  * <li>Adding one or more messages per control in a form</li>
26  * <li>Rolling the local messages up to the form header</li>
27  * <li>Adding one or more general messages to the form header</li>
28  * </ul>
29  * <p>
30  * To use it in a form, do the following:
31  * <ol>
32  * <li>For each interactive control, add a listener to it to monitor user input</li>
33  * <li>Every time the input changes, validate it. If there is a problem, add a
34  * message with a unique key to the manager. If there is already a message with
35  * the same key in the manager, its type and message text will be replaced (no
36  * duplicates). Note that you add can messages with different keys to the same
37  * control to track multiple problems with the user input.</li>
38  * <li>If the problem has been cleared, remove the message using the key
39  * (attempting to remove a message that is not in the manager is safe).</li>
40  * <li>If something happens in the form that is not related to any control, use
41  * the other <code>addMessage</code> method.</li>
42  * </ol>
43  * <p>
44  * This interface should only be referenced. It must not be implemented or
45  * extended.
46  * </p>
47  *
48  * @since 3.3
49  * @see IMessageProvider
50  * @see IManagedForm
51  */

52
53 public interface IMessageManager {
54     /**
55      * Adds a general message that is not associated with any decorated field.
56      * Note that subsequent calls using the same key will not result in
57      * duplicate messages. Instead, the previous message with the same key will
58      * be replaced with the new message.
59      *
60      * @param key
61      * a unique message key that will be used to look the message up
62      * later
63      *
64      * @param messageText
65      * the message to add
66      * @param data
67      * an object for application use (can be <code>null</code>)
68      * @param type
69      * the message type as defined in <code>IMessageProvider</code>.
70      */

71     void addMessage(Object JavaDoc key, String JavaDoc messageText, Object JavaDoc data, int type);
72
73     /**
74      * Adds a message that should be associated with the provided control. Note
75      * that subsequent calls using the same key will not result in duplicate
76      * messages. Instead, the previous message with the same key will be
77      * replaced with the new message.
78      *
79      * @param key
80      * the unique message key
81      * @param messageText
82      * the message to add
83      * @param data
84      * an object for application use (can be <code>null</code>)
85      * @param type
86      * the message type
87      * @param control
88      * the control to associate the message with
89      */

90     void addMessage(Object JavaDoc key, String JavaDoc messageText, Object JavaDoc data, int type,
91             Control control);
92
93     /**
94      * Removes the general message with the provided key. Does nothing if
95      * message for the key does not exist.
96      *
97      * @param key
98      * the key of the message to remove
99      */

100     void removeMessage(Object JavaDoc key);
101
102     /**
103      * Removes all the general messages. If there are local messages associated
104      * with controls, the replacement message may show up drawing user's
105      * attention to these local messages. Otherwise, the container will clear
106      * the message area.
107      */

108     void removeMessages();
109
110     /**
111      * Removes a keyed message associated with the provided control. Does
112      * nothing if the message for that key does not exist.
113      *
114      * @param key
115      * the id of the message to remove
116      * @param control
117      * the control the message is associated with
118      */

119     void removeMessage(Object JavaDoc key, Control control);
120
121     /**
122      * Removes all the messages associated with the provided control. Does
123      * nothing if there are no messages for this control.
124      *
125      * @param control
126      * the control the messages are associated with
127      */

128     void removeMessages(Control control);
129
130     /**
131      * Removes all the local field messages and all the general container
132      * messages.
133      */

134     void removeAllMessages();
135
136     /**
137      * Updates the message container with the messages currently in the manager.
138      * There are two scenarios in which a client may want to use this method:
139      * <ol>
140      * <li>When controls previously managed by this manager have been disposed.</li>
141      * <li>When automatic update has been turned off.</li>
142      * </ol>
143      * In all other situations, the manager will keep the form in sync
144      * automatically.
145      *
146      * @see #setAutoUpdate(boolean)
147      */

148     void update();
149
150     /**
151      * Controls whether the form is automatically updated when messages are
152      * added or removed. By default, auto update is on. Clients can turn it off
153      * prior to adding or removing a number of messages as a batch. Turning it
154      * back on will trigger an update.
155      *
156      * @param enabled
157      * sets the state of the automatic update
158      */

159     void setAutoUpdate(boolean enabled);
160
161     /**
162      * Tests whether the form will be automatically updated when messages are
163      * added or removed.
164      *
165      * @return <code>true</code> if auto update is active, <code>false</code>
166      * otherwise.
167      */

168     boolean isAutoUpdate();
169
170     /**
171      * Sets the alternative message prefix provider. The default prefix provider
172      * is set by the manager.
173      *
174      * @param provider
175      * the new prefix provider or <code>null</code> to turn the
176      * prefix generation off.
177      */

178     void setMessagePrefixProvider(IMessagePrefixProvider provider);
179
180     /**
181      * @return the current prefix provider or <code>null</code> if prefixes
182      * are not generated.
183      */

184     IMessagePrefixProvider getMessagePrefixProvider();
185
186     /**
187      * Message manager uses SWT.LEFT|SWT.BOTTOM for the default decoration
188      * position. Use this method to change it.
189      *
190      * @param position
191      * the decoration position
192      * @see ControlDecoration
193      */

194     void setDecorationPosition(int position);
195
196     /**
197      * Returns the currently used decoration position for all control messages.
198      *
199      * @return the current decoration position
200      */

201
202     int getDecorationPosition();
203
204     /**
205      * When message manager is used in context of a form, and there are
206      * hyperlink listeners for messages in the header, the hyperlink event will
207      * carry an object of type <code>IMessage[]</code> as an href. You can use
208      * this method to create a summary text from this array consistent with the
209      * tool tip used by the form header.
210      *
211      * @param messages
212      * an array of messages
213      * @return a textual representation of the messages with one message per
214      * line.
215      * @see Form#addMessageHyperlinkListener(org.eclipse.ui.forms.events.IHyperlinkListener)
216      */

217     String JavaDoc createSummary(IMessage[] messages);
218 }
Popular Tags