SearchView.yml

---
name: Titanium.UI.Android.SearchView
summary: A specialized text field for entering search text.
description: |
    | Android |
    | ------- |
    | ![Android](./searchview_android.png) |

    `SearchView` provides a user interface to enter a search query and submit a request to a search provider.

    Search views are most commonly used for filtering the rows in a [TableView](Titanium.UI.TableView).
    Similar to [SearchBar](Titanium.UI.SearchBar), you can add a search view to a table view by setting the table view's
    [search](Titanium.UI.TableView.search) property. A search view can be used without a `TableView`.

    You can also use a `SearchView` object as the <Titanium.UI.ListView.searchView>
    property of a [ListView](Titanium.UI.ListView) object.

    You can also add `SearchView` to an `ActionBar` as a view (see example below).

    Use the <Titanium.UI.Android.createSearchView> method or **`<SearchView>`** Alloy element to create
    a search view. You must set the Alloy element's `ns` attribute to **Ti.UI.Android**:

    ``` xml
    <SearchView ns="Ti.UI.Android" platform="android"/>
    ```
extends: Titanium.UI.View
excludes:
    methods: [add]
since: "3.0.2"
platforms: [android]
methods:
  - name: blur
    summary: Causes the search view to lose focus.

  - name: focus
    summary: Causes the search view to gain focus.

events:
  - name: blur
    summary: Fired when the search view loses focus.

  - name: cancel
    summary: Fired when the cancel button is pressed.
    description: |
         Due to the current [Android Issue](http://code.google.com/p/android/issues/detail?id=25758), this event does not work
         with Android 4.0+. Alternatively, when using SearchView in the action bar, you can listen for the [MenuItem.collapse](Titanium.Android.MenuItem.collapse) event.

  - name: change
    summary: Fired when the value of the search view changes.

  - name: focus
    summary: Fired when the search view gains focus.

  - name: submit
    summary: If the search query is not empty, fired when the search button is clicked on soft keyboard

properties:
  - name: color
    summary: Color of the text in this SearchView, as a color name or hex triplet.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>.
    type: String

  - name: hintText
    summary: Text to show when the search view field is not focused.
    type: String
    default: no hint text

  - name: hintTextColor
    summary: Color of hint text that displays when field is empty.
    description: |
        Color of hint text that displays when field is empty.
    type: String
    default: Default Android theme's hint text color.
    since: 7.1.0

  - name: value
    summary: Value of the search view.
    description: |
       This value cannot be set until after the search view is created.
    type: String

  - name: iconified
    summary: Iconifies or expands the search view
    description: see [Android Documentation](https://developer.android.com/reference/android/widget/SearchView.html#setIconified(boolean)) for more details.
    type: Boolean
    default: undefined

  - name: iconifiedByDefault
    summary: Sets the default or resting state of the search view
    description: see [Android Documentation](https://developer.android.com/reference/android/widget/SearchView.html#setIconifiedByDefault(boolean)) for more details.
    type: Boolean
    default: true

  - name: submitEnabled
    summary: Whether to display the submit button when necessary or never display.
    type: Boolean
    default: undefined

examples:

  - title: Search View for Table in Action Bar
    example: |
        The following example creates a SearchView widget for a TableView
        and displays it as an Action Bar item if the Google API level is 11 or later.
        If not, it defaults to use the search bar.

        ``` js
        var win = Ti.UI.createWindow({
            fullscreen: false
        });

        // Use action bar search view
        var search = Ti.UI.Android.createSearchView({
            hintText: "Table Search"
        });

        win.activity.onCreateOptionsMenu = function(e) {
            var menu = e.menu;
            var menuItem = menu.add({
                title: 'Table Search',
                actionView : search,
                icon: (Ti.Android.R.drawable.ic_menu_search ? Ti.Android.R.drawable.ic_menu_search : "my_search.png"),
                showAsAction: Ti.Android.SHOW_AS_ACTION_IF_ROOM | Ti.Android.SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW
            });
        };

        var data = [];
        data.push(Ti.UI.createTableViewRow({title:'Apple'}));
        data.push(Ti.UI.createTableViewRow({title:'Banana'}));
        data.push(Ti.UI.createTableViewRow({title:'Orange'}));
        data.push(Ti.UI.createTableViewRow({title:'Raspberry'}));

        var tableview = Titanium.UI.createTableView({
            data: data,
            search: search,
            searchAsChild: false
        });

        win.add(tableview);
        win.open();
        ```

  - title: Alloy XML Markup
    example: |
        Previous example as an Alloy project.

        index.xml:
        ``` xml
        <Alloy>
            <Window id="win" backgroundColor="blue" fullscreen="false" layout="vertical">
                <TableView id="tableview" top="10" searchAsChild="false">
                    <TableViewRow title="Apple" />
                    <TableViewRow title="Banana" />
                    <TableViewRow title="Orange" />
                    <TableViewRow title="Raspberry" />
                </TableView>
            </Window>
        </Alloy>
        ```

        index.js:
        ``` js
        // use action bar search view
        var search = Alloy.createController("searchview").getView();
        $.tableview.search = search;
        $.win.addEventListener("open", function() {
            $.win.activity.onCreateOptionsMenu = function(e) {
                e.menu.add({
                    title: "Table Search",
                    icon: (Ti.Android.R.drawable.ic_menu_search ? Ti.Android.R.drawable.ic_menu_search : "my_search.png"),
                    actionView: search,
                    showAsAction : Ti.Android.SHOW_AS_ACTION_ALWAYS | Ti.Android.SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW
                });
            }
            $.win.activity.invalidateOptionsMenu();
        });

        $.win.open();
        ```

        searchview.xml:
        ``` xml
        <Alloy>
            <SearchView id="searchView" ns="Ti.UI.Android" platform="android" hintText="Table Search" />
        </Alloy>
        ```