From 45a704cfa577332795ef0301f157fd480ec4be6a Mon Sep 17 00:00:00 2001 From: Till Hellmund Date: Sun, 4 Nov 2018 23:35:21 +0100 Subject: [PATCH] Update README.md --- README.md | 140 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 127 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 3e7d5342b..b0e23aca6 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,149 @@ Android Week View ================= -**Android Week View** is an Android library to display calendar views within an app. It was developed by [Raquib-ul Alam](https://github.com/alamkanak). Because it is not currently maintained and does not work when using API level 28, I’m providing this fork. +**Android Week View** is an Android library for displaying calendar views within an app. It was initially developed by [Raquib-ul Alam](https://github.com/alamkanak), but is not currently maintained and does not work when using API level 28. Therefore, I’m providing this fork. Usage --------- -1. Add JitPack repository to your build file. +1. Add the JitPack repository to your project-level build file and the dependency to the app-level build file. ```groovy +// build.gradle (project-level) allprojects { repositories { - ... - maven { url 'https://jitpack.io' } + ... + maven { url 'https://jitpack.io' } } } + +// build.gradle (app-level) +implementation 'com.github.thellmund:Android-Week-View:1.3' // Bugfix-only version +implementation 'com.github.thellmund:Android-Week-View:3.0' // Version with updated API ``` -2. Add the dependency. -```groovy -// For the bugfix-only version -implementation 'com.github.thellmund:Android-Week-View:1.3' +2. Add `WeekView` in your XML layout. +```xml + +``` + +3. Prepare the class of objects that you want to display in `WeekView` by implementing `WeekViewDisplayable`. +```java +public class CalendarItem implements WeekViewDisplayable { + + private long id; + private String title; + private DateTime startTime; + private DateTime endTime; + private String location; + private int color; + + /* ... */ + + @Override + public WeekViewEvent toWeekViewEvent() { + // Note: It's important to pass "this" as the last argument to WeekViewEvent's constructor. + // This way, the EventClickListener can return this object in its onEventClick() method. + boolean isAllDay = DateUtils.isAllDay(startTime, endTime); + return new WeekViewEvent<>( + id, title, startTime.toGregorianCalendar(), + endTime.toGregorianCalendar(), location, color, isAllDay, this + ); + } + +} +``` -// For the version with an updated API -implementation 'com.github.thellmund:Android-Week-View:2.0' +4. Configure `WeekView` in code. +```java +WeekView weekView = (WeekView) findViewById(R.id.weekView); +weekView.setOnEventClickListener(new EventClickListener() { + @Override + public void onEventClick(CalendarItem event, RectF eventRect) { + // Do something with the CalendarItem + } +}); + +// WeekView has infinite horizontal scrolling. Therefore, you need to provide the events +// of a month whenever that the currently displayed month changes. +weekView.setMonthChangeListener(new MonthLoader.MonthChangeListener() { + @Override + public List> onMonthChange(Calendar startDate, Calendar endDate) { + return mDatabase.getCalendarItemsInRange(startDate, endDate); + } +}); ``` -More info about version 2.0 here: [Release 2.0](https://github.com/thellmund/Android-Week-View/releases/tag/2.0) -Below, you find the original README by [Raquib-ul Alam](https://github.com/alamkanak). +--- + +Customization +------------------- + +Many aspects of `WeekView` and the individual event chips can be customized. + +- `allDayEventHeight`: All-day events are displayed in a header row at the top. This attributes specifies their height. If not set, these events will be set to the height of their content. +- `columnGap`: The horizontal gap between individual days. +- `dayBackgroundColor`: The background color of the current day, e.g. to emphasize it in a multi-day view. +- `eventMarginVertical`: The vertical gap between back-to-back events. +- `eventPadding`: The gap between the event title and the border of its event chip. +- `eventTextColor`: The color of the event title and location in the event chip. +- `eventTextSize`: The size of text in the event chip. +- `firstDayOfWeek`: The first day of the week. Default is Monday. +- `headerColumnBackground`: The background of the time column which is displayed on the left-hand side. +- `headerColumnPadding` +- `headerColumnTextColor`: The color of the hour text in the time column. +- `headerRowBackgroundColor`: The background color of the header row which runs at the top of `WeekView`. +- `headerRowPadding`: The padding within the header row. +- `hourHeight`: The height with with one hour is displayed. Default is 50dp. +- `hourSeparatorColor`: The color of the horizontal lines that indicate the hours. +- `hourSeparatorHeight`: The height of the horizontal hour lines. +- `noOfVisibleDays`: The number of days that are visible. Default is 3. +- `overlappingEventGap`: The horizontal gap between events that occur concurrently. +- `textSize`: The text size used for text in the time column and the days row, which contains the currently displayed days. +- `todayBackgroundColor`: The background color of the current day. +- `todayHeaderTextColor`: The text color of the current day in the days row. +- `showDistinctPastFutureColor`: Indicates whether distinct background colors should be used for past and future days. Default is false. +- `futureBackgroundColor`: The background color to use for future days. Requires `showDistinctPastFutureColor` to be true. +- `pastBackgroundColor`: The background color to use for past days. Requires `showDistinctPastFutureColor` to be true. +- `showDistinctWeekendColor`: Indicates whether weekends should be marked with a distinct color. Default is false. +- `futureWeekendBackgroundColor`: The background color of future weekend days. Requires `showDistinctWeekendColor` to be true. +- `pastWeekendBackgroundColor`: The background color of past weekend days. Requires `showDistinctWeekendColor` to be true. +- `showNowLine`: Indicates whether a horizontal line should be displayed at the current time. Default is false. +- `nowLineColor`: The color of the now line. +- `nowLineThickness`: The height of the now line. +- `scrollDuration`: The duration of automatic scrolling. The value determines how fast `WeekView` scrolls to a particular day. --- -Android Week View +Customization +------------------- + +The following interfaces are used to provide data and interactability to `WeekView`. +- `setMonthChangeListener()` to provide events to the calendar by months +- `setOnEventClickListener()` to get a callback when an event is clicked +- `setEventLongPressListener()` to get a callback when an event is long pressed +- `setDateTimeInterpreter()` to set your own labels for the calendar header row and header column +- `setWeekViewLoader()` to provide events to the calendar +- `setEmptyViewClickListener()` to get a callback when any empty space is clicked +- `setEmptyViewLongPressListener()` to get a callback when any empty space is long pressed +- `setScrollListener()` to get an event every time the first visible day has changed + +--- + +[Original README] Android Week View ================= ![](images/screen-shot.png)