summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAnna Koskinen <Ansku@users.noreply.github.com>2021-09-13 13:48:05 +0300
committerGitHub <noreply@github.com>2021-09-13 13:48:05 +0300
commit9141c7a6de641a965dd4e5620fd44452a1691521 (patch)
tree5d1d66f4f0c573a1be792d9aca970e094d4e9a9c
parenta1478127b1bdb8590794f1b929a456a7be88b110 (diff)
downloadvaadin-framework-9141c7a6de641a965dd4e5620fd44452a1691521.tar.gz
vaadin-framework-9141c7a6de641a965dd4e5620fd44452a1691521.zip
Checkstyle tweaks to DateField widgets. (#12400)
- Added and updated JavaDocs. - Updated comments. - Updated to use non-deprecated method calls. - Removed unnecessary warning suppressions. - Suppressed warnings for unavoidable deprecation.
-rw-r--r--client/src/main/java/com/vaadin/client/ui/VAbstractCalendarPanel.java104
-rw-r--r--client/src/main/java/com/vaadin/client/ui/VAbstractDateFieldCalendar.java34
-rw-r--r--client/src/main/java/com/vaadin/client/ui/VAbstractPopupCalendar.java45
-rw-r--r--client/src/main/java/com/vaadin/client/ui/VDateCalendarPanel.java2
-rw-r--r--client/src/main/java/com/vaadin/client/ui/VDateField.java85
-rw-r--r--client/src/main/java/com/vaadin/client/ui/VDateFieldCalendar.java4
-rw-r--r--client/src/main/java/com/vaadin/client/ui/VDateTimeCalendarPanel.java27
-rw-r--r--client/src/main/java/com/vaadin/client/ui/VDateTimeFieldCalendar.java4
-rw-r--r--client/src/main/java/com/vaadin/client/ui/VPopupCalendar.java16
-rw-r--r--client/src/main/java/com/vaadin/client/ui/VPopupTimeCalendar.java18
10 files changed, 316 insertions, 23 deletions
diff --git a/client/src/main/java/com/vaadin/client/ui/VAbstractCalendarPanel.java b/client/src/main/java/com/vaadin/client/ui/VAbstractCalendarPanel.java
index fa05cc9b1f..e4fafcc43b 100644
--- a/client/src/main/java/com/vaadin/client/ui/VAbstractCalendarPanel.java
+++ b/client/src/main/java/com/vaadin/client/ui/VAbstractCalendarPanel.java
@@ -72,12 +72,17 @@ import com.vaadin.shared.util.SharedUtil;
* 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 {
/**
@@ -109,6 +114,12 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
* {@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);
}
@@ -185,7 +196,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
* 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;
@@ -212,6 +223,9 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
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");
@@ -222,6 +236,12 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
addBlurHandler(this);
}
+ /**
+ * Sets the parent date field widget.
+ *
+ * @param parent
+ * the parent widget
+ */
public void setParentField(VDateField<R> parent) {
this.parent = parent;
}
@@ -384,6 +404,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
/**
* Updates year, month, day from focusedDate to value
*/
+ @SuppressWarnings("deprecation")
private void selectFocused() {
if (focusedDate != null
&& isDateInsideRange(focusedDate, getResolution())) {
@@ -418,14 +439,30 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
}
}
+ /**
+ * @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;
}
@@ -566,9 +603,11 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
updateAssistiveLabels();
+ @SuppressWarnings("deprecation")
final String monthName = needsMonth
? getDateTimeService().getMonth(displayedMonth.getMonth())
: "";
+ @SuppressWarnings("deprecation")
final int year = displayedMonth.getYear() + 1900;
getFlexCellFormatter().setStyleName(0, 2,
@@ -610,6 +649,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
}
}
+ @SuppressWarnings("deprecation")
private void updateControlButtonRangeStyles(boolean needsMonth) {
if (focusedDate == null) {
@@ -674,6 +714,12 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
return parent;
}
+ /**
+ * Sets date time service for the widget.
+ *
+ * @param dateTimeService
+ * date time service
+ */
public void setDateTimeService(DateTimeService dateTimeService) {
this.dateTimeService = dateTimeService;
}
@@ -683,12 +729,22 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
* 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)) {
@@ -734,6 +790,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
.compareTo(dateStrResolution) <= 0;
}
+ @SuppressWarnings("deprecation")
private String dateStrResolution(Date date, R minResolution) {
String dateStrResolution = (1900 + date.getYear()) + "";
while (dateStrResolution.length() < 4) {
@@ -785,6 +842,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
/**
* Builds the day and time selectors of the calendar.
*/
+ @SuppressWarnings("deprecation")
private void buildCalendarBody() {
final int weekColumn = 0;
@@ -988,6 +1046,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
* resolution of the calendar is changed and no date has been
* selected.
*/
+ @SuppressWarnings("deprecation")
protected void doRenderCalendar(boolean updateDate) {
super.setStylePrimaryName(
getDateField().getStylePrimaryName() + "-calendarpanel");
@@ -1021,6 +1080,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
/**
* Moves the focus forward the given number of days.
*/
+ @SuppressWarnings("deprecation")
private void focusNextDay(int days) {
if (focusedDate == null) {
return;
@@ -1060,6 +1120,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
/**
* Selects the next month
*/
+ @SuppressWarnings("deprecation")
private void focusNextMonth() {
if (focusedDate == null) {
@@ -1075,8 +1136,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
}
// 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(
@@ -1089,6 +1149,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
renderCalendar();
}
+ @SuppressWarnings("deprecation")
private static void addOneMonth(Date date) {
int currentMonth = date.getMonth();
int requestedMonth = (currentMonth + 1) % 12;
@@ -1105,6 +1166,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
}
}
+ @SuppressWarnings("deprecation")
private static void removeOneMonth(Date date) {
int currentMonth = date.getMonth();
@@ -1123,6 +1185,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
/**
* Selects the previous month
*/
+ @SuppressWarnings("deprecation")
private void focusPreviousMonth() {
if (focusedDate == null) {
@@ -1150,6 +1213,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
/**
* Selects the previous year
*/
+ @SuppressWarnings("deprecation")
private void focusPreviousYear(int years) {
if (focusedDate == null) {
@@ -1192,6 +1256,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
/**
* Selects the next year
*/
+ @SuppressWarnings("deprecation")
private void focusNextYear(int years) {
if (focusedDate == null) {
@@ -1439,6 +1504,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
* @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) {
@@ -1715,6 +1781,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
return date;
}
+ @SuppressWarnings("deprecation")
private Date parseRangeString(String dateStr) {
if (dateStr == null || "".equals(dateStr)) {
return null;
@@ -1764,6 +1831,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
* 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
@@ -1798,8 +1866,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
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;
}
@@ -1836,6 +1903,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
private class Day extends InlineHTML {
private final Date date;
+ @SuppressWarnings("deprecation")
Day(Date date) {
super("" + date.getDate());
this.date = date;
@@ -1847,6 +1915,11 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
}
}
+ /**
+ * Returns the current date value.
+ *
+ * @return current date value
+ */
public Date getDate() {
return value;
}
@@ -1955,6 +2028,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
private String rangeEnd;
+ @SuppressWarnings("deprecation")
@Override
public String getSubPartName(
com.google.gwt.user.client.Element subElement) {
@@ -2008,7 +2082,7 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
return w.getElement().isOrHasChild(subElement);
}
- @SuppressWarnings("unchecked")
+ @SuppressWarnings({ "unchecked", "deprecation" })
@Override
public com.google.gwt.user.client.Element getSubPartElement(
String subPart) {
@@ -2064,6 +2138,20 @@ public abstract class VAbstractCalendarPanel<R extends Enum<R>>
*/
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);
}
diff --git a/client/src/main/java/com/vaadin/client/ui/VAbstractDateFieldCalendar.java b/client/src/main/java/com/vaadin/client/ui/VAbstractDateFieldCalendar.java
index 7ae639d0b5..56adf9e3f4 100644
--- a/client/src/main/java/com/vaadin/client/ui/VAbstractDateFieldCalendar.java
+++ b/client/src/main/java/com/vaadin/client/ui/VAbstractDateFieldCalendar.java
@@ -20,6 +20,12 @@ import com.vaadin.client.ui.VAbstractCalendarPanel.SubmitListener;
/**
* 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> {
@@ -27,6 +33,14 @@ public abstract class VAbstractDateFieldCalendar<PANEL extends VAbstractCalendar
/** 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;
@@ -40,8 +54,7 @@ public abstract class VAbstractDateFieldCalendar<PANEL extends VAbstractCalendar
@Override
public void onCancel() {
- // TODO Auto-generated method stub
-
+ // NOP
}
});
calendarPanel.setFocusOutListener(event -> {
@@ -50,13 +63,28 @@ public abstract class VAbstractDateFieldCalendar<PANEL extends VAbstractCalendar
});
}
- @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();
}
diff --git a/client/src/main/java/com/vaadin/client/ui/VAbstractPopupCalendar.java b/client/src/main/java/com/vaadin/client/ui/VAbstractPopupCalendar.java
index c268393a3e..81bcc7475a 100644
--- a/client/src/main/java/com/vaadin/client/ui/VAbstractPopupCalendar.java
+++ b/client/src/main/java/com/vaadin/client/ui/VAbstractPopupCalendar.java
@@ -57,7 +57,12 @@ import com.vaadin.shared.ui.datefield.TextualDateFieldState;
* 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>
@@ -70,6 +75,7 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
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. */
@@ -96,6 +102,17 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
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);
@@ -139,7 +156,7 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
// 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(
@@ -182,8 +199,7 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
popup.setWidget(wrapper);
popup.addCloseHandler(this);
- DOM.setElementProperty(calendar.getElement(), "id",
- "PID_VAADIN_POPUPCAL");
+ calendar.getElement().setPropertyString("id", "PID_VAADIN_POPUPCAL");
sinkEvents(Event.ONKEYDOWN);
@@ -207,7 +223,7 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
/**
* 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
@@ -247,15 +263,29 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
* 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
@@ -302,6 +332,7 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
}
}
+ @SuppressWarnings("deprecation")
@Override
public void bindAriaCaption(
com.google.gwt.user.client.Element captionElement) {
@@ -536,7 +567,7 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
* 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;
@@ -552,6 +583,7 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
}
}
+ @SuppressWarnings("deprecation")
@Override
public com.google.gwt.user.client.Element getSubPartElement(
String subPart) {
@@ -562,6 +594,7 @@ public abstract class VAbstractPopupCalendar<PANEL extends VAbstractCalendarPane
return super.getSubPartElement(subPart);
}
+ @SuppressWarnings("deprecation")
@Override
public String getSubPartName(
com.google.gwt.user.client.Element subElement) {
diff --git a/client/src/main/java/com/vaadin/client/ui/VDateCalendarPanel.java b/client/src/main/java/com/vaadin/client/ui/VDateCalendarPanel.java
index 6970d7d26f..d03f46e648 100644
--- a/client/src/main/java/com/vaadin/client/ui/VDateCalendarPanel.java
+++ b/client/src/main/java/com/vaadin/client/ui/VDateCalendarPanel.java
@@ -18,6 +18,8 @@ package com.vaadin.client.ui;
import com.vaadin.shared.ui.datefield.DateResolution;
/**
+ * A calendar panel widget to show and select a date.
+ *
* @author Vaadin Ltd
* @since 8.0
*/
diff --git a/client/src/main/java/com/vaadin/client/ui/VDateField.java b/client/src/main/java/com/vaadin/client/ui/VDateField.java
index 07389617a0..a4f97a1342 100644
--- a/client/src/main/java/com/vaadin/client/ui/VDateField.java
+++ b/client/src/main/java/com/vaadin/client/ui/VDateField.java
@@ -41,6 +41,7 @@ import com.vaadin.shared.ui.datefield.AbstractDateFieldServerRpc;
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. */
@@ -51,10 +52,13 @@ public abstract class VDateField<R extends Enum<R>> extends FlowPanel
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;
/**
@@ -99,34 +103,74 @@ public abstract class VDateField<R extends Enum<R>> extends FlowPanel
/** 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;
}
@@ -162,6 +206,7 @@ public abstract class VDateField<R extends Enum<R>> extends FlowPanel
*
* @see #setCurrentDate(Map)
* @param defaultValues
+ * a map from resolutions to date values
* @since 8.1.2
*/
public void setDefaultDate(Map<R, Integer> defaultValues) {
@@ -178,10 +223,21 @@ public abstract class VDateField<R extends Enum<R>> extends FlowPanel
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;
}
@@ -196,14 +252,31 @@ public abstract class VDateField<R extends Enum<R>> extends FlowPanel
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;
}
@@ -213,12 +286,22 @@ public abstract class VDateField<R extends Enum<R>> extends FlowPanel
* 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;
}
diff --git a/client/src/main/java/com/vaadin/client/ui/VDateFieldCalendar.java b/client/src/main/java/com/vaadin/client/ui/VDateFieldCalendar.java
index dbe7162d36..5c249c2f6f 100644
--- a/client/src/main/java/com/vaadin/client/ui/VDateFieldCalendar.java
+++ b/client/src/main/java/com/vaadin/client/ui/VDateFieldCalendar.java
@@ -34,11 +34,15 @@ import com.vaadin.shared.ui.datefield.DateResolution;
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.
diff --git a/client/src/main/java/com/vaadin/client/ui/VDateTimeCalendarPanel.java b/client/src/main/java/com/vaadin/client/ui/VDateTimeCalendarPanel.java
index e9290a741f..a7d6f63e48 100644
--- a/client/src/main/java/com/vaadin/client/ui/VDateTimeCalendarPanel.java
+++ b/client/src/main/java/com/vaadin/client/ui/VDateTimeCalendarPanel.java
@@ -20,7 +20,6 @@ import java.util.Date;
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;
@@ -28,6 +27,8 @@ import com.vaadin.client.DateTimeService;
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
*/
@@ -80,6 +81,7 @@ public class VDateTimeCalendarPanel
* Constructs the ListBoxes and updates their value
*
*/
+ @SuppressWarnings("deprecation")
private void buildTime() {
clear();
@@ -201,6 +203,7 @@ public class VDateTimeCalendarPanel
/**
* Updates the value to correspond to the values in value.
*/
+ @SuppressWarnings("deprecation")
public void updateTimes() {
if (getDate() == null) {
setDate(new Date());
@@ -253,6 +256,7 @@ public class VDateTimeCalendarPanel
* .event.dom.client.ChangeEvent)
*/
@Override
+ @SuppressWarnings("deprecation")
public void onChange(ChangeEvent event) {
/*
* Value from dropdowns gets always set for the value. Like year and
@@ -311,6 +315,18 @@ public class VDateTimeCalendarPanel
*/
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);
}
@@ -318,6 +334,7 @@ public class VDateTimeCalendarPanel
* 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;
@@ -378,7 +395,9 @@ public class VDateTimeCalendarPanel
}
@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;
@@ -395,7 +414,9 @@ public class VDateTimeCalendarPanel
}
@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();
}
diff --git a/client/src/main/java/com/vaadin/client/ui/VDateTimeFieldCalendar.java b/client/src/main/java/com/vaadin/client/ui/VDateTimeFieldCalendar.java
index 55aa900feb..41c89cc590 100644
--- a/client/src/main/java/com/vaadin/client/ui/VDateTimeFieldCalendar.java
+++ b/client/src/main/java/com/vaadin/client/ui/VDateTimeFieldCalendar.java
@@ -38,11 +38,15 @@ import com.vaadin.shared.ui.datefield.DateTimeResolution;
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.
diff --git a/client/src/main/java/com/vaadin/client/ui/VPopupCalendar.java b/client/src/main/java/com/vaadin/client/ui/VPopupCalendar.java
index 9f38f14201..af2160d5c1 100644
--- a/client/src/main/java/com/vaadin/client/ui/VPopupCalendar.java
+++ b/client/src/main/java/com/vaadin/client/ui/VPopupCalendar.java
@@ -24,6 +24,7 @@ import java.util.Map;
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
@@ -35,6 +36,11 @@ import com.vaadin.shared.ui.datefield.DateResolution;
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);
}
@@ -54,6 +60,15 @@ public class VPopupCalendar
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;
@@ -85,6 +100,7 @@ public class VPopupCalendar
}
@Override
+ @SuppressWarnings("deprecation")
protected void updateBufferedResolutions() {
super.updateBufferedResolutions();
Date currentDate = getDate();
diff --git a/client/src/main/java/com/vaadin/client/ui/VPopupTimeCalendar.java b/client/src/main/java/com/vaadin/client/ui/VPopupTimeCalendar.java
index bbd6827400..7a01228875 100644
--- a/client/src/main/java/com/vaadin/client/ui/VPopupTimeCalendar.java
+++ b/client/src/main/java/com/vaadin/client/ui/VPopupTimeCalendar.java
@@ -33,8 +33,8 @@ import com.vaadin.client.LocaleService;
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
*
@@ -43,6 +43,11 @@ import com.vaadin.shared.ui.datefield.DateTimeResolution;
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);
}
@@ -65,6 +70,14 @@ public class VPopupTimeCalendar extends
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;
@@ -108,6 +121,7 @@ public class VPopupTimeCalendar extends
}
@Override
+ @SuppressWarnings("deprecation")
protected void updateBufferedResolutions() {
super.updateBufferedResolutions();
Date currentDate = getDate();