api_uicontrols/com.tomtom.tools.android.api.uicontrols.searchview/TtSearchView

TtSearchView

class TtSearchView @JvmOverloads constructor(context: Context, attrs: AttributeSet?, defStyleAttr: Int = R.attr.tt_searchview_style) : SearchView

Overview

A SearchView with a search indicator, toggleable collapsed/expanded width, and a lock feature that allows for preventing any user interaction. When the input field shows a query, the search view shows a query icon at the end of the input field. While the search is ongoing, the search view can show a search indicator next to the clear icon.

Features

Searching

The client can updateSearchState of the search view to communicate the current state to the user. See the SearchState for the available states.

Locking

The client can control whether the search view is interactive by setting the ttIsLocked value.

When ttIsLocked is true:

The search view is in the locked state and cannot be interacted with.
The hint is replaced with an explanatory ttLockedReason message.
The search icon is replaced with ttLockedIcon.

Expansion

The client can make the search view expand when it is tapped and collapse when it loses focus by setting ttExpandedWidth.

When ttExpandedWidth is set:

If the collapsed search view has been tapped, it expands its width to the ttExpandedWidth.
If the expanded search view has lost focus, it collapses back to its initial size, as declared in the XML file or according to the value provided by the LayoutParams.

NOTE: If ttExpandedWidth is set, the search view, while collapsed, will not accept any input even if focused and has to be first expanded.

NOTE: If ttExpandedWidth is reset to 0, the search view will resize its width to the value declared in the XML file or according to the value provided by the LayoutParams. If that width is too small for the search view to be usable, the client can updateLayoutParams. It is only valid to updateLayoutParams when ttExpandedWidth is 0, otherwise the collapse or expansion of the search view will override the LayoutParams set by the client.

Theming and customization

For the detailed theming and customization guide refer to the developer portal documentation.

For the reference, below is the stock search view style.

Search view default style

<resources>
    <style name="TtSearchView">
        <item name="android:background">@drawable/tt_searchview_background_selector</item>
        <item name="android:gravity">center_vertical</item>
        <item name="android:height">?attr/tt_searchview_height</item>
        <item name="android:layout_height">?attr/tt_searchview_height</item>
        <item name="android:stateListAnimator">?attr/tt_statelistanimator_none</item>
        <item name="android:textCursorDrawable">@drawable/tt_text_cursor</item>
        <item name="closeIcon">?attr/tt_inputfield_clear_icon</item>
        <item name="iconifiedByDefault">false</item>
        <item name="queryBackground">@null</item>
        <item name="queryHint">@string/tt_common_action_search</item>
        <item name="ttLockedIcon">?attr/tt_lock_icon</item>
        <item name="ttLockedReason">@null</item>
        <item name="ttSearchHintTextColor">?attr/tt_surface_content_color_emphasis_low</item>
        <item name="ttSearchIcon">?attr/tt_search_icon</item>
        <item name="ttSearchIconTint">?attr/tt_surface_content_color_emphasis_high</item>
        <item name="ttSearchingIndicatorTint">?attr/tt_surface_content_color_emphasis_high</item>
        <item name="ttSearchTextAppearance">?attr/tt_label_text_style_l</item>
        <item name="ttSearchTextColor">?attr/tt_surface_content_color_emphasis_high</item>
        <item name="ttTypeOnlyMode">false</item>
    </style>
</resources>

XML Attributes

All theme attributes used by this control are declared in com.tomtom.tools.android.core.theme. To use this control, it is mandatory to define these attribute values. Attributes affecting the search view are listed below.

Platform-wide attributes

NOTE: Changes to attributes listed in this section could cause side effects if not done carefully because it might affect other UI controls.


