com.gwtplatform.mvp.client

Class PresenterWidget<V extends View>

java.lang.Object

com.gwtplatform.mvp.client.HandlerContainerImpl

com.gwtplatform.mvp.client.PresenterWidget<V>

Type Parameters:

V - The View type.

All Implemented Interfaces:

HasHandlers, IsWidget, HandlerContainer, HasPopupSlot, HasSlots

Direct Known Subclasses:

EditManufacturerPresenter, EditRatingPresenter, HeaderPresenter, MessagesPresenter, NavigationTabPresenter, Presenter, RootPresenter

public abstract class PresenterWidget<V extends View>
extends HandlerContainerImpl
implements HasHandlers, HasSlots, HasPopupSlot, IsWidget

A presenter that does not have to be a singleton. Pages from your application will usually be singletons and extend the Presenter class.

Choosing between a Presenter and PresenterWidget is a design decision that requires some thought. For example, a PresenterWidget is useful when you need a custom widget with extensive logic. For example, a chat box that can be instantiated multiple times and needs to communicate with the server would be a good candidate for a PresenterWidget. The drawback of a PresenterWidget is that it is managed by its parent presenter, which increases coupling. Therefore, you should use a Presenter when the parent is not expected to know its child. Moreover, only Presenter can be attached to name tokens in order to support browser history.

PresenterWidgets and Presenters are organized in a hierarchy. Internally, parent presenters have links to their currently attached children presenters. A parent Presenter can contain either Presenters or PresenterWidgets, but a PresenterWidget can only contain PresenterWidgets.

To reveal a PresenterWidget you should insert it within a slot of its containing presenter using one of the following methods:

• setInSlot(Object, PresenterWidget)
• setInSlot(Object, PresenterWidget, boolean)
• addToSlot(Object, PresenterWidget)
• addToPopupSlot(PresenterWidget)
• addToPopupSlot(PresenterWidget, boolean)

Revealing a Presenter is done differently, refer to the class documentation for more details.

To hide a PresenterWidget or a Presenter you can use setInSlot(java.lang.Object, com.gwtplatform.mvp.client.PresenterWidget<?>) to place another presenter in the same slot, or you can call one of the following methods:

• removeFromSlot(Object, PresenterWidget)
• clearSlot(Object)
• PopupView.hide() if the presenter is a popup or a dialog box.

Hide a Presenter using these methods, but

A presenter has a number of lifecycle methods that you can hook on to:

• HandlerContainerImpl.onBind()
• onReveal()
• onReset()
• onHide()
• HandlerContainerImpl.onUnbind()

Revealing or hiding a PresenterWidget triggers an internal chain of events that result in these lifecycle methods being called. For an example, here is what happens following a call to setInSlot(Object, PresenterWidget):

• If a presenter already occupies this slot it is removed.
• If the presenter owning the slot is currently visible then onHide() is called on the removed presenter and, recursively, on its children (bottom-up: first the children, then the parent)
• If the parent is not visible and is a Presenter, it asks to be set in one of its parent slot by firing a RevealContentEvent. For more details, see the documentation for Presenter.
• If, at this point, the presenter owning the slot is not visible, then the chain stops. Otherwise, onReveal() is called on the PresenterWidget that was just added.
• onReveal() is called recursively on that presenter's children (top-down: first the parent, then the children).
• If setInSlot(Object, PresenterWidget, boolean) was called with false as the third parameter then the process stops. Otherwise, onReset() is called on all the currently visible presenters (top-down: first the parent, then the children).

Constructor Summary

Constructors

Constructor and Description
PresenterWidget(boolean autoBind, EventBus eventBus, V view) Creates a PresenterWidget that is not necessarily using automatic binding.
PresenterWidget(EventBus eventBus, V view) Creates a PresenterWidget that uses automatic binding.

Method Summary

Methods

