// (c) 2003 Allen I Holub. All rights reserved.
package com.holub.ui;
import java.awt.event.*;
import java.util.Date;
import java.util.Calendar; // makes javadoc happy
/*** An interface for Date selection.
*
* <p>
* See {@link DateSelectorPanel} for a discussion of how date selectors
* look and work. This interface defines the public methods of that
* class to allow for the use of a Gang-of-Four Decorator to add
* optional labels.
* <p>
* Most of the interface methods have to do with action-listeners support.
* The listeners are notified in two situations, which can be
* distinguished from one another by calling
* {@link ActionEvent#getID}:
* <table border=1 cellspacing=0 cellpadding=2>
* <tr><td><b><code>getID()</code> Returns:</b></td><td><b>Description:</b></td></tr>
* <tr> <td>{@link #CHANGE_ACTION}</td>
* <td>
* This event is sent when the calendar panel changes the displayed month or
* year (tyically because some sort of navigator bar asked it to).
* Call <code>event</code>.{@link ActionEvent#getActionCommand getActionCommand()}
* to get a string holding the current (after the scroll) month and year.
* You can also call {@link #getDateRepresentation} or
* {@link #getCalendarRepresentation} to get
* get the date the user selected.
* </td>
* </tr>
* <tr><td>{@link #SELECT_ACTION}</td>
* <td>
* Sent every time the user clicks on a date.
* Call <code>event</code>.{@link ActionEvent#getActionCommand getActionCommand()}
* to get a string
* representing the selected date. (This string takes the same
* form as the one returned by {@link Date#toString}.)
* You can also call {@link #getDateRepresentation()} to get
* get the date the user selected.
* </td>
* </tr>
* </table>
* The following example demonstrates how to create a single JPanel
* that contains a title displaying the name of the current month and
* year as well as a calendar for that date. The ActionListener automatically
* updates the label every time the user navigates to another month.
* (You will rarely have to do this, since the
* {@link TitledDateSelector} class will handle exactly
* that problem for you, but the example demonstrates the technique.)
* <PRE>
private static JPanel createCalendarPane(DateSelector s)
{
JPanel panel = new JPanel();
panel.setLayout( new BorderLayout() );
final JLabel month = new JLabel("MMM YYYY");
s.addActionListener
( new ActionListener()
{ public void actionPerformed( ActionEvent e )
{ if( e.getID() == DateSelector.CHANGE_ACTION )
month.setText( e.getActionCommand() );
else
System.out.println( e.getActionCommand() );
}
}
);
panel.add( month, BorderLayout.NORTH );
panel.add( s, BorderLayout.CENTER );
return panel;
}
* </PRE>
* <p>
* Classes that implement this interface must also
* <code>extend Container</code> or some <code>Container</code>
* derivative. (You can't mandate this in the compiler because
* Container is not an interface, so can't be a base class
* of DateSelector.)
*
* <!-- ====================== distribution terms ===================== -->
* <p><blockquote
* style="border-style: solid; border-width:thin; padding: 1em 1em 1em 1em;">
* <center>
* Copyright © 2003, Allen I. Holub. All rights reserved.
* </center>
* <br>
* <br>
* This code is distributed under the terms of the
* <a href="http://www.gnu.org/licenses/gpl.html"
* >GNU Public License</a> (GPL)
* with the following ammendment to section 2.c:
* <p>
* As a requirement for distributing this code, your splash screen,
* about box, or equivalent must include an my name, copyright,
* <em>and URL</em>. An acceptable message would be:
* <center>
* This program contains Allen Holub's <em>XXX</em> utility.<br>
* (c) 2003 Allen I. Holub. All Rights Reserved.<br>
* http://www.holub.com<br>
* </center>
* If your progam does not run interactively, then the foregoing
* notice must appear in your documentation.
* </blockquote>
* <!-- =============================================================== -->
* @author Allen I. Holub
* @see DateSelectorPanel
* @see DateSelectorDialog
*/
public interface DateSelector
{
public static final int CHANGE_ACTION = 0;
public static final int SELECT_ACTION = 1;
public void addActionListener(ActionListener l);
public void removeActionListener(ActionListener l);
public Calendar getCalendarRepresentation();
public Date getDateRepresentation();
public void displayDate( Calendar src );
public void displayDate( Date src );
/** Must work just like {@link Calendar#roll(int,boolean)} */
public void roll(int flag, boolean up);
/** Must work just like {@link Calendar#get(int)} */
public int get(int flag);
}