1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><!-- InstanceBegin template="/Templates/JCalendar.dwt" codeOutsideHTMLIsLocked="false" -->
<head>
<!-- InstanceBeginEditable name="doctitle" -->
<title>JCalendar - Tutorial</title>
<!-- InstanceEndEditable -->
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<!-- InstanceBeginEditable name="head" -->
<!-- InstanceEndEditable -->
<link href="stylesheet.css" rel="stylesheet" type="text/css" />
</head>
<body>
<p><img src="images/Logo.png" width="800" height="150" /></p>
<table width="800" border="0" cellspacing="0" cellpadding="10">
<tr>
<td width="150" align="left" valign="top" id="sidebar">
<p><a href="index.html">Introduction</a></p>
<p><a href="features.html">Features</a></p>
<p><a href="screenshots.html">Screen<br />
shots</a></p>
<p><a href="tutorial.html">Tutorial</a></p>
<p><a href="examples.html">Examples</a></p>
<p><a href="api/index.html">API<br />
documentation</a></p>
<p><a href="https://sourceforge.net/project/showfiles.php?group_id=113939">Download</a></p>
<p><a href="resources.html">Other<br />
resources</a></p>
<p><a href="../../index.html">Return to<br />
FLib </a></p>
<p><a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=113939&type=1" alt="SourceForge.net Logo" width="88" height="31" border="0" align="top" title="" /></a></p>
<p><a href="http://www.jars.com/"><img src="http://www.jars.com/images/r750.gif" alt="Rated JARS Top 25%" width="104" height="56" border="0" align="top" title="" /></a></p> </td>
<td id="content" width="614" align="left" valign="top"><!-- InstanceBeginEditable name="content" -->
<h1>Tutorial</h1>
<h2>JCalendar</h2>
<p>JCalendar is the generic name for two Java components: one is called
JCalendar and the other is called JCalendarCombo. They both share common
features, particularly the ability to select a date and/or time. The former
accomplishes this with a panel and the latter with a combo-box.</p>
<h3>Creating the Components</h3>
<p>The simplest constructors for JCalendar and JCalendarCombo have no arguments.
They create calendar components that allow a date to be selected from
the default calendar in the default locale.</p>
<p>The next step is to select the specific Calendar and Locale classes to
use (but the JCalendar components have only been tested with the Gregorian
calendar). There are three more parameters that can be specified:</p>
<ul>
<li>Whether to select a date, a time or both.</li>
<li>Whether to display today's date at the bottom of the component.</li>
<li>The SimpleDateFormat pattern to use in displaying the time selection
field.</li>
</ul>
<p>Normally, the calendar components allow you to select a null date/time
(press Delete or Backspace to set a null selection). This is useful for
cases where the user has an option of not specifying a date/time. You
can turn this off by calling <code>setNullAllowed(false)</code>.</p>
<p>For the JCalendarCombo, you also have the option of making the combo-box
editable (as with any combo-box). You can control the date format that
appears in the combo-box field with <code>setDateFormat()</code>.</p>
<h3>Date Selections</h3>
<p>You can set the selected date with <code>setDate()</code>. The default
date/time selection will be today's date/time unless you explicitly set
a date. You can read the currently selected date at any time using <code>getDate()</code>
or <code>getCalendar()</code>. Finally, you can add a DateListener to
listen for date changes. Each time the date/time changes, the listener
is called. </p>
<h3>Fonts</h3>
<p>You may specify the font to use for each elements that makes
up a calendar component. The elements are:</p>
<ul>
<li>The month-year title.</li>
<li>The day-of-week labels (Mon, Tue, etc.).</li>
<li>The day buttons.</li>
<li>The time spinner.</li>
<li>The today's date message.</li>
</ul>
<p>In addition, the combo box text can be changed in the usual
way—by calling setFont() on the combo box component.</p>
<h3>Keyboard Control</h3>
<p>The calendar appears with buttons that allow the user to move a month
or year backwards or forward. You can use the arrow keys to do the same:</p>
<ul>
<li>Left Arrow - Move back a month.</li>
<li>Right Arrow - Move forward a month.</li>
<li>Shift Left Arrow - Move back a year.</li>
<li>Shift Right Arrow - Move forward a year.</li>
</ul>
<p>In addition, you can use Delete or Backspace to select a null date (if
null dates are allowed).</p>
<p>As normal, you can tab through the various buttons (including the day
buttons) and press Enter to activate the button.</p>
<p>If there is a time field, it can be a little problematic. Once it has
focus, the up/down arrow keys increment/decrement portions of the time
field. The left/right keys select the portion of the time to increment/decrement.
You will need to tab out of the time field or use the mouse to select
a button elsewhere in the calendar in order to restore the normal keyboard
controls.</p>
<p>The JCalendarCombo has some additional keyboard controls. The down arrow
pops up a calendar if one is not visible. The up arrow hides the calendar
pop-up (as does the Enter key). The Escape key also hides the calendar,
but restores the date to the value it had before the calendar was popped
up.</p>
<h3>Internationalization</h3>
<p>The JCalendar components take advantage of the internationalization and
localization work done by the Calendar class. In order to fully localize
JCalendar to other than US English, you will need to obtain the source
code for JCalendar and create a org.freixas.jcalendar.Bundle_<em><locale></em>.properties
file which translates the text in org.freixas.jcalendar.Bundle.properties,
where <em><locale></em> is a two-letter country code.</p>
<p>The main thing in this file are the tooltips for the various buttons
and the text for displaying today's date as well as some error messages.</p>
<h3>Look-and-Feel</h3>
<p>It was important for my own use that the JCalendar combo-box adopt the
current Java Look-and-Feel (L&F). As it turns out, it is impossible
to design a class that can automatically do this for all possible L&F's.
If you need to use a L&F other than Metal, Windows or Motif, you will
need to obtain the JCalendar source code and make some changes.</p>
<p>In the <code>updateUI()</code> method of JCalendarCombo.java, you will
need to add some code that looks like this:</p>
<pre>else if (cui instanceof SomeComboBoxUI) {
cui = new SomeDateComboBoxUI();
}</pre>
<p>Then in the inner class section of the code, add a new inner class:</p>
<pre>class SomeDateComboBoxUI
extends SomeComboBoxUI
{
protected ComboPopup createPopup() {
return new CalendarComboPopup();
}
}
</pre>
<p>Of course, the word "Some" would be replaced by the name of
your L&F (Metal, Motif, etc.). When your L&F is installed, the
JCalendarCombo combo-box will now look the same as a normal JComboBox.</p>
<h3>Summary</h3>
<p>The JCalendar components are designed to be easy to use—create
the component you want, set up a few options and register a DateListener
and you're in business. </p>
<p>After reading this tutorial, you should examine the <a href="examples.html">example
programs</a> provided which exercise many of the features of JCalendar
components.</p>
<!-- InstanceEndEditable --></td>
</tr>
</table>
</body>
<!-- InstanceEnd --></html>
|
