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:
- Bridging the concept of typed messages and control decorations
- Adding one or more messages per control in a form
- Rolling the local messages up to the form header
- Adding one or more general messages to the form header
To use it in a form, do the following:
- For each interactive control, add a listener to it to monitor user input
- 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.
- 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).
- 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
-
Restriction:
- This interface is not intended to be implemented by clients.
-
Restriction:
- This interface is not intended to be extended by clients.
|
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. |
addMessage
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
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
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
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
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
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
void removeAllMessages()
- Removes all the local field messages and all the general container
messages.
-
update
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:
- When controls previously managed by this manager have been disposed.
- 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
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
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
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
IMessagePrefixProvider getMessagePrefixProvider()
-
-
Returns:
- the current prefix provider or
null if prefixes
are not generated.
setDecorationPosition
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
int getDecorationPosition()
- Returns the currently used decoration position for all control messages.
-
-
Returns:
- the current decoration position
createSummary
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)
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.
