- Added and updated JavaDocs. - Deprecated unused fields and methods that update them. - Suppressed unavoidable deprecated calls. - Switched other deprecated calls to use currently recommended calls.tags/8.14.0.beta1
@@ -46,9 +46,16 @@ import com.vaadin.client.ui.ShortcutActionHandler.ShortcutActionHandlerOwner; | |||
import com.vaadin.client.ui.popupview.VisibilityChangeEvent; | |||
import com.vaadin.client.ui.popupview.VisibilityChangeHandler; | |||
/** | |||
* Widget class for the PopupView component. | |||
* | |||
* @author Vaadin Ltd | |||
* | |||
*/ | |||
public class VPopupView extends HTML | |||
implements HasEnabled, Iterable<Widget>, DeferredWorker { | |||
/** Default classname for this widget. */ | |||
public static final String CLASSNAME = "v-popupview"; | |||
/** | |||
@@ -113,7 +120,12 @@ public class VPopupView extends HTML | |||
popup.setAutoHideOnHistoryEventsEnabled(false); | |||
} | |||
/** For internal use only. May be removed or replaced in the future. */ | |||
/** | |||
* For internal use only. May be removed or replaced in the future. | |||
* | |||
* @param popup | |||
* the popup that should be shown | |||
*/ | |||
public void preparePopup(final CustomPopup popup) { | |||
popup.setVisible(true); | |||
popup.setWidget(loading); | |||
@@ -130,6 +142,7 @@ public class VPopupView extends HTML | |||
* Can be overridden to customize the popup position. | |||
* | |||
* @param popup | |||
* the popup whose position should be updated | |||
*/ | |||
public void showPopup(final CustomPopup popup) { | |||
popup.setPopupPosition(0, 0); | |||
@@ -220,6 +233,7 @@ public class VPopupView extends HTML | |||
* (other than it being a VOverlay) is to be considered private and | |||
* potentially subject to change. | |||
*/ | |||
@SuppressWarnings("deprecation") | |||
public class CustomPopup extends VOverlay | |||
implements StateChangeEvent.StateChangeHandler { | |||
@@ -237,6 +251,11 @@ public class VPopupView extends HTML | |||
private ShortcutActionHandler shortcutActionHandler; | |||
/** | |||
* Constructs a popup widget for VPopupView. | |||
* | |||
* @see CustomPopup | |||
*/ | |||
public CustomPopup() { | |||
super(true, false); // autoHide, not modal | |||
setOwner(VPopupView.this); | |||
@@ -361,6 +380,13 @@ public class VPopupView extends HTML | |||
return super.remove(w); | |||
} | |||
/** | |||
* Sets the connector of the popup content widget. Should not be | |||
* {@code null}. | |||
* | |||
* @param newPopupComponent | |||
* the connector to set | |||
*/ | |||
public void setPopupConnector(ComponentConnector newPopupComponent) { | |||
if (newPopupComponent != popupComponentConnector) { | |||
@@ -377,6 +403,15 @@ public class VPopupView extends HTML | |||
} | |||
/** | |||
* Should this popup automatically hide when the user takes the mouse | |||
* cursor out of the popup area? If this is {@code false}, the user must | |||
* click outside the popup to close it. The default is {@code true}. | |||
* | |||
* @param hideOnMouseOut | |||
* {@code true} if this popup should hide when mouse is moved | |||
* away, {@code false} otherwise | |||
*/ | |||
public void setHideOnMouseOut(boolean hideOnMouseOut) { | |||
this.hideOnMouseOut = hideOnMouseOut; | |||
} | |||
@@ -405,6 +440,14 @@ public class VPopupView extends HTML | |||
} | |||
} | |||
/** | |||
* Adds the given visibility change handler to this widget. | |||
* | |||
* @param visibilityChangeHandler | |||
* the handler that should be triggered when visibility changes | |||
* @return the registration object for removing the given handler when no | |||
* longer needed | |||
*/ | |||
public HandlerRegistration addVisibilityChangeHandler( | |||
final VisibilityChangeHandler visibilityChangeHandler) { | |||
return addHandler(visibilityChangeHandler, |
@@ -36,6 +36,7 @@ import com.vaadin.client.StyleConstants; | |||
*/ | |||
public class VProgressBar extends Widget implements HasEnabled { | |||
/** Default classname for this widget. */ | |||
public static final String PRIMARY_STYLE_NAME = "v-progressbar"; | |||
Element wrapper = DOM.createDiv(); | |||
@@ -45,6 +46,10 @@ public class VProgressBar extends Widget implements HasEnabled { | |||
private float state = 0.0f; | |||
private boolean enabled; | |||
/** | |||
* Constructs a widget for the ProgressBar component or renderer. | |||
*/ | |||
@SuppressWarnings("deprecation") | |||
public VProgressBar() { | |||
setElement(DOM.createDiv()); | |||
getElement().appendChild(wrapper); | |||
@@ -68,20 +73,52 @@ public class VProgressBar extends Widget implements HasEnabled { | |||
} | |||
/** | |||
* Sets whether or not this progress indicator is indeterminate. In | |||
* indeterminate mode there is an animation indicating that the task is | |||
* running but without providing any information about the current progress. | |||
* | |||
* @param indeterminate | |||
* {@code true} to set to indeterminate mode, {@code false} | |||
* otherwise | |||
*/ | |||
public void setIndeterminate(boolean indeterminate) { | |||
this.indeterminate = indeterminate; | |||
setStyleName(getStylePrimaryName() + "-indeterminate", indeterminate); | |||
} | |||
/** | |||
* Sets the value of this progress bar. The value is a {@code float} between | |||
* 0 and 1 where 0 represents no progress at all and 1 represents fully | |||
* completed. | |||
* | |||
* @param state | |||
* the new progress value | |||
*/ | |||
public void setState(float state) { | |||
final int size = Math.round(100 * state); | |||
indicator.getStyle().setWidth(size, Unit.PCT); | |||
} | |||
/** | |||
* Gets whether or not this progress indicator is indeterminate. In | |||
* indeterminate mode there is an animation indicating that the task is | |||
* running but without providing any information about the current progress. | |||
* | |||
* @return {@code true} if set to indeterminate mode, {@code false} | |||
* otherwise | |||
*/ | |||
public boolean isIndeterminate() { | |||
return indeterminate; | |||
} | |||
/** | |||
* Returns the current value of this progress bar. The value is a | |||
* {@code float} between 0 and 1 where 0 represents no progress at all and 1 | |||
* represents fully completed. | |||
* | |||
* @return the current progress value | |||
*/ | |||
public float getState() { | |||
return state; | |||
} |
@@ -53,8 +53,11 @@ import elemental.json.JsonObject; | |||
public class VRadioButtonGroup extends FocusableFlowPanelComposite | |||
implements Field, ClickHandler, HasEnabled { | |||
/** Default classname for this widget. */ | |||
public static final String CLASSNAME = "v-select-optiongroup"; | |||
/** Default classname for all radio buttons within this widget. */ | |||
public static final String CLASSNAME_OPTION = "v-select-option"; | |||
/** Default classname for the selected radio button within this widget. */ | |||
public static final String CLASSNAME_OPTION_SELECTED = "v-select-option-selected"; | |||
private final Map<RadioButton, JsonObject> optionsToItems; | |||
@@ -72,6 +75,9 @@ public class VRadioButtonGroup extends FocusableFlowPanelComposite | |||
private final String groupId; | |||
private List<Consumer<JsonObject>> selectionChangeListeners; | |||
/** | |||
* Constructs a widget for the RadioButtonGroup component. | |||
*/ | |||
public VRadioButtonGroup() { | |||
groupId = DOM.createUniqueId(); | |||
getWidget().setStyleName(CLASSNAME); | |||
@@ -80,8 +86,11 @@ public class VRadioButtonGroup extends FocusableFlowPanelComposite | |||
selectionChangeListeners = new ArrayList<>(); | |||
} | |||
/* | |||
* Build all the options | |||
/** | |||
* Build all the options. | |||
* | |||
* @param items | |||
* the list of options | |||
*/ | |||
public void buildOptions(List<JsonObject> items) { | |||
Roles.getRadiogroupRole().set(getElement()); | |||
@@ -194,6 +203,14 @@ public class VRadioButtonGroup extends FocusableFlowPanelComposite | |||
} | |||
} | |||
/** | |||
* Sets the tabulator index for the container element that holds the radio | |||
* buttons. It represents the entire radio button group within the browser's | |||
* focus cycle. | |||
* | |||
* @param tabIndex | |||
* tabulator index for the radio button group | |||
*/ | |||
public void setTabIndex(int tabIndex) { | |||
for (Widget anOptionsContainer : getWidget()) { | |||
FocusWidget widget = (FocusWidget) anOptionsContainer; | |||
@@ -201,9 +218,11 @@ public class VRadioButtonGroup extends FocusableFlowPanelComposite | |||
} | |||
} | |||
/** | |||
* Sets radio buttons enabled according to this widget's enabled and | |||
* read-only status, as well as each option's own enabled status. | |||
*/ | |||
protected void updateEnabledState() { | |||
// sets options enabled according to the widget's enabled, | |||
// readonly and each options own enabled | |||
for (Map.Entry<RadioButton, JsonObject> entry : optionsToItems | |||
.entrySet()) { | |||
RadioButton radioButton = entry.getKey(); | |||
@@ -214,10 +233,28 @@ public class VRadioButtonGroup extends FocusableFlowPanelComposite | |||
} | |||
} | |||
/** | |||
* Returns whether HTML is allowed in the item captions. | |||
* | |||
* @return {@code true} if the captions are used as HTML, {@code false} if | |||
* used as plain text | |||
*/ | |||
public boolean isHtmlContentAllowed() { | |||
return htmlContentAllowed; | |||
} | |||
/** | |||
* Sets whether HTML is allowed in the item captions. If set to | |||
* {@code true}, the captions are displayed as HTML and the developer is | |||
* responsible for ensuring no harmful HTML is used. If set to | |||
* {@code false}, the content is displayed as plain text. | |||
* <p> | |||
* This value is delegated from the RadioButtonGroupState. | |||
* | |||
* @param htmlContentAllowed | |||
* {@code true} if the captions are used as HTML, {@code false} | |||
* if used as plain text | |||
*/ | |||
public void setHtmlContentAllowed(boolean htmlContentAllowed) { | |||
this.htmlContentAllowed = htmlContentAllowed; | |||
} | |||
@@ -227,10 +264,22 @@ public class VRadioButtonGroup extends FocusableFlowPanelComposite | |||
return enabled; | |||
} | |||
/** | |||
* Returns whether this radio button group is read-only or not. | |||
* | |||
* @return {@code true} if this widget is read-only, {@code false} otherwise | |||
*/ | |||
public boolean isReadonly() { | |||
return readonly; | |||
} | |||
/** | |||
* Sets the read-only status of this radio button group. | |||
* | |||
* @param readonly | |||
* {@code true} if this widget should be read-only, {@code false} | |||
* otherwise | |||
*/ | |||
public void setReadonly(boolean readonly) { | |||
if (this.readonly != readonly) { | |||
this.readonly = readonly; | |||
@@ -246,6 +295,14 @@ public class VRadioButtonGroup extends FocusableFlowPanelComposite | |||
} | |||
} | |||
/** | |||
* Adds the given selection change handler to this widget. | |||
* | |||
* @param selectionChanged | |||
* the handler that should be triggered when selection changes | |||
* @return the registration object for removing the given handler when no | |||
* longer needed | |||
*/ | |||
public Registration addSelectionChangeHandler( | |||
Consumer<JsonObject> selectionChanged) { | |||
selectionChangeListeners.add(selectionChanged); | |||
@@ -253,6 +310,12 @@ public class VRadioButtonGroup extends FocusableFlowPanelComposite | |||
.remove(selectionChanged); | |||
} | |||
/** | |||
* Removes previous selection and adds new selection. | |||
* | |||
* @param selectedItemKey | |||
* the key of the selected radio button | |||
*/ | |||
public void selectItemKey(String selectedItemKey) { | |||
// At most one item could be selected so reset all radio buttons | |||
// before applying current selection |
@@ -53,23 +53,43 @@ public class VSlider extends SimpleFocusablePanel | |||
*/ | |||
private static final int MIN_SIZE = 50; | |||
/** | |||
* Current client-side communication engine. | |||
* | |||
* @deprecated this field is no longer used by the framework | |||
*/ | |||
@Deprecated | |||
protected ApplicationConnection client; | |||
/** | |||
* Current connector id. | |||
* | |||
* @deprecated this field is no longer used by the framework | |||
*/ | |||
@Deprecated | |||
protected String id; | |||
/** Is this widget disabled. */ | |||
protected boolean disabled; | |||
/** Is this widget read-only. */ | |||
protected boolean readonly; | |||
private int acceleration = 1; | |||
/** Minimum value of slider. */ | |||
protected double min; | |||
/** Maximum value of slider. */ | |||
protected double max; | |||
/** Resolution (precision level) of slider. */ | |||
protected int resolution; | |||
/** Current value of slider. */ | |||
protected Double value; | |||
private boolean updateValueOnClick; | |||
/** Current orientation (vertical/horizontal) of slider. */ | |||
protected SliderOrientation orientation = SliderOrientation.HORIZONTAL; | |||
private final HTML feedback = new HTML("", false); | |||
@SuppressWarnings("deprecation") | |||
private final VOverlay feedbackPopup = new VOverlay(true, false) { | |||
{ | |||
setOwner(VSlider.this); | |||
@@ -82,20 +102,20 @@ public class VSlider extends SimpleFocusablePanel | |||
} | |||
}; | |||
/* DOM element for slider's base */ | |||
/** DOM element for slider's base. */ | |||
private final Element base; | |||
private static final int BASE_BORDER_WIDTH = 1; | |||
/* DOM element for slider's handle */ | |||
/** DOM element for slider's handle. */ | |||
private final Element handle; | |||
/* DOM element for decrement arrow */ | |||
/** DOM element for decrement arrow. */ | |||
private final Element smaller; | |||
/* DOM element for increment arrow */ | |||
/** DOM element for increment arrow. */ | |||
private final Element bigger; | |||
/* Temporary dragging/animation variables */ | |||
/** Temporary dragging/animation variables. */ | |||
private boolean dragging = false; | |||
private VLazyExecutor delayedValueUpdater = new VLazyExecutor(100, () -> { | |||
@@ -103,6 +123,9 @@ public class VSlider extends SimpleFocusablePanel | |||
acceleration = 1; | |||
}); | |||
/** | |||
* Constructs a widget for the Slider component. | |||
*/ | |||
public VSlider() { | |||
super(); | |||
@@ -138,6 +161,15 @@ public class VSlider extends SimpleFocusablePanel | |||
updateStyleNames(style, true); | |||
} | |||
/** | |||
* Updates the style names for this widget and the child elements. | |||
* | |||
* @param styleName | |||
* the new style name | |||
* @param isPrimaryStyleName | |||
* {@code true} if the new style name is primary, {@code false} | |||
* otherwise | |||
*/ | |||
protected void updateStyleNames(String styleName, | |||
boolean isPrimaryStyleName) { | |||
@@ -161,6 +193,13 @@ public class VSlider extends SimpleFocusablePanel | |||
} | |||
} | |||
/** | |||
* Updates the value shown in the feedback pop-up when the slider is moved. | |||
* The value should match the current value of this widget. | |||
* | |||
* @param value | |||
* the new value to show | |||
*/ | |||
public void setFeedbackValue(double value) { | |||
feedback.setText(String.valueOf(value)); | |||
} | |||
@@ -293,7 +332,7 @@ public class VSlider extends SimpleFocusablePanel | |||
delayedValueUpdater.trigger(); | |||
DOM.eventPreventDefault(event); | |||
event.preventDefault(); | |||
DOM.eventCancelBubble(event, true); | |||
} | |||
} else if (targ.equals(getElement()) | |||
@@ -321,7 +360,7 @@ public class VSlider extends SimpleFocusablePanel | |||
} | |||
private void processMouseWheelEvent(final Event event) { | |||
final int dir = DOM.eventGetMouseWheelVelocityY(event); | |||
final int dir = event.getMouseWheelVelocityY(); | |||
if (dir < 0) { | |||
increaseValue(false); | |||
@@ -331,7 +370,7 @@ public class VSlider extends SimpleFocusablePanel | |||
delayedValueUpdater.trigger(); | |||
DOM.eventPreventDefault(event); | |||
event.preventDefault(); | |||
DOM.eventCancelBubble(event, true); | |||
} | |||
@@ -347,7 +386,7 @@ public class VSlider extends SimpleFocusablePanel | |||
handle.addClassName(getStylePrimaryName() + "-handle-active"); | |||
DOM.setCapture(getElement()); | |||
DOM.eventPreventDefault(event); // prevent selecting text | |||
event.preventDefault(); // prevent selecting text | |||
DOM.eventCancelBubble(event, true); | |||
event.stopPropagation(); | |||
} | |||
@@ -432,7 +471,8 @@ public class VSlider extends SimpleFocusablePanel | |||
* webkit (only browser that really supports touches). | |||
* | |||
* @param event | |||
* @return | |||
* the event whose position to check | |||
* @return the client position | |||
*/ | |||
protected int getEventPosition(Event event) { | |||
if (isVertical()) { | |||
@@ -442,6 +482,9 @@ public class VSlider extends SimpleFocusablePanel | |||
} | |||
} | |||
/** | |||
* Run internal layouting. | |||
*/ | |||
public void iLayout() { | |||
if (isVertical()) { | |||
setHeight(); | |||
@@ -555,18 +598,54 @@ public class VSlider extends SimpleFocusablePanel | |||
return KeyCodes.KEY_RIGHT; | |||
} | |||
/** | |||
* Sets the current client-side communication engine. | |||
* | |||
* @param client | |||
* the application connection that manages this component | |||
* @deprecated the updated field is no longer used by the framework | |||
*/ | |||
@Deprecated | |||
public void setConnection(ApplicationConnection client) { | |||
this.client = client; | |||
} | |||
/** | |||
* Sets the id of this component's connector. | |||
* | |||
* @param id | |||
* the connector id | |||
* @deprecated the updated field is no longer used by the framework | |||
*/ | |||
@Deprecated | |||
public void setId(String id) { | |||
this.id = id; | |||
} | |||
/** | |||
* Disables or enables this slider. Users cannot interact with a disabled | |||
* widget, and the default styles show it as grayed out (via opacity). The | |||
* slider is enabled by default. | |||
* | |||
* @param disabled | |||
* a boolean value specifying whether the slider should be | |||
* disabled or not | |||
* @see #setReadOnly(boolean) | |||
*/ | |||
public void setDisabled(boolean disabled) { | |||
this.disabled = disabled; | |||
} | |||
/** | |||
* Sets the read-only status of this slider. Users cannot interact with a | |||
* read-only widget, but the default styles don't show it grayed out unless | |||
* it's also disabled. The slider is not read-only by default. | |||
* | |||
* @param readonly | |||
* a boolean value specifying whether the slider should be in | |||
* read-only mode or not | |||
* @see #setDisabled(boolean) | |||
*/ | |||
public void setReadOnly(boolean readonly) { | |||
this.readonly = readonly; | |||
} | |||
@@ -575,6 +654,13 @@ public class VSlider extends SimpleFocusablePanel | |||
return orientation == SliderOrientation.VERTICAL; | |||
} | |||
/** | |||
* Sets the slider orientation. Updates the style names if the given | |||
* orientation differs from previously set orientation. | |||
* | |||
* @param orientation | |||
* the orientation to use | |||
*/ | |||
public void setOrientation(SliderOrientation orientation) { | |||
if (this.orientation != orientation) { | |||
this.orientation = orientation; | |||
@@ -582,14 +668,35 @@ public class VSlider extends SimpleFocusablePanel | |||
} | |||
} | |||
/** | |||
* Sets the minimum value for slider. | |||
* | |||
* @param value | |||
* the minimum value to use | |||
*/ | |||
public void setMinValue(double value) { | |||
min = value; | |||
} | |||
/** | |||
* Sets the maximum value for slider. | |||
* | |||
* @param value | |||
* the maximum value to use | |||
*/ | |||
public void setMaxValue(double value) { | |||
max = value; | |||
} | |||
/** | |||
* Sets the resolution (precision level) for slider as the number of | |||
* fractional digits that are considered significant. Determines how big | |||
* change is used when increasing or decreasing the value, and where more | |||
* precise values get rounded. | |||
* | |||
* @param resolution | |||
* the number of digits after the decimal point | |||
*/ | |||
public void setResolution(int resolution) { | |||
this.resolution = resolution; | |||
} | |||
@@ -664,6 +771,7 @@ public class VSlider extends SimpleFocusablePanel | |||
} | |||
} | |||
@SuppressWarnings("deprecation") | |||
@Override | |||
public com.google.gwt.user.client.Element getSubPartElement( | |||
String subPart) { | |||
@@ -674,6 +782,7 @@ public class VSlider extends SimpleFocusablePanel | |||
return null; | |||
} | |||
@SuppressWarnings("deprecation") | |||
@Override | |||
public String getSubPartName( | |||
com.google.gwt.user.client.Element subElement) { | |||
@@ -687,6 +796,8 @@ public class VSlider extends SimpleFocusablePanel | |||
* Specifies whether or not click event should update the Slider's value. | |||
* | |||
* @param updateValueOnClick | |||
* {@code true} if a click should update slider's value, | |||
* {@code false} otherwise | |||
*/ | |||
public void setUpdateValueOnClick(boolean updateValueOnClick) { | |||
this.updateValueOnClick = updateValueOnClick; |
@@ -45,9 +45,12 @@ public class SliderConnector extends AbstractFieldConnector | |||
private final ElementResizeListener resizeListener = event -> getWidget() | |||
.iLayout(); | |||
@SuppressWarnings("deprecation") | |||
@Override | |||
public void init() { | |||
super.init(); | |||
// The widget no longer uses the connection, but the value is still set | |||
// to ensure backwards compatibility. | |||
getWidget().setConnection(getConnection()); | |||
getWidget().addValueChangeHandler(this); | |||
@@ -78,10 +81,13 @@ public class SliderConnector extends AbstractFieldConnector | |||
rpc.valueChanged(event.getValue()); | |||
} | |||
@SuppressWarnings("deprecation") | |||
@Override | |||
public void onStateChanged(StateChangeEvent stateChangeEvent) { | |||
super.onStateChanged(stateChangeEvent); | |||
// The widget no longer uses the connector id, but the value is still | |||
// set to ensure backwards compatibility. | |||
getWidget().setId(getConnectorId()); | |||
getWidget().setDisabled(!isEnabled()); | |||
getWidget().setReadOnly(isReadOnly()); |
@@ -30,6 +30,7 @@ public class RadioButtonGroupState extends AbstractSingleSelectState { | |||
primaryStyleName = "v-select-optiongroup"; | |||
} | |||
/** Is HTML allowed in the item captions. */ | |||
@DelegateToWidget | |||
public boolean htmlContentAllowed = false; | |||
} |