android-ago

This library provides RelativeTimeTextView, a custom TextView that takes a reference time and always displays the relative time with respect to the reference point, automatically refreshing the display text as needed. This is a common pattern seen in several apps like chat apps, social networking, email etc.

This library can be seen as a wrapper on top of the excellent android.text.format.DateUtils class. Note that the library does not expose all the options provided by the DateUtils class. I have left out many features because I couldn't decide what would be the best way to achieve the flexibility - dozens of XML attributes? Contributions in this regard are welcome.

Obtaining

###Gradle

Add the following to your build.gradle

dependencies {
    compile 'com.github.curioustechizen.android-ago:library:1.3.0'
}

###Eclipse+ADT

Clone the repo
In Eclipse, go to File -> New -> Other. Expand Android and select Android Project from Existing Code
Browse to the android-ago sub-folder of the cloned repo and hit Finish

Usage

Include RelativeTimeTextView in your layouts.
Set the reference time either using setReferenceTime method or using the XML attribute reference_time.
Optionally, you can set a prefix using relative_time_prefix through XML or setPrefix from Java code.
Similarly, you can set a suffix using relative_time_suffix through XML or setSuffix from Java code.

In your layout:

<com.github.curioustechizen.ago.RelativeTimeTextView
    android:id="@+id/timestamp"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:relative_time_prefix="Completed "
    android:layout_marginTop="@dimen/margin_primary" />

In your Java code:

RelativeTimeTextView v = (RelativeTimeTextView)findViewById(R.id.timestamp); //Or just use Butterknife!
v.setReferenceTime(new Date().getTime());

See the sample project for a concrete example.

Why is this library even needed?

One might ask, why not just use DateUtils directly? Well, the answer is that the custom TextView provided by this library is responsible for keeping track of its own reference time and of updating the display text over regular periodic intervals. It is also responsible for scheduling (or cancelling a scheduled) update of the display text. All you have to do is set the reference time once.

Who's Using this Library?

See here. If you would like to add your app to this list, please edit the wiki.

Android version support statement

The library has been tested on API 11 and above. However, theoretically, it works on API 3 and above since all it uses is [DateUtils#getRelativeTimeSpanString](http://developer.android.com/reference/android/text/format/DateUtils.html#getRelativeTimeSpanString(long, long, long, int)).

The minSdkVersion has been set to 8, however do not expect support from me for API version < 11.

###License