GuideDialog_en
GuideDialog can create a mask to display operational guidance images or provide hints for button operations.
GuideDialog can be displayed around a component on the interface, creating a spotlight effect. The spotlight can be circular (outer and inner), square (outer and inner), or rectangular, with the option to set rounded corners for square and rectangular modes.
First, prepare a custom guide image or custom layout, then use the following code to display a guide dialog:
Custom images support resource images (redId), Drawable, or Bitmap.
// Using a custom image
GuideDialog.show(R.mipmap.img_guide_tip);
// Using a custom layout
GuideDialog.show(new OnBindView<CustomDialog>(R.layout.layout_custom_dialog) {
@Override
public void onBind(final CustomDialog dialog, View v) {
ImageView btnOk;
btnOk = v.findViewById(R.id.btn_ok);
btnOk.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
dialog.dismiss();
}
});
}
});You can also use the build() method to construct a CustomDialog:
GuideDialog.build()
.setTipImage(R.mipmap.img_guide_tip)
.show();If you are using ViewBinding, you can also replace it with OnBindingView to get the layout instance directly through binding:
GuideDialog.show(new OnBindingView<CustomDialog, LayoutCustomViewBinding>() {
@Override
public void onBind(CustomDialog dialog, View view, LayoutCustomViewBinding binding) {
//View childView = binding.childView
}
});To guide users based on an existing layout on the interface, bind the layout when displaying GuideDialog:
// view is the layout to which GuideDialog needs to be bound
GuideDialog.show(view, R.mipmap.img_tip_login);After binding the layout, a “stage light” effect will illuminate the bound layout by default. The stage light effect supports the following modes:
| STAGE_LIGHT_TYPE Type | Introduction | Illustration |
|---|---|---|
| RECTANGLE | Displays a rectangle stage light around the bound layout |  |
| SQUARE_OUTSIDE | Displays a square stage light around the bound layout |  |
| SQUARE_INSIDE | Displays a square stage light inside the bound layout |  |
| CIRCLE_OUTSIDE | Displays a circular stage light around the bound layout |  |
| CIRCLE_INSIDE | Displays a circular stage light inside the bound layout |  |
Then use the code to set it:
// Specify in the launch method
GuideDialog.show(btnFullScreenDialogLogin, GuideDialog.STAGE_LIGHT_TYPE.CIRCLE_OUTSIDE, R.mipmap.img_tip_login);
// Use the set method to specify
GuideDialog.show(btnFullScreenDialogLogin, R.mipmap.img_tip_login)
.setStageLightType(GuideDialog.STAGE_LIGHT_TYPE.CIRCLE_OUTSIDE);When using rectangle RECTANGLE and square SQUARE_*, you can specify rounded corners:
.setStageLightFilletRadius(15) // Set rounded corners, unit: pixelsThe guide image/layout in GuideDialog is the part that provides guidance hints. It can be displayed alone or around the bound layout.
When using a guide image, you can specify a resource image (redId), Drawable, or Bitmap. Apart from starting the dialog with a static method, you can also specify separately:
GuideDialog.build()
.setCustomView(new OnBindView(...)) // Specify guide layout
.setTipImage(...) // Specify guide imagePlease note, the guide image and guide layout are mutually exclusive. Using a guide layout will invalidate the guide image.
You can make GuideDialog display around the bound layout:
// Specify in the launch method
GuideDialog.show(btnFullScreenDialogLogin, R.mipmap.img_tip_login, Gravity.BOTTOM|Gravity.CENTER_HORIZONTAL);
// Use the set method to specify
GuideDialog.build()
.setAlignBaseViewGravity(Gravity.BOTTOM | Gravity.CENTER_HORIZONTAL);You can also set the distance between the guide image/layout and the bound layout
:
// Specify the margins (left, top, right, bottom in pixels) between the guide image/layout and the bound layout
.setBaseViewMargin(left, top, right, bottom)
.setBaseViewMargin(new int[]{left, top, right, bottom})
// Specify only the top margin
.setBaseViewMarginTop(-dip2px(30))When using the guide image/layout alone and not binding a guide layout, GuideDialog functions almost identically to Custom Dialog CustomDialog. You can set Align to modify the launch mode of GuideDialog:
GuideDialog.show(...)
.setAlign(ALIGN.TOP);ALIGN is an enumeration, with values defined as follows:
CENTER Central display (default)
TOP Top display (equivalent to top center)
TOP_CENTER Top center display
TOP_LEFT Top left display
TOP_RIGHT Top right display
BOTTOM Bottom display (equivalent to bottom center)
BOTTOM_CENTER Bottom center display
BOTTOM_LEFT Bottom left display
BOTTOM_RIGHT Bottom right display
LEFT Left display (equivalent to left center)
LEFT_CENTER Left center display
LEFT_TOP Left top display
LEFT_BOTTOM Left bottom display
RIGHT Right display (equivalent to right center)
RIGHT_CENTER Right center display
RIGHT_TOP Right top display
RIGHT_BOTTOM Right bottom display
Please note: For example, the difference between displaying at the top left (TOP_LEFT) and the left top (LEFT_TOP) lies in the direction of the entrance and exit animations. The animation for top left display enters from the top of the screen and positions at the left side, whereas for left top display, the animation enters from the left of the screen and positions at the top.
You can also customize the start/close animations, supporting the use of custom anim resource files:
GuideDialog.build()
.setCustomView(...)
.setEnterAnimResId(R.anim.enter_anim)
.setExitAnimResId(R.anim.exit_anim)
.show();Or:
GuideDialog.build()
.setCustomView(...)
.setAnimResId(R.anim.enter_anim, R.anim.exit_anim)
.show();Please note that the start animations must be set before the dialog launches, i.e., using the build() method to construct the dialog.
Set a location click for the guide bound layout:
.setOnStageLightPathClickListener(new OnDialogButtonClickListener<GuideDialog>() {
@Override
public boolean onClick(GuideDialog dialog, View v) {
toast("Clicked on the original button");
btnCustomDialogAlign.callOnClick(); // Call the original button click event
return false;
}
});Set a click on the outer mask:
.setOnBackgroundMaskClickListener(new OnBackgroundMaskClickListener<CustomDialog>() {
@Override
public boolean onClick(CustomDialog dialog, View v) {
toast("Clicked on the outer mask");
return false; // Returning true can prevent the dialog from being closed by clicking on the mask
}
})GuideDialog by default will enable immersive non-safe area isolation mode, meaning it will set padding in the root layout, separating the non-touchable unsafe areas of the top status bar and bottom navigation bar, ensuring the custom layout is definitely within the safe area. However, this may conflict with the immersive framework you use, or if no immersive mode is configured (meaning both the top navigation bar and bottom status bar are non-immersive), leading to extra space being left out in the top/bottom display of GuideDialog. In this case, you can use the following settings to close the immersive padding:
GuideDialog.build()
.setCustomView(...)
.setAutoUnsafePlacePadding(false)
.show();Please note, setAutoUnsafePlacePadding(Boolean) must be set before the dialog starts, i.e., using the build() method to construct the dialog.
To monitor the lifecycle of a dialog, you can implement the .setDialogLifecycleCallback(...) interface. It's recommended to use the build() method to construct the dialog:
GuideDialog.build()
.setDialogLifecycleCallback(new DialogLifecycleCallback<CustomDialog>() {
@Override
public void onShow(CustomDialog dialog) {
// Callback when CustomDialog starts
}
@Override
public void onDismiss(CustomDialog dialog) {
// Callback when CustomDialog closes
}
})
.show();GuideDialog also supports Lifecycle. You can use .getLifecycle() to get the Lifecycle object.
You can also handle lifecycle events by overriding them when creating an instance using new, for example:
// Event overriding demonstration
new GuideDialog() {
@Override
public void onShow(GuideDialog dialog) {
//...
tip("onShow");
}
@Override
public void onDismiss(GuideDialog dialog) {
//...
tip("onDismiss");
}
}You can also use the methods .onShow(DialogXRunnable) and .onDismiss(DialogXRunnable) to handle lifecycle transactions, for example:
GuideDialog.show(...)
.onShow(new DialogXRunnable<GuideDialog>() {
@Override
public void run(GuideDialog dialog) {
//GuideDialog show!
}
})
.onDismiss(new DialogXRunnable<GuideDialog>() {
@Override
public void run(GuideDialog dialog) {
//GuideDialog dismiss!
}
});// Force refresh the interface
.refreshUI();
// Close the dialog
.dismiss();
// Get the instantiated dialog object, you can use this method for deeper customization of the Dialog's functionality
.getDialogImpl()
// Get custom layout instance
.getCustomView()
// Set dialog width
.setWidth(px)
// Set dialog height
.setHeight(px)
// Hide the dialog (without animation), to restore display execute the non-static method .show()
.hide();
// Hide the dialog (simulate closing dialog animation), to restore display execute the non-static method .show()
.hideWithExitAnim();
// Check if it is currently showing
.isShow()
// Front dialog box display hierarchy
.bringToFront()
// Specify the level of dialog display
.setThisOrderIndex(int)