Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
kizitonwose committed Jul 11, 2020
1 parent 00cac7b commit 6bb40d5
Show file tree
Hide file tree
Showing 3 changed files with 65 additions and 55 deletions.
109 changes: 65 additions & 44 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,21 +34,67 @@ Download the sample app [here](https://github.com/kizitonwose/CalendarView/relea

View the sample app's source code [here](https://github.com/kizitonwose/CalendarView/tree/master/sample)

## Usage
## Setup

#### Step 1

The library uses `java.time` classes via [ThreeTenABP](https://github.com/JakeWharton/ThreeTenABP) for backward compatibility since these classes were added in Java 8. Therefore, you need to initialize ThreeTenABP in your application class.
The library uses `java.time` classes via [API desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) for backward compatibility since these classes were added in Java 8.

```kotlin
class SampleApp : Application() {
override fun onCreate() {
super.onCreate()
AndroidThreeTen.init(this)
}
To setup your project for desugaring, you need to first ensure that you are using [Android Gradle plugin](https://developer.android.com/studio/releases/gradle-plugin#updating-plugin) 4.0.0 or higher.

Then include the following in your app's build.gradle file:

```groovy
android {
defaultConfig {
// Required ONLY when setting minSdkVersion to 20 or lower
multiDexEnabled true
}
compileOptions {
// Flag to enable support for the new language APIs
coreLibraryDesugaringEnabled true
// Sets Java compatibility to Java 8
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
dependencies {
coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:<latest-version>'
}
```

You can find the latest version of `desugar_jdk_libs` [here](https://mvnrepository.com/artifact/com.android.tools/desugar_jdk_libs).

#### Step 2

Add the JitPack repository to your project level `build.gradle`:

```groovy
allprojects {
repositories {
google()
jcenter()
maven { url "https://jitpack.io" }
}
}
```

Add CalendarView to your app `build.gradle`:

```groovy
dependencies {
implementation 'com.github.kizitonwose:CalendarView:<latest-version>'
}
```

**You can find the latest version of `CalendarView` on the JitPack badge above the preview images.**

## Usage

#### Step 1

Add CalendarView to your XML like any other view.

```xml
Expand All @@ -60,8 +106,6 @@ Add CalendarView to your XML like any other view.
```
See all available [attributes](#attributes).

#### Step 2

Create your day view resource in `res/layout/calendar_day_layout.xml`.

```xml
Expand All @@ -78,11 +122,11 @@ Create your view container which acts as a view holder for each date cell.
The view passed in here is the inflated day view resource which you provided.

```kotlin
class DayViewContainer(view: View) : ViewContainer(view) {
val textView = view.calendarDayText
// Without the kotlin android extensions plugin
// val textView = view.findViewById<TextView>(R.id.calendarDayText)
class DayViewContainer(view: View) : ViewContainer(view) {
val textView = view.findViewById<TextView>(R.id.calendarDayText)

// With ViewBinding
// val textView = CalendarDayLayoutBinding.bind(view).calendarDayText
}
```

Expand All @@ -100,7 +144,7 @@ calendarView.dayBinder = object : DayBinder<DayViewContainer> {
}
```

#### Step 3
#### Step 2

Setup the desired dates in your Fragment or Activity:

Expand Down Expand Up @@ -241,37 +285,16 @@ Remember that all the screenshots above are just examples of what you can achiev

**Made a cool calendar with this library? Share an image [here](https://github.com/kizitonwose/CalendarView/issues/1).**

## Setup

### Gradle

Add the JitPack repository to your project level `build.gradle`:

```groovy
allprojects {
repositories {
google()
jcenter()
maven { url "https://jitpack.io" }
}
}
```

Add this to your app `build.gradle`:

```groovy
dependencies {
implementation 'com.github.kizitonwose:CalendarView:<latest-version>'
}
```
**Note: `<latest-version>` value can be found on the JitPack badge above the preview images.**

## FAQ

**Q**: How do I use this library in a Java project?

**A**: It works out of the box, however, the `MonthScrollListener` is not an interface but a Kotlin function. To set the `MonthScrollListener` in a Java project see [this](https://github.com/kizitonwose/CalendarView/issues/74).

**Q**: How do I disable user scrolling on the calendar so I can only scroll programmatically?

**A**: See [this](https://github.com/kizitonwose/CalendarView/issues/38#issuecomment-525786644).

**Q**: Why am I getting the same `YearMonth` value in the `CalendarMonth` passed into the `MonthScrollListener`?

**A**: This is because you have set `app:cv_hasBoundaries` to `false` in XML or have called `calendarView.hasBoundaries = false` in code. When this is set, the underlying `YearMonth` is undefined on all indices as each index could have multiple months depending on your `maxRowCount` value. If you need the month value with the `hasBoundaries = false` setting, you can get it from any of the `CalendarDay` values in the `CalendarMonth` class. You can always check if the first and last dates are from different months and act accordingly.
Expand All @@ -282,10 +305,8 @@ Found a bug? feel free to fix it and send a pull request or [open an issue](http

## Inspiration

CalendarView was inspired by the iOS library [JTAppleCalendar][jt-cal-url]. I used JTAppleCalendar in an iOS project but couldn't find anything as customizable on Android so I built this.
CalendarView was inspired by the iOS library [JTAppleCalendar][https://github.com/patchthecode/JTAppleCalendar]. I used JTAppleCalendar in an iOS project but couldn't find anything as customizable on Android so I built this.
You'll find some similar terms like `InDateStyle`, `OutDateStyle`, `DayOwner` etc.

## License
CalendarView is distributed under the MIT license. See [LICENSE](https://github.com/kizitonwose/CalendarView/blob/master/LICENSE.md) for details.

[jt-cal-url]: https://github.com/patchthecode/JTAppleCalendar
1 change: 0 additions & 1 deletion sample/src/main/AndroidManifest.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@
package="com.kizitonwose.calendarviewsample">

<application
android:name=".CalendarViewApp"
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
Expand Down

This file was deleted.

0 comments on commit 6bb40d5

Please sign in to comment.