# Titanium.UI.RefreshControl

> The RefreshControl is a representation of the native iOS [UIRefreshControl](https://developer.apple.com/documentation/uikit/uirefreshcontrol) and Android [SwipeRefreshLayout](https://developer.android.com/reference/android/support/v4/widget/SwipeRefreshLayout.html).

- Source: https://titaniumsdk.com/docs/sdk/12.7.1/Titanium.UI.RefreshControl
- Titanium SDK version: 12.7.1
- Kind: proxy
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 6.2.0, iPhone 3.2.0, iPad 3.2.0
- Extends: Titanium.Proxy
- Inheritance: Titanium.Proxy

| Android | iOS |
| ------- | --- |
| ![Android](./refreshcontrol_android.png) |  |

You use a `RefreshControl` with a [Titanium.UI.TableView](https://titaniumsdk.com/docs/sdk/Titanium.UI.TableView.md), [Titanium.UI.ListView](https://titaniumsdk.com/docs/sdk/Titanium.UI.ListView.md) or [Titanium.UI.ScrollView](https://titaniumsdk.com/docs/sdk/Titanium.UI.ScrollView.md) object.
It provides an alternate method to implement **pull to refresh** functionality provided by
[Titanium.UI.TableView.headerPullView](https://titaniumsdk.com/docs/sdk/Titanium.UI.TableView.md#headerPullView) and [Titanium.UI.ListView.pullView](https://titaniumsdk.com/docs/sdk/Titanium.UI.ListView.md#pullView) properties.

Use the [Titanium.UI.createRefreshControl](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#createRefreshControl) method to create a RefreshControl.

**Important iOS 10+ Note**: If you use the RefreshControl inside a [Titanium.UI.Window](https://titaniumsdk.com/docs/sdk/Titanium.UI.Window.md) that has the `largeTitleEnabled` property
set to `true`, you also need to set the `extendEdges` property to either `[Ti.UI.EXTEND_EDGE_TOP]` or `[Ti.UI.EXTEND_EDGE_ALL]`
in order to prevent a flickering of the refresh spinner. In Titanium SDK 8+, the `extendEdges` property will be set to `[Ti.UI.EXTEND_EDGE_ALL]`
by default to match the native behavior.

## Example: Basic Pull To Refresh

A basic sample showing the usage of refreshstart event with endRefreshing functionality.

``` js
const win = Ti.UI.createWindow();
let counter = 0;
function genData() {
    const data = [];
    for (let i = 1; i <= 3; i++) {
        data.push({ properties:{ title: `ROW ${counter + i}` } });
    }
    counter += 3;
    return data;
}
const section = Ti.UI.createListSection();
section.items = genData();
const control = Ti.UI.createRefreshControl({
    tintColor: 'red'
});
const listView = Ti.UI.createListView({
    sections: [section],
    refreshControl: control
});
control.addEventListener('refreshstart', () => {
    Ti.API.info('refreshstart');
    setTimeout(() => {
        Ti.API.debug('Timeout');
        section.appendItems(genData());
        control.endRefreshing();
    }, 2000);
});
win.add(listView);
win.open();
```

## Example: Alloy example

TableView with a RefreshControl

``` xml
<Alloy>
    <Window>
        <TableView id="table">
          <RefreshControl id="refresh" onRefreshstart="refreshstart"/>
            <TableViewSection id="sectionFruit" headerTitle="Fruit">
                <TableViewRow title="Apple"/>
                <TableViewRow title="Bananas"/>
            </TableViewSection>
        </TableView>
    </Window>
</Alloy>
```

``` js
function refreshstart(e){
  $.refresh.endRefreshing();
}

$.index.open();
```

## Properties

### backgroundColor

- Type: String | Titanium.UI.Color
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 12.4.0

The background color for the refresh control, as a color name or hex triplet.

For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md).

### offset

- Type: RefreshControlOffset
- Platforms: Android
- Since: Titanium SDK 12.7.0

Offset of the refresh control view.

### tintColor

- Type: String | Titanium.UI.Color
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 6.2.0, iPhone 3.2.0, iPad 3.2.0

The tint color for the refresh control, as a color name or hex triplet.

For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md).

### title

- Type: Titanium.UI.AttributedString
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.2.0

The attributed title of the control.

Title text is only supported on iOS. Android will ignore this property.

## Methods

### beginRefreshing

- Platforms: Android, iPhone, iPad, macOS

Tells the control that a refresh operation was started programmatically.

Call this method when an external event source triggers a programmatic refresh of your table.
This method updates the state of the refresh control to reflect the in-progress refresh operation.
When the refresh operation ends, be sure to call the [endRefreshing](https://titaniumsdk.com/docs/sdk/Titanium.UI.RefreshControl.md#endRefreshing)
method to return the control to its default state.
Note: When triggering the refreshing programmatically, the styling is not applied and the refresh control is tinted
in the native gray.

### endRefreshing

- Platforms: Android, iPhone, iPad, macOS

Tells the control that a refresh operation has ended.

Call this method at the end of any refresh operation (whether it was initiated programmatically or by the user)
to return the refresh control to its default state.

## Events

### refreshend

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 6.2.0, iPhone 6.0.0, iPad 6.0.0

Fired in response to a user finished action to refresh the contents of the
table view, list view or scroll view.

Event properties:

- `bubbles` (Boolean): This is false. This event does not bubble

### refreshstart

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 6.2.0, iPhone 3.2.0, iPad 3.2.0

Fired in response to a user initiated an action to refresh the contents of the
table view, list view or scroll view.

Event properties:

- `bubbles` (Boolean): This is false. This event does not bubble

## Inherited members

7 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.7.1/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.