tsc_Toast

The tsc_Toast class allows a notification (pop-up toast) to be displayed over any form, at a configurable position. A toast is a small popup window that appears  briefly to inform the user of something. It is usually set to timeout and disappear after a few seconds.

This is a stand-alone UI element, not necessarily related to any particular form.

Enumerations

tsc_ToastType represents the type of toast notification. The type determines the color of the toast, however burned is not supported.
The toast types defined here correspond to the toast types listed in standard Trimble UI design.

enum tsc_ToastType

{

    tsc_ToastTypeWhite,

    tsc_ToastTypeDark,

    tsc_ToastTypePrimary,

    tsc_ToastTypeSecondary,

    tsc_ToastTypeDanger,

    tsc_ToastTypeWarning,

    tsc_ToastTypeSuccess

};

tsc_Icon represents an optional icon to display on the left-hand side of a toast notification.

enum tsc_Icon

{

    tsc_IconNone,    ///< No icon

    tsc_IconInfo,    ///< An "i" in a circle

    tsc_IconTick,    ///< A checkmark

    tsc_IconWarning  ///< An exclamation mark in a triangle

};

tsc_AlignWidth specifies which user interface element the target item should be aligned with.

enum tsc_AlignWith

{

    tsc_AlignWithMainWindow,

    tsc_AlignWithCurrentForm,

    tsc_AlignWithCurrentField,

    tsc_AlignWithMapOrVideo,

    tsc_AlignWithLastButtonClicked,

    tsc_AlignWithLastMouseClick

};

tsc_XAlignment specifies how the target item should be aligned horizontally with respect to another item.

enum tsc_XAlignment

{

    tsc_XAlignLeft,        // Align the left side of the item relative to the left side of the other item, offset to the right by XOffset.

    tsc_XAlignCenter,      // Center the item horizontally relative to the other item; XOffset is ignored.

    tsc_XAlignRight,       // Align right side of the item relative to the right side of the other item, offset to the left by XOffset.

    tsc_XAlignBesideLeft,  // Place the item beside the other item, on the left, with a gap of XOffset.

    tsc_XAlignBesideRight  // Place the item beside the other item, on the right, with a gap of XOffset.

};

tsc_YAlignment specifies how the target item should be aligned vertically with respect to another item.

enum tsc_YAlignment

{

    tsc_YAlignTop,       // Align the top side of the item relative to the top side of the other item, offset below it by YOffset.

    tsc_YAlignCenter,    // Center the item vertically relative to the other item; YOffset is ignored.

    tsc_YAlignBottom,    // Align the bottom side of the item relative to the bottom side of the other item, offset above it by YOffset.

    tsc_YAlignAbove,     // Place the item above the other item, with a gap of YOffset.

    tsc_YAlignBelow      // Place the item below the other item, with a gap of YOffset.

};

struct tsc_RelativePosition

tsc_RelativePosition defines the position of a user interface element relative to another item.

struct tsc_RelativePosition

{

    tsc_XAlignment  XAlignment = tsc_XAlignLeft;

    tsc_YAlignment  YAlignment = tsc_YAlignTop;

    int             XOffset = 0;

    int             YOffset = 0;

};

class tsc_Toast

This class represents a "toast" notification message. 

Parameters specify the type of toast, the message text to display, and the duration in  seconds before the toast will automatically close. 

tsc_Toast (int toastId, tsc_ToastType toastType, const tsc_String& message, double duration);
Constructs an instance with the default icon and position, to remain displayed for duration seconds.
Passing a zero duration will cause the toast to be displayed indefinitely (until the user dismisses it). This is not recommended, as it is generally better for toasts to disappear automatically after a short time.
The toastId parameter can be any value the caller chooses to assign. A unique  positive integer is recommended, as it allows the calling code identify the originating toast in event handlers, such as when an action button is clicked, however, zero can be used if this is not a requirement.

void SetIcon(tsc_Icon icon);
Sets or changes the optional icon to be displayed at the left.

void SetPosition(tsc_AlignWith alignWith, const tsc_RelativePosition& relativePosition);
Changes the position to be relative to some other UI element.

void SetActionText(const char* actionText);
void SetActionText(x_Code actionText);
Sets the text for an optional action button that will be displayed on the right-hand side of the toast. If the user clicks the action button, the toast will close and the caller will be notified. The click notification can be handled in the OnToastClosed() event handler of the owning form. Only one of SetActionText() or SetActionImage() should be called.

void SetActionImage(const tsc_Image& actionImage);
Sets the icon for an optional action button that will be displayed on the right-hand side of the toast. If the user clicks the action button, the toast will close and the caller will be notified. The click notification can be handled in the OnToastClosed() event handler of the owning form. Only one of SetActionText() or SetActionImage() should be called.

void ShowCloseButton(bool show);
Determines whether a close button (X) will be shown at the right-hand end of the toast. By default, a close button is not shown. If the close button is shown, the user can click it to dismiss the toast. If no close button is shown, the user can click anywhere inside the toast to dismiss it.    

void Show();
Displays the toast with the previously set attributes, for the duration specified. The tsc_Toast instance may be destroyed after calling Show; the notification will still remain displayed for the supplied duration.

void Close();

Removes the toast if called before its duration has expired.

Example code

    tsc_RelativePosition relativePosition { tsc_XAlignCenter, tsc_YAlignBottom, 0, 20 };

    tsc_Toast toast { tsc_ToastTypePrimary, "Select and Measure two points to complete resection", 5.0 };

    toast.SetIcon(tsc_IconInfo);

    toast.SetPosition(tsc_AlignWithMapOrVideo, relativePosition);

    toast.Show();