{"id":13604288,"url":"https://github.com/curioustechizen/android-ago","last_synced_at":"2025-04-11T23:32:14.958Z","repository":{"id":10074850,"uuid":"12130224","full_name":"curioustechizen/android-ago","owner":"curioustechizen","description":"An Android TextView that always displays an auto refreshing relative time span with respect to a reference time","archived":false,"fork":false,"pushed_at":"2020-10-01T14:00:15.000Z","size":1034,"stargazers_count":658,"open_issues_count":13,"forks_count":109,"subscribers_count":25,"default_branch":"master","last_synced_at":"2024-11-07T08:42:44.008Z","etag":null,"topics":["android","textview","time"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/curioustechizen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-08-15T08:41:48.000Z","updated_at":"2024-10-31T02:09:53.000Z","dependencies_parsed_at":"2022-09-10T19:10:32.613Z","dependency_job_id":null,"html_url":"https://github.com/curioustechizen/android-ago","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curioustechizen%2Fandroid-ago","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curioustechizen%2Fandroid-ago/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curioustechizen%2Fandroid-ago/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curioustechizen%2Fandroid-ago/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/curioustechizen","download_url":"https://codeload.github.com/curioustechizen/android-ago/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248495114,"owners_count":21113574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","textview","time"],"created_at":"2024-08-01T19:00:42.959Z","updated_at":"2025-04-11T23:32:09.947Z","avatar_url":"https://github.com/curioustechizen.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"# android-ago\n\nThis 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.\n\n![Here is a screenshot from the sample app][1]\n\nThis 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.\n\n## Why should I use this instead of DateUtils class?\n\nBecause this library **automatically refreshes the display text as needed**. It internally uses `DateUtils` class.\n\nImagine you use `DateUtils` directly without using this library.\n  - Imagine that it is **9 am** now. You set a reference time of **9:05 am**. Your TextView displays `in 5 mins`\n  - Now the time becomes **9:01 am**. You still display `in 5 mins` even though you should be showing `in 4 mins`\n  \nTo do this correctly, you will need to keep refreshing the text views every minute. However, even that is not necessary. If the reference time is 3 hours from now, you only need to refresh every hour - not every minute.\n\nThis library handles all of this for you. `RelativeTimeTextView` automatically refreshes the display text _**only as often as necessary**_.\n\n\n# Obtaining\n\n### Gradle\n\nAdd the following to your build.gradle\n\n    dependencies {\n        compile 'com.github.curioustechizen.android-ago:library:1.4.0'\n    }\n\n**Important:** v1.3.4 Fixed a major bug (#47). If you are using an older version, please update to at least 1.3.4 now.\n\n### Eclipse+ADT\n  1. Clone the repo\n  2. In Eclipse, go to `File` -\u003e `New` -\u003e `Other`. Expand `Android` and select `Android Project from Existing Code`\n  3. Browse to the `android-ago` sub-folder of the cloned repo and hit `Finish`\n\n\n# Usage\n  - Include `RelativeTimeTextView` in your layouts. \n  - Set the reference time either using `setReferenceTime` method or using the XML attribute `reference_time`.\n  \nIn your layout:\n```xml\n\u003ccom.github.curioustechizen.ago.RelativeTimeTextView\n    android:id=\"@+id/timestamp\"\n    android:layout_width=\"wrap_content\"\n    android:layout_height=\"wrap_content\"\n    android:layout_marginTop=\"@dimen/margin_primary\" /\u003e\n```\n\nIn your Java code:\n```java\nRelativeTimeTextView v = (RelativeTimeTextView)findViewById(R.id.timestamp); //Or just use Butterknife!\nv.setReferenceTime(new Date().getTime());\n```\n\nSee the sample project for a concrete example.\n\n## Customization\n\nBy default, this library simply calls `DateUtils.getRelativeTimeSpanString`. This might not be sufficient for you. For example, you might need to add a prefix. RTTV provides a hook for such cases - the `getRelativeTimeDisplayString` method. You can override this method and add whatever prefixes or suffixes you need.\n\nHere is a simple example:\n\n```xml\n\u003c!-- strings.xml --\u003e\n\u003cstring name=\"format_relative_time_with_prefix\"\u003eUpdated %1$s\u003c/string\u003e\n```\n\n```java\nclass PrefixRttv extends RelativeTimeTextView {\n    @Override\n    protected CharSequence getRelativeTimeDisplayString(long referenceTime, long now) {\n        final String relativeTime = super.getRelativeTimeDisplayString(referenceTime, now);\n        return getResources.getString(R.string.format_relative_time_with_prefix, relativeTime);\n    }    \n}\n```\n\nMore examples in the sample project\n\n## Advanced customization\n\nWhat if the string returned by `DateUtils.getRelativeTimeSpanString` does not suit you? Well, you can still use RTTV for its auto-refresh capability and take over complete control of the display string itself. Simply override `getRelativeTimeDisplayString` and don't call through to the `super`  method. Instead, perform your own logic and return whatever string you wish here.\n\n```xml\n\u003c!-- strings.xml --\u003e\n\u003cstring name=\"future\"\u003eSome day, in the distance future\u003c/string\u003e\n\u003cstring name=\"past\"\u003eOnce upon a time, long long ago\u003c/string\u003e\n\u003cstring name=\"now\"\u003eRight NOW!\u003c/string\u003e\n```\n\n```java\nclass FullyCustomRttv extends RelativeTimeTextView {\n    @Override\n    protected CharSequence getRelativeTimeDisplayString(long referenceTime, long now) {\n        //Notice that we don't call super here.\n        int resourceId = 0;\n        if(referenceTime == now) resourceId = R.id.now;\n        else if(referenceTime \u003e now) resourceId = R.id.future;\n        else resourceId = past;\n        \n        return getResources().getString(resourceId);\n    }    \n}\n```\n\nSee the examples in the sample project for more details.\n\n## Who's Using this Library?\n\nSee [here](https://github.com/curioustechizen/android-ago/wiki/Apps-using-android-ago). If you would like to add your app to this list, please edit the wiki.\n\n\n## Android version support statement\n\nThe 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)).\n\nThe minSdkVersion has been set to 8, however do not expect support from me for API version \u003c 11.\n\n\n# Usage with Data Binding\n\nSee `android-ago-sample-databinding` for an example of how to use this library with the Android data binding library. Thanks to @Dev-IL for providing this sample.\n\n\n### License\n\n \n\tCopyright 2017 Kiran Rao\n\n\tLicensed under the Apache License, Version 2.0 (the \"License\");\n\tyou may not use this file except in compliance with the License.\n\tYou may obtain a copy of the License at\n\n\t   http://www.apache.org/licenses/LICENSE-2.0\n\n\tUnless required by applicable law or agreed to in writing, software\n\tdistributed under the License is distributed on an \"AS IS\" BASIS,\n\tWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n\tSee the License for the specific language governing permissions and\n\tlimitations under the License.\n\n\n  [1]: screenshots/android-ago-sample-screenshot_1.4.0.png \"screenshot.png\"\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurioustechizen%2Fandroid-ago","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcurioustechizen%2Fandroid-ago","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurioustechizen%2Fandroid-ago/lists"}