- Added and updated JavaDocs.
- Updated comments.
- Updated to use non-deprecated method calls.
- Removed unnecessary warning suppressions.
- Suppressed warnings for unavoidable deprecation.
* the resolution type which this field is based on (day, month, ...)
* @since 8.0
*/
-@SuppressWarnings("deprecation")
public abstract class VAbstractCalendarPanel<R extends Enum<R>>
extends FocusableFlexTable implements KeyDownHandler, KeyPressHandler,
MouseOutHandler, MouseDownHandler, MouseUpHandler, BlurHandler,
FocusHandler, SubPartAware {
+ /**
+ * Interface for updating date field value based on the current calendar
+ * panel data or canceling the update.
+ *
+ * @author Vaadin Ltd
+ */
public interface SubmitListener {
/**
* {@code focused} value.
*/
public interface FocusChangeListener {
+ /**
+ * Called when focused date has changed in the calendar panel.
+ *
+ * @param focusedDate
+ * the currently focused date in the panel
+ */
void focusChanged(Date focusedDate);
}
* Represents a click handler for when a user selects a value by using the
* mouse
*/
- @SuppressWarnings("unchecked")
+ @SuppressWarnings({ "unchecked", "deprecation" })
private ClickHandler dayClickHandler = event -> {
if (!isEnabled() || isReadonly()) {
return;
private Map<String, String> dateStyles = new HashMap<String, String>();
private DateTimeFormat df = DateTimeFormat.getFormat("yyyy-MM-dd");
+ /**
+ * Constructs a calendar panel widget for displaying and selecting a date.
+ */
public VAbstractCalendarPanel() {
getElement().setId(DOM.createUniqueId());
setStyleName(VDateField.CLASSNAME + "-calendarpanel");
addBlurHandler(this);
}
+ /**
+ * Sets the parent date field widget.
+ *
+ * @param parent
+ * the parent widget
+ */
public void setParentField(VDateField<R> parent) {
this.parent = parent;
}
/**
* Updates year, month, day from focusedDate to value
*/
+ @SuppressWarnings("deprecation")
private void selectFocused() {
if (focusedDate != null
&& isDateInsideRange(focusedDate, getResolution())) {
}
}
+ /**
+ * @deprecated This method is not used by the framework code anymore.
+ * @return {@code false}
+ */
+ @Deprecated
protected boolean onValueChange() {
return false;
}
+ /**
+ * Returns the current date resolution.
+ *
+ * @return the resolution
+ */
public R getResolution() {
return resolution;
}
+ /**
+ * Sets the current date resolution.
+ *
+ * @param resolution
+ * the new resolution
+ */
public void setResolution(R resolution) {
this.resolution = resolution;
}
updateAssistiveLabels();
+ @SuppressWarnings("deprecation")
final String monthName = needsMonth
? getDateTimeService().getMonth(displayedMonth.getMonth())
: "";
+ @SuppressWarnings("deprecation")
final int year = displayedMonth.getYear() + 1900;
getFlexCellFormatter().setStyleName(0, 2,
}
}
+ @SuppressWarnings("deprecation")
private void updateControlButtonRangeStyles(boolean needsMonth) {
if (focusedDate == null) {
return parent;
}
+ /**
+ * Sets date time service for the widget.
+ *
+ * @param dateTimeService
+ * date time service
+ */
public void setDateTimeService(DateTimeService dateTimeService) {
this.dateTimeService = dateTimeService;
}
* selector or not. ISO 8601 defines that a week always starts with a Monday
* so the week numbers are only shown if this is the case.
*
- * @return true if week number should be shown, false otherwise
+ * @return {@code true} if week number should be shown, {@code false}
+ * otherwise
*/
public boolean isShowISOWeekNumbers() {
return showISOWeekNumbers;
}
+ /**
+ * Sets whether ISO 8601 week numbers should be shown in the value selector
+ * or not. ISO 8601 defines that a week always starts with a Monday so the
+ * week numbers are only shown if this is the case.
+ *
+ * @param showISOWeekNumbers
+ * {@code true} if week number should be shown, {@code false}
+ * otherwise
+ */
public void setShowISOWeekNumbers(boolean showISOWeekNumbers) {
this.showISOWeekNumbers = showISOWeekNumbers;
if (initialRenderDone && isBelowMonth(resolution)) {
.compareTo(dateStrResolution) <= 0;
}
+ @SuppressWarnings("deprecation")
private String dateStrResolution(Date date, R minResolution) {
String dateStrResolution = (1900 + date.getYear()) + "";
while (dateStrResolution.length() < 4) {
/**
* Builds the day and time selectors of the calendar.
*/
+ @SuppressWarnings("deprecation")
private void buildCalendarBody() {
final int weekColumn = 0;
* resolution of the calendar is changed and no date has been
* selected.
*/
+ @SuppressWarnings("deprecation")
protected void doRenderCalendar(boolean updateDate) {
super.setStylePrimaryName(
getDateField().getStylePrimaryName() + "-calendarpanel");
/**
* Moves the focus forward the given number of days.
*/
+ @SuppressWarnings("deprecation")
private void focusNextDay(int days) {
if (focusedDate == null) {
return;
/**
* Selects the next month
*/
+ @SuppressWarnings("deprecation")
private void focusNextMonth() {
if (focusedDate == null) {
}
// Now also checking whether the day is inside the range or not. If not
- // inside,
- // correct it
+ // inside, correct it
if (!isDateInsideRange(requestedNextMonthDate,
getResolution(this::isDay))) {
requestedNextMonthDate = adjustDateToFitInsideRange(
renderCalendar();
}
+ @SuppressWarnings("deprecation")
private static void addOneMonth(Date date) {
int currentMonth = date.getMonth();
int requestedMonth = (currentMonth + 1) % 12;
}
}
+ @SuppressWarnings("deprecation")
private static void removeOneMonth(Date date) {
int currentMonth = date.getMonth();
/**
* Selects the previous month
*/
+ @SuppressWarnings("deprecation")
private void focusPreviousMonth() {
if (focusedDate == null) {
/**
* Selects the previous year
*/
+ @SuppressWarnings("deprecation")
private void focusPreviousYear(int years) {
if (focusedDate == null) {
/**
* Selects the next year
*/
+ @SuppressWarnings("deprecation")
private void focusNextYear(int years) {
if (focusedDate == null) {
* @return Return true if the key press was handled by the method, else
* return false.
*/
+ @SuppressWarnings("deprecation")
protected boolean handleNavigationDayMode(int keycode, boolean ctrl,
boolean shift) {
return date;
}
+ @SuppressWarnings("deprecation")
private Date parseRangeString(String dateStr) {
if (dateStr == null || "".equals(dateStr)) {
return null;
* an additional action which will be executed in case
* rerendering is not required
*/
+ @SuppressWarnings("deprecation")
protected void doSetDate(Date currentDate, boolean needRerender,
Runnable focusAction) {
// Check that we are not re-rendering an already active date
dateThatFitsInsideRange.getMonth(), 1);
// value was adjusted. Set selected to null to not cause
// confusion, but this is only needed (and allowed) when we have
- // a day
- // resolution
+ // a day resolution
if (isDay(getResolution())) {
value = null;
}
private class Day extends InlineHTML {
private final Date date;
+ @SuppressWarnings("deprecation")
Day(Date date) {
super("" + date.getDate());
this.date = date;
}
}
+ /**
+ * Returns the current date value.
+ *
+ * @return current date value
+ */
public Date getDate() {
return value;
}
private String rangeEnd;
+ @SuppressWarnings("deprecation")
@Override
public String getSubPartName(
com.google.gwt.user.client.Element subElement) {
return w.getElement().isOrHasChild(subElement);
}
- @SuppressWarnings("unchecked")
+ @SuppressWarnings({ "unchecked", "deprecation" })
@Override
public com.google.gwt.user.client.Element getSubPartElement(
String subPart) {
*/
public class FocusedDate extends Date {
+ /**
+ * Constructs a date instance that keeps track of the currently selected
+ * date within the calendar panel and updates the related text field
+ * accordingly if there is one.
+ *
+ * @param year
+ * the year value
+ * @param month
+ * the month value between 0-11
+ * @param date
+ * the day of the month value between 1-31
+ * @see FocusedDate
+ */
+ @SuppressWarnings("deprecation")
public FocusedDate(int year, int month, int date) {
super(year, month, date);
}
/**
* A client side implementation for inline date field.
+ *
+ * @param <PANEL>
+ * the calendar panel type this field uses
+ * @param <R>
+ * the resolution type which this field is based on (day, month, ...)
+ * @author Vaadin Ltd
*/
public abstract class VAbstractDateFieldCalendar<PANEL extends VAbstractCalendarPanel<R>, R extends Enum<R>>
extends VDateField<R> {
/** For internal use only. May be removed or replaced in the future. */
public final PANEL calendarPanel;
+ /**
+ * Constructs a date selection widget with an inline date/time selector.
+ *
+ * @param panel
+ * the calendar panel instance that should be displayed
+ * @param resolution
+ * the resolution this widget should display (day, month, ...)
+ */
public VAbstractDateFieldCalendar(PANEL panel, R resolution) {
super(resolution);
calendarPanel = panel;
@Override
public void onCancel() {
- // TODO Auto-generated method stub
-
+ // NOP
}
});
calendarPanel.setFocusOutListener(event -> {
});
}
- @SuppressWarnings("deprecation")
+ /**
+ * Update buffered values and send them (if any) to the server.
+ */
public abstract void updateValueFromPanel();
+ /**
+ * Sets the tabulator index for the calendar panel element that represents
+ * the entire widget in the browser's focus cycle.
+ *
+ * @param tabIndex
+ * the new tabulator index
+ */
public void setTabIndex(int tabIndex) {
calendarPanel.getElement().setTabIndex(tabIndex);
}
+ /**
+ * Returns the tabulator index of the calendar panel element that represents
+ * the entire widget in the browser's focus cycle.
+ *
+ * @return the tabulator index
+ */
public int getTabIndex() {
return calendarPanel.getElement().getTabIndex();
}
* then pass set it by calling the
* <code>setCalendarPanel(VAbstractCalendarPanel panel)</code> method.
*
+ * @param <PANEL>
+ * the calendar panel type this field uses
+ * @param <R>
+ * the resolution type which this field is based on (day, month, ...)
* @since 8.0
+ * @author Vaadin Ltd
*/
public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPanel<R>, R extends Enum<R>>
extends VAbstractTextualDate<R>
public PANEL calendar;
/** For internal use only. May be removed or replaced in the future. */
+ @SuppressWarnings("deprecation")
public final VOverlay popup;
/** For internal use only. May be removed or replaced in the future. */
private static final String CALENDAR_TOGGLE_ID = "popupButton";
+ /**
+ * Constructs a date selection widget with a text field and a pop-up
+ * date/time selector.
+ *
+ * @param calendarPanel
+ * the calendar panel instance that should be displayed in the
+ * pop-up
+ * @param resolution
+ * the resolution this widget should display (day, month, ...)
+ */
+ @SuppressWarnings("deprecation")
public VAbstractPopupCalendar(PANEL calendarPanel, R resolution) {
super(resolution);
// FIXME: Problem is, that the element with the provided id does not
// exist yet in html. This is the same problem as with the context menu.
- // Apply here the same fix (#11795)
+ // Apply here the same fix (#3901)
Roles.getTextboxRole().setAriaControlsProperty(text.getElement(),
Id.of(calendar.getElement()));
Roles.getButtonRole().setAriaControlsProperty(
popup.setWidget(wrapper);
popup.addCloseHandler(this);
- DOM.setElementProperty(calendar.getElement(), "id",
- "PID_VAADIN_POPUPCAL");
+ calendar.getElement().setPropertyString("id", "PID_VAADIN_POPUPCAL");
sinkEvents(Event.ONKEYDOWN);
/**
* Changes the current date, and updates the
* {@link VDateField#bufferedResolutions}, possibly
- * {@link VDateField#sendBufferedValues()} to the server if needed
+ * {@link VDateField#sendBufferedValues()} to the server if needed.
*
* @param newDate
* the new {@code Date} to update
* Sets the state of the text field of this component. By default the text
* field is enabled. Disabling it causes only the button for date selection
* to be active, thus preventing the user from entering invalid dates. See
- * <a href="http://dev.vaadin.com/ticket/6790>#6790</a>.
+ * <a href="http://dev.vaadin.com/ticket/6790">#6790</a>.
+ * <p>
+ * If the text field is enabled, it represents this widget within the
+ * browser's tabulator focus cycle. When the text field is disabled, that
+ * role is instead given to the date selection button. If the entire
+ * component is disabled, the focus cycle skips this widget altogether.
*
* @param textFieldEnabled
+ * {@code true} if the text field should be enabled,
+ * {@code false} if disabled
*/
public void setTextFieldEnabled(boolean textFieldEnabled) {
this.textFieldEnabled = textFieldEnabled;
updateTextFieldEnabled();
}
+ /**
+ * Updates the text field's enabled status to correspond with the latest
+ * value set through {@link #setTextFieldEnabled(boolean)} and this
+ * component's general {@link #setEnabled(boolean)}.
+ *
+ * @see #setTextFieldEnabled(boolean)
+ */
protected void updateTextFieldEnabled() {
boolean reallyEnabled = isEnabled() && isTextFieldEnabled();
// IE has a non input disabled themeing that can not be overridden so we
}
}
+ @SuppressWarnings("deprecation")
@Override
public void bindAriaCaption(
com.google.gwt.user.client.Element captionElement) {
* Get the key code that opens the calendar panel. By default it is the down
* key but you can override this to be whatever you like
*
- * @return
+ * @return the key code that opens the calendar panel
*/
protected int getOpenCalenderPanelKey() {
return KeyCodes.KEY_DOWN;
}
}
+ @SuppressWarnings("deprecation")
@Override
public com.google.gwt.user.client.Element getSubPartElement(
String subPart) {
return super.getSubPartElement(subPart);
}
+ @SuppressWarnings("deprecation")
@Override
public String getSubPartName(
com.google.gwt.user.client.Element subElement) {
import com.vaadin.shared.ui.datefield.DateResolution;
/**
+ * A calendar panel widget to show and select a date.
+ *
* @author Vaadin Ltd
* @since 8.0
*/
public abstract class VDateField<R extends Enum<R>> extends FlowPanel
implements Field, HasEnabled {
+ /** Default classname for this widget. */
public static final String CLASSNAME = "v-datefield";
/** For internal use only. May be removed or replaced in the future. */
private R currentResolution;
+ /** Currently used locale string, e.g. {@code en_US}. */
protected String currentLocale;
+ /** Is the widget read-only or not. */
protected boolean readonly;
+ /** Is the widget enabled or not. */
protected boolean enabled;
/**
/** For internal use only. May be removed or replaced in the future. */
public DateTimeService dts;
+ /** Should ISO 8601 week numbers be shown in the date selector or not. */
protected boolean showISOWeekNumbers;
+ /**
+ * Constructs a widget for a date field.
+ *
+ * @param resolution
+ * the resolution for this widget (day, month, ...)
+ */
public VDateField(R resolution) {
setStyleName(CLASSNAME);
dts = new DateTimeService();
currentResolution = resolution;
}
+ /**
+ * Returns the current resolution.
+ *
+ * @return the resolution
+ */
public R getCurrentResolution() {
return currentResolution;
}
+ /**
+ * Sets the resolution.
+ *
+ * @param currentResolution
+ * the new resolution
+ */
public void setCurrentResolution(R currentResolution) {
this.currentResolution = currentResolution;
}
+ /**
+ * Returns the current locale String.
+ *
+ * @return the locale String
+ */
public String getCurrentLocale() {
return currentLocale;
}
+ /**
+ * Sets the locale String.
+ *
+ * @param currentLocale
+ * the new locale String.
+ */
public void setCurrentLocale(String currentLocale) {
this.currentLocale = currentLocale;
}
+ /**
+ * Returns the current date value.
+ *
+ * @return the date value
+ */
public Date getCurrentDate() {
return date;
}
+ /**
+ * Sets the date value.
+ *
+ * @param date
+ * the new date value
+ */
public void setCurrentDate(Date date) {
this.date = date;
}
*
* @see #setCurrentDate(Map)
* @param defaultValues
+ * a map from resolutions to date values
* @since 8.1.2
*/
public void setDefaultDate(Map<R, Integer> defaultValues) {
return defaultDate;
}
+ /**
+ * Returns whether this widget is read-only or not.
+ *
+ * @return {@code true} if read-only, {@code false} otherwise
+ */
public boolean isReadonly() {
return readonly;
}
+ /**
+ * Sets whether this widget should be read-only or not.
+ *
+ * @param readonly
+ * {@code true} if read-only, {@code false} otherwise
+ */
public void setReadonly(boolean readonly) {
this.readonly = readonly;
}
this.enabled = enabled;
}
+ /**
+ * Returns the date time service for this widget.
+ *
+ * @return the date time service
+ */
public DateTimeService getDateTimeService() {
return dts;
}
+ /**
+ * Returns the connector id that corresponds with this widget.
+ *
+ * @return the connector id
+ * @deprecated This method is not used by the framework code anymore.
+ */
+ @Deprecated
public String getId() {
return connector.getConnectorId();
}
+ /**
+ * Returns the current application connection.
+ *
+ * @return the application connection
+ */
public ApplicationConnection getClient() {
return client;
}
* selector or not. ISO 8601 defines that a week always starts with a Monday
* so the week numbers are only shown if this is the case.
*
- * @return true if week number should be shown, false otherwise
+ * @return {@code true} if week number should be shown, {@code false}
+ * otherwise
*/
public boolean isShowISOWeekNumbers() {
return showISOWeekNumbers;
}
+ /**
+ * Sets whether ISO 8601 week numbers should be shown in the date selector
+ * or not. ISO 8601 defines that a week always starts with a Monday so the
+ * week numbers are only shown if this is the case.
+ *
+ * @param showISOWeekNumbers
+ * {@code true} if week number should be shown, {@code false}
+ * otherwise
+ */
public void setShowISOWeekNumbers(boolean showISOWeekNumbers) {
this.showISOWeekNumbers = showISOWeekNumbers;
}
public class VDateFieldCalendar
extends VAbstractDateFieldCalendar<VDateCalendarPanel, DateResolution> {
+ /**
+ * Constructs a widget for the InlineDateField component.
+ */
public VDateFieldCalendar() {
super(GWT.create(VDateCalendarPanel.class), YEAR);
}
@Override
+ @SuppressWarnings("deprecation")
public void updateBufferedValues() {
// If field is invisible at the beginning, client can still be null when
// this function is called.
import com.google.gwt.event.dom.client.ChangeEvent;
import com.google.gwt.event.dom.client.ChangeHandler;
import com.google.gwt.event.dom.client.KeyCodes;
-import com.google.gwt.user.client.Element;
import com.google.gwt.user.client.ui.FlowPanel;
import com.google.gwt.user.client.ui.ListBox;
import com.google.gwt.user.client.ui.Widget;
import com.vaadin.shared.ui.datefield.DateTimeResolution;
/**
+ * A calendar panel widget to show and select a date and a time.
+ *
* @author Vaadin Ltd
* @since 8.0
*/
* Constructs the ListBoxes and updates their value
*
*/
+ @SuppressWarnings("deprecation")
private void buildTime() {
clear();
/**
* Updates the value to correspond to the values in value.
*/
+ @SuppressWarnings("deprecation")
public void updateTimes() {
if (getDate() == null) {
setDate(new Date());
* .event.dom.client.ChangeEvent)
*/
@Override
+ @SuppressWarnings("deprecation")
public void onChange(ChangeEvent event) {
/*
* Value from dropdowns gets always set for the value. Like year and
*/
public interface TimeChangeListener {
+ /**
+ * Handle time change.
+ *
+ * @param hour
+ * the new hour value
+ * @param min
+ * the new minute value
+ * @param sec
+ * the new second value
+ * @param msec
+ * the new millisecond value
+ */
void changed(int hour, int min, int sec, int msec);
}
* The time change listener is triggered when the user changes the time.
*
* @param listener
+ * the listener to use
*/
public void setTimeChangeListener(TimeChangeListener listener) {
timeChangeListener = listener;
}
@Override
- public String getSubPartName(Element subElement) {
+ @SuppressWarnings("deprecation")
+ public String getSubPartName(
+ com.google.gwt.user.client.Element subElement) {
if (time != null) {
if (contains(time.hours, subElement)) {
return SUBPART_HOUR_SELECT;
}
@Override
- public Element getSubPartElement(String subPart) {
+ @SuppressWarnings("deprecation")
+ public com.google.gwt.user.client.Element getSubPartElement(
+ String subPart) {
if (SUBPART_HOUR_SELECT.equals(subPart)) {
return time.hours.getElement();
}
public class VDateTimeFieldCalendar extends
VAbstractDateFieldCalendar<VDateTimeCalendarPanel, DateTimeResolution> {
+ /**
+ * Constructs a widget for the InlineDateTimeField component.
+ */
public VDateTimeFieldCalendar() {
super(GWT.create(VDateTimeCalendarPanel.class), MINUTE);
}
@Override
+ @SuppressWarnings("deprecation")
public void updateBufferedValues() {
// If field is invisible at the beginning, client can still be null when
// this function is called.
import com.google.gwt.core.client.GWT;
import com.vaadin.shared.ui.datefield.DateResolution;
+import com.vaadin.shared.ui.datefield.DateTimeResolution;
/**
* Represents a date selection component with a text field and a popup date
public class VPopupCalendar
extends VAbstractPopupCalendar<VDateCalendarPanel, DateResolution> {
+ /**
+ * Constructs a date selection component with a text field and a pop-up date
+ * selector. Uses a {@link VDateCalendarPanel} as the pop-up content.
+ * Default resolution is {@link DateTimeResolution#YEAR}.
+ */
public VPopupCalendar() {
super(GWT.create(VDateCalendarPanel.class), YEAR);
}
super.setCurrentResolution(resolution == null ? YEAR : resolution);
}
+ /**
+ * Creates a date based on the provided date values map. Any values of a
+ * more precise resolution than day are ignored.
+ *
+ * @param dateValues
+ * a map with date values to convert into a date
+ * @return the date based on the dateValues map
+ */
+ @SuppressWarnings("deprecation")
public static Date makeDate(Map<DateResolution, Integer> dateValues) {
if (dateValues.get(YEAR) == null) {
return null;
}
@Override
+ @SuppressWarnings("deprecation")
protected void updateBufferedResolutions() {
super.updateBufferedResolutions();
Date currentDate = getDate();
import com.vaadin.shared.ui.datefield.DateTimeResolution;
/**
- * Represents a date-time selection component with a text field and a popup date
- * selector.
+ * Represents a date-time selection component with a text field and a pop-up
+ * date-and-time selector.
*
* @author Vaadin Ltd
*
public class VPopupTimeCalendar extends
VAbstractPopupCalendar<VDateTimeCalendarPanel, DateTimeResolution> {
+ /**
+ * Constructs a date-time selection component with a text field and a pop-up
+ * date-and-time selector. Uses a {@link VDateTimeCalendarPanel} as the
+ * pop-up content. Default resolution is {@link DateTimeResolution#MINUTE}.
+ */
public VPopupTimeCalendar() {
super(GWT.create(VDateTimeCalendarPanel.class), MINUTE);
}
super.setCurrentResolution(resolution == null ? MINUTE : resolution);
}
+ /**
+ * Creates a date based on the provided date values map.
+ *
+ * @param dateValues
+ * a map with date values to convert into a date
+ * @return the date based on the dateValues map
+ */
+ @SuppressWarnings("deprecation")
public static Date makeDate(Map<DateTimeResolution, Integer> dateValues) {
if (dateValues.get(YEAR) == null) {
return null;
}
@Override
+ @SuppressWarnings("deprecation")
protected void updateBufferedResolutions() {
super.updateBufferedResolutions();
Date currentDate = getDate();
projects / vaadin-framework.git / commitdiff