Modifier and Type	Method and Description
protected <H extends EventHandler> HandlerRegistration	addHandler(GwtEvent.Type<H> type, H handler) Registers an event handler towards the EventBus.
protected <H extends EventHandler> void	addRegisteredHandler(GwtEvent.Type<H> type, H handler) Registers an event handler towards the EventBus and registers it to be automatically removed when HandlerContainerImpl.unbind() is called.
void	addToPopupSlot(PresenterWidget<? extends PopupView> child) This method sets some popup content within the Presenter and centers it.
void	addToPopupSlot(PresenterWidget<? extends PopupView> child, boolean center) This method sets some popup content within the Presenter.
void	addToSlot(Object slot, PresenterWidget<?> content) This method adds some content in a specific slot of the Presenter.
protected <H extends EventHandler> void	addVisibleHandler(GwtEvent.Type<H> type, H handler) Registers an event handler towards the EventBus and registers it to be only active when the presenter is visible is called.
Widget	asWidget()
void	clearSlot(Object slot) This method clears the content in a specific slot.
void	fireEvent(GwtEvent<?> event)
protected EventBus	getEventBus() Access the EventBus object associated with that presenter.
V	getView() Returns the View for the current presenter.
Widget	getWidget() Deprecated.
boolean	isVisible() Verifies if the presenter is currently visible on the screen.
protected void	onHide() Lifecycle method called whenever this presenter is about to be hidden.
protected void	onReset() Lifecycle method called on all visible presenters whenever a presenter is revealed anywhere in the presenter hierarchy.
protected void	onReveal() Lifecycle method called whenever this presenter is about to be revealed.
void	removeFromPopupSlot(PresenterWidget<? extends PopupView> child) This method removes popup content within the Presenter.
void	removeFromSlot(Object slot, PresenterWidget<?> content) This method removes some content in a specific slot of the Presenter.
void	setInSlot(Object slot, PresenterWidget<?> content) This method sets some content in a specific slot of the Presenter.
void	setInSlot(Object slot, PresenterWidget<?> content, boolean performReset) This method sets some content in a specific slot of the Presenter.

Methods inherited from class com.gwtplatform.mvp.client.HandlerContainerImpl

bind, isBound, onBind, onUnbind, registerHandler, unbind

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PresenterWidget

public PresenterWidget(boolean autoBind,
               EventBus eventBus,
               V view)

Creates a PresenterWidget that is not necessarily using automatic binding. Automatic binding will only work when instantiating this object using Guice/GIN dependency injection. See HandlerContainerImpl.HandlerContainerImpl(boolean) for more details on automatic binding.

Parameters:

autoBind - true to request automatic binding, false otherwise.

eventBus - The EventBus.

view - The View.

PresenterWidget

public PresenterWidget(EventBus eventBus,
               V view)

Creates a PresenterWidget that uses automatic binding. This will only work when instantiating this object using Guice/GIN dependency injection. See HandlerContainerImpl.HandlerContainerImpl() for more details on automatic binding.

Parameters:

eventBus - The EventBus.

view - The View.

Method Detail

addToPopupSlot

public void addToPopupSlot(PresenterWidget<? extends PopupView> child)

Description copied from interface: HasPopupSlot

This method sets some popup content within the Presenter and centers it. The view associated with the content's presenter must inherit from PopupView. The popup will be visible and the corresponding presenter will receive the lifecycle events as needed.

Contrary to the View.setInSlot(Object, com.google.gwt.user.client.ui.IsWidget) method, no ResetPresentersEvent is fired, so onReset() is not invoked.

Specified by:

addToPopupSlot in interface HasPopupSlot

Parameters:

child - The popup child, a PresenterWidget.

See Also:

HasPopupSlot.addToPopupSlot(PresenterWidget)

addToPopupSlot

public void addToPopupSlot(PresenterWidget<? extends PopupView> child,
                  boolean center)

Description copied from interface: HasPopupSlot

This method sets some popup content within the Presenter. The view associated with the content's presenter must inherit from PopupView. The popup will be visible and the corresponding presenter will receive the lifecycle events as needed.

Contrary to the View.setInSlot(Object, com.google.gwt.user.client.ui.IsWidget) method, no ResetPresentersEvent is fired, so onReset() is not invoked.

Specified by:

addToPopupSlot in interface HasPopupSlot

Parameters:

child - The popup child, a PresenterWidget.

center - Pass true to center the popup, otherwise its position will not be adjusted.

