SearchBar.yml

---
name: Titanium.UI.SearchBar
summary: A specialized text field for entering search text.
description: |
    <table id="platformComparison">
      <tr>
        <td><img src="images/searchbar/searchbar_android.png" height="25" /></td>
        <td><img src="images/searchbar/searchbar_ios.png" height="25" /></td>
      </tr>
      <tr><th>Android</th><th>iOS</th></tr>
    </table>

    The `SearchBar` object is closely modeled on an iOS native search bar.
    As such, not all features are supported on other platforms. For Android applications, 
    consider using a <Titanium.UI.Android.SearchView> object instead.
    
    Search bars are most commonly used for filtering the rows in a [TableView](Titanium.UI.TableView).
    You can add a search bar to a table view by setting the table view's 
    [search](Titanium.UI.TableView.search) property. 

    A search bar can also be used without a table view.

    Use the <Titanium.UI.createSearchBar> method or Alloy **`<SearchBar>`** element to create a search bar.

    #### Android Platform Implementation Notes

    On Android, there are several issues with the current implementation:

    * The cancel button does not work. It does not clear the search bar text or 
      close the onscreen keyboard.

    * Calling the `blur` method on the search bar closes the onscreen keyboard, 
      but the search bar retains its focused appearance.

    * The search bar does not lose focus when the user clicks on a row in the search
      results.

    * The `value` property cannot be specified in the `createSearchBar` method.

    To use a search bar on Android, you may need to explicitly control the focus and
    clearing of the search bar, depending on your desired behavior. For example, to clear
    the search bar and dismiss the onscreen keyboard when the user selects a row, you
    could add code like this to the `click` event handler on your table view:
        
        myTableView.addEventListener('click', function(e) {
            if (Ti.Platform.name === 'android') {
                // Clear search bar
                mySearchBar.value ="";
                // hiding and showing the search bar forces it back to its non-focused appearance.
                mySearchBar.hide();
                mySearchBar.show();
            }
            // standard click event handling here
    
extends: Titanium.UI.View
excludes: { methods: [ add, removeAllChildren ] }
since: "0.8"
platforms: [android, iphone, ipad]
methods:

  - name: blur
    summary: Causes the search bar to lose focus.

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

  - name: setShowCancel
    summary: Shows or hides the cancel button.
    description: |
        Sets the value of the [showCancel](Titanium.UI.SearchBar.showCancel) property.

        On iOS, this method can be used to specify animation properties when changing the
        state of the cancel button. 

            searchBar.setShowCancel(true, { animated: true });

    parameters:
      - name: showCancel
        summary: New value for [showCancel](Titanium.UI.SearchBar.showCancel).
        type: Boolean
        
      - name: animated
        summary: |
            Dictionary of animation properties. Currently only a
            single boolean property, `animated` is supported. Only used on iOS.
        type: Dictionary
        optional: true
        default: No animation.
events:

  - name: blur
    summary: Fired when the search bar loses focus.
    properties:
      - name: value
        summary: Value of the search bar.
        type: String

  - name: bookmark
    summary: Fired when the bookmark button is pressed.
    platforms: ['iphone', 'ipad']
    properties:
      - name: value
        summary: Value of the search bar.
        type: String
      
  - name: cancel
    summary: Fired when the cancel button is pressed.
    properties:
      - name: value
        summary: Value of the search bar.
        type: String

  - name: change
    summary: Fired when the value of the search bar changes.
    properties:
      - name: value
        summary: Value of the search bar.
        type: String

  - name: focus
    summary: Fired when the search bar gains focus.
    platforms: ['android', 'iphone', 'ipad']
    properties:
      - name: value
        summary: Value of the search bar.
        type: String

  - name: return
    summary: Fired when keyboard search button is pressed.
    properties:
      - name: value
        summary: Value of the search bar.
        type: String

properties:

  - name: autocapitalization
    summary: Determines how text is capitalized during typing. 
    type: Number
    constants: Titanium.UI.TEXT_AUTOCAPITALIZATION_*
    platforms: [iphone, ipad]
    default: No autocapitalization.

  - name: autocorrect
    summary: Determines whether the text in the search bar is autocorrected during typing.
    type: Boolean
    platforms: [iphone, ipad]
    default: false

  - name: barColor
    summary: Bar color of the search bar view, as a color name or hex triplet.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>. 
        
        On iOS and Android, `barColor` specifies the color of the "frame" around the search text field.
    type: String
    platforms: [android, iphone, ipad]
    default: System default bar color.

  - name: hintText
    summary: Text to show when the search bar field is not focused.
    type: String
    default: On iOS, "Search"; on Android, no hint text.

  - name: hinttextid
    summary: |
        Key identifying a string from the locale file to use for the
        [hintText](Titanium.UI.SearchBar.hintText) property.
    description: Only one of `hintText` or `hinttextid` should be specified.
    type: String

  - name: keyboardType
    summary: Keyboard type constant to use when the field is focused.
    type: Number
    platforms: [iphone, ipad]
    constants: Titanium.UI.KEYBOARD_TYPE_*
    default: <Titanium.UI.KEYBOARD_TYPE_DEFAULT>

  - name: keyboardAppearance
    summary: Determines the appearance of the keyboard to be displayed the field is focused.
    type: Number
    since: 5.2.0
    platforms: [iphone, ipad]
    constants: Titanium.UI.KEYBOARD_APPEARANCE_*
    default: <Titanium.UI.KEYBOARD_APPEARANCE_DEFAULT>

  - name: prompt
    summary: Single line of text displayed at the top of the search bar.
    type: String
    platforms: [android, iphone, ipad]
    default: No prompt.

  - name: promptid
    summary: |
        Key identifying a string from the locale file to use for the
        [prompt](Titanium.UI.SearchBar.prompt) property.
    type: String
    platforms: [iphone, ipad]

  - name: showBookmark
    summary: Determines whether the bookmark button is displayed.
    type: Boolean
    platforms: [iphone, ipad]
    default: false

  - name: showCancel
    summary: Determines whether the cancel button is displayed.
    description: |
        On iOS, you can specify that showing and hiding the cancel button should be animated.
        The change is not animated by default. To enable animation, call 
        [setShowCancel](Titanium.UI.SearchBar.setShowCancel).
    type: Boolean
    default: false

  - name: value
    summary: Value of the search bar.
    description: |
        On Android, the value cannot be set until after the search bar is created.
    type: String
    
examples:

  - title: Simple Search Bar
    example: |
        
            var search = Titanium.UI.createSearchBar({
            	barColor:'#000', 
            	showCancel:true,
            	height:43,
            	top:0,
            });

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

            <Alloy>
                <SearchBar id="search" barColor="#000" showCancel="true" height="43" top="0" />
            </Alloy>