Return to Home Altitude List Item Widget

Return-To-Home Altitude List Item Widget is a EDIT type of widget which will display the current value of the altitude that the drone is restricted to fly at, when the drone is automatically returning home. The widget also provides functionality to modify this value. The user can tap on the value and edit it in the permitted range. The permitted range is shown next to the edit field as a hint.

The widget will show values in feet instead of meters when the unit mode is Imperial. This can be achieved using Unit Mode List Item Widget.

Following are examples of the widget states:

Disconnected

Normal

Out of range

The user will be shown toast message if they try to set a value out of range.

The modifying of return-to-home altitude is subject to following conditions.

Beginner Mode - If the drone has beginner (novice) mode enabled, the return-to-home altitude is restricted to 30m / 100ft. The user will not be able to edit this value while in this mode.

Restricted below Max Altitude - The return-to-home altitude value cannot exceed the maximum altitude set on the device. The user will be shown an error dialog to indicate the failure of set action.

If the max altitude value is modified to be lower than the current value of return-to-home altitude, the return-to-home altitude will be updated to match the max altitude value.

Success Dialog - When the value of return-to-home altitude is updated successfully, the user will be shown a dialog.

The user will be shown toast message if the setting of the value fails.

Usage

<dji.ux.beta.core.panel.listitem.returntohomealtitude.ReturnToHomeAltitudeListItemWidget
     android:id="@+id/return_to_home_altitude_list_item"
     android:layout_width="match_parent"
     android:layout_height="wrap_content" />

Customizations

The UI elements can be customized to match the style of the user's application. The customizations can be done using attributes in XML or programmatically using the APIs. The widget supports all the customizations that its parent EDIT supports.

XML Example

<dji.ux.beta.core.panel.listitem.returntohomealtitude.ReturnToHomeAltitudeListItemWidget
     android:id="@+id/return_to_home_altitude_list_item"
     android:background="@color/light_gray"
     app:uxsdk_list_item_title_text_color="@color/black"
     app:uxsdk_list_item_edit_text_normal_color="@color/green"
     app:uxsdk_list_item_edit_background="@drawable/edit_background_selector"
     app:uxsdk_list_item_error_color="@color/yellow"
     app:uxsdk_list_item_dialog_theme="@style/UXSDKDialogCustomTheme"
     app:uxsdk_list_item_icon_color="@color/black"
     app:uxsdk_list_item_hint_text_color="@color/black"
     android:layout_width="match_parent"
     android:layout_height="wrap_content" />

The dialogs can be customized by using a custom theme.

<style name="UXSDKDialogCustomTheme" parent="Theme.AppCompat.Dialog.Alert">
   <item name="colorAccent">@color/red</item>
   <item name="android:background">@color/gray</item>
</style>

Attributes

List of the customizable XML attributes

uxsdk_list_item_dialog_theme - The style resource for theming the dialogs.
uxsdk_toast_messages_enabled - The flag for enabling or disabling toast messages.
uxsdk_list_item_error_dialog_icon - The icon for the error dialog shown in the widget.
uxsdk_list_item_success_dialog_icon - The icon for the success dialog shown in the widget.

Java Example

ReturnToHomeAltitudeListItemWidget returnToHomeAltitudeListItemWidget = findViewById(R.id.return_to_home_altitude_list_item);
returnToHomeAltitudeListItemWidget.setBackgroundColor(getResources().getColor(R.color.light_gray));
returnToHomeAltitudeListItemWidget.setListItemTitleTextColor(getResources().getColor(R.color.black));
returnToHomeAltitudeListItemWidget.setListItemTitleIconColor(getResources().getColor(R.color.black));
returnToHomeAltitudeListItemWidget.setErrorValueColor(getResources().getColor(R.color.yellow));
returnToHomeAltitudeListItemWidget.setEditTextNormalColor(getResources().getColor(R.color.green));
returnToHomeAltitudeListItemWidget.setListItemEditTextBackground(getResources().getDrawable(R.drawable.edit_background_selector));
returnToHomeAltitudeListItemWidget.setListItemHintTextColor(getResources().getColor(R.color.black));
returnToHomeAltitudeListItemWidget.setDialogTheme(R.style.UXSDKDialogCustomTheme);

Kotlin Example

val returnToHomeAltitudeListItemWidget = findViewById<ReturnToHomeAltitudeListItemWidget>(R.id.return_to_home_altitude_list_item)
returnToHomeAltitudeListItemWidget.setBackgroundColor(resources.getColor(R.color.light_gray))
returnToHomeAltitudeListItemWidget.listItemTitleTextColor = resources.getColor(R.color.black)
returnToHomeAltitudeListItemWidget.listItemTitleIconColor = resources.getColor(R.color.black)
returnToHomeAltitudeListItemWidget.errorValueColor = resources.getColor(R.color.yellow)
returnToHomeAltitudeListItemWidget.editTextNormalColor = resources.getColor(R.color.green)
returnToHomeAltitudeListItemWidget.listItemEditTextBackground = resources.getDrawable(R.drawable.edit_background_selector)
returnToHomeAltitudeListItemWidget.listItemHintTextColor = resources.getColor(R.color.black)
returnToHomeAltitudeListItemWidget.dialogTheme = R.style.UXSDKDialogCustomTheme

APIs

List of the customization APIs

@StyleRes var dialogTheme: Int - The style resource for all the format dialogs.
var toastMessagesEnabled: Boolean - The flag used to enable or disable toast messages in the widget.
var errorDialogIcon: Drawable? - The icon for the error dialog shown in the widget.
var successDialogIcon: Drawable? - The icon for the success dialog shown in the widget.

Hooks

The widget provides hooks for the users to add functionality based on the state changes in the widget. The ReturnToHomeAltitudeItemWidget provides the following hooks:

ModelState - Provides hooks in events received by the widget from the widget model.
- data class ProductConnected(val isConnected: Boolean) : ModelState() - Event when the product is connected or disconnected.
- data class ReturnToHomeAltitudeStateUpdated(val returnToHomeAltitudeState: ReturnToHomeAltitudeState) : ModelState() - Event when the return-to-home altitude level state is updated.
- object SetReturnToHomeAltitudeSucceeded : ModelState() - Event when setting the return-to-home altitude value is successful.
- data class SetReturnToHomeAltitudeFailed(val error: UXSDKError) : ModelState() - Event when setting the return-to-home altitude value fails.

The user can subscribe to this using public override fun getWidgetStateUpdate(): Flowable<ModelState>.

UIState - Provides hooks in events related to user interaction with the widget.
- object EditStarted : UIState() - Event when the edit text is tapped for editing.
- object EditFinished : UIState() - Event when the user completes inputting the value and hits done.
- data class DialogDisplayed(val info: Any?) : UIState() - Event when a dialog is displayed.
- data class DialogActionConfirmed(val info: Any?) : UIState() - Event when the positive button on the dialog is clicked.
- data class DialogActionCanceled(val info: Any?) : UIState() - Event when the negative button on the dialog is clicked.
- data class DialogDismissed(val info: Any?) : UIState() - Event when a dialog is dismissed.

The info param is an instance of DialogType and can be used as a dialog identifier. Its types are:

MaxAltitudeExceeded - Error dialog shown when user tries to set return-to-home altitude higher than max altitude.
ReturnHomeAltitudeChangeConfirmation - Success dialog shown when the return-to-home altitude is set successfully.

The user can subscribe to this using fun getUIStateUpdates(): Flowable<UIState>.

DJI UX SDK Version 5 Beta 5