Class DatePicker

All Implemented Interfaces:
CustomPopup.CustomPopupCloseListener, ImageObserver, MenuContainer, Serializable, Accessible

public class DatePicker extends JPanel implements CustomPopup.CustomPopupCloseListener
DatePicker, This class implements a date picker GUI component. This class supports a complete set of "default functionality" without requiring any DatePickerSettings. However, the settings of a date picker can optionally be customized by creating a DatePickerSettings instance and passing it to the DatePicker constructor. After the date picker is constructed, the settings instance should not be changed. By default, the language and internationalization settings of a date picker are determined from the operating system defaults using Locale.getDefault(). If desired, the locale and language can be modified by passing a locale to the constructor of a DatePickerSettings instance, and passing that instance to the constructor of a DatePicker. Automatic Date Validation: Every date picker stores its current text, and its last valid date. The last valid date is returned when you call DatePicker.getDate(). If a person uses their keyboard to type into the text field, any text that is not a valid date will be displayed in red, any vetoed date will have a strikethrough, and any valid date will be displayed in black. Valid dates are automatically committed to the date picker. Any invalid or vetoed text is automatically reverted to the last valid date whenever the the date picker loses focus. // Basic usage example: // Create a date picker. DatePicker datePicker = new DatePicker(); // Create a panel, and add the date picker. JPanel panel = new JPanel(); panel.add(datePicker);
See Also:
  • Constructor Details

    • DatePicker

      public DatePicker()
      Constructor with Default Values, Create a date picker instance using the default operating system locale and language, and default date picker settings.
    • DatePicker

      public DatePicker(DatePickerSettings settings)
      Constructor with Custom Settings, Create a date picker instance using the supplied date picker settings.
  • Method Details

    • setSettings

      public void setSettings(DatePickerSettings settings)
      setSettings, This will set the settings instance for this date picker. The previous settings will be deleted. Note that calling this function effectively re-initializes the picker component. All aspects of the component will be changed to match the provided settings. Any currently selected date will not be changed by this function. If the popup calendar panel is open up the time that this function is called, the open calendar will not be changed by this function. Calendar panels showing the new settings will be displayed only after a new popup calendar panel is opened.
    • addDateChangeListener

      public void addDateChangeListener(DateChangeListener listener)
      addDateChangeListener, This adds a date change listener to this date picker. For additional details, see the DateChangeListener class documentation.
    • clear

      public void clear()
      clear, This will clear the date picker text. If the date picker is set to allow empty dates, then the last valid date will also be cleared. If the date picker is set to disallow empty dates, then the last valid date will not be changed by this function.
    • closePopup

      public void closePopup()
      closePopup, This closes the calendar popup. The popup can close itself automatically, so this function does not generally need to be called programmatically. Notes: The popup can be automatically closed for various reasons. 1) The user may press escape. 2) The popup may lose focus. 3) The window may be moved. 4) The user may toggle the calendar with the "toggle calendar" button. 5) The user may select a date in the calendar.
    • convert

      public Convert convert()
      convert, This is used to access the Convert class instance. The convert class allows the programmer to get or set the date picker java.time.LocalDate value using other common data types, such as java.util.Date. Example usage: datePicker.convert().getDateWithDefaultZone(); See the documentation of the Convert class for additional information and usage examples.
    • getComponentToggleCalendarButton

      public JButton getComponentToggleCalendarButton()
      getComponentToggleCalendarButton, Returns the "toggle calendar" button for this date picker. Direct access to the calendar button is provided so that the programmer can optionally assign an image to the button, or perform advanced or unusual modifications to the date picker's appearance and behavior. Note: This function should not be used to programmatically open or close the date picker calendar. The following functions are provided for that purpose: openPopup(), closePopup(), and togglePopup().
    • getBaseline

      public int getBaseline(int width, int height)
      getBaseline, This returns the baseline value of the dateTextField.
      Overrides:
      getBaseline in class JComponent
    • getComponentDateTextField

      public JTextField getComponentDateTextField()
      getComponentDateTextField, Returns the date text field for this date picker. It is not expected that most programmers will need or want to use this function. Important Note: Direct access to the text field is provided so the programmer can perform advanced or unusual modifications of the date picker's appearance or behavior. However, this function should be used only as a last resort, to implement functionality that is not available from other functions or settings. The DatePickerSettings class provides multiple ways to customize the date picker text field, and those functions should be preferred for the needs they address. It is suggested that the programmer become familiar with the functions and settings in DatePickerSettings class before directly accessing the date picker text field. The DatePickerSettings class can customize the following text field attributes: The text field width, the background and foreground colors, the fonts, font size, and font colors, and the date formats. Warning: To ensure proper behavior of the date picker, the text field should not be used to get or set the the date (or text) values of the date picker. Instead, the programmer should use the DatePicker.getDate() and DatePicker.getText() (and Set) functions for those purposes. The DateChangeListener interface can be used to listen for changes to the date value.
    • getDate

      public LocalDate getDate()
      getDate, This returns the last valid date, or returns null to represent an empty date. If "DatePickerSettings.allowEmptyDates" is true, then this can return null. If allow empty dates is false, then this can never return null. Note: If the automatic validation of date picker text has not yet occurred, then the the last valid date may not always match the current text.
       Additional Text Validation Details:
       Whenever the current date picker text is not valid, the value returned by getDate()
       will generally not match the date picker text. The date picker can contain invalid text
       whenever both items (1) and (2) below are true:
      
       1) The user has manually typed text that cannot be parsed by the parsing formats into a valid
       date, or the user has typed a date that is vetoed by a current veto policy, or the user has
       cleared (or left only whitespace) in the text when allowEmptyDates is false.
      
       2) The date picker text field has continued to have focus, and therefore the automatic
       validation (revert/commit) process has not yet occurred.
       
    • getDateChangeListeners

      public ArrayList<DateChangeListener> getDateChangeListeners()
      getDateChangeListeners, This returns a new ArrayList, that contains any date change listeners that are registered with this DatePicker.
    • getDateStringOrEmptyString

      public String getDateStringOrEmptyString()
      getDateStringOrEmptyString, This returns the last valid date in an ISO-8601 formatted string "uuuu-MM-dd". For any CE years that are between 0 and 9999 inclusive, the output will have a fixed length of 10 characters. Years before or after that range will output longer strings. If the last valid date is empty, this will return an empty string ("").
    • getDateStringOrSuppliedString

      public String getDateStringOrSuppliedString(String emptyDateString)
      getDateStringOrSuppliedString, This returns the last valid date in an ISO-8601 formatted string "uuuu-MM-dd". For any CE years that are between 0 and 9999 inclusive, the output will have a fixed length of 10 characters. Years before or after that range will output longer strings. If the last valid date is empty, this will return the value of emptyDateString.
    • getSettings

      public DatePickerSettings getSettings()
      getSettings, This returns the date picker settings instance.
    • getText

      public String getText()
      getText, This returns the current text that is present in the date picker text field. This text can contain anything that was written by the user. It is specifically not guaranteed to contain a valid date. This should not be used to retrieve the date picker date. Instead, use DatePicker.getDate() for retrieving the date.
    • isDateAllowed

      public boolean isDateAllowed(LocalDate date)
      isDateAllowed, This checks to see if the specified date is allowed by any currently set veto policy, and allowed by the current setting of allowEmptyDates. If allowEmptyDates is false, and the specified date is null, then this returns false. If a veto policy exists, and the specified date is vetoed, then this returns false. If the date is not vetoed, or if empty dates are allowed and the date is null, then this returns true.
    • isEnabled

      public boolean isEnabled()
      isEnabled, Returns true if this component is enabled, otherwise returns false.
      Overrides:
      isEnabled in class Component
    • isPopupOpen

      public boolean isPopupOpen()
      isPopupOpen, This returns true if the calendar popup is open. This returns false if the calendar popup is closed
    • isTextFieldValid

      public boolean isTextFieldValid()
      isTextFieldValid, This returns true if, and only if, the text field contains a parsable date or a valid empty string. Note that this does not guarantee that the text in the text field is in a standard format. Valid dates can be in any one of the parsingFormats that are accepted by the date picker. More specifically, this returns true if: 1) the text field contains a parsable date that exists, and that has not been vetoed by a current veto policy, OR 2) (allowEmptyDates == true) and dateTextField.getText().trim() contains an empty string. Otherwise returns false.
    • isTextValid

      public boolean isTextValid(String text)
      isTextValid, This function can be used to see if the supplied text represents a "valid date" according to the settings of this date picker. More specifically, this returns true if: 1) the text contains a parsable date that exists, and that has not been vetoed by a current veto policy, OR 2) (allowEmptyDates == true) and text.trim() contains an empty string. Otherwise returns false.
    • openPopup

      public void openPopup()
      openPopup, This opens the calendar popup. If the date picker contains a lastValidDate, the calendar will be opened to the month and year of the lastValidDate, with the lastValidDate marked as selected. If the lastValidDate is null, then the calendar will be opened with today's month and year displayed, and no date will be selected. This function creates a new calendar and a new custom popup instance each time that it is called. The associated object instances are automatically disposed and set to null when a popup is closed.
    • removeDateChangeListener

      public void removeDateChangeListener(DateChangeListener listener)
      removeDateChangeListener, This removes the specified date change listener from this date picker.
    • setDate

      public final void setDate(LocalDate optionalDate)
      setDate, This sets this date picker to the specified date. Dates that are set from this function are processed through the same validation procedures as dates that are entered by the user. More specifically: The "veto policy" and "allowEmptyTimes" settings are used to determine whether or not a particular value is "allowed". Allowed values will be set in the text field, and also committed to the "last valid value". Disallowed values will be set in the text field (with a disallowed indicator font), but will not be committed to the "last valid value". A date value can be checked against any current veto policy, and against the allowEmptyDates setting, by calling isDateAllowed(). This can be used to determine (in advance), if a particular value would be allowed. Note: If empty dates are allowed, and the component does not have a veto policy, then all possible values will (always) be allowed. These are the default settings of this component. Implementation Note: Whenever the text field changes to a valid date string, the lastValidDate is also automatically set (unless the date is vetoed). This occurs through the DocumentListener which is registered on the dateTextField.
    • setDateToToday

      public void setDateToToday()
      setDateToToday, This sets the date to today's date. This function is subject to the same validation behaviors as if a user typed today's date into the date picker. See setDate() for additional details.
    • setEnabled

      public void setEnabled(boolean enabled)
      setEnabled, This enables or disables the date picker. When the date picker is enabled, dates can be selected by the user using any methods that are allowed by the current settings. When the date picker is disabled, there is no way for the user to interact with the component. More specifically, dates cannot be selected with the mouse, or with the keyboard, and the date picker components change their color scheme to indicate the disabled state. Any currently stored text and last valid date values are retained while the component is disabled.
      Overrides:
      setEnabled in class JComponent
    • setLocale

      public void setLocale(Locale locale)
      setLocale, The locale for a DatePicker should generally be set in the DatePickerSettings. This function only exists to avoid confusion with the swing function Component.setLocale(). This forwards any function calls to: DatePicker.getSettings().setLocale(). For the complete Javadocs, see DatePickerSettings.setLocale().
      Overrides:
      setLocale in class Component
    • setText

      public void setText(String text)
      setText, This sets the text of the date picker text field to the supplied value. This will have the same effect on the last valid date as if the user was typing into the text field. In other words, it may or may not change the last valid date. This should not be used to set the date of the date picker, instead use DatePicker.setDate().
    • setTextFieldToValidStateIfNeeded

      public void setTextFieldToValidStateIfNeeded()
      setTextFieldToValidStateIfNeeded, This function will check the contents of the text field, and when needed, will set the text to match the "last valid date" in a standardized valid format. This function is automatically called whenever the date picker text field loses focus, or at other times when the text must be set to a valid state. It is not expected that the programmer will normally need to call this function directly. This function has two possible effects: 1) If the current text is already valid and is in the standard format, then this will do nothing. If the text is not valid, or if the text is not in the standard format, then: 2) This will replace the invalid text in the text field with a standard date field text string that matches the last valid date.
    • toString

      public String toString()
      toString, This returns the last valid date in an ISO-8601 formatted string "uuuu-MM-dd". For any CE years that are between 0 and 9999 inclusive, the output will have a fixed length of 10 characters. Years before or after that range will output longer strings. If the last valid date is empty, this will return an empty string (""). This returns the same value as getDateStringOrEmptyString().
      Overrides:
      toString in class Component
    • togglePopup

      public void togglePopup()
      togglePopup, This creates and shows a calendar popup. If the popup is already open, then this will close the popup. This is called when the user clicks on the toggle calendar button of the date picker. This function does not generally need to be called programmatically.
    • zDrawTextFieldIndicators

      public void zDrawTextFieldIndicators()
      zDrawTextFieldIndicators, This will draw the text field indicators, to indicate to the user the state of any text in the text field, including the validity of any date that has been typed. The text field indicators include the text field background color, foreground color, font color, and font. Note: This function is called automatically by the date picker. Under most circumstances, the programmer will not need to call this function. List of possible text field states: DisabledComponent, ValidFullOrEmptyValue, UnparsableValue, VetoedValue, DisallowedEmptyValue.
    • zEventCustomPopupWasClosed

      public void zEventCustomPopupWasClosed(CustomPopup popup)
      zEventCustomPopupWasClosed, This is called automatically whenever the CustomPopup that is associated with this date picker is closed. This should be called regardless of the type of event which caused the popup to close. Notes: The popup can be automatically closed for various reasons. 1) The user may press escape. 2) The popup may lose focus. 3) The window may be moved. 4) The user may toggle the calendar with the "toggle calendar" button. 5) The user may select a date in the calendar.
      Specified by:
      zEventCustomPopupWasClosed in interface CustomPopup.CustomPopupCloseListener
    • addComponentListener

      public void addComponentListener(ComponentListener listener)
    • removeComponentListener

      public void removeComponentListener(ComponentListener listener)
    • fireComponentEvent

      protected void fireComponentEvent(ComponentEvent e)