If the two simple ways of storing and managing events for a calendar are not
enough, you may need to implement a custom event provider. It is the most
flexible way of providing events. You need to attach the event provider to the
Calendar
using the
setEventProvider()
method.
Event queries are done by asking the event provider for all the events between two given dates. The range of these dates is guaranteed to be at least as long as the start and end dates set for the component. The component can, however, ask for a longer range to ensure correct rendering. In particular, all start dates are expanded to the start of the day, and all end dates are expanded to the end of the day.
An event provider could use the built-in
BasicEvent
, but it is usually more proper to define
a custom event type that is bound directly to the data source. Custom
events may be useful for some other purposes as well, such as when you
need to add extra information to an event or customize how it is acquired.
Custom events must implement the CalendarEvent
interface or extend an existing event class. The built-in
BasicEvent
class should serve as a good example of
implementing simple events. It keeps the data in member variables.
public class BasicEvent implements CalendarEventEditor, EventChangeNotifier { ... public String getCaption() { return caption; } public String getDescription() { return description; } public Date getEnd() { return end; } public Date getStart() { return start; } public String getStyleName() { return styleName; } public boolean isAllDay() { return isAllDay; } public void setCaption(String caption) { this.caption = caption; fireEventChange(); } public void setDescription(String description) { this.description = description; fireEventChange(); } public void setEnd(Date end) { this.end = end; fireEventChange(); } public void setStart(Date start) { this.start = start; fireEventChange(); } public void setStyleName(String styleName) { this.styleName = styleName; fireEventChange(); } public void setAllDay(boolean isAllDay) { this.isAllDay = isAllDay; fireEventChange(); } public void addListener(EventChangeListener listener) { ... } public void removeListener(EventChangeListener listener) { ... } protected void fireEventChange() {...} }
You may have noticed that there was some additional code in the
BasicEvent
that was not in the
CalendarEvent
interface. Namely
BasicEvent
also implements two additional
interfaces:
CalendarEditor
This interface defines setters for all the fields, and is required for some of the default handlers to work.
EventChangeNotifier
This interface adds the possibility to listen for changes in
the event, and enables the Calendar
to
render the changes immediately.
The start time and end time are mandatory, but caption, description, and style name are not. The style name is used as a part of the CSS class name for the HTML DOM element of the event.
In addition to the basic event interfaces, you can enhance the
functionality of your event and event provider classes by using the
EventChange
and
EventSetChange
events. They let the
Calendar
component to know about changes in events
and update itself accordingly. The BasicEvent
and
BasicEventProvider
examples given earlier include a
simple implementation of these interfaces.
An event provider needs to implement the
CalendarEventProvider
interface. It has
only one method to be implemented. Whenever the calendar is painted,
getEvents(Date, Date)
method is called and it
must return a list of events between the given start and end time.
The following example implementation returns only one example event. The event starts from the current time and is five hours long.
public class MyEventProvider implements CalendarEventProvider{ public List<Event> getEvents(Date startDate, Date endDate){ List<Event> events = new ArrayList<Event>(); GregorianCalendar cal = new GregorianCalendar(); cal.setTime(new Date()); Date start = cal.getTime(); cal.add(GregorianCalendar.HOUR, 5); Date end = cal.getTime(); BasicEvent event = new BasicEvent(); event.setCaption("My Event"); event.setDescription("My Event Description"); event.setStart(start); event.setEnd(end); events.add(event); return events; } }
It is important to notice that the Calendar
may
query for dates beyond the range defined by start date and end
date. Particularly, it may expand the date range to make sure the user
interface is rendered correctly.