com.smartgwt.client.widgets.notify

Class Notify

java.lang.Object

com.smartgwt.client.widgets.notify.Notify

public class Notify
extends java.lang.Object

Notify provides a means to display on-screen messages that are automatically dismissed after a configurable amount of time, as an alternative to modal notification dialogs that can lower end user productivity. Messages may be shown at a particular location, specified either with viewport-relative coordinates, or as an edge or center location relative to the viewport or a canvas. Messages can be configured to appear and disappear instantly, by sliding into (or out of) view, or by fading in (or out).

One or more actions can be provided when addMessage() is called to display a message. They will be rendered as links on which to click to execute the action.

The behavior and appearance of messages are configured per NotifyType, which is simply a string that identifies that message group, similar to log category. By calling configureMessages() with the NotifyType, it can be assigned a NotifySettings configuration to control message animation, placement, and the the Label used to render each message, allowing styling and autofit behavior to be configured.

Messages of the same NotifyType may be stacked to provide a visible history, with a configurable stacking direction and maximum stacking depth. Details on how to configure messages are provided in the documentation for NotifySettings.

Messages for different NotifyTypes are stacked separately and animated by independent Framework pipelines. It's up to you to configure the placement of supported NotifyTypes in your app so that they don't overlap, as the Framework doesn't manage it. For example, separate NotifyTypes could be assigned separate screen edges, or assigned a different NotifySettings.positionCanvas.

To dismiss a message manually before its scheduled duration expires, you may call dismissMessage() with a NotifyType (to dismiss all such messages) or an ID previously returned by addMessage() (to dismiss that single message).

Warnings and Errors

Each notification may be assigned a messagePriority in the settings passed to addMessage(). By default, all NotifyTypes are configured to have priority MESSAGE, except for "error" and "warn" NotifyTypes, which are configured with priority ERROR and WARN, respectively.

The messagePriority determines the default styling of a message, and which message to remove if a new message is sent while the message stack is already at its limit. We recommended applying a messagePriority as the best approach for showing pre-styled warnings and errors, since that allows you to interleave them with ordinary messages in a single NotifyType.

Alternatively, you can display pre-styled warnings and errors by calling addMessage() with the separate NotifyTypes "warning" and "error", respectively, but then you must take care to assign each NotifyType used to a separate screen location to avoid one rendering on top of the other.

Viewport Considerations

Messages are edge or corner-aligned based on the viewport width and viewport height of the current page rather than screen, so you may need to scroll to see the targeted corner or edge. Note that widgets placed offscreen below or to the right of a page may cause the browser to report a larger viewport, and prevent messages from being visible, even if no scrollbars are present. If you need to stage widgets offscreen for measurement or other reasons, place them above or to the left.

Modal Windows and Click Masks

Messages are always shown above all other widgets, including modal windows and click masks. This is because it's expected that messages are "out of band" and logically indepedent of the widget hierarchy being shown. We apply this layering policy even for windows and widgets created by NotifyActions. If there may a scenario where a message can block a window created by an action, set NotifySettings.canDismiss to true so that an unobstructed view of the underlying widgets can be restored.

In the linked sample, note how we take care to reuse the existing modal window, if any, if the "Launch..." link is clicked, so that repeated clicks never stack windows over each other.

See Also:

com.smartgwt.client.util.isc#say, com.smartgwt.client.util.isc#confirm

Field Summary

Fields

Modifier and Type	Field and Description
static int	ERROR Highest priority.
static int	MESSAGE Third-highest priority.
static int	WARN Second-highest priority.

Constructor Summary

Constructors

Constructor and Description
Notify()

Method Summary

