CalendarView

Documentation Index

• Introduction
• API
• To do

Introduction

This document describes the API and usage of the classes in CalendarView.

CalendarView is a collection of JAVA classes which are useful for the display of calendars. The first version, using JAVA 1.0, is available for free use. Future versions will be distributed as a package using JAVA 1.1 and transitioning to JFC. They will include better documentation and the source to a fully functional client/server date book application suitable for small businesses. These versions will be available from Odin Consulting.

CalendarView Beta 1.0 is available for free download. Click here for a JAR file containing the source code. Click here to get the JAR file containing the precompiled classes.

All versions of CalendarView 1.0 are distributed under the terms of my "LinkWare" license. Subject to the terms of this license, you are free to use CalendarView 1.0 for any purpose. All I ask is that if you redistribute copies of CalendarView 1.0 in their original or modified form, include a link or pointer to my site.

API

• Calendar Containers
• Calendar Views
• Calendar Interactors

• Calendar Date Class
• Tabbed Dialog Component
• Year Entry Box Component
• Miscellaneous

Calendar Containers

CalendarView contains a YearTextField centered over a calendar display component. The display component must implement CalendarViewDisplay.

CalendarView registers its display component as a YearListener for the YearTextField. In turn, CalendarView registers itself as the DateStartListener for the display component and will update the text field as necessary.

• CalendarView()
  
  
  Constructor. When the zero argument constructor is used, the CalendarView must be initialized by calling one of the setView methods.



• CalendarView(CalendarViewDisplay View)
  
  
  Constructor which initializes the display component to View showing today's date.



• CalendarView(CalendarViewDisplay View,CalendarDate Init)
  
  
  Constructor which initializes the display component to View showing Init.



• public void setView(CalendarViewDisplay View)
  
  
  Set the display component to View. If a previous display component had been set, have View continue to show the same selected date as that component. Otherwise, have View show today's date.



• public void setView(CalendarViewDisplay View,CalendarDate fallback)
  
  
  Set the display component to View. If a previous display component had been set, have View continue to show the same selected date as that component. Otherwise, have View show fallback.

An interface which must be implemented by components which are to be contained by the CalendarView class.

• public void installWidgets(CalendarDate selected)
  
  
  Initialize any components contained by the display component. selected is the initially selected date. This method is called whenever the setView method in CalendarView is invoked.



• public void removeAll()
  
  
  Remove all components from the display. If the CalendarView implementation extends Container, then this method will be inherited from Container.



• public CalendarDate getSelectedDate()
  
  
  Return the currently selected date.



• public void setDateStartListener(DateStartListener listener)
  
  
  Set the date start listener. The date start listener must be notified by the display component whenever the starting date displayed by the component changes. For instance, the CalendarWeekView uses arrow buttons to allow the user to display the previous or the next week. Whenever one of these buttons is pressed, the date start listener is informed of the new start date.



• public DateStartListener getDateStartListener()
  
  
  Return the date start listener.

An interface which must be implemented by interactor components which are to be contained by the CalendarView class. See CalendarDayInteractor as an example of an interactor component.

• public void acceptChanges()
  
  
  Accept any changes made by the user. This method should cause the changes to be recorded for later use. Changes may be recorded at other times even when this method is not called at the component's own discretion.



• public void discardChanges()
  
  
  Discard any changes made by the user since the last time changes were recorded. Revert the display back to the last recorded values.

A DateStartListener may be registered with a CalendarViewDisplay. The DateStartListener will be notified each time the starting date of the calendar view has changed.

• public void newDateStart(CalendarDate dateBefore,CalendarDate dateAfter)
  
  
  Change the date from dateBefore to dateAfter.

Calendar Views

A compound component which presents a view of an entire month of the calendar at once. The component contains a tabbed dialog box with a tab for each month in the year. Each month is an instance of the CalendarMonthViewDays component.

• public CalendarMonthView(MonthDayHandler Handler)
  
  
  Constructor. Pass Handler to each CalendarMonthViewDays component.

A compound component which presents a view of a week. The component contains a left ButtonArrow and a right ButtonArrow centered over a label which states the date range covered by the week. Underneath these is an instance of the CalendarWeekViewDays component.

Clicks on the left arrow will cycle the display backward through time by a week per click. Clicks on the right arrow will cycle the display forward through time by a week per click.

• public CalendarWeekView(WeekDayHandler Handler)
  
  
  Constructor. Pass Handler to the CalendarWeekViewDays component.

Calendar Interactors

A compound component which presents an interactive view of a single day in the calendar. The component contains a title label, a left ButtonArrow, the current date and a right ButtonArrow centered over a component which implements the DayInteractorComponent interface.

The CalendarDayInteractor compound component allows direct user interaction with the calendar contents for the selected date, but does not provide any native support for doing so. This task is left up to the programmer implementing the DayInteractorComponent. The example uses a subclass of TextArea extended to add the interface methods.

