Home

Getting started with WeekView

Add the JitPack repository to your project-level build.gradle file.

allprojects {
  repositories {
    // your other repositories ...
    maven { url 'https://jitpack.io' }
  }
}

WeekView requires at minimum Java 8 and Android API 15. Make sure you include the following in your module-level build.gradle file.

android {
  // ...
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
  kotlinOptions {
    jvmTarget = "1.8"
  }
}

Then, add the dependency for WeekView to your module-level build.gradle file.

implementation 'com.github.thellmund.Android-Week-View:core:5.2.4'

If you use the Java 8 Date/Time API (JSR310), JodaTime or ThreeTenABP, you can add the following additional dependencies to use LocalDate and LocalDateTime instead of Calendar.

Note: JodaTime and ThreeTenABP are no longer actively maintained. It’s best to opt for the Java 8 Date/Time API and core library desugaring.

// Add this module to use WeekView with the Java 8 Date/Time API. This module
// uses core library desugaring, making it available on API 21 and above.
implementation 'com.github.thellmund.Android-Week-View:jsr310:5.2.4'

// The development of JodaTime and ThreeTenABP are winding down. 
// It’s best to opt for the Java 8 Date/Time API.
implementation 'com.github.thellmund.Android-Week-View:jodatime:5.2.4'
implementation 'com.github.thellmund.Android-Week-View:threetenabp:5.2.4'

To allow emojis in the titles and subtitles of your events, add the following dependency.

implementation 'com.github.thellmund.Android-Week-View:emoji:5.2.4'

Usage

To use WeekView, perform the following steps: To use WeekView, perform the following steps:

1. Add WeekView to your XML layout file
2. Create an adapter
3. Provide data to WeekView
4. Interact with WeekView

Finally, I recommend to become familiar with the WeekView nomenclature.

---

1. Add WeekView to your layout

You need to add a WeekView in your XML layout file. You can customize the appearance with these attributes.

Tip: Whenever you make changes, the layout preview in Android Studio will update automatically.

<com.alamkanak.weekview.WeekView
  android:id="@+id/weekView"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  app:defaultEventColor="@color/primaryColor"
  app:eventTextColor="@color/white"
  app:timeColumnTextSize="12sp"
  app:hourHeight="60dp"
  app:timeColumnPadding="8dp"
  app:timeColumnTextColor="@color/light_blue"
  app:timeColumnBackgroundColor="@color/white"
  app:headerPadding="12dp"
  app:columnGap="8dp"
  app:numberOfVisibleDays="3"
  app:headerBackgroundColor="@color/light_gray"
  app:dayBackgroundColor="@color/white"
  app:todayBackgroundColor="@color/light_blue" />

---

2. Create an adapter

You need to hook up WeekView with an adapter. Implement WeekView.SimpleAdapter or WeekView.PagingAdapter based on your desired pagination behavior.

Simple Adapter

This adapter allows to you submit a single list of elements to WeekView. Whenever you submit a new list, the previously submitted list will be replaced.

data class MyEvent(
  val id: Long,
  val title: String, 
  val startTime: Calendar, 
  val endTime: Calendar
)

class MyCustomSimpleAdapter : WeekView.SimpleAdapter<MyEvent>() {
  
  override fun onCreateEntity(
    context: Context, 
    item: MyEvent
  ): WeekViewEntity {
    return WeekViewEntity.Event.Builder(item)
      .setId(item.id)
      .setTitle(item.title)
      .setStartTime(item.startTime)
      .setEndTime(item.endTime)
      .build()
  }
}

Paging Adapter

This adapter allows you to submit elements to WeekView in a paginated way. Previously submitted elements are cached. If the user scrolls to a date range that hasn’t been cached, a callback to onLoadMore will be dispatched.

data class MyEvent(
  val id: Long,
  val title: String, 
  val startTime: Calendar, 
  val endTime: Calendar
)

class MyCustomPagingAdapter(
  private val loadMoreHandler: LoadMoreHandler
) : WeekView.PagingAdapter<MyEvent>() {
  
  override fun onCreateEntity(
    context: Context, 
    item: MyEvent
  ): WeekViewEntity {
    return WeekViewEntity.Event.Builder(item)
      .setId(item.id)
      .setTitle(item.title)
      .setStartTime(item.startTime)
      .setEndTime(item.endTime)
      .build()
  }
  
  override fun onLoadMore(startDate: Calendar, endDate: Calendar) {
    loadMoreHandler.loadMore(startDate, endDate)
  }
}

JodaTime, JSR310 and ThreeTenABP

If you use WeekView with JodaTime, the Java 8 Date API (JSR310) or ThreeTenABP, you can use custom adapters instead of WeekView.SimpleAdapter<T> and WeekView.PagingAdapter<T>.

• JodaTime: Extend WeekViewSimpleAdapterJodaTime<T> or WeekViewPagingAdapterJodaTime<T>.
• JSR310: Extend WeekViewSimpleAdapterJsr310<T> or WeekViewPagingAdapterJsr310<T>.
• ThreeTenABP: Extend WeekViewSimpleAdapterThreeTenAbp<T> or WeekViewPagingAdapterThreeTenAbp<T>.

---

To provide data to WeekView, you need to submit a list of elements to its adapter.

data class MyEvent(
  val id: Long,
  val title: String, 
  val startTime: Calendar, 
  val endTime: Calendar
)

class BasicViewModel : ViewModel() {
  private val _events = MutableLiveData<List<MyEvent>>()
  val events: LiveData<List<MyEvent>> = _events
  
  // ...
}

class BasicActivity : AppCompatActivity() {
  private val viewModel by viewModels<BasicViewModel>()
  
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_basic)
    
    val adapter = MyCustomPagingAdapter<Event>()
    weekView.adapter = adapter
    
    viewModel.events.observe(this) { events ->
      adapter.submitList(events)
    }
  }
}

---

4. Interact with WeekView

You can enable interaction with WeekView and overriding any of the following methods in its adapter:

class MyCustomPagingAdapter : WeekView.PagingAdapter<MyEvent>() {
  fun onEventClick(data: MyEvent)
  fun onEventClick(data: MyEvent, bounds: RectF)
  fun onEventLongClick(data: MyEvent)
  fun onEventLongClick(data: MyEvent, bounds: RectF)
  fun onEmptyViewClick(time: Calendar)
  fun onEmptyViewLongClick(time: Calendar)
  fun onRangeChanged(firstVisibleDate: Calendar, lastVisibleDate: Calendar)
}