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.
###Android Studio
- Clone the repo
- Open build.gradle in the root folder of the cloned project in Android Studio
###Eclipse+ADT
- Clone the repo
- In Eclipse, go to
File
->New
->Other
. ExpandAndroid
and selectAndroid Project from Existing Code
- Browse to the
android-ago
sub-folder of the cloned repo and hitFinish
###Maven Central This project is not available on Maven Central yet. Please follow #3 to know when this is done.
If you are using Gradle as your dependency manager, you can simply add Android-Ago repository and its dependency in your build.gradle
file, as the example below.
buildscript {
repositories {
jcenter()
}
dependencies {
classpath 'com.android.tools.build:gradle:0.12.+'
// NOTE: Do not place your application dependencies here; they belong
// in the individual module build.gradle files
}
}
allprojects {
repositories {
jcenter()
}
}
apply plugin: 'android'
repositories {
maven { url 'https://github.com/macksuelsantos/android-ago/raw/master/repo' }
}
dependencies {
compile 'com.android.support:support-v4:19.0.1'
compile 'com.github.curioustechizen.ago:Android-Ago-lib:0.1.0'
}
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:
```xml
<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.
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.
See here. If you would like to add your app to this list, please edit the wiki.
###License
Copyright 2013 Kiran Rao
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.