• public CalendarDayInteractor(DayInteractorComponent Handler)
  
  
  Constructor. Use Handler to display the calendar contents and interact with the user. Displays the default title, "Today's Calendar".



• public CalendarDayInteractor(DayInteractorComponent Handler,String Title)
  
  
  Constructor. Use Handler to display the calendar contents and interact with the user. Displays Title centered at the top.

An interface which must be implemented by the component used to provide user interaction in the CalendarDayInteractor.

• public void setSelectedDate(CalendarDate Selected)
  
  
  Reset contents to reflect the Selected date.



• public void acceptChanges()
  
  
  Record current contents. The implementor of DayInteractorComponent is not required to wait for an invocation of this method to record changes.



• public void discardChanges()
  
  
  Discard current contents. The implementor of DayInteractorComponent is not required to wait for an invocation of this method to discard changes.

Renders a single month in standard U.S. calendar notation. A MonthDayHandler must be registered with the CalendarMonthViewDays class. The MonthDayHandler is responsible for drawing the contents of each day box and for responding to double click actions which occur within a day box.

• public CalendarMonthViewDays(MonthDayHandler days,int Year,int Month)
  
  
  Constructor. Create a month view for Month and Year. Month is in the standard Java range of 0 to 11. Year should be the year A.D., not the year-1900 as used by Java. The contents of each day box and mouse double clicks will be handled by days.



• public final void redraw()
  
  
  Force a redraw of the calendar. This method should be called if the contents of the calendar have changed due to an external event.



• public final void setSelected(int Day)
  
  
  Set the selected day to Day.



• public final CalendarDate getSelected()
  
  
  Return the currently selected day as a CalendarDate object.



• public final CalendarDate getStart()
  
  
  Return the first day of the month as a CalendarDate object.

This interface is implemented by the object which will handle drawing and user interaction inside of each day box in a CalendarMonthViewDays component.

• public void drawMonthDay(Graphics g,CalendarDate date,Dimension size,Dimension label,boolean selected)
  
  
  Draw the current contents of date into g. The entire day box extends from (0,0) to (size.width-1,size.height-1). The section from (0,0) to (label.width-1,label.height-1) will be occluded by the day of month label. This method can safely draw to the remainder of the box.
  [diagram goes here]
  If date is currently selected, selected will be true.



• public void handleMonthDayClick(CalendarDate date,CalendarMonthViewDays controller)
  
  
  Called when the user double clicks on the day box corresponding to date. The redraw method in controller should be called if the double click action results to a change in the calendar contents.

Renders each day in a week. The days are drawn as boxes stacked vertically with a day of month indicator in the top left corner of each box. A WeekDayHandler must be registered with the CalendarWeekViewDays class. The WeekDayHandler is responsible for drawing the contents of each day box and for responding to double click actions which occur within a day box.

• public CalendarWeekViewDays(WeekDayHandler days,CalendarDate Start)
  
  
  Constructor. Create a week view which contains Start. The contents of each day box and mouse double clicks will be handled by days.



• public final void redraw()
  
  
  Force a redraw of the calendar. This method should be called if the contents of the calendar have changed due to an external event.



• public final void setSelected(CalendarDate day)
  
  
  Set the selected day to day.



• public final CalendarDate getSelected()
  
  
  Return the currently selected day as a CalendarDate object.



• public final CalendarDate getStart()
  
  
  Return the first day of the week as a CalendarDate object.



• public final void setDateStartListener(DateStartListener Listener)
  
  
  Set the DateStartListener. See also CalendarViewDisplay.



• public final DateStartListener getDateStartListener()
  
  
  Return the DateStartListener. See also CalendarViewDisplay.

This interface is implemented by the object which will handle drawing and user interaction inside of each day box in a CalendarWeekViewDays component.

• public void drawWeekDay(Graphics g,CalendarDate date,Dimension size,Dimension label,boolean selected)
  
  
  Draw the current contents of date into g. The entire day box extends from (0,0) to (size.width-1,size.height-1). The section from (0,0) to (label.width-1,label.height-1) will be occluded by the day of month label. This method can safely draw to the remainder of the box.
  [diagram goes here]
  If date is currently selected, selected will be true.



• public void handleWeekDayClick(CalendarDate date,CalendarWeekViewDays controller)
  
  
  Called when the user double clicks on the day box corresponding to date. The redraw method in controller should be called if the double click action results to a change in the calendar contents.

Calendar Date Class

Encapsulates the Java 1.0 Date class to allow seamless upgrade to the Calendar class introduced in Java 1.1. Contains methods and constructors exactly analagous to the Date class methods and constructors.

Tabbed Dialog Component

Yet another tabbed dialog implementation. This one is rather weak. It allows only a single row of tabs and has hardcoded layout rules (center the labels, bold the selected tab, etc.). I would have done a better job, but the JFC release of Java will contain an official tabbed dialog component, so this is essentially throwaway code.

Important: YetAnotherTabbedDialog allows components to be added only through the use of the add method documented here. The only method to remove components is removeAll. The result of calling some other add or remove method is undefined.

