Views topic

Views

This is part of the kalender documentation.

The view configuration decides which calendar you get and how it behaves when you switch away from it. For what the user can do inside a view, see Interaction.

Switching between views

Switch between views by setting a different ViewConfiguration on KalenderController.viewConfiguration. What carries over on a switch is controlled per dimension:

Date (all views): dateTransition. Use DateTransition.carryFocus (default, follows your current date) or DateTransition.restorePerView (each view reopens its own last date, matched by name).
Scroll & zoom (multi-day views): scrollTransition / zoomTransition. Use preserve (default), reset, or restorePerView.

For custom logic, provide a dateResolver / scrollResolver / zoomResolver. Each overrides the matching enum, and a null from scrollResolver or zoomResolver falls back to it. kCarryFocusDate(transition) gives you the default carry-focus date to build on.

initialDateTime is only read when the controller is created. To show a fixed date on a switch, return it from a dateResolver. The resolvers also run when the location changes, which transition.locationChanged reports.

Shared options

All configurations accept:

displayRange: the total date range the calendar can navigate within (e.g. Jan 2024 to Dec 2025). Defaults to 1 January two years back through 1 January two years ahead.
initialDateTime: the date the controller's view opens on. Defaults to today in the controller's location.
multiDayRule: which events go in the multi-day header, see Multi-day and all-day events.
name: identifies the configuration. ViewParts.name and the restorePerView transitions match on it, so it must be unique among the configurations an app switches between. Each named constructor sets one.
nowCallback: overrides how the calendar resolves "now", see Now Callback.

MultiDayViewConfiguration.week(
  displayRange: KalenderDateTimeRange(
    start: DateTime(2024, 1, 1),
    end: DateTime(2025, 12, 31),
  ),
  initialDateTime: DateTime(2024, 6, 15),
)

MultiDay View

Displays one or more days with time on the vertical axis.

Constructor	Description
`MultiDayViewConfiguration.singleDay()`	Single day
`MultiDayViewConfiguration.week()`	A week, 7 days by default
`MultiDayViewConfiguration.workWeek()`	Monday to Friday, 5 days by default
`MultiDayViewConfiguration.custom(numberOfDays: n)`	Custom number of days
`MultiDayViewConfiguration.freeScroll(numberOfDays: n)`	Scrolls freely across days, without page snaps

These views also control which hours exist, where the day opens vertically, and how tall an hour is:

timeOfDayRange: the hours the body lays out. Defaults to KalenderTimeRange.allDay(), which is 00:00 to 23:59. Narrowing it makes the page shorter. Events outside it are clipped. Narrow it only when events cannot fall outside it.
initialTimeOfDay: the time at the top of the viewport when the view opens. Defaults to midnight. A time outside timeOfDayRange opens at its nearest end.
initialHeightPerMinute: the starting zoom, in logical pixels per minute. Defaults to 0.7, giving a 42 pixel hour. Change it later through the controller, see Zoom.
firstDayOfWeek: which day a week starts on, as DateTime.monday through DateTime.sunday. Defaults to DateTime.monday. Applies to week, singleDay and custom. workWeek and freeScroll fix it themselves.
numberOfDays: how many days a page shows. week and workWeek take 1 through 7 and drop days off the end of the page without changing the pagination, so week(numberOfDays: 6) shows Monday to Saturday and still turns a week at a time. custom and freeScroll require it and page by it, so they take any number. singleDay fixes it at 1.

MultiDayViewConfiguration.week(
  // Working hours only. The timeline runs 08:00 to 18:00 and nothing else exists.
  timeOfDayRange: KalenderTimeRange(
    start: const KalenderTime(hour: 8, minute: 0),
    end: const KalenderTime(hour: 18, minute: 0),
  ),
  initialTimeOfDay: const KalenderTime(hour: 8, minute: 0),
  initialHeightPerMinute: 0.7,
  firstDayOfWeek: DateTime.sunday,
)

Month View

Shows a whole month, weeks as rows.

Constructor	Description
`MonthViewConfiguration.singleMonth()`	Single month

Month view can be adjusted with firstDayOfWeek and showWeekNumbers:

MonthViewConfiguration.singleMonth(
  initialDateTime: DateTime(2025, 1, 1),
  firstDayOfWeek: DateTime.monday,
  showWeekNumbers: true,
)

When showWeekNumbers is enabled, the month body adds a column on the leading side with one week number per visible row while keeping the day grid at 7 columns.

Schedule View

Presents events in a chronological scrollable list.

Constructor	Description
`ScheduleViewConfiguration.continuous()`	Single continuous list
`ScheduleViewConfiguration.paginated()`	Paginated by month

Headers and bodies

KalenderView shows a header above a body. Its views list holds one ViewParts per kind of view, and the parts that accept the controller's configuration decide what is shown. The default list holds all three built-in parts:

