| /******************************************************************************* |
| * Copyright (c) 2007 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| ******************************************************************************/ |
| |
| package org.eclipse.ui.forms; |
| |
| import org.eclipse.jface.dialogs.IMessageProvider; |
| import org.eclipse.jface.fieldassist.ControlDecoration; |
| import org.eclipse.swt.widgets.Control; |
| import org.eclipse.ui.forms.widgets.Form; |
| |
| /** |
| * This interface provides for managing typed messages in a form. Typed messages |
| * are messages associated with a type that indicates their severity (error, |
| * warning, information). The interface is responsible for: |
| * <ul> |
| * <li>Bridging the concept of typed messages and control decorations</li> |
| * <li>Adding one or more messages per control in a form</li> |
| * <li>Rolling the local messages up to the form header</li> |
| * <li>Adding one or more general messages to the form header</li> |
| * </ul> |
| * <p> |
| * To use it in a form, do the following: |
| * <ol> |
| * <li>For each interactive control, add a listener to it to monitor user input</li> |
| * <li>Every time the input changes, validate it. If there is a problem, add a |
| * message with a unique key to the manager. If there is already a message with |
| * the same key in the manager, its type and message text will be replaced (no |
| * duplicates). Note that you add can messages with different keys to the same |
| * control to track multiple problems with the user input.</li> |
| * <li>If the problem has been cleared, remove the message using the key |
| * (attempting to remove a message that is not in the manager is safe).</li> |
| * <li>If something happens in the form that is not related to any control, use |
| * the other <code>addMessage</code> method.</li> |
| * </ol> |
| * <p> |
| * This interface should only be referenced. It must not be implemented or |
| * extended. |
| * </p> |
| * |
| * @since 3.3 |
| * @see IMessageProvider |
| * @see IManagedForm |
| * @noimplement This interface is not intended to be implemented by clients. |
| * @noextend This interface is not intended to be extended by clients. |
| */ |
| |
| public interface IMessageManager { |
| /** |
| * Adds a general message that is not associated with any decorated field. |
| * Note that subsequent calls using the same key will not result in |
| * duplicate messages. Instead, the previous message with the same key will |
| * be replaced with the new message. |
| * |
| * @param key |
| * a unique message key that will be used to look the message up |
| * later |
| * |
| * @param messageText |
| * the message to add |
| * @param data |
| * an object for application use (can be <code>null</code>) |
| * @param type |
| * the message type as defined in <code>IMessageProvider</code>. |
| */ |
| void addMessage(Object key, String messageText, Object data, int type); |
| |
| /** |
| * Adds a message that should be associated with the provided control. Note |
| * that subsequent calls using the same key will not result in duplicate |
| * messages. Instead, the previous message with the same key will be |
| * replaced with the new message. |
| * |
| * @param key |
| * the unique message key |
| * @param messageText |
| * the message to add |
| * @param data |
| * an object for application use (can be <code>null</code>) |
| * @param type |
| * the message type |
| * @param control |
| * the control to associate the message with |
| */ |
| void addMessage(Object key, String messageText, Object data, int type, |
| Control control); |
| |
| /** |
| * Removes the general message with the provided key. Does nothing if |
| * message for the key does not exist. |
| * |
| * @param key |
| * the key of the message to remove |
| */ |
| void removeMessage(Object key); |
| |
| /** |
| * Removes all the general messages. If there are local messages associated |
| * with controls, the replacement message may show up drawing user's |
| * attention to these local messages. Otherwise, the container will clear |
| * the message area. |
| */ |
| void removeMessages(); |
| |
| /** |
| * Removes a keyed message associated with the provided control. Does |
| * nothing if the message for that key does not exist. |
| * |
| * @param key |
| * the id of the message to remove |
| * @param control |
| * the control the message is associated with |
| */ |
| void removeMessage(Object key, Control control); |
| |
| /** |
| * Removes all the messages associated with the provided control. Does |
| * nothing if there are no messages for this control. |
| * |
| * @param control |
| * the control the messages are associated with |
| */ |
| void removeMessages(Control control); |
| |
| /** |
| * Removes all the local field messages and all the general container |
| * messages. |
| */ |
| void removeAllMessages(); |
| |
| /** |
| * Updates the message container with the messages currently in the manager. |
| * There are two scenarios in which a client may want to use this method: |
| * <ol> |
| * <li>When controls previously managed by this manager have been disposed.</li> |
| * <li>When automatic update has been turned off.</li> |
| * </ol> |
| * In all other situations, the manager will keep the form in sync |
| * automatically. |
| * |
| * @see #setAutoUpdate(boolean) |
| */ |
| void update(); |
| |
| /** |
| * Controls whether the form is automatically updated when messages are |
| * added or removed. By default, auto update is on. Clients can turn it off |
| * prior to adding or removing a number of messages as a batch. Turning it |
| * back on will trigger an update. |
| * |
| * @param enabled |
| * sets the state of the automatic update |
| */ |
| void setAutoUpdate(boolean enabled); |
| |
| /** |
| * Tests whether the form will be automatically updated when messages are |
| * added or removed. |
| * |
| * @return <code>true</code> if auto update is active, <code>false</code> |
| * otherwise. |
| */ |
| boolean isAutoUpdate(); |
| |
| /** |
| * Sets the alternative message prefix provider. The default prefix provider |
| * is set by the manager. |
| * |
| * @param provider |
| * the new prefix provider or <code>null</code> to turn the |
| * prefix generation off. |
| */ |
| void setMessagePrefixProvider(IMessagePrefixProvider provider); |
| |
| /** |
| * @return the current prefix provider or <code>null</code> if prefixes |
| * are not generated. |
| */ |
| IMessagePrefixProvider getMessagePrefixProvider(); |
| |
| /** |
| * Message manager uses SWT.LEFT|SWT.BOTTOM for the default decoration |
| * position. Use this method to change it. |
| * |
| * @param position |
| * the decoration position |
| * @see ControlDecoration |
| */ |
| void setDecorationPosition(int position); |
| |
| /** |
| * Returns the currently used decoration position for all control messages. |
| * |
| * @return the current decoration position |
| */ |
| |
| int getDecorationPosition(); |
| |
| /** |
| * When message manager is used in context of a form, and there are |
| * hyperlink listeners for messages in the header, the hyperlink event will |
| * carry an object of type <code>IMessage[]</code> as an href. You can use |
| * this method to create a summary text from this array consistent with the |
| * tool tip used by the form header. |
| * |
| * @param messages |
| * an array of messages |
| * @return a textual representation of the messages with one message per |
| * line. |
| * @see Form#addMessageHyperlinkListener(org.eclipse.ui.forms.events.IHyperlinkListener) |
| */ |
| String createSummary(IMessage[] messages); |
| } |