• public YetAnotherTabbedDialog()
  
  
  Create a new tabbed dialog with the default maximum number of components.



• public YetAnotherTabbedDialog(int max)
  
  
  Create a new tabbed dialog with a maximum number of components of max. Exceeding max will cause an array bounds exception.



• public Component add(String name,Component comp)
  
  
  Add a tab to the box. This is the only supported method to add components to the tabbed dialog box. The component is added to a CardLayout. The visibility of the components in the CardLayout is controlled by a row of tabs across the top of the tabbed dialog box component. Each tab displays the name of the corresponding component. A different tab may be selected by clicking on it with the mouse.



• public void removeAll()
  
  
  Remove all tabs from the box.



• public final int getSelected()
  
  
  Return the index of the selected tab. The component corresponding to that tab can be retrieved by calling the getComponent method inherited from Panel.



• public void setSelected(int i)
  
  
  Set the selected tab to the i'th tab.

Year Entry Box Component

A subclass of TextField which allows only integer numeric input. It performs range checking on the final value to ensure that it is acceptable to Java as a valid year. A YearListener may be registered with the YearTextField. The year listener is notified whenever the TextField's contents are accepted by the user and refer to a valid year.

• public YearTextField(String contents,YearListener Y)
  
  
  Constructor. Initialize the text field to contents. Inform Y of accepted changes to the text field's contents.

YearListener is an interface which is implemented by users of the YearTextField component. The YearListener will be notified whenever the contents of the YearTextField are accepted by the user (by, e.g. pressing the return key).

• public void newYear(int Year)
  
  
  Called when the user presses the return key in the YearTextField. Year is the current contents of the text field converted into an integer (e.g. 1997).

Miscellaneous

Static methods for drawing 3d boxes. Box3d is used by various CalendarView classes to highlight the selected day and to draw the tabs in the tabbed dialog boxes.

• public static void draw(Graphics g,int x,int y,int width,int height,Color dark,Color light,boolean raised,boolean bottom,boolean rounded)
  
  
  Draw a 3 dimensional box into g with upper left corner at (x,y), width width and height height. The color dark will be used to render the shadow side of the box, and light will be used to render the bright side. If raised is true, then the box will have a raised appearance, otherwise it will have a sunken appearance. If bottom is true, then the bottom side of the box will be drawn, otherwise only the left, top and right sides of the box will be drawn. If rounded is true, the box will be drawn with slightly rounded corners.



• public static void draw(Component c,Graphics g,int x,int y,int width,int height,boolean raised,boolean rounded)
  
  
  Draw a 3 dimensional box into g with upper left corner at (x,y), width width and height height. The shadow and light colors will be computed from the foreground and background colors of c. If raised is true, then the box will have a raised appearance, otherwise it will have a sunken appearance. If rounded is true, the box will be drawn with slightly rounded corners. All four sides of the box will be drawn.



• public static void draw(Component c,Graphics g,int x,int y,int width,int height,boolean raised)
  
  
  Draw a 3 dimensional box into g with upper left corner at (x,y), width width and height height. The shadow and light colors will be computed from the foreground and background colors of c. If raised is true, then the box will have a raised appearance, otherwise it will have a sunken appearance. The box will have square corners. All four sides of the box will be drawn.

A clickable arrow button which can point up, down, left or right. The arrow image has a 3d raised appearance which becomes sunken when pushed. A ButtonListener can be registered with the arrow button to receive messages in response to mouse clicks on the arrow. ButtonArrow is used by the CalendarView compound components to provide simple date traversal.

• public ButtonArrow(String direction)
  
  
  Constructor. Create a button arrow pointing in the direction indicated by direction. direction may be "left", "right", "up" or "down".



• public void setDirection(String direction)
  
  
  Change the arrow so that it points in direction. direction may be "left", "right", "up" or "down".



• public final void setButtonListener(ButtonListener Listener)
  
  
  Register Listener to receive click actions on the button.



• public final ButtonListener getButtonListener()
  
  
  Return the object registered to receive click actions on the button.

An interface for receiving clicks on a ButtonArrow.

• public void buttonAction(Event e, ButtonArrow button)
  
  
  Called when the user presses and releases the mouse button while the pointer is over an arrow button. The event e is the button release event which triggered this call. button is the button object which was clicked upon.

A collection of static methods which perform computations on colors.

This class provides access to month name abbreviations. The Java 1.0 version uses a static array of english month names. Its use will be discontinued in the Java 1.1 version of CalendarView in favor of the date formatting routines provided in the java.text package which provide international support.

This class provides access to week day names. The Java 1.0 version uses a static array of english week day names. Its use will be discontinued in the Java 1.1 version of CalendarView in favor of the date formatting routines provided in the java.text package which provide international support.

To do

These are the items that are on my to do list for CalendarView 1.1 which will be written for JAVA 1.1 using bean technology. CalendarView 1.1 will be available from Odin Consulting.

For 1.2: