001: /*******************************************************************************
002: * Copyright (c) 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: ******************************************************************************/package org.eclipse.ui.forms;
011:
012: import org.eclipse.jface.dialogs.IMessageProvider;
013: import org.eclipse.jface.fieldassist.ControlDecoration;
014: import org.eclipse.swt.widgets.Control;
015: import org.eclipse.ui.forms.widgets.Form;
016:
017: /**
018: * This interface provides for managing typed messages in a form. Typed messages
019: * are messages associated with a type that indicates their severity (error,
020: * warning, information). The interface is responsible for:
021: * <ul>
022: * <li>Bridging the concept of typed messages and control decorations</li>
023: * <li>Adding one or more messages per control in a form</li>
024: * <li>Rolling the local messages up to the form header</li>
025: * <li>Adding one or more general messages to the form header</li>
026: * </ul>
027: * <p>
028: * To use it in a form, do the following:
029: * <ol>
030: * <li>For each interactive control, add a listener to it to monitor user input</li>
031: * <li>Every time the input changes, validate it. If there is a problem, add a
032: * message with a unique key to the manager. If there is already a message with
033: * the same key in the manager, its type and message text will be replaced (no
034: * duplicates). Note that you add can messages with different keys to the same
035: * control to track multiple problems with the user input.</li>
036: * <li>If the problem has been cleared, remove the message using the key
037: * (attempting to remove a message that is not in the manager is safe).</li>
038: * <li>If something happens in the form that is not related to any control, use
039: * the other <code>addMessage</code> method.</li>
040: * </ol>
041: * <p>
042: * This interface should only be referenced. It must not be implemented or
043: * extended.
044: * </p>
045: *
046: * @since 3.3
047: * @see IMessageProvider
048: * @see IManagedForm
049: */
050:
051: public interface IMessageManager {
052: /**
053: * Adds a general message that is not associated with any decorated field.
054: * Note that subsequent calls using the same key will not result in
055: * duplicate messages. Instead, the previous message with the same key will
056: * be replaced with the new message.
057: *
058: * @param key
059: * a unique message key that will be used to look the message up
060: * later
061: *
062: * @param messageText
063: * the message to add
064: * @param data
065: * an object for application use (can be <code>null</code>)
066: * @param type
067: * the message type as defined in <code>IMessageProvider</code>.
068: */
069: void addMessage(Object key, String messageText, Object data,
070: int type);
071:
072: /**
073: * Adds a message that should be associated with the provided control. Note
074: * that subsequent calls using the same key will not result in duplicate
075: * messages. Instead, the previous message with the same key will be
076: * replaced with the new message.
077: *
078: * @param key
079: * the unique message key
080: * @param messageText
081: * the message to add
082: * @param data
083: * an object for application use (can be <code>null</code>)
084: * @param type
085: * the message type
086: * @param control
087: * the control to associate the message with
088: */
089: void addMessage(Object key, String messageText, Object data,
090: int type, Control control);
091:
092: /**
093: * Removes the general message with the provided key. Does nothing if
094: * message for the key does not exist.
095: *
096: * @param key
097: * the key of the message to remove
098: */
099: void removeMessage(Object key);
100:
101: /**
102: * Removes all the general messages. If there are local messages associated
103: * with controls, the replacement message may show up drawing user's
104: * attention to these local messages. Otherwise, the container will clear
105: * the message area.
106: */
107: void removeMessages();
108:
109: /**
110: * Removes a keyed message associated with the provided control. Does
111: * nothing if the message for that key does not exist.
112: *
113: * @param key
114: * the id of the message to remove
115: * @param control
116: * the control the message is associated with
117: */
118: void removeMessage(Object key, Control control);
119:
120: /**
121: * Removes all the messages associated with the provided control. Does
122: * nothing if there are no messages for this control.
123: *
124: * @param control
125: * the control the messages are associated with
126: */
127: void removeMessages(Control control);
128:
129: /**
130: * Removes all the local field messages and all the general container
131: * messages.
132: */
133: void removeAllMessages();
134:
135: /**
136: * Updates the message container with the messages currently in the manager.
137: * There are two scenarios in which a client may want to use this method:
138: * <ol>
139: * <li>When controls previously managed by this manager have been disposed.</li>
140: * <li>When automatic update has been turned off.</li>
141: * </ol>
142: * In all other situations, the manager will keep the form in sync
143: * automatically.
144: *
145: * @see #setAutoUpdate(boolean)
146: */
147: void update();
148:
149: /**
150: * Controls whether the form is automatically updated when messages are
151: * added or removed. By default, auto update is on. Clients can turn it off
152: * prior to adding or removing a number of messages as a batch. Turning it
153: * back on will trigger an update.
154: *
155: * @param enabled
156: * sets the state of the automatic update
157: */
158: void setAutoUpdate(boolean enabled);
159:
160: /**
161: * Tests whether the form will be automatically updated when messages are
162: * added or removed.
163: *
164: * @return <code>true</code> if auto update is active, <code>false</code>
165: * otherwise.
166: */
167: boolean isAutoUpdate();
168:
169: /**
170: * Sets the alternative message prefix provider. The default prefix provider
171: * is set by the manager.
172: *
173: * @param provider
174: * the new prefix provider or <code>null</code> to turn the
175: * prefix generation off.
176: */
177: void setMessagePrefixProvider(IMessagePrefixProvider provider);
178:
179: /**
180: * @return the current prefix provider or <code>null</code> if prefixes
181: * are not generated.
182: */
183: IMessagePrefixProvider getMessagePrefixProvider();
184:
185: /**
186: * Message manager uses SWT.LEFT|SWT.BOTTOM for the default decoration
187: * position. Use this method to change it.
188: *
189: * @param position
190: * the decoration position
191: * @see ControlDecoration
192: */
193: void setDecorationPosition(int position);
194:
195: /**
196: * Returns the currently used decoration position for all control messages.
197: *
198: * @return the current decoration position
199: */
200:
201: int getDecorationPosition();
202:
203: /**
204: * When message manager is used in context of a form, and there are
205: * hyperlink listeners for messages in the header, the hyperlink event will
206: * carry an object of type <code>IMessage[]</code> as an href. You can use
207: * this method to create a summary text from this array consistent with the
208: * tool tip used by the form header.
209: *
210: * @param messages
211: * an array of messages
212: * @return a textual representation of the messages with one message per
213: * line.
214: * @see Form#addMessageHyperlinkListener(org.eclipse.ui.forms.events.IHyperlinkListener)
215: */
216: String createSummary(IMessage[] messages);
217: }
|