showToast
Overview
showToast:options: displays a lightweight Toast message to the user.
Toast is typically used to display operation results, status prompts, or short text notifications, such as "Operation succeeded" or "Loading failed". The caller can use SUDOPShowToastOptions to configure the prompt text, icon, display duration, and whether to show a transparent mask layer.
Constant Definition
objectivec
static NSString * const kSUDOPShowToastOptionsIconTypeSuccess = @"success";
static NSString * const kSUDOPShowToastOptionsIconTypeFail = @"fail";
static NSString * const kSUDOPShowToastOptionsIconTypeLoading = @"loading";Icon Types
| Constant | Value | Description |
|---|---|---|
kSUDOPShowToastOptionsIconTypeSuccess | success | Success icon. |
kSUDOPShowToastOptionsIconTypeFail | fail | Failure icon. |
kSUDOPShowToastOptionsIconTypeLoading | loading | Loading icon. |
Type Declaration
objectivec
/**
Options for configuring toast message display behavior.
*/
@interface SUDOPShowToastOptions : NSObject
/**
The text content of the toast message.
*/
@property(nonatomic, strong) NSString *title;
/**
The icon type or identifier to be displayed alongside the toast message.
*/
@property(nonatomic, strong) NSString *icon;
/**
The local file path of a custom icon.
The priority of `image` is higher than `icon`.
@availability 1.1.0 and above
*/
@property(nonatomic, strong) NSString *image;
/**
The duration (in milliseconds) for which the toast should be displayed.
@default 1500
*/
@property(nonatomic, assign) NSInteger duration;
/**
Whether to show a transparent mask layer to prevent touch-through events.
When set to YES, user interactions behind the toast are blocked.
*/
@property(nonatomic, assign) BOOL mask;
@endMethod Declaration
objectivec
/**
Displays a toast message (brief non-intrusive notification) to the user.
@param stateHandle The state handle object that manages the operation state and callbacks.
@param options The options configuration for the toast (e.g., message text, duration, position).
*/
- (void)showToast:(id<SUDOPStateHandle>)stateHandle
options:(SUDOPShowToastOptions *)options;Parameters
SUDOPShowToastOptions
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
title | NSString * | Yes | - | The text content displayed by the Toast. |
icon | NSString * | No | - | The Toast icon type or icon identifier; the built-in values success, fail, loading can be used. |
image | NSString * | No | - | The local file path of a custom icon; image has higher priority than icon. Available since version 1.1.0 and above. |
duration | NSInteger | No | 1500 | The Toast display duration, in milliseconds. |
mask | BOOL | No | NO | Whether to show a transparent mask layer. When set to YES, user taps on the page content behind the Toast are blocked while the Toast is displayed. |
Method Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
stateHandle | id<SUDOPStateHandle> | Yes | The state handle object, used to manage the current operation state and callbacks. |
options | SUDOPShowToastOptions * | Yes | The Toast display configuration object, containing the text, icon, display duration, mask layer, and other settings. |
Example
Display a normal Toast
objectivec
id<SUDOPStateHandle> stateHandle = self.stateHandle;
SUDOPShowToastOptions *options = [[SUDOPShowToastOptions alloc] init];
options.title = @"Operation succeeded";
options.duration = 1500;
[self showToast:stateHandle options:options];Display a success Toast
objectivec
SUDOPShowToastOptions *options = [[SUDOPShowToastOptions alloc] init];
options.title = @"Saved successfully";
options.icon = kSUDOPShowToastOptionsIconTypeSuccess;
options.duration = 1500;
[self showToast:self.stateHandle options:options];Display a failure Toast
objectivec
SUDOPShowToastOptions *options = [[SUDOPShowToastOptions alloc] init];
options.title = @"Submission failed";
options.icon = kSUDOPShowToastOptionsIconTypeFail;
options.duration = 2000;
[self showToast:self.stateHandle options:options];Display a loading Toast
objectivec
SUDOPShowToastOptions *options = [[SUDOPShowToastOptions alloc] init];
options.title = @"Loading";
options.icon = kSUDOPShowToastOptionsIconTypeLoading;
options.duration = 3000;
options.mask = YES;
[self showToast:self.stateHandle options:options];Use a custom icon
objectivec
SUDOPShowToastOptions *options = [[SUDOPShowToastOptions alloc] init];
options.title = @"Added to favorites";
options.icon = kSUDOPShowToastOptionsIconTypeSuccess;
options.image = @"/var/mobile/Containers/Data/Application/xxx/icon_star.png";
options.duration = 1500;
[self showToast:self.stateHandle options:options];When both
imageandiconare set, the local icon specified byimagetakes precedence.
Process Flow
- The business side creates a
SUDOPShowToastOptionsobject. - Set the Toast text content
title. - Set the built-in icon type
iconas needed, e.g.,success,fail,loading. - To use a custom icon, set
imageto the local icon file path. - Set the display duration
durationas needed, in milliseconds. - Set whether to show the transparent mask layer
maskas needed. - Call
showToast:options:to display the Toast. - The SDK automatically hides the Toast after the specified duration.
Notes
stateHandleshould not be empty; otherwise the SDK may fail to correctly manage the current operation state or callbacks.optionsshould not be empty.titleis recommended to be required; when empty, the Toast may display no text, depending on the SDK implementation.durationis in milliseconds, with a default value of1500.imageonly supports local file paths, and is available since SDK version1.1.0and above.imagehas higher priority thanicon; when both are set, the custom image is displayed first.iconis recommended to use the built-in constants provided by the SDK, to avoid string spelling errors.- When
maskis set toYES, user taps on the page content behind the Toast are blocked while the Toast is displayed. - When
maskis set toNO, the page behind the Toast may still respond to user interactions. - If this method is called multiple times in a short period, the SDK may overwrite the previous Toast or queue them for display, depending on the SDK implementation.
- This method has no synchronous return value; the display result or exception information should be based on the SDK callback or state callback.