Modifier and Type	Method and Description
static MessageID	addMessage(java.lang.String contents) Displays a new message, subject to the stored configuration for the passed notifyType, overridden by any passed settings.
static MessageID	addMessage(java.lang.String contents, NotifyAction... actions)
static MessageID	addMessage(java.lang.String contents, NotifyAction[] actions, java.lang.String notifyType)
static MessageID	addMessage(java.lang.String contents, NotifyAction[] actions, java.lang.String notifyType, NotifySettings settings) Displays a new message, subject to the stored configuration for the passed notifyType, overridden by any passed settings.
static boolean	canDismissMessage(MessageID messageID) Can the message corresponding to the messageID be dismissed? Returns false if the message is no longer being shown.
static void	configureDefaultSettings(NotifySettings settings) Changes the default settings that are applied when you create a new NotifyType with configureMessages().
static void	configureMessages(java.lang.String notifyType, NotifySettings settings) Sets the default NotifySettings for the specified NotifyType.
static void	dismissMessage(MessageID messageID) Dismisses one or more messages currently being shown, subject to the existing settings for their NotifyType.
static void	dismissMessage(java.lang.String messageID) Dismisses one or more messages currently being shown, subject to the existing settings for their NotifyType.
static boolean	messageHasActions(MessageID messageID)
static void	setMessageActions(MessageID messageID, NotifyAction... actions) Updates the actions of the message from those, if any, passed originally to addMessage(), while preserving any existing contents.
static void	setMessageContents(MessageID messageID, java.lang.String contents) Updates the contents of the message from what was passed originally to addMessage(), while preserving any existing actions.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ERROR

public static final int ERROR

Highest priority. Default priority of NotifyType: "error".

See Also:

Constant Field Values

WARN

public static final int WARN

Second-highest priority. Default priority of NotifyType: "warn".

See Also:

Constant Field Values

MESSAGE

public static final int MESSAGE

Third-highest priority. Default priority for all NotifyTypes other than "error" and "warn".

See Also:

Constant Field Values

Constructor Detail

Notify

public Notify()

Method Detail

addMessage

public static MessageID addMessage(java.lang.String contents)

Displays a new message, subject to the stored configuration for the passed notifyType, overridden by any passed settings. Returns an opaque MessageID that can be passed to dismissMessage() to clear it.

Note that an empty string may be passed for contents if actions have been provided, so you may have the message consist only of your specified actions.

Most users should do all configuration up front via a call to configureMessages(). The settings argument in this method is provided to allow adjustment of properties that affect only one message, such as autoFitWidth, styleName, or labelProperties. Making changes to stacking-related properties via this argument isn't supported, unless specifically documented on the property.

Parameters:

contents - message to be displayed. See HTMLString

Returns:

opaque identifier for message

See Also:

com.smartgwt.client.util.isc#say, com.smartgwt.client.util.isc#confirm, com.smartgwt.client.util.isc#notify, HTMLString

addMessage

public static MessageID addMessage(java.lang.String contents,
                                   NotifyAction... actions)

See Also:

addMessage(java.lang.String)

addMessage

public static MessageID addMessage(java.lang.String contents,
                                   NotifyAction[] actions,
                                   java.lang.String notifyType)

See Also:

addMessage(java.lang.String)

addMessage

public static MessageID addMessage(java.lang.String contents,
                                   NotifyAction[] actions,
                                   java.lang.String notifyType,
                                   NotifySettings settings)

Displays a new message, subject to the stored configuration for the passed notifyType, overridden by any passed settings. Returns an opaque MessageID that can be passed to dismissMessage() to clear it.

Note that an empty string may be passed for contents if actions have been provided, so you may have the message consist only of your specified actions.

Most users should do all configuration up front via a call to configureMessages(). The settings argument in this method is provided to allow adjustment of properties that affect only one message, such as autoFitWidth, styleName, or labelProperties. Making changes to stacking-related properties via this argument isn't supported, unless specifically documented on the property.

Parameters:

contents - message to be displayed. See HTMLString

actions - actions (if any) for this message

notifyType - category of message; default "message". See NotifyType

settings - display and behavior settings for this message that override the configured settings for the notifyType

Returns:

opaque identifier for message

See Also:

com.smartgwt.client.util.isc#say, com.smartgwt.client.util.isc#confirm, com.smartgwt.client.util.isc#notify

canDismissMessage

public static boolean canDismissMessage(MessageID messageID)

