jcalendar
Project home

JCalendar Features User Interface Components Properties Additional components Screenshots Demo      webstart» Downloads Changes Future Plans

JCalendar JCalendar is a Swing component for selecting a date. Features Easy to configure Highly customizable. See components. Attractive user interface

User Interface

Controls area Calendar view Weeks header Day of week header Day area

button for selecting the previous year; button for selecting the previous month; label that displays the current month, clicking on it will display a popup menu from which you can select a month; label that displays the current year, clicking on it will display a popup menu from which you can select a year between (x - minYearAmount, x + maxYearAmount), where x = updateYearsOnChange ? currentYear : initialYear; button for selecting the next month; button for selecting the next year; header containing the week day labels; clicking on a weekday will change that day to become the first day of the week in the user interface if changingFirstDayOfWeekAllowed property is set; cell containing a date; cell containing a selected date; grid lines; can be vertical or horizontal and are displayed if property showHorizontalLines/showVerticalLines is set.

Components

The JCalendar is composed from different components. For increased flexibility, some of these components are designed to be rendered by other components. Using such renderers you can customize the appearence and tooltip. Usually, such a renderer is an interface that provides two methods: one for returning the component to be used and one for returning the tooltip string (or null if no tooltip is needed). A basic default renderer class implementation is provided for every renderer interface. You can use this renderer to extend or to wrap it in your own renderer. Your imagination will be the only limit here.

JCalendar has two primary components: the controls area and the calendar view.

The controls area contains the user controls for selecting the visible month (items 1-6 from user interface). The controls are shown only if the property showControls is set to true. The control area can be positioned above or under the calendar according to the value of the controlsPosition property.

The calendar view is a monthly view of the currently displayed date. This view has 3 components: a weeks header (on vertical), a day of week header (on horizontal) and a main area with days within the month.

The weeks header is located on the left side of the calendar view on the vertical and it displays the index of the weeks in year. This component can be customized by implementing WeekRenderer. Creating your own renderer you can have different background and foreground colors, fonts for odd/even weeks, icons for special weeks and you can even display something else than the week index etc. Of course a default renderer is provided: DefaultWeekRenderer.

The day of week header is located on the upper side of the calendar view on the horizontal and it displays the days of the week, from Sunday to Saturday. The first day is determined according to the Locale used. You can change the first day of the week by clicking on another day of the week, that will become the first day of the week. This is allowed if and only if the changingFirstDayOfWeekAllowed is set to true (default behavior).This component can be customized by implementing DayOfWeekRenderer. Creating your own renderer you can have different background and foreground colors, fonts for every day of the week (e.g. red for Saturday and Sunday, black for the rest) etc. Of course a default renderer is provided: DefaultDayOfWeekRenderer.

The day of month area is located on the center of the calendar view and displays the days from one month (the current month), the days from the previous month that are in the first week of displayed month and the days from the next month that are in the last week of current month. From this area you can select a day. This component can be customized by implementing DayRenderer.Creating your own renderer you can have different background and foreground colors, fonts for every day of the month, e.g. red foreground for Saturday and Sunday, black for the rest, faded aspect or invisible for the days in the previous and next month, alternative background for weeks, add icons to displays phases of the moon, add text or tooltip for your events of the day, highlighted appearence for today etc. Of course a default renderer is provided: DefaultDayRenderer.

Properties

Besides renderers, JCalendar component can be customized setting properties on it or on renderers. Every time a property is changed (programatically or from the user interface) a java.beans.PropertyChangeEvent is generated with the corresponding property name, old value and new value.

Below there is a table describing every property: name, detailed description, if it can be changed programatically and if it can be changed directly from the graphical interface by the end user. The properties are displayed in section, according to the parent component.

Property	Description	Code	UI
JCalendar component
month	The month for this calendar.
year	The year for this calendar.
dateFormatSymbols	The symbols used to display months and weekdays
showControls	If the user controls are shown in the UI
controlsPosition	The position of user controls. The possible values are JCalendar.TOP and JCalendar.BOTTOM for showing the controls above and under the calendar.
controlsStep	The amount with which the year/month is increased/decreased. if the controls contains buttons for big steps.
weekDayDisplayType	How the week days are displayed in the column header. JCalendar.ONE for the first letter of the week day name JCalendar.SHORT for the short name of the week day name JCalendar.SHORT for the long name of the week day name
showHorizontalLines	If the horizontal grid lines are shown in the calendar.
showVerticalLines	If the vertical grid lines are shown in the calendar.
selectionMode	The selection mode that can be single selection, continuous interval or multiple intervals.
changingFirstDayOfWeekAllowed	If the user can change the first day of week by clicking on the corresponding column header.
showCellTooltips	If the tooltips over the calendar days are shown.
selectionMode	The selection mode that can be single selection, continuous interval or multiple intervals.
tooltipDateFormat	The selection mode that can be single selection, continuous interval or multiple intervals.

Additional components

The JCalendar distribution contains a few additional components that can be used as standalone as well.

• JFontChooser is a component very similar to Swing JColorChooser that can help you select a font
• ArrowIcon is an icon that displays a set of arrows orientated to either north, south, east or west.
• HTMLColorsChooserPanel and LnFColorsChooserPanel are two color chooser panel to be used inside a Swing JColorChooser.
• JTableRowHeader is a row header that is used in conjuction with a table displayed inside a scroll pane. The row header is very similar to a column header and displays the row number. What and how it is to be displayed can be configured defining your own renderer for this component.

Screenshots

Metal look'n'feel	Windows look'n'feel	Metouia look'n'feel
Different background and foreground colors for weekend days header, week days header, weekend days, week days, odd and even weeks, controls, grid lines	Notice the tooltips for the calendar cells	Espanol language and short display for weekday names in header
Controls area positioned under the calendar	No controls displayed	First day of the week is Wednesday

Demo     START»

The JCalendar distribution includes a demo application with which you can configure this component. The demo application will preview the component and generate the Java code for configuration. The JCalendar distribution contains some other useful components that can be used as standalone components. The demo application contains tabs for any of these components to demonstrate their functionality.

The JCalendar demo tab has four panels: Calendar - the preview component; Configuration - a panel containing controls for changing the preview component properties; Sample code - text component containing the Java code that generates the component in the preview panel; Output - text component to display output like selected dates in the preview component.

You can run this demo from distribution (java -jar jcalendar.jar) or see the web-start demo.

Below you have screenshots of the demo application

Click on the images to see a larger version

Changes

v2.0

There are a huge amount of differences between v2.0 and 1.0. The most important ones are the increased flexibility by adding renderers and migration to Java 5.0. Why are we renouncing to compatibility with Java 1.3 and 1.4. Simply, the most important reason: progress. Altough compatibility with Java 1.4 is still ensured by using Retroweaver. Because of the huge amount of changes the backward compatiblity is ensured only to a certain level with v1.0. A lot of methods and interfaces were deprecated and probably they'll be removed in future versions.

Download

Future Plans