Skip to content

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 ​

ConstantValueDescription
kSUDOPShowToastOptionsIconTypeSuccesssuccessSuccess icon.
kSUDOPShowToastOptionsIconTypeFailfailFailure icon.
kSUDOPShowToastOptionsIconTypeLoadingloadingLoading 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;

@end

Method 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 ​

ParameterTypeRequiredDefaultDescription
titleNSString *Yes-The text content displayed by the Toast.
iconNSString *No-The Toast icon type or icon identifier; the built-in values success, fail, loading can be used.
imageNSString *No-The local file path of a custom icon; image has higher priority than icon. Available since version 1.1.0 and above.
durationNSIntegerNo1500The Toast display duration, in milliseconds.
maskBOOLNoNOWhether 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 ​

ParameterTypeRequiredDescription
stateHandleid<SUDOPStateHandle>YesThe state handle object, used to manage the current operation state and callbacks.
optionsSUDOPShowToastOptions *YesThe 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 image and icon are set, the local icon specified by image takes precedence.

Process Flow ​

  1. The business side creates a SUDOPShowToastOptions object.
  2. Set the Toast text content title.
  3. Set the built-in icon type icon as needed, e.g., success, fail, loading.
  4. To use a custom icon, set image to the local icon file path.
  5. Set the display duration duration as needed, in milliseconds.
  6. Set whether to show the transparent mask layer mask as needed.
  7. Call showToast:options: to display the Toast.
  8. The SDK automatically hides the Toast after the specified duration.

Notes ​

  • stateHandle should not be empty; otherwise the SDK may fail to correctly manage the current operation state or callbacks.
  • options should not be empty.
  • title is recommended to be required; when empty, the Toast may display no text, depending on the SDK implementation.
  • duration is in milliseconds, with a default value of 1500.
  • image only supports local file paths, and is available since SDK version 1.1.0 and above.
  • image has higher priority than icon; when both are set, the custom image is displayed first.
  • icon is recommended to use the built-in constants provided by the SDK, to avoid string spelling errors.
  • When mask is set to YES, user taps on the page content behind the Toast are blocked while the Toast is displayed.
  • When mask is set to NO, 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.