Parts	Built-in header	Built-in body
`MultiDayViewParts`	`MultiDayHeader`	`MultiDayBody`
`MonthViewParts`	`MonthHeader`	`MonthBody`
`ScheduleViewParts`	None	`ScheduleBody`

A null header or body shows the built-in widget, and SizedBox.shrink() shows nothing. Any widget can be a header or a body, so either can wrap the built-in one, for example to put a toolbar above the header. The built-in widgets work only inside a KalenderView.

The list needs parts for every kind of configuration the controller shows. Parts with a name show only the configuration with that name, and come before the unnamed parts of their kind. Use this when two configurations of one kind, such as a week and a day, need different parts:

KalenderView(
  eventsController: eventsController,
  kalenderController: kalenderController,
  views: [
    // Shown for the configuration named 'Day'.
    const MultiDayViewParts(name: 'Day', header: SizedBox.shrink()),
    // Shown for every other multi-day configuration.
    MultiDayViewParts(header: Column(children: [CustomWidget(), const MultiDayHeader()])),
    const MonthViewParts(),
    const ScheduleViewParts(),
  ],
)

Per-view configuration

The built-in header and body widgets accept view-specific configuration objects:

View	Header config class	Body config class
MultiDay	`MultiDayHeaderConfiguration`	`MultiDayBodyConfiguration`
Month	None	`MonthBodyConfiguration`
Schedule	None	`ScheduleBodyConfiguration`

MultiDayHeader and the bodies also accept callbacks, interaction and tileComponents (see Appearance), and MonthHeader accepts callbacks. See Interaction for interaction and snapping. An event dragged from the header into the body reports onEventChange to the header's callbacks and onEventChanged to the body's.

Every option below is shown at its default.

MultiDayHeaderConfiguration

MultiDayHeader(
  configuration: MultiDayHeaderConfiguration(
    showTiles: true,
    allowSingleDayEvents: false,
    tileHeight: 24,
    eventPadding: EdgeInsets.only(left: 0, right: 4, bottom: 2),
    pageTriggerConfiguration: PageTriggerConfiguration(),
    // See Layout for writing your own.
    multiDayLayoutStrategy: const MultiDayLayoutStrategy.byDuration(),
    // Null means no cap on the rows of events shown per day.
    maximumNumberOfVerticalEvents: null,
  ),
)

MultiDayBodyConfiguration

MultiDayBody(
  configuration: MultiDayBodyConfiguration(
    showMultiDayEvents: false,
    horizontalPadding: EdgeInsets.only(left: 0, right: 4),
    eventLayoutStrategy: const EventLayoutStrategy.overlap(),
    pageTriggerConfiguration: PageTriggerConfiguration(),
    scrollTriggerConfiguration: ScrollTriggerConfiguration(),
    keepPagesAlive: false,
    // Null lets a tile be as short as its duration. Set a floor, e.g. 24, to
    // keep short events readable.
    minimumTileHeight: null,
    // Null uses the ambient physics. Set your own, e.g. BouncingScrollPhysics().
    scrollPhysics: null,
    pageScrollPhysics: null,
  ),
)

MonthBodyConfiguration

MonthBody(
  configuration: MonthBodyConfiguration(
    tileHeight: 24,
    eventPadding: EdgeInsets.only(left: 0, right: 4, bottom: 2),
    pageTriggerConfiguration: PageTriggerConfiguration(),
    // See Layout for writing your own.
    multiDayLayoutStrategy: const MultiDayLayoutStrategy.byDuration(),
  ),
)

ScheduleBodyConfiguration

ScheduleBody(
  configuration: ScheduleBodyConfiguration(
    emptyDay: EmptyDayBehavior.showOnlyToday,
    leadingWidth: 56,
    pageTriggerConfiguration: PageTriggerConfiguration(),
    scrollTriggerConfiguration: ScrollTriggerConfiguration(),
    // Null uses the ambient physics. Set your own, e.g. BouncingScrollPhysics().
    scrollPhysics: null,
    pageScrollPhysics: null,
  ),
)

Classes

