Class TimePicker

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

public class TimePicker extends JPanel implements CustomPopup.CustomPopupCloseListener
TimePicker, This class implements a time picker GUI component. This class supports a complete set of "default functionality" without requiring any TimePickerSettings. However, the settings of a time picker can optionally be customized by creating a TimePickerSettings instance and passing it to the TimePicker constructor. After the time picker is constructed, the settings instance should not be changed. By default, the language and internationalization settings of a time 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 TimePickerSettings instance, and passing that instance to the constructor of a TimePicker. Automatic Time Validation: Every time picker stores its current text, and its last valid time. The last valid time is returned when you call TimePicker.getTime(). If a person uses their keyboard to type into the text field, any text that is not a valid time will be displayed in red, any vetoed time will have a strikethrough, and any valid time will be displayed in black. Valid times are automatically committed to the time picker. Any invalid or vetoed text is automatically reverted to the last valid time whenever the the time picker loses focus. // Basic usage example: // Create a time picker. TimePicker timePicker = new TimePicker(); // Create a panel, and add the time picker. JPanel panel = new JPanel(); panel.add(timePicker);
See Also:
  • Constructor Details

    • TimePicker

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

      public TimePicker(TimePickerSettings settings)
      Constructor with Custom Settings, Create a time picker instance using the supplied time picker settings.
  • Method Details

    • addTimeChangeListener

      public void addTimeChangeListener(TimeChangeListener listener)
      addTimeChangeListener, This adds a time change listener to this time picker. For additional details, see the TimeChangeListener class documentation.
    • clear

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

      public void closePopup()
      closePopup, This closes the menu 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 menu with the "toggle menu" button. 5) The user may select a time in the menu.
    • getBaseline

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

      public JButton getComponentDecreaseSpinnerButton()
      getComponentDecreaseSpinnerButton, Returns the decrease spinner button that is used by this time picker. The spinner buttons are only visible if the programmer has enabled them in the TimePickerSettings. Note: Direct access to the time picker components is provided so the programmer can perform advanced or unusual modifications of the time picker's appearance or behavior. However, directly accessing the components should be used only as a last resort, to implement functionality that is not available from other functions or settings.
    • getComponentIncreaseSpinnerButton

      public JButton getComponentIncreaseSpinnerButton()
      getComponentIncreaseSpinnerButton, Returns the increase spinner button that is used by this time picker. The spinner buttons are only visible if the programmer has enabled them in the TimePickerSettings. Note: Direct access to the time picker components is provided so the programmer can perform advanced or unusual modifications of the time picker's appearance or behavior. However, directly accessing the components should be used only as a last resort, to implement functionality that is not available from other functions or settings.
    • getComponentSpinnerPanel

      public JPanel getComponentSpinnerPanel()
      getComponentSpinnerPanel, Returns the panel that holds the spinner buttons in this time picker. The spinner buttons (and panel) are only visible if the programmer has enabled them in the TimePickerSettings. Note: Direct access to the time picker components is provided so the programmer can perform advanced or unusual modifications of the time picker's appearance or behavior. However, directly accessing the components should be used only as a last resort, to implement functionality that is not available from other functions or settings.
    • getComponentTimeTextField

      public JTextField getComponentTimeTextField()
      getComponentTimeTextField, Returns the time text field that is used by this time 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 time 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 TimePickerSettings class provides multiple ways to customize the time picker, 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 TimePickerSettings class before directly accessing the time picker text field. The TimePickerSettings class can customize the following text field attributes: The background and foreground colors, the fonts, font size, and font colors, and the time formats. Warning: To ensure proper behavior of the time picker, the text field should not be used to get or set the the time (or text) values of the time picker. Instead, the programmer should use the TimePicker.getTime() and TimePicker.getText() (and Set) functions for those purposes. The TimeChangeListener interface can be used to listen for changes to the time value.
    • getComponentToggleTimeMenuButton

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

      public boolean getEnableArrowKeys()
      getEnableArrowKeys, Returns the value of this setting. See the set function for additional information.
    • getTime

      public LocalTime getTime()
      getTime, This returns the last valid time, or returns null to represent an empty time. If "TimePickerSettings.allowEmptyTimes" is true, then this can return null. If allow empty times is false, then this can never return null. Note: If the automatic validation of time picker text has not yet occurred, then the the last valid time may not always match the current text.
       Additional Text Validation Details:
       Whenever the current time picker text is not valid, the value returned by getTime()
       will generally not match the time picker text. The time 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
       time, or the user has typed a time that is vetoed by a current veto policy, or the user has
       cleared (or left only whitespace) in the text when allowEmptyTimes is false.
      
       2) The time picker text field has continued to have focus, and therefore the automatic
       validation (revert/commit) process has not yet occurred.
       
    • getTimeChangeListeners

      public ArrayList<TimeChangeListener> getTimeChangeListeners()
      getTimeChangeListeners, This returns a new ArrayList, that contains any time change listeners that are registered with this TimePicker.
    • getTimeStringOrEmptyString

      public String getTimeStringOrEmptyString()
      getTimeStringOrEmptyString, This will return the last valid time as a string. If the last valid time is empty, this will return an empty string (""). Time values will be output in one of the following ISO-8601 formats: "HH:mm", "HH:mm:ss", "HH:mm:ss.SSS", "HH:mm:ss.SSSSSS", "HH:mm:ss.SSSSSSSSS". The format used will be the shortest that outputs the full value of the time where the omitted parts are implied to be zero.
    • getTimeStringOrSuppliedString

      public String getTimeStringOrSuppliedString(String emptyTimeString)
      getTimeStringOrSuppliedString, This will return the last valid time as a string. If the last valid time is empty, this will return the value of emptyTimeString. Time values will be output in one of the following ISO-8601 formats: "HH:mm", "HH:mm:ss", "HH:mm:ss.SSS", "HH:mm:ss.SSSSSS", "HH:mm:ss.SSSSSSSSS". The format used will be the shortest that outputs the full value of the time where the omitted parts are implied to be zero.
    • getSettings

      public TimePickerSettings getSettings()
      getSettings, This returns the time picker settings instance.
    • getText

      public String getText()
      getText, This returns the current text that is present in the time picker text field. This text can contain anything that was written by the user. It is specifically not guaranteed to contain a valid time. This should not be used to retrieve the time picker time. Instead, use TimePicker.getTime() for retrieving the time.
    • 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 time menu popup is open. This returns false if the time menu popup is closed
    • isTextFieldValid

      public boolean isTextFieldValid()
      isTextFieldValid, This returns true if, and only if, the text field contains a parsable time or a valid empty string. Note that this does not guarantee that the text in the text field is in a standard format. Valid times can be in any one of the parsingFormats that are accepted by the time picker. More specifically, this returns true if: 1) the text field contains a parsable time that exists, and that has not been vetoed by a current veto policy, OR 2) (allowEmptyTime == true) and timeTextField.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 time" according to the settings of this time picker. More specifically, this returns true if: 1) the text contains a parsable time that exists, and that has not been vetoed by a current veto policy, OR 2) (allowEmptyTimes == true) and text.trim() contains an empty string. Otherwise returns false.
    • isTimeAllowed

      public boolean isTimeAllowed(LocalTime time)
      isTimeAllowed, This checks to see if the specified time is allowed by any currently set veto policy, and allowed by the current setting of allowEmptyTimes. If allowEmptyTimes is false, and the specified time is null, then this returns false. If a veto policy exists, and the specified time is vetoed, then this returns false. If the time is not vetoed, or if empty times are allowed and the time is null, then this returns true.
    • openPopup

      public void openPopup()
      openPopup, This creates and shows the menu popup. This function creates a new menu panel 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.
    • removeTimeChangeListener

      public void removeTimeChangeListener(TimeChangeListener listener)
      removeTimeChangeListener, This removes the specified time change listener from this time picker.
    • setEnableArrowKeys

      public void setEnableArrowKeys(boolean enableArrowKeys)
      setEnableArrowKeys, This sets the variable that determines if the arrow keys will be handled by this time picker. If this is set to true, then the up and down arrow keys can be used as spinner controls, and the right arrow will open the time picker menu. If this is set to false, then the arrow keys will not be handled. This is set to true by default.
    • setEnabled

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

      public void setText(String text)
      setText, This sets the text of the time picker text field to the supplied value. This will have the same effect on the last valid time as if the user was typing into the text field. In other words, it may or may not change the last valid time. This should not be used to set the time of the time picker, instead use TimePicker.setTime().
    • 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 time" in a standardized valid format. This function is automatically called whenever the time 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 time field text string that matches the last valid time.
    • setTime

      public void setTime(LocalTime optionalTime)
      setTime, This sets this time picker to the specified time. Times that are set from this function are processed through the same validation procedures as times 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 value can be checked against any current veto policy, and against the allowEmptyTimes setting, by calling isTimeAllowed(). This can be used to determine (in advance), if a particular value would be allowed. Note: If empty times 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 time string, the lastValidTime is also automatically set (unless the time is vetoed). This occurs through the DocumentListener which is registered on the timeTextField.
    • setTimeToNow

      public void setTimeToNow()
      setTimeToNow, This sets the time to the current time. This function is subject to the same validation behaviors as if a user typed the current time into the time picker. See setTime() for additional details.
    • toString

      public String toString()
      toString, This will return the last valid time as a string. If the last valid time is empty, this will return an empty string (""). Time values will be output in one of the following ISO-8601 formats: "HH:mm", "HH:mm:ss", "HH:mm:ss.SSS", "HH:mm:ss.SSSSSS", "HH:mm:ss.SSSSSSSSS". The format used will be the shortest that outputs the full value of the time where the omitted parts are implied to be zero. This returns the same value as getTimeStringOrEmptyString()
      Overrides:
      toString in class Component
    • togglePopup

      public void togglePopup()
      togglePopup, This creates and shows a menu popup. If the popup is already open, then this will close the popup. This is called when the user clicks on the toggle menu button of the time 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 time 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 time 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 time 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 popup menu with the "toggle time menu" button. 5) The user may select a time in the popup menu.
      Specified by:
      zEventCustomPopupWasClosed in interface CustomPopup.CustomPopupCloseListener
    • zInternalTryChangeTimeByIncrement

      public void zInternalTryChangeTimeByIncrement(int changeAmountMinutes)
    • zSetAppropriateTextFieldMinimumWidth

      public void zSetAppropriateTextFieldMinimumWidth()
      zSetAppropriateTextFieldMinimumWidth, This sets the minimum (and preferred) width of the time picker text field. The width will be determined (or calculated) from the current time picker settings, as described below. If the programmer has not supplied a setting for the minimum size, then a default minimum size will be calculated from the current display format (which includes the locale information), and the font for valid times. If the programmer has supplied a setting for the text field minimum size, then the programmer supplied value will be used instead, unless a default override is allowed. (In this case, the default value will only be used if the default setting is larger than the programmer supplied setting). For additional details, see the javadoc for this function: TimePickerSettings.setSizeTextFieldMinimumWidthDefaultOverride().