`tt_animation_duration_medium_ms`	The duration of the expansion animation.
`tt_icon_size_6`	The searching indicator size.
`tt_inputfield_clear_icon`	The clear search icon drawable.
`tt_label_text_style_l`	The input field text appearance.
`tt_loading_icon`	The searching indicator drawable.
`tt_lock_icon`	The lock indicator drawable.
`tt_spacing_5`	The input field padding.

TtSearchView attributes


`ttSearchTextAppearance`	R.attr.tt_label_text_style_l	The input field text appearance.
`ttSearchTextColor`	R.attr.tt_surface_content_color_emphasis_high	The input field text color. Overrides the `ttSearchTextAppearance`.
`ttSearchHintTextColor`	R.attr.tt_surface_content_color_emphasis_low	The input field hint color. Also used for lock reason text. Overrides the `ttSearchTextAppearance`.
`ttSearchIcon`	R.attr.tt_search_icon	The search icon.
`ttSearchIconTint`	R.attr.tt_surface_content_color_emphasis_high	The search icon tint.
`ttSearchingIndicatorTint`	R.attr.tt_surface_content_color_emphasis_high	The searching indicator icon tint.
`ttIsLocked`	`false`	The boolean, indicating whether the search view is locked.
`ttLockedIcon`	R.attr.tt_lock_icon	The lock icon.
`ttLockedReason`	`null`	The lock reason explanatory text.
`ttExpandedWidth`	`0.0f`	The width of the search view in expanded mode.
`ttTypeOnlyMode`	`false`	The boolean, indicating whether the text selection, copying, etc. are allowed.

Parameters

context

The display context.

attrs

The attribute set provided in the layout XML file.

defStyleAttr

The default style attribute set. The default value is R.attr.tt_searchview_style

Constructors

TtSearchView

@JvmOverloads

constructor(context: Context, attrs: AttributeSet?, defStyleAttr: Int = R.attr.tt_searchview_style)

Types

SearchState

enum SearchState : Enum<TtSearchView.SearchState>

The state of the search view. The view's visual components can have different appearances for each state.

Properties

ttExpandedWidth

var ttExpandedWidth: Float

If set, this view's width will expand to the given value when tapped. When the view loses focus, it will collapse back to its original width.

ttIsLocked

var ttIsLocked: Boolean

When true, the search view is in the locked state and cannot be interacted with. The view will then show an explanatory message if expanded, and the search icon will be replaced with a locked state icon.

ttLockedIcon

var ttLockedIcon: Drawable?

The drawable for the lock icon. If null, lock icon is not shown.

ttLockedReason

var ttLockedReason: String?

When ttIsLocked is true, this string is shown in the input field explaining why the search view is locked.

ttSearchHintTextColor

var ttSearchHintTextColor: Int

The color for the hint text in the search input field. The same color applies for ttLockedReason.

ttSearchIcon

var ttSearchIcon: Drawable?

The drawable for the search icon. If null, search icon is not shown.

ttSearchIconTint

var ttSearchIconTint: Int?

The tint color for ttSearchIcon. If null, no tint applies.

ttSearchingIndicatorTint

var ttSearchingIndicatorTint: Int?

The tint color for the searching indicator. If null, no tint applies.

ttSearchTextAppearance

var ttSearchTextAppearance: Int

The TextAppearance for the search input field. Applies to the query text, the hint text and the ttLockedReason.

ttSearchTextColor

var ttSearchTextColor: Int

The color for the query text in the search input field.

ttTypeOnlyMode

var ttTypeOnlyMode: Boolean

When true, the search view is in the type only mode, meaning that all text utils like text select and cut/copy/paste text along with the long click and double click interactions are disabled.

Functions

getSearchState

fun getSearchState(): TtSearchView.SearchState

Retrieve the view's SearchState.

onInterceptTouchEvent

open override fun onInterceptTouchEvent(ev: MotionEvent): Boolean

This override is necessary in order to make sure tapping on any part of the SearchView will expand it if it's collapsed. Otherwise, child views would intercept the click and expanding would not work correctly.

requestFocus