Eclipse Platform
Release 3.3

org.eclipse.ui.forms
Interface IMessageManager


public interface IMessageManager

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:

To use it in a form, do the following:

  1. For each interactive control, add a listener to it to monitor user input
  2. 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.
  3. 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).
  4. If something happens in the form that is not related to any control, use the other addMessage method.

This interface should only be referenced. It must not be implemented or extended.

Since:
3.3
See Also:
IMessageProvider, IManagedForm

Method Summary
 void addMessage(Object key, String messageText, Object data, int type)
          Adds a general message that is not associated with any decorated field.
 void addMessage(Object key, String messageText, Object data, int type, Control control)
          Adds a message that should be associated with the provided control.
 String createSummary(IMessage[] messages)
          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 IMessage[] as an href.
 int getDecorationPosition()
          Returns the currently used decoration position for all control messages.
 IMessagePrefixProvider getMessagePrefixProvider()
           
 boolean isAutoUpdate()
          Tests whether the form will be automatically updated when messages are added or removed.
 void removeAllMessages()
          Removes all the local field messages and all the general container messages.
 void removeMessage(Object key)
          Removes the general message with the provided key.
 void removeMessage(Object key, Control control)
          Removes a keyed message associated with the provided control.
 void removeMessages()
          Removes all the general messages.
 void removeMessages(Control control)
          Removes all the messages associated with the provided control.
 void setAutoUpdate(boolean enabled)
          Controls whether the form is automatically updated when messages are added or removed.
 void setDecorationPosition(int position)
          Message manager uses SWT.LEFT|SWT.BOTTOM for the default decoration position.
 void setMessagePrefixProvider(IMessagePrefixProvider provider)
          Sets the alternative message prefix provider.
 void update()
          Updates the message container with the messages currently in the manager.
 

Method Detail

addMessage

public void addMessage(Object key,
                       String messageText,
                       Object data,
                       int type)
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.

Parameters:
key - a unique message key that will be used to look the message up later
messageText - the message to add
data - an object for application use (can be null)
type - the message type as defined in IMessageProvider.

addMessage

public void addMessage(Object key,
                       String messageText,
                       Object data,
                       int type,
                       Control control)
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.

Parameters:
key - the unique message key
messageText - the message to add
data - an object for application use (can be null)
type - the message type
control - the control to associate the message with

removeMessage

public void removeMessage(Object key)
Removes the general message with the provided key. Does nothing if message for the key does not exist.

Parameters:
key - the key of the message to remove

removeMessages

public void removeMessages()
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.


removeMessage

public void removeMessage(Object key,
                          Control control)
Removes a keyed message associated with the provided control. Does nothing if the message for that key does not exist.

Parameters:
key - the id of the message to remove
control - the control the message is associated with

removeMessages

public void removeMessages(Control control)
Removes all the messages associated with the provided control. Does nothing if there are no messages for this control.

Parameters:
control - the control the messages are associated with

removeAllMessages

public void removeAllMessages()
Removes all the local field messages and all the general container messages.


update

public void update()
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:
  1. When controls previously managed by this manager have been disposed.
  2. When automatic update has been turned off.
In all other situations, the manager will keep the form in sync automatically.

See Also:
setAutoUpdate(boolean)

setAutoUpdate

public void setAutoUpdate(boolean enabled)
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.

Parameters:
enabled - sets the state of the automatic update

isAutoUpdate

public boolean isAutoUpdate()
Tests whether the form will be automatically updated when messages are added or removed.

Returns:
true if auto update is active, false otherwise.

setMessagePrefixProvider

public void setMessagePrefixProvider(IMessagePrefixProvider provider)
Sets the alternative message prefix provider. The default prefix provider is set by the manager.

Parameters:
provider - the new prefix provider or null to turn the prefix generation off.

getMessagePrefixProvider

public IMessagePrefixProvider getMessagePrefixProvider()
Returns:
the current prefix provider or null if prefixes are not generated.

setDecorationPosition

public void setDecorationPosition(int position)
Message manager uses SWT.LEFT|SWT.BOTTOM for the default decoration position. Use this method to change it.

Parameters:
position - the decoration position
See Also:
ControlDecoration

getDecorationPosition

public int getDecorationPosition()
Returns the currently used decoration position for all control messages.

Returns:
the current decoration position

createSummary

public String createSummary(IMessage[] messages)
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 IMessage[] 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.

Parameters:
messages - an array of messages
Returns:
a textual representation of the messages with one message per line.
See Also:
Form.addMessageHyperlinkListener(org.eclipse.ui.forms.events.IHyperlinkListener)

Eclipse Platform
Release 3.3

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2007. All rights reserved.