📅 Customizable, animated calendar widget including day & week views.

| Event positioning demo | Dark mode & custom range | | :--------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------: | | | |

• Getting started
  • 1. Initialize time_machine
  • 2. Define your

    Event

    s
  • 3. Create an

    EventProvider

  • 4. Create a

    TimetableController

  • 5. Create your

    Timetable

• Theming
• Features & Coming soon

Getting started

1. Initialize time_machine

This package uses time_machine for handling date and time, which you first have to initialize.

Add this to your

pubspec.yaml

yaml
flutter:
  assets:
    - packages/time_machine/data/cultures/cultures.bin
    - packages/time_machine/data/tzdb/tzdb.bin

Modify your

main.dart

main()

void main() async { // Call these two functions before

runApp()

runApp(MyApp()); } ``` ^{Source: https://pub.dev/packages/time_machine#flutter-specific-notes}

2. Define your

Event

s

Events are provided as instances of

Event

BasicEvent

Event

Note: Most classes of timetable accept a type-parameter

E extends Event

. Please set it to your chosen

Event

-subclass (e.g.

BasicEvent

) to avoid runtime exceptions.

In addition, you also need a

Widget

BasicEvent

BasicEventWidget

3. Create an

EventProvider

As the name suggests, you use

EventProvider

Event

EventProvider

• EventProvider.list(List events)

  : If you have a non-changing list of events.

• EventProvider.simpleStream(Stream> eventStream)

  : If you have a limited, changing list of events.

• EventProvider.stream({StreamedEventGetter eventGetter})

  : If your events can change or you have many events and only want to load the relevant subset.

final myEventProvider = EventProvider.list([
  BasicEvent(
    id: 0,
    title: 'My Event',
    color: Colors.blue,
    start: LocalDate.today().at(LocalTime(13, 0, 0)),
    end: LocalDate.today().at(LocalTime(15, 0, 0)),
  ),
]);

For trying out the behavior of changing events, you can create a

StreamController>

add()

Future.delayed()

final eventController = StreamController>()..add([]);
final provider = EventProvider.simpleStream(eventController.stream);
Future.delayed(Duration(seconds: 5), () => eventController.add(/* some events */));

// Don't forget to close the stream controller when you're done, e.g. in dispose:
eventController.close();

See the example for more

EventProvider

samples!

4. Create a

TimetableController

Similar to a

ScrollController

TabController

TimetableController

Timetable

EventProvider

final myController = TimetableController(
  eventProvider: myEventProvider,
  // Optional parameters with their default values:
  initialTimeRange: InitialTimeRange.range(
    startTime: LocalTime(8, 0, 0),
    endTime: LocalTime(20, 0, 0),
  ),
  initialDate: LocalDate.today(),
  visibleRange: VisibleRange.week(),
  firstDayOfWeek: DayOfWeek.monday,
);

Don't forget to

dispose

your controller, e.g. in

State.dispose

!

5. Create your

Timetable

Using your

TimetableController

Timetable

Timetable(
  controller: myController,
  eventBuilder: (event) => BasicEventWidget(event),
  allDayEventBuilder: (context, event, info) =>
      BasicAllDayEventWidget(event, info: info),
)

And you're done 🎉

Theming

For a full list of visual properties that can be tweaked, see

TimetableThemeData

To apply a theme, specify it in the

Timetable

Timetable(
  controller: /* ... */,
  theme: TimetableThemeData(
    primaryColor: Colors.teal,
    partDayEventMinimumDuration: Period(minutes: 30),
    // ...and many more!
  ),
),

Localization

time_machine is used internally for date & time formatting. By default, it uses

en_US

Culture

Culture.current

TimeMachine.initialize

// Supported cultures: https://github.com/Dana-Ferguson/time_machine/tree/master/lib/data/cultures
Culture.current = await Cultures.getCulture('de');

To automatically react to locale changes of the app, see Dana-Ferguson/time_machine#28.

Note: A better solution for Localization is already planned.

Features & Coming soon

• [x] Smartly arrange overlapping events
• [x] Zooming
• [x] Selectable

  VisibleRange

  s
• [x] Display all-day events at the top
• [x] Theming
• [ ] Animate between different

  VisibleRange

  s: see #17
• [ ] Month-view, Agenda-view: see #17
• [x] Listener when tapping the background (e.g. for creating an event)
• [ ] Support for event resizing