See Also:

HasPopupSlot.addToPopupSlot(PresenterWidget)

removeFromPopupSlot

public void removeFromPopupSlot(PresenterWidget<? extends PopupView> child)

Description copied from interface: HasPopupSlot

This method removes popup content within the Presenter. The view associated with the content's presenter must inherit from PopupView.

Specified by:

removeFromPopupSlot in interface HasPopupSlot

Parameters:

child - The popup child, a PresenterWidget, which has previously been added using HasPopupSlot.addToPopupSlot(PresenterWidget) or HasPopupSlot.addToPopupSlot(PresenterWidget, boolean)

addToSlot

public void addToSlot(Object slot,
             PresenterWidget<?> content)

Description copied from interface: HasSlots

This method adds some content in a specific slot of the Presenter. The attached View should manage this slot when its View#addToSlot(Object, com.google.gwt.user.client.ui.Widget) is called.

Contrary to the HasSlots.setInSlot(java.lang.Object, com.gwtplatform.mvp.client.PresenterWidget<?>) method, no ResetPresentersEvent is fired, so onReset() is not invoked.

For more details on slots, see HasSlots.

Specified by:

addToSlot in interface HasSlots

Parameters:

slot - An opaque object identifying which slot this content is being added into.

content - The content, a PresenterWidget. Passing null will not add anything.

clearSlot

public void clearSlot(Object slot)

Description copied from interface: HasSlots

This method clears the content in a specific slot. No ResetPresentersEvent is fired. The attached View should manage this slot when its View#setInSlot(Object, com.google.gwt.user.client.ui.Widget) is called. It should also clear the slot when the View#setInSlot(Object, com.google.gwt.user.client.ui.Widget) method is called with null as a parameter.

For more details on slots, see HasSlots.

Specified by:

clearSlot in interface HasSlots

Parameters:

slot - An opaque object identifying which slot to clear.

fireEvent

public void fireEvent(GwtEvent<?> event)

Specified by:

fireEvent in interface HasHandlers

getView

public V getView()

Returns the View for the current presenter.

Returns:

The view.

asWidget

public Widget asWidget()

Specified by:

asWidget in interface IsWidget

getWidget

@Deprecated
public Widget getWidget()

Deprecated.

Makes it possible to access the Widget object associated with that presenter.

Returns:

The Widget associated with that presenter.

isVisible

public boolean isVisible()

Verifies if the presenter is currently visible on the screen. A presenter should be visible if it successfully revealed itself and was not hidden later.

Returns:

true if the presenter is visible, false otherwise.

removeFromSlot

public void removeFromSlot(Object slot,
                  PresenterWidget<?> content)

Description copied from interface: HasSlots

This method removes some content in a specific slot of the Presenter. No ResetPresentersEvent is fired. The attached View should manage this slot when its View#removeFromSlot(Object, com.google.gwt.user.client.ui.Widget) is called.

For more details on slots, see HasSlots.

Specified by:

removeFromSlot in interface HasSlots

Parameters:

slot - An opaque object identifying which slot this content is being removed from.

content - The content, a PresenterWidget. Passing null will not remove anything.

setInSlot

public void setInSlot(Object slot,
             PresenterWidget<?> content)

Description copied from interface: HasSlots

This method sets some content in a specific slot of the Presenter. A ResetPresentersEvent will be fired after the top-most visible presenter is revealed, resulting in a call to onReset().

For more details on slots, see HasSlots.

Specified by:

setInSlot in interface HasSlots

Parameters:

slot - An opaque object identifying which slot this content is being set into. The attached view should know what to do with this slot.

content - The content, a PresenterWidget. Passing null will clear the slot.

setInSlot

public void setInSlot(Object slot,
             PresenterWidget<?> content,
             boolean performReset)

Description copied from interface: HasSlots

This method sets some content in a specific slot of the Presenter. The attached View should manage this slot when its View#setInSlot(Object, com.google.gwt.user.client.ui.Widget) is called. It should also clear the slot when the setInSlot method is called with null as a parameter.

For more details on slots, see HasSlots.

Specified by:

setInSlot in interface HasSlots

