# Class ToastBar

java.lang.Object
com.codename1.components.ToastBar

public final class ToastBar extends Object

An API to present status messages to the user in an unobtrusive manner. This is useful if there are background tasks that need to display information to the user. E.g. If a network request fails, of let the user know that "Jobs are being synchronized".

Example Usage

    Form hi = new Form("ToastBarDemo", BoxLayout.y());

    Button basic = new Button("Basic");
    Button progress = new Button("Progress");
    Button expires = new Button("Expires");
    Button delayed = new Button("Delayed");
    hi.add(basic).add(progress).add(expires).add(delayed);

    basic.addActionListener(e -> {
      ToastBar.Status status = ToastBar.getInstance().createStatus();
      status.setMessage("Hello world");
      status.show();
      //...  Some time later you must clear the status
      // status.clear();
    });

    progress.addActionListener(e -> {
      ToastBar.Status status = ToastBar.getInstance().createStatus();
      status.setMessage("Hello world");
      status.setShowProgressIndicator(true);
      status.show();
      // ... Some time later you must clear it
    });

    expires.addActionListener(e -> {
      ToastBar.Status status = ToastBar.getInstance().createStatus();
      status.setMessage("Hello world");
      status.setExpires(3000);  // only show the status for 3 seconds, then have it automatically clear
      status.show();
    });

    delayed.addActionListener(e -> {
      ToastBar.Status status = ToastBar.getInstance().createStatus();
      status.setMessage("Hello world");
      status.showDelayed(300); // Wait 300 ms to show the status
      // ... Some time later, clear the status... this may be before it shows at all
    });

    hi.show();

Advanced Usage

See the StatusBarDemo

Screenshots

Status With Progress Bar

Status With Multi-Line Message

Video Demo

Note: the video above refers to the `ToastBar` based on its development name of StatusBar. This was changed to avoid confusion with the iOS StatusBar.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `class`
  `ToastBar.Status`
  Represents a single status message.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ToastBar.Status`
  `createStatus()`
  Creates a new Status.
  `static int`
  `getDefaultMessageTimeout()`
  The default timeout for info/error messages
  `String`
  `getDefaultMessageUIID()`
  Gets the default UIID to be used for the style of the `ToastBar` text.
  `String`
  `getDefaultUIID()`
  Gets the default UIID to be used for the style of the `ToastBar` component.
  `static ToastBar`
  `getForTopLevel(TopLevelContainer top)`
  The toast bar for a given top level.
  `static ToastBar`
  `getInstance()`
  Gets reference to the singleton StatusBar instance
  `int`
  `getPosition()`
  Gets the position of the toast bar on the screen.
  `static void`
  `setDefaultMessageTimeout(int aDefaultMessageTimeout)`
  The default timeout for info/error messages
  `void`
  `setDefaultMessageUIID(String defaultMessageUIID)`
  Sets the default UIID to be used for the style of the `ToastBar` text.
  `void`
  `setDefaultUIID(String defaultUIID)`
  Sets the defaults UIID to be used for the style of the `ToastBar` component.
  `void`
  `setPosition(int position)`
  Sets the position of the toast bar on the screen.
  `void`
  `setVisible(boolean visible)`
  Shows or hides the `ToastBar`.
  `static void`
  `showConnectionProgress(String message, ConnectionRequest cr, SuccessCallback<NetworkEvent> onSuccess, FailureCallback<NetworkEvent> onError)`
  `static void`
  `showErrorMessage(String msg)`
  Simplifies a common use case of showing an error message with an error icon that fades out after a few seconds
  `static ToastBar.Status`
  `showErrorMessage(String msg, int timeout)`
  Simplifies a common use case of showing an error message with an error icon that fades out after a few seconds
  `static ToastBar.Status`
  `showInfoMessage(String msg)`
  Simplifies a common use case of showing an information message with an info icon that fades out after a few seconds
  `static ToastBar.Status`
  `showMessage(String msg, char icon)`
  Simplifies a common use case of showing an error message with an error icon that fades out after a few seconds
  `static ToastBar.Status`
  `showMessage(String msg, char icon, int timeout)`
  Simplifies a common use case of showing a message with an icon that fades out after a few seconds
  `static ToastBar.Status`
  `showMessage(String msg, char icon, int timeout, ActionListener listener)`
  Simplifies a common use case of showing a message with an icon that fades out after a few seconds
  `static ToastBar.Status`
  `showMessage(String msg, char icon, ActionListener listener)`
  Simplifies a common use case of showing an error message with an error icon that fades out after a few seconds
  `ToastBar`
  `useFormLayeredPane(boolean useFormLayeredPane)`
  By default the ToastBar uses the LayeredPane.

  ### Methods inherited from class Object

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

- ## Method Details

  - ### getDefaultMessageTimeout

    public static int getDefaultMessageTimeout()

    The default timeout for info/error messages

    ###### Returns

    the defaultMessageTimeout

  - ### setDefaultMessageTimeout

    public static void setDefaultMessageTimeout(int aDefaultMessageTimeout)

    The default timeout for info/error messages

    ###### Parameters

    - `aDefaultMessageTimeout`: the defaultMessageTimeout to set

  - ### getInstance

    public static ToastBar getInstance()

    Gets reference to the singleton StatusBar instance

    The singleton shows on whichever `com.codename1.ui.Form` is current, including while a desktop window has the focus. To toast on a window use `#getForTopLevel(com.codename1.ui.TopLevelContainer)`, which is what the static helpers on this class do.

  - ### getForTopLevel

    public static ToastBar getForTopLevel(TopLevelContainer top)

    The toast bar for a given top level.

    The singleton follows whichever `Form` is current, which is the behaviour every existing application relies on, so a `Form` or null still gets it. A `com.codename1.ui.Window` gets its own instance instead, cached on the window and dying with it -- a settable host on the singleton would have meant one window silently redirecting another surface's toasts.

    ###### Parameters

    - `top`: the top level to show on, may be null

    ###### Returns

    the toast bar for that top level, never null

  - ### showErrorMessage

    public static void showErrorMessage(String msg)

    Simplifies a common use case of showing an error message with an error icon that fades out after a few seconds

    ###### Parameters

    - `msg`: the error message

  - ### showMessage

    public static ToastBar.Status showMessage(String msg, char icon, int timeout, ActionListener listener)

    Simplifies a common use case of showing a message with an icon that fades out after a few seconds

    ###### Parameters

    - `msg`: the message

    - `icon`: the material icon to show from `com.codename1.ui.FontImage`

    - `timeout`: the timeout value in milliseconds

    - `listener`: the action to perform when the ToastBar is tapped

    ###### Returns

    the status if we want to clear it before timeout elapses

  - ### showMessage

    public static ToastBar.Status showMessage(String msg, char icon, int timeout)

    Simplifies a common use case of showing a message with an icon that fades out after a few seconds

    ###### Parameters

    - `msg`: the message

    - `icon`: the material icon to show from `com.codename1.ui.FontImage`

    - `timeout`: the timeout value in milliseconds

    ###### Returns

    the status if we want to clear it before timeout elapses

  - ### showMessage

    public static ToastBar.Status showMessage(String msg, char icon, ActionListener listener)

    Simplifies a common use case of showing an error message with an error icon that fades out after a few seconds

    ###### Parameters

    - `msg`: the message

    - `icon`: the material icon to show from `com.codename1.ui.FontImage`

    - `listener`: the action to perform when the ToastBar is tapped

    ###### Returns

    the status if we want to clear it before timeout elapses

  - ### showMessage

    public static ToastBar.Status showMessage(String msg, char icon)

    Simplifies a common use case of showing an error message with an error icon that fades out after a few seconds

    ###### Parameters

    - `icon`: the material icon to show from `com.codename1.ui.FontImage`

    - `msg`: the message

    ###### Returns

    the status if we want to clear it before timeout elapses

  - ### showInfoMessage

    public static ToastBar.Status showInfoMessage(String msg)

    Simplifies a common use case of showing an information message with an info icon that fades out after a few seconds

    ###### Parameters

    - `msg`: the message

    ###### Returns

    the status if we want to clear it before timeout elapses

  - ### showErrorMessage

    public static ToastBar.Status showErrorMessage(String msg, int timeout)

    Simplifies a common use case of showing an error message with an error icon that fades out after a few seconds

    ###### Parameters

    - `msg`: the error message

    - `timeout`: the timeout value in milliseconds

    ###### Returns

    the status if we want to clear it before timeout elapses

  - ### showConnectionProgress

    public static void showConnectionProgress(String message, ConnectionRequest cr, SuccessCallback<NetworkEvent> onSuccess, FailureCallback<NetworkEvent> onError)

  - ### getDefaultUIID

    public String getDefaultUIID()

    Gets the default UIID to be used for the style of the `ToastBar` component. By default this is "ToastBarComponent".

    ###### Returns

    the defaultUIID

  - ### setDefaultUIID

    public void setDefaultUIID(String defaultUIID)

    Sets the defaults UIID to be used for the style of the `ToastBar` component. By default this is "ToastBarComponent"

    ###### Parameters

    - `defaultUIID`: the defaultUIID to set

  - ### getDefaultMessageUIID

    public String getDefaultMessageUIID()

    Gets the default UIID to be used for the style of the `ToastBar` text. By default this is "ToastBarMessage"

    ###### Returns

    the defaultMessageUIID

  - ### setDefaultMessageUIID

    public void setDefaultMessageUIID(String defaultMessageUIID)

    Sets the default UIID to be used for the style of the `ToastBar` text. By default this is "ToastBarMessage"

    ###### Parameters

    - `defaultMessageUIID`: the defaultMessageUIID to set

  - ### useFormLayeredPane

    public ToastBar useFormLayeredPane(boolean useFormLayeredPane)

    By default the ToastBar uses the LayeredPane. However, it may be better in many cases to use the FormLayerd pane. This allows you to toggle whether to use the FormLayeredPane.

    Key use-case is for displaying the ToastBar over a Sheet, which is on the FormLayeredPane. If you don't set this to true, then the ToastBar will be displayed behind the Sheet.

    ###### Parameters

    - `useFormLayeredPane`: True to use the form layered pane to display the toastbar.

    ###### Returns

    Self for chaining.

  - ### getPosition

    public int getPosition()

    Gets the position of the toast bar on the screen. Either `Component#TOP` or `Component#BOTTOM`.

    ###### Returns

    the position

  - ### setPosition

    public void setPosition(int position)

    Sets the position of the toast bar on the screen.

    ###### Parameters

    - `position`: the position to set Should be one of `Component#TOP` and `Component#BOTTOM`

  - ### createStatus

    public ToastBar.Status createStatus()
    Creates a new Status.

  - ### setVisible

    public void setVisible(boolean visible)

    Shows or hides the `ToastBar`.

    ###### Parameters

    - `visible`