ContinuousScheduleIndexCalculator Views: Calculates page indices and date ranges for a continuous schedule view.
CustomIndexCalculator Views: Calculates page indices and date ranges for a custom multi-day view.
DayIndexCalculator Views: Calculates page indices and date ranges for a single day view.
HorizontalConfiguration Views: The base class for all horizontal views of the calendar.
KalenderView Views: A calendar that shows the events of eventsController in the view kalenderController holds.
KalenderViewState Views: The state of a KalenderView. It holds the ViewController the view shows.
MonthBody Views: The weeks of a month view, one page per month. The default body of MonthViewParts.
MonthBodyConfiguration Views: The configuration of a MonthBody.
MonthHeader Views: The weekday names above a MonthBody. The default header of MonthViewParts.
MonthIndexCalculator Views: Calculates page indices and date ranges for a month view.
MonthViewConfiguration Views
MonthViewParts Views: The parts of a MonthViewConfiguration: a MonthHeader and a MonthBody by default.
MonthWeek Views: A single week in the month view.
MultiDayBody Views: The scrollable body of a multi-day view: a timeline and one column of events per day. The default body of MultiDayViewParts.
MultiDayBodyConfiguration Views: The configuration used by the MultiDayBody.
MultiDayHeader Views: The day headers and multi-day events above a MultiDayBody. The default header of MultiDayViewParts.
MultiDayHeaderConfiguration Views: The configuration used by the MultiDayHeader.
MultiDayPage Views
MultiDayViewConfiguration Views: The configuration used by the MultiDayBody and MultiDayHeader.
MultiDayViewParts Views: The parts of a MultiDayViewConfiguration: a MultiDayHeader and a MultiDayBody by default.
PageIndexCalculator Views: Calculates page indices and date ranges for paginated calendar views.
PaginatedSchedule Views: A PageView of SchedulePositionLists for a PaginatedScheduleViewController.
PaginatedScheduleIndexCalculator Views: Calculates page indices and date ranges for a paginated schedule view.
ScheduleBody Views: Displays events as a vertical list. The default body of ScheduleViewParts.
ScheduleBodyConfiguration Views
SchedulePositionList Views: A scrollable list of the schedule items in range, tracking the position of every item.
ScheduleViewConfiguration Views
ScheduleViewParts Views: The parts of a ScheduleViewConfiguration: a ScheduleBody and no header by default.
VerticalConfiguration Views: The base class for all vertical views of the calendar.
ViewConfiguration Views: The base class for all ViewConfigurations.
ViewParts<C extends ViewConfiguration> Views: The header and body KalenderView shows for a kind of ViewConfiguration.
ViewSnapshot Views: What a view shows, as returned by ViewController.snapshot.
ViewTransitionContext Views: The inputs available when resolving how a view switch or a location change should transfer state.
WeekIndexCalculator Views: Calculates page indices and date ranges for a week view.

Constants

kDefaultEmptyDayBehavior → const EmptyDayBehavior Views
kDefaultFirstDayOfWeek → const int Views
kDefaultHeightPerMinute → const double Views
kDefaultHorizontalPadding → const EdgeInsets Views
kDefaultInitialTimeOfDay → const KalenderTime Views
kDefaultMultiDayEventPadding → const EdgeInsets Views
kDefaultScheduleLeadingWidth → const double Views: The default width of the leading (date) column in the schedule view.
kDefaultShowEventTiles → const bool Views
kDefaultShowMultiDayEvents → const bool Views
kDefaultTileHeight → const double Views

Functions

kCarryFocusDate(ViewTransitionContext transition) → FloatingDateTime Views: The date the previous view focused on, from its ViewController.snapshot. Used by DateTransition.carryFocus.
kDefaultRange() → KalenderDateTimeRange Views
kDefaultToDaily(ViewController old) → FloatingDateTime Views: The date old focused on.
kDefaultToMonthly(ViewController old) → FloatingDateTime Views: The date old focused on.
kDefaultToSchedule(ViewController old) → FloatingDateTime Views: The date old focused on.
kDefaultToWeekly(ViewController old) → FloatingDateTime Views: The date old focused on.

Enums

DateTransition Views: How the horizontal date is chosen when switching to a view.
EmptyDayBehavior Views: The default behavior for empty days in the schedule view.
MultiDayViewType Views
ScheduleViewType Views: The type of the schedule view.
ScrollTransition Views: How the vertical scroll position (time-of-day) is chosen when switching to a multi-day view.
ZoomTransition Views: How the zoom (heightPerMinute) is chosen when switching to a multi-day view.

Typedefs

DateResolver = FloatingDateTime Function(ViewTransitionContext transition) Views: Resolves the initial date for the incoming view. Overrides DateTransition.
NowCallback = DateTime Function() Views: A callback that returns the current DateTime representing "now" for the calendar.
ScrollResolver = KalenderTime? Function(ViewTransitionContext transition) Views: Resolves the time of day the incoming multi-day view opens on. A null result falls back to ScrollTransition.
ZoomResolver = double? Function(ViewTransitionContext transition) Views: Resolves the zoom (heightPerMinute) the incoming multi-day view opens on. A null result falls back to ZoomTransition.

Views topic

Views

Switching between views

Shared options

MultiDay View

Month View

Schedule View

Headers and bodies

Per-view configuration

Classes

Constants

Functions

Enums

Typedefs

kalender package

Views topic