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   key, String   messageText, Object   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   key, String   messageText, Object   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   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   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   createSummary(IMessage[] messages);
218 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags