public final class ToastBar

Object
ToastBar

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 types

class ToastBar.Status Represents a single status message.

Methods

`public static int getDefaultMessageTimeout()`	The default timeout for info/error messages
`public static void setDefaultMessageTimeout(int aDefaultMessageTimeout)`	The default timeout for info/error messages
`public static` `ToastBar getInstance()`	Gets reference to the singleton StatusBar instance
`public static` `ToastBar getForTopLevel(TopLevelContainer top)`	The toast bar for a given top level.
`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
`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
`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
`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
`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
`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
`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
`public static void showConnectionProgress(String message, ConnectionRequest cr, SuccessCallback<NetworkEvent> onSuccess, FailureCallback<NetworkEvent> onError)`
`public` `String getDefaultUIID()`	Gets the default UIID to be used for the style of the `ToastBar` component.
`public void setDefaultUIID(String defaultUIID)`	Sets the defaults UIID to be used for the style of the `ToastBar` component.
`public` `String getDefaultMessageUIID()`	Gets the default UIID to be used for the style of the `ToastBar` text.
`public void setDefaultMessageUIID(String defaultMessageUIID)`	Sets the default UIID to be used for the style of the `ToastBar` text.
`public` `ToastBar useFormLayeredPane(boolean useFormLayeredPane)`	By default the ToastBar uses the LayeredPane.
`public int getPosition()`	Gets the position of the toast bar on the screen.
`public void setPosition(int position)`	Sets the position of the toast bar on the screen.
`public` `ToastBar.Status createStatus()`	Creates a new Status.
`public void setVisible(boolean visible)`	Shows or hides the `ToastBar`.

Inherited methods

From Object

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

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 int: 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 TopLevelContainer: 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 String: 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 String: the message
icon char: the material icon to show from com.codename1.ui.FontImage
timeout int: the timeout value in milliseconds
listener ActionListener: 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 String: the message
icon char: the material icon to show from com.codename1.ui.FontImage
timeout int: 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 String: the message
icon char: the material icon to show from com.codename1.ui.FontImage
listener ActionListener: 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

msg String: the message
icon char: the material icon to show from com.codename1.ui.FontImage

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 String: 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 String: the error message
timeout int: 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 String: 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 String: 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 boolean: 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 int: 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.