Can the message corresponding to the messageID be dismissed? Returns false if the message is no longer being shown. The messageID must have been previously returned by addMessage().

Parameters:

messageID - message identifier to dismiss

Returns:

whether message can be dismissed

See Also:

dismissMessage(com.smartgwt.client.widgets.notify.MessageID)

configureDefaultSettings

public static void configureDefaultSettings(NotifySettings settings)

Changes the default settings that are applied when you create a new NotifyType with configureMessages(). If you want to change the defaults for the built-in NotifyTypes "message", "warn", and "error", with this method, it must be called before the first call to configureMessages() or addMessage(). Once a NotifyType has been created, you must use configureMessages() to change its settings.

Note that for defaults that depend on priority (and thus differ between the built-in NotifyTypes), this method only sets the defaults for the "message" NotifyType.

Parameters:

settings - changes to NotifyType defaults

See Also:

configureMessages(java.lang.String, com.smartgwt.client.widgets.notify.NotifySettings)

configureMessages

public static void configureMessages(java.lang.String notifyType,
                                     NotifySettings settings)

Sets the default NotifySettings for the specified NotifyType. This may be overridden by passing settings to addMessage() when the message is shown, but changing stacking-related properties via addMessage() isn't supported,

By default, the NotifyTypes "message", "warn", and "error" are predefined, each with their own NotifySettings with different styleNames. When configuring a new (non-predefined) NotifyType with this method, any NotifySettings left unset will default to those for NotifyType "message".

Parameters:

notifyType - category of message; null defaults to "message". See NotifyType

settings - settings to store for the notifyType

See Also:

configureDefaultSettings(com.smartgwt.client.widgets.notify.NotifySettings)

dismissMessage

public static void dismissMessage(MessageID messageID)

Dismisses one or more messages currently being shown, subject to the existing settings for their NotifyType. You may either pass the opaque message identifier returned from the call to addMessage() to dismiss a single message, or a NotifyType to dismiss all such messages.

Parameters:

messageID - message identifier or category to dismiss

See Also:

NotifySettings.getDuration(), NotifyAction.getWholeMessage()

dismissMessage

public static void dismissMessage(java.lang.String messageID)

Dismisses one or more messages currently being shown, subject to the existing settings for their NotifyType. You may either pass the opaque message identifier returned from the call to addMessage() to dismiss a single message, or a NotifyType to dismiss all such messages.

Parameters:

messageID - message identifier or category to dismiss

See Also:

NotifySettings.getDuration(), NotifyAction.getWholeMessage(), NotifyType

messageHasActions

public static boolean messageHasActions(MessageID messageID)

Parameters:

messageID - message identifier to check

Returns:

whether message has any actions

See Also:

addMessage(java.lang.String), setMessageActions(com.smartgwt.client.widgets.notify.MessageID, com.smartgwt.client.widgets.notify.NotifyAction...)

setMessageActions

public static void setMessageActions(MessageID messageID,
                                     NotifyAction... actions)

Updates the actions of the message from those, if any, passed originally to addMessage(), while preserving any existing contents.

See setMessageContents() for further guidance and animation details.

Parameters:

messageID - message identifier from addMessage()

actions - updated actions for this message

setMessageContents

public static void setMessageContents(MessageID messageID,
                                      java.lang.String contents)

Updates the contents of the message from what was passed originally to addMessage(), while preserving any existing actions.

The purpose of this method is to support messages that contain timer countdowns or other data that perhaps need refreshing during display. If you find yourself replacing the entire content with something new, you should probably just add it as a new message.

Note that this method has minimal animation support. The change in message content and corresponding resizing are instant, but the repositioning of the message or stack (if stacked) to keep your requested alignment is controlled by NotifySettings.repositionMethod, allowing slide animation. However, that setting is ignored and the repositioning is instant if you've chosen viewport alignment to a border or corner along the bottom or right viewport edge, or if an animation is already in progress, in which case the instant repositioning will happen after it completes.

Parameters:

messageID - message identifier from addMessage()

contents - updated message. See HTMLString