Parameters:

slot - An opaque object identifying which slot this content is being set into.

content - The content, a PresenterWidget. Passing null will clear the slot.

performReset - Pass true if you want a ResetPresentersEvent to be fired after the content has been added and this presenter is visible, pass false otherwise.

addHandler

protected <H extends EventHandler> HandlerRegistration addHandler(GwtEvent.Type<H> type,
                                                      H handler)

Registers an event handler towards the EventBus. Use this only in the rare situations where you want to manually control when the handler is unregistered, otherwise call addRegisteredHandler(com.google.gwt.event.shared.GwtEvent.Type, EventHandler).

Type Parameters:

H - The handler type.

Parameters:

type - See GwtEvent.Type.

handler - The handler to register.

Returns:

The HandlerRegistration you should use to unregister the handler.

addRegisteredHandler

protected <H extends EventHandler> void addRegisteredHandler(GwtEvent.Type<H> type,
                                                 H handler)

Registers an event handler towards the EventBus and registers it to be automatically removed when HandlerContainerImpl.unbind() is called. This is usually the desired behavior, but if you want to unregister handlers manually use addHandler(com.google.gwt.event.shared.GwtEvent.Type<H>, H) instead.

Type Parameters:

H - The handler type.

Parameters:

type - See GwtEvent.Type.

handler - The handler to register.

See Also:

addHandler(com.google.gwt.event.shared.GwtEvent.Type, EventHandler)

addVisibleHandler

protected <H extends EventHandler> void addVisibleHandler(GwtEvent.Type<H> type,
                                              H handler)

Registers an event handler towards the EventBus and registers it to be only active when the presenter is visible is called.

Type Parameters:

H - The handler type.

Parameters:

type - See GwtEvent.Type.

handler - The handler to register.

See Also:

addRegisteredHandler(com.google.gwt.event.shared.GwtEvent.Type, com.google.gwt.event.shared.EventHandler), addHandler(com.google.gwt.event.shared.GwtEvent.Type, EventHandler)

getEventBus

protected final EventBus getEventBus()

Access the EventBus object associated with that presenter. You should not usually use this method to interact with the event bus. Instead call fireEvent(com.google.gwt.event.shared.GwtEvent<?>), addRegisteredHandler(com.google.gwt.event.shared.GwtEvent.Type<H>, H) or addHandler(com.google.gwt.event.shared.GwtEvent.Type<H>, H).

Returns:

The EventBus associated with that presenter.

onHide

protected void onHide()

Lifecycle method called whenever this presenter is about to be hidden.

Important: Make sure you call your superclass onHide() if you override. Also, do not call directly, see PresenterWidget for more details on lifecycle methods.

You should override this method to dispose of any object created directly or indirectly during the call to onReveal().

This method will not be invoked a multiple times without onReveal() being called.

In a presenter hierarchy, this method is called bottom-up: first on the child presenters, then on the parent.

onReset

protected void onReset()

Lifecycle method called on all visible presenters whenever a presenter is revealed anywhere in the presenter hierarchy.

Important: Make sure you call your superclass onReset() if you override. Also, do not call directly, fire a ResetPresentersEvent to perform a reset manually. See PresenterWidget for more details on lifecycle methods.

This is one of the most frequently used lifecycle method. This is usually a good place to refresh any information displayed by your presenter.

Note that onReset() is not called only when using addToSlot(Object, PresenterWidget), addToPopupSlot(PresenterWidget) or #setInSlot(Object, PresenterWidget, boolean)} with false as the third parameter.

In a presenter hierarchy, this method is called top-down: first on the parent presenters, then on the children.

onReveal

protected void onReveal()

Lifecycle method called whenever this presenter is about to be revealed.

Important: Make sure you call your superclass onReveal() if you override. Also, do not call directly, see PresenterWidget for more details on lifecycle methods.

You should override this method to perform any action or initialisation that needs to be done when the presenter is revealed. Any initialisation you perform here should be taken down in onHide().

Information that needs to be updated whenever the user navigates should be refreshed in onReset().

In a presenter hierarchy, this method is called top-down: first on the parent presenters, then on the children.