Class Notify
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#saycom.smartgwt.client.util.isc#confirm
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic MessageIDaddMessage(String contents) Displays a new message, subject to thestored configurationfor the passednotifyType, overridden by any passedsettings.static MessageIDaddMessage(String contents, NotifyAction... actions) static MessageIDaddMessage(String contents, NotifyAction[] actions, String notifyType) static MessageIDaddMessage(String contents, NotifyAction[] actions, String notifyType, NotifySettings settings) Displays a new message, subject to thestored configurationfor the passednotifyType, overridden by any passedsettings.static booleancanDismissMessage(MessageID messageID) Can the message corresponding to themessageIDbe dismissed? Returns false if the message is no longer being shown.static voidconfigureDefaultSettings(NotifySettings settings) Changes the default settings that are applied when you create a newNotifyTypewithconfigureMessages().static voidconfigureMessages(String notifyType, NotifySettings settings) Sets the defaultNotifySettingsfor the specifiedNotifyType.static voiddismissMessage(MessageID messageID) Dismisses one or more messages currently being shown, subject to the existing settings for theirNotifyType.static voiddismissMessage(String messageID) Dismisses one or more messages currently being shown, subject to the existing settings for theirNotifyType.static booleanmessageHasActions(MessageID messageID) static voidsetMessageActions(MessageID messageID, NotifyAction... actions) Updates the actions of the message from those, if any, passed originally toaddMessage(), while preserving any existingcontents.static voidsetMessageContents(MessageID messageID, String contents) Updates the contents of the message from what was passed originally toaddMessage(), while preserving any existingactions.
-
Field Details
-
ERROR
public static final int ERRORHighest priority. Default priority ofNotifyType: "error".- See Also:
-
WARN
public static final int WARNSecond-highest priority. Default priority ofNotifyType: "warn".- See Also:
-
MESSAGE
public static final int MESSAGEThird-highest priority. Default priority for allNotifyTypes other than "error" and "warn".- See Also:
-
-
Constructor Details
-
Notify
public Notify()
-
-
Method Details
-
addMessage
Displays a new message, subject to thestored configurationfor the passednotifyType, overridden by any passedsettings. Returns an opaqueMessageIDthat can be passed todismissMessage()to clear it.Note that an empty string may be passed for
contentsifactionshave 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(). Thesettingsargument in this method is provided to allow adjustment of properties that affect only one message, such asautoFitWidth,styleName, orlabelProperties. Making changes tostacking-related properties via this argument isn't supported, unless specifically documented on the property.- Parameters:
contents- message to be displayed. SeeHTMLString- Returns:
- opaque identifier for message
- See Also:
-
com.smartgwt.client.util.isc#saycom.smartgwt.client.util.isc#confirmcom.smartgwt.client.util.isc#notifyHTMLString
-
addMessage
- See Also:
-
addMessage
- See Also:
-
addMessage
public static MessageID addMessage(String contents, NotifyAction[] actions, String notifyType, NotifySettings settings) Displays a new message, subject to thestored configurationfor the passednotifyType, overridden by any passedsettings. Returns an opaqueMessageIDthat can be passed todismissMessage()to clear it.Note that an empty string may be passed for
contentsifactionshave 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(). Thesettingsargument in this method is provided to allow adjustment of properties that affect only one message, such asautoFitWidth,styleName, orlabelProperties. Making changes tostacking-related properties via this argument isn't supported, unless specifically documented on the property.- Parameters:
contents- message to be displayed. SeeHTMLStringactions- actions (if any) for this messagenotifyType- category of message; default "message". SeeNotifyTypesettings- display and behavior settings for this message that override theconfiguredsettings for thenotifyType- Returns:
- opaque identifier for message
- See Also:
-
com.smartgwt.client.util.isc#saycom.smartgwt.client.util.isc#confirmcom.smartgwt.client.util.isc#notify
-
canDismissMessage
Can the message corresponding to themessageIDbe dismissed? Returns false if the message is no longer being shown. ThemessageIDmust have been previously returned byaddMessage().- Parameters:
messageID- message identifier to dismiss- Returns:
- whether message can be dismissed
- See Also:
-
configureDefaultSettings
Changes the default settings that are applied when you create a newNotifyTypewithconfigureMessages(). 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 toconfigureMessages()oraddMessage(). Once a NotifyType has been created, you must useconfigureMessages()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
Sets the defaultNotifySettingsfor the specifiedNotifyType. This may be overridden by passing settings toaddMessage()when the message is shown, but changingstacking-related properties viaaddMessage()isn't supported,By default, the
NotifyTypes "message", "warn", and "error" are predefined, each with their ownNotifySettingswith differentstyleNames. When configuring a new (non-predefined) NotifyType with this method, anyNotifySettingsleft unset will default to those for NotifyType "message".- Parameters:
notifyType- category of message; null defaults to "message". SeeNotifyTypesettings- settings to store for thenotifyType- See Also:
-
dismissMessage
Dismisses one or more messages currently being shown, subject to the existing settings for theirNotifyType. You may either pass the opaque message identifier returned from the call toaddMessage()to dismiss a single message, or aNotifyTypeto dismiss all such messages.- Parameters:
messageID- message identifier or category to dismiss- See Also:
-
dismissMessage
Dismisses one or more messages currently being shown, subject to the existing settings for theirNotifyType. You may either pass the opaque message identifier returned from the call toaddMessage()to dismiss a single message, or aNotifyTypeto dismiss all such messages.- Parameters:
messageID- message identifier or category to dismiss- See Also:
-
messageHasActions
- Parameters:
messageID- message identifier to check- Returns:
- whether message has any actions
- See Also:
-
setMessageActions
Updates the actions of the message from those, if any, passed originally toaddMessage(), while preserving any existingcontents.See
setMessageContents()for further guidance and animation details.- Parameters:
messageID- message identifier fromaddMessage()actions- updated actions for this message
-
setMessageContents
Updates the contents of the message from what was passed originally toaddMessage(), while preserving any existingactions.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
alignmentis controlled byNotifySettings.repositionMethod, allowing slide animation. However, that setting is ignored and the repositioning is instant if you've chosenviewport alignmentto a border or corner along thebottom or rightviewport edge, or if an animation is already in progress, in which case the instant repositioning will happen after it completes.- Parameters:
messageID- message identifier fromaddMessage()contents- updated message. SeeHTMLString
-