Package com.smartgwt.client.widgets.notify

# Class Notify

java.lang.Object
com.smartgwt.client.widgets.notify.Notify

public class Notify extends 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 `NotifyType`s are stacked separately and animated by independent Framework pipelines. It's up to you to configure the placement of supported `NotifyType`s in your app so that they don't overlap, as the Framework doesn't manage it. For example, separate `NotifyType`s 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 `NotifyType`s are configured to have priority `MESSAGE`, except for "error" and "warn" `NotifyType`s, 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 `NotifyType`s "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 `NotifyAction`s. 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
  Description
  `static final int`
  `ERROR`
  Highest priority.
  `static final int`
  `MESSAGE`
  Third-highest priority.
  `static final int`
  `WARN`
  Second-highest priority.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Notify()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static MessageID`
  `addMessage(String contents)`
  Displays a new message, subject to the `stored configuration` for the passed `notifyType`, overridden by any passed `settings`.
  `static MessageID`
  `addMessage(String contents, NotifyAction... actions)`
  See `addMessage()`
  `static MessageID`
  `addMessage(String contents, NotifyAction[] actions, String notifyType)`
  See `addMessage()`
  `static MessageID`
  `addMessage(String contents, NotifyAction[] actions, 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(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(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, 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 Details

  - ### 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 `NotifyType`s other than "error" and "warn".
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### Notify

    public Notify()

- ## Method Details

  - ### addMessage

    public static MessageID addMessage(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(String contents, NotifyAction... actions)
    See `addMessage()`

  - ### addMessage

    public static MessageID addMessage(String contents, NotifyAction[] actions, String notifyType)
    See `addMessage()`

  - ### addMessage

    public static MessageID addMessage(String contents, NotifyAction[] actions, 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(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 `NotifyType`s "message", "warn", and "error" are predefined, each with their own `NotifySettings` with different `styleName`s. 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(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, 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`