<commit_before>---
name: Titanium.UI.SearchBar
summary: A specialized text field for entering search text.
description: |
    The `SearchBar` object is closely modeled on an iOS native search bar.
    As such, not all features are supported on other platforms.
    
    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 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.

    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
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.

  - name: cancel
    summary: Fired when the cancel button is pressed.

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

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

  - name: return
    summary: Fired when keyboard search button is pressed.

properties:

  - name: autocapitalization
    summary: Determines how text is capitalized during typing. 
    description: |
        Specify one of the following constants from <Titanium.UI>: 
        [TEXT_AUTOCAPITALIZATION_NONE](Titanium.UI.TEXT_AUTOCAPITALIZATION_NONE), 
        [TEXT_AUTOCAPITALIZATION_WORDS](Titanium.UI.TEXT_AUTOCAPITALIZATION_WORDS), 
        [TEXT_AUTOCAPITALIZATION_SENTENCES](Titanium.UI.TEXT_AUTOCAPITALIZATION_SENTENCES), or 
        [TEXT_AUTOCAPITALIZATION_ALL](Titanium.UI.TEXT_AUTOCAPITALIZATION_ALL).

    type: Number
    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.
    description: |
        On iOS, `barColor` specifies the color of the "frame" around the search text field.
    type: String
    platforms: [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]
    default: System default keyboard.

  - name: prompt
    summary: Single line of text displayed at the top of the search bar.
    type: String
    platforms: [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: 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.
    type: String
    
examples:

  - title: Simple Search Bar
    example: |<commit_msg>[TIDOC-401] Added caveat about setting value in the create method on Android.<commit_after>---
name: Titanium.UI.SearchBar
summary: A specialized text field for entering search text.
description: |
    The `SearchBar` object is closely modeled on an iOS native search bar.
    As such, not all features are supported on other platforms.
    
    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 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
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.

  - name: cancel
    summary: Fired when the cancel button is pressed.

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

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

  - name: return
    summary: Fired when keyboard search button is pressed.

properties:

  - name: autocapitalization
    summary: Determines how text is capitalized during typing. 
    description: |
        Specify one of the following constants from <Titanium.UI>: 
        [TEXT_AUTOCAPITALIZATION_NONE](Titanium.UI.TEXT_AUTOCAPITALIZATION_NONE), 
        [TEXT_AUTOCAPITALIZATION_WORDS](Titanium.UI.TEXT_AUTOCAPITALIZATION_WORDS), 
        [TEXT_AUTOCAPITALIZATION_SENTENCES](Titanium.UI.TEXT_AUTOCAPITALIZATION_SENTENCES), or 
        [TEXT_AUTOCAPITALIZATION_ALL](Titanium.UI.TEXT_AUTOCAPITALIZATION_ALL).

    type: Number
    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.
    description: |
        On iOS, `barColor` specifies the color of the "frame" around the search text field.
    type: String
    platforms: [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]
    default: System default keyboard.

  - name: prompt
    summary: Single line of text displayed at the top of the search bar.
    type: String
    platforms: [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: 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: |
{'fraction_non_alphanumeric': 0.06384233134001516, 'fraction_numerical': 0.000589572980712541, 'mean_word_length': 2.7036805988771055, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5086241', 'n_tokens_mistral': 3276, 'n_tokens_neox': 3136, 'n_words': 1380}