Package org.evoludo.ui

Class ContextMenu

Object

UIObject

Widget

Panel

ComplexPanel

FlowPanel

ContextMenu

All Implemented Interfaces:

ContextMenuHandler, MouseOutHandler, MouseOverHandler, TouchCancelHandler, TouchEndHandler, TouchMoveHandler, TouchStartHandler, HasAttachHandlers, EventHandler, HasHandlers, EventListener, HasVisibility, HasWidgets, HasWidgets.ForIsWidget, IndexedPanel, IndexedPanel.ForIsWidget, InsertPanel, InsertPanel.ForIsWidget, IsWidget, Iterable<Widget>, FullscreenChangeHandler, HasFullscreenChangeHandlers

public class ContextMenu
extends FlowPanel
implements ContextMenuHandler, MouseOverHandler, MouseOutHandler, TouchStartHandler, TouchEndHandler, TouchMoveHandler, TouchCancelHandler, FullscreenChangeHandler, HasFullscreenChangeHandlers

Context menu extension to GWT's user interface.

Main class for implementing context menus in GWT applications. Context menus work through a shared instance (like Tooltip's). Each widget that sports context menus (the listener widget) must be associated with a context menu provider.

The context menu opens when the ContextMenuHandler fires (typically by a right click on mouse as a pointing device and a two-finger tap/click on a touch pad). For devices without a pointer the context menu is triggered by a two-finger touch (after some configurable delay). The context menu is automatically closed for one of the following events:

1. an entry has been selected
2. scrolling of the window
3. on devices with pointers: once the pointer exited the menu (after some delay)
4. on devices without pointers: by tapping anywhere else on the screen

CSS Style Rules

.gwt-ContextMenu

the context menu element.

Author:

Christoph Hauert

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	ContextMenu.Listener	Listener interface for widgets that offer context menus.
static interface	ContextMenu.Provider	Provider interface for classes that are responsible for supplying the contents of the context menu.
protected class	ContextMenu.Registration	Manage registrations of listener widgets, their context menu providers and the corresponding event handlers.
class	ContextMenu.TouchTimer	Timer for handling touch events triggering the context menu.

Nested classes/interfaces inherited from class UIObject

UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled

Nested classes/interfaces inherited from interface HasWidgets

HasWidgets.ForIsWidget

Nested classes/interfaces inherited from interface IndexedPanel

IndexedPanel.ForIsWidget

Nested classes/interfaces inherited from interface InsertPanel

InsertPanel.ForIsWidget

Field Summary

Fields

Modifier and Type	Field	Description
private boolean	autoClose	true to close sub-menus automatically when pointer exited the sub-menu.
private boolean	autoHide	true to automatically set timer for hiding context menu after pointer exited context menu.
private boolean	autoOpen	true to open sub-menus automatically on hovering over the corresponding parent menu item.
protected ContextMenu	childMenu	Reference to current child menu or null if no child menu is visible.
protected static ContextMenu	contextMenu	Shared instance of context menu.
private static final int	DEFAULT_OFFSET_X	Default horizontal offset of context menu relative to the coordinates of the context menu triggering event.
private static final int	DEFAULT_OFFSET_Y	Default vertical offset of context menu relative to the coordinates of the context menu triggering event.
private static final int	DELAY_HIDE	Default delay before hiding the context (sub)menu (in milliseconds) after the pointer has exited the context (sub)menu.
private int	delayHide	Delay before hiding the context (sub)menu (in milliseconds) after the pointer has exited the context (sub)menu.
(package private) HandlerRegistration	fullscreenChangeHandler	Reference to fullscreen change handler.
private Timer	hideContextMenuTimer	Timer for closing the context menu after a fixed delay.
private boolean	isMouseOver	true if pointer is currently over context (sub)menu.
static final int	LONG_TOUCH_TIME	Delay in milliseconds before the touch event is considered a 'long touch' instead of a 'tap'.
private int	longTouch	Delay before two finger touch triggers context menu, provided that no other touch event fired during delayTap milliseconds.
private int	offsetX	Horizontal offset of context menu relative to coordinates of context menu triggering event.
private int	offsetY	Vertical offset of context menu relative to coordinates of context menu triggering event.
protected ContextMenu	parentMenu	Reference to the parent menu.
protected HashMap<ContextMenu.Listener,ContextMenu.Registration>	participants	Lookup table of listener widgets sporting context menus and their corresponding providers of the context menu contents.
protected Style	style	Reference to style of context menu.
protected ContextMenu.TouchTimer	touchTimer	Timer for handling touch events that are scheduled to trigger context menu.

Fields inherited from class UIObject

DEBUG_ID_PREFIX

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	ContextMenu()	Create new context menu.
	ContextMenu(ContextMenu parent)	Create new context submenu for parent menu.

Method Summary

Modifier and Type	Method	Description
ContextMenuItem	add(String name, ContextMenu submenu)	Add new submenu to context menu.
void	add(ContextMenu.Listener listener, ContextMenu.Provider provider)	Register a new listener widget for context menu requests and associate with the provider of the context menu.
HandlerRegistration	addFullscreenChangeHandler(FullscreenChangeHandler handler)	Adds a FullscreenChangeEvent handler.
void	addSeparator()	Add new separator to context menu.
protected void	cancelHideTimer()	Cancel the timer for hiding the context menu.
void	close()	Close submenu or context menu if this is the top level.
void	closeAll()	Recursively close hierarchy of context submenus, including the top level context menu.
void	closeChildMenu()	Close submenu, if one is showing.
ContextMenu	getParentMenu()	Get the parent menu.
boolean	isAutoClose()	Checks if submenus close automatically when pointer stops hovering over corresponding menu item in parent menu.
boolean	isAutoHide()	Checks if context menu hides automatically (with some delay) after pointer exited.
boolean	isAutoOpen()	Checks if submenus open automatically when pointer hovers over corresponding menu item in parent menu.
static boolean	isShowing()	Check if context menu is visible.
boolean	isSubmenu()	Check if this is a submenu.
void	onContextMenu(ContextMenuEvent event)
void	onFullscreenChange(FullscreenChangeEvent event)	Called when a FullscreenChangeEvent is fired.
void	onMouseOut(MouseOutEvent event)
void	onMouseOver(MouseOverEvent event)
void	onTouchCancel(TouchCancelEvent event)
void	onTouchEnd(TouchEndEvent event)
void	onTouchMove(TouchMoveEvent event)
void	onTouchStart(TouchStartEvent event)
protected void	open()	Open submenu.
void	openChildMenu(ContextMenu child)	Open submenu child.
void	setAutoClose(boolean auto)	Sets whether submenus should close automatically when pointer stops hovering over corresponding menu item in parent menu.
void	setAutoHide(boolean auto)	Sets whether context menu hides automatically (with delay) after pointer exits context menu.
void	setAutoOpen(boolean auto)	Sets whether submenus should open automatically when pointer hovers over corresponding menu item in parent menu.
void	setDelayHide(int delay)	Set delay before hiding the context (sub)menu (in milliseconds) after the pointer has exited the context menu, provided that autoHide is set to true.
protected void	setHideTimer()	Set timer for delayed hiding of context menu if autoClose is true.
void	setLongTouch(int delay)	Set delay (in milliseconds) before showing the context menu after a two finger touch, provided that no other touch events fired during delay.
void	setOffset(int ox, int oy)	Sets the horizontal and vertical offset between the location where the context menu was triggered and the position of the top left corner of the context menu.
static ContextMenu	sharedContextMenu()	The context menu is added to the RootPanel of the GWT application and shared among all elements that sport a context menu.
protected void	showAt(int x, int y)	Show context menu (or submenu) at position (x, y) relative to browser window.
void	showAt(ContextMenu.Listener listener, int x, int y)	Prepares context menu (or submenu) for showing at position (x, y) relative to browser window.

Methods inherited from class FlowPanel

add, clear, insert, insert

Methods inherited from class ComplexPanel

add, add, adjustIndex, checkIndexBoundsForAccess, checkIndexBoundsForInsertion, getChildren, getWidget, getWidgetCount, getWidgetIndex, getWidgetIndex, insert, insert, iterator, remove, remove

Methods inherited from class Panel

add, adopt, doAttachChildren, doDetachChildren, orphan, remove

Methods inherited from class Widget

addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, fireEvent, getHandlerCount, getLayoutData, getParent, isAttached, isOrWasAttached, onAttach, onBrowserEvent, onDetach, onLoad, onUnload, removeFromParent, setLayoutData, sinkEvents, unsinkEvents

Methods inherited from class UIObject

addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, onEnsureDebugId, removeStyleDependentName, removeStyleName, resolvePotentialElement, setElement, setElement, setHeight, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkBitlessEvent, toString

Methods inherited from class Object

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

Methods inherited from interface HasHandlers

fireEvent

Methods inherited from interface IndexedPanel

getWidget, getWidgetCount, getWidgetIndex, remove

Methods inherited from interface IndexedPanel.ForIsWidget

getWidgetIndex

Methods inherited from interface InsertPanel.ForIsWidget

add

Methods inherited from interface Iterable

forEach, spliterator

Field Details

DEFAULT_OFFSET_X

private static final int DEFAULT_OFFSET_X

Default horizontal offset of context menu relative to the coordinates of the context menu triggering event.

See Also:

• offsetX
• Constant Field Values

DEFAULT_OFFSET_Y

private static final int DEFAULT_OFFSET_Y

Default vertical offset of context menu relative to the coordinates of the context menu triggering event.

See Also:

• Constant Field Values

offsetX

private int offsetX

Horizontal offset of context menu relative to coordinates of context menu triggering event. In general, this should be a negative number such that any pointing device actually ends up on top of the context menu.

See Also:

• DEFAULT_OFFSET_X
• setOffset(int, int)
• showAt(int, int)

offsetY

private int offsetY

Vertical offset of context menu relative to coordinates of context menu triggering event. In general, this should be a negative number such that any pointing device actually ends up on top of the context menu.

See Also:

• DEFAULT_OFFSET_Y
• setOffset(int, int)
• showAt(int, int)

DELAY_HIDE

private static final int DELAY_HIDE

Default delay before hiding the context (sub)menu (in milliseconds) after the pointer has exited the context (sub)menu.

See Also:

• Constant Field Values

delayHide

private int delayHide

Delay before hiding the context (sub)menu (in milliseconds) after the pointer has exited the context (sub)menu.

See Also:

• DELAY_HIDE
• setDelayHide(int)
• setHideTimer()
• cancelHideTimer()

LONG_TOUCH_TIME

public static final int LONG_TOUCH_TIME

Delay in milliseconds before the touch event is considered a 'long touch' instead of a 'tap'.

See Also:

• Constant Field Values

longTouch

private int longTouch

Delay before two finger touch triggers context menu, provided that no other touch event fired during delayTap milliseconds.

See Also:

• LONG_TOUCH_TIME
• setLongTouch(int)

style

protected Style style

Reference to style of context menu. Most important to control positioning of context menu.

autoHide

private boolean autoHide

true to automatically set timer for hiding context menu after pointer exited context menu.

autoOpen

private boolean autoOpen

true to open sub-menus automatically on hovering over the corresponding parent menu item.

autoClose

private boolean autoClose

true to close sub-menus automatically when pointer exited the sub-menu.

isMouseOver

private boolean isMouseOver

true if pointer is currently over context (sub)menu.

fullscreenChangeHandler

HandlerRegistration fullscreenChangeHandler

Reference to fullscreen change handler. When entering fullscreen the context menu needs to be moved from the RootPanel to the fullscreen element and vice versa.

participants

protected HashMap<ContextMenu.Listener,ContextMenu.Registration> participants

Lookup table of listener widgets sporting context menus and their corresponding providers of the context menu contents.

parentMenu

protected ContextMenu parentMenu

Reference to the parent menu. This is null for the shared, top level context menu.

childMenu

protected ContextMenu childMenu

Reference to current child menu or null if no child menu is visible.

contextMenu

protected static ContextMenu contextMenu

Shared instance of context menu.

hideContextMenuTimer

private Timer hideContextMenuTimer

Timer for closing the context menu after a fixed delay.

See Also:

• DELAY_HIDE

touchTimer

protected ContextMenu.TouchTimer touchTimer

Timer for handling touch events that are scheduled to trigger context menu.

Constructor Details

ContextMenu

protected ContextMenu()

Create new context menu. Use shared instance to create top level context menu, sharedContextMenu().

ContextMenu

public ContextMenu(ContextMenu parent)

Create new context submenu for parent menu. Cannot be used to create top level context menu. Use shared instance instead, sharedContextMenu().

Note: for submenus only.

Parameters:

parent - menu (cannot be null)

Method Details

sharedContextMenu

public static ContextMenu sharedContextMenu()

The context menu is added to the RootPanel of the GWT application and shared among all elements that sport a context menu. Always use this shared instance to build context menus.

Returns:

shared instance of context menu.

isShowing

public static boolean isShowing()

Check if context menu is visible.

Returns:

true if context menu is showing

add

public void add(ContextMenu.Listener listener,
 ContextMenu.Provider provider)

Register a new listener widget for context menu requests and associate with the provider of the context menu.

Parameters:

listener - widget sporting a context menu

provider - provides context menu entries for this listener widget

addSeparator

public void addSeparator()

Add new separator to context menu.

add

public ContextMenuItem add(String name,
 ContextMenu submenu)

Add new submenu to context menu.

Parameters:

name - of menu item with submenu

submenu - to add

Returns:

context menu item that controls submenu

showAt

protected void showAt(int x,
 int y)

Show context menu (or submenu) at position (x, y) relative to browser window.

Parameters:

x - horizontal position of context menu

y - vertical position of context menu

showAt

public void showAt(ContextMenu.Listener listener,
 int x,
 int y)

Prepares context menu (or submenu) for showing at position (x, y) relative to browser window. Retrieves the context menu provider for the listener widget and asks the provider to supply context menu for coordinates (x', y') relative to listener widget. No context menu is shown if no provider found or if provider did not supply any context menu entries.

Parameters:

listener - widget that requested the context menu

x - horizontal position of context menu

y - vertical position of context menu

See Also:

• ContextMenu.Provider.populateContextMenuAt(ContextMenu, int, int)

openChildMenu

public void openChildMenu(ContextMenu child)

Open submenu child. If needed, first close any other currently open submenu.

Parameters:

child - new child menu to open

closeChildMenu

public void closeChildMenu()

Close submenu, if one is showing.

open

protected void open()

Open submenu.

close

public void close()

Close submenu or context menu if this is the top level.

closeAll

public void closeAll()

Recursively close hierarchy of context submenus, including the top level context menu.

setHideTimer

protected void setHideTimer()

Set timer for delayed hiding of context menu if autoClose is true. This timer is used when pointer exits context (sub)menu.

See Also:

• delayHide

cancelHideTimer

protected void cancelHideTimer()

Cancel the timer for hiding the context menu. Triggered when pointer re-enters context (sub)menu before the timer for hiding the menu runs out. This cascades through the entire (sub)menu hierarchy.

setAutoHide

public void setAutoHide(boolean auto)

Sets whether context menu hides automatically (with delay) after pointer exits context menu.

Parameters:

auto - true to automatically hide context menu after delay

See Also:

• setAutoClose(boolean)
• setDelayHide(int)

isAutoHide

public boolean isAutoHide()

Checks if context menu hides automatically (with some delay) after pointer exited.

Returns:

true if context menu hides automatically

See Also:

• setAutoHide(boolean)

setAutoOpen

public void setAutoOpen(boolean auto)

Sets whether submenus should open automatically when pointer hovers over corresponding menu item in parent menu.

Parameters:

auto - true to open submenus automatically

See Also:

• setAutoClose(boolean)

isAutoOpen

public boolean isAutoOpen()

Checks if submenus open automatically when pointer hovers over corresponding menu item in parent menu.

Returns:

true if context menu opens automatically

See Also:

• setAutoOpen(boolean)

setAutoClose

public void setAutoClose(boolean auto)

Sets whether submenus should close automatically when pointer stops hovering over corresponding menu item in parent menu.

Parameters:

auto - true to close submenus automatically

See Also:

• setAutoOpen(boolean)

isAutoClose

public boolean isAutoClose()

Checks if submenus close automatically when pointer stops hovering over corresponding menu item in parent menu.

Returns:

true if context menu closes automatically

See Also:

• setAutoClose(boolean)

setOffset

public void setOffset(int ox,
 int oy)

Sets the horizontal and vertical offset between the location where the context menu was triggered and the position of the top left corner of the context menu. Typically the offset should be negative in both directions to ensure that once the context menu is visible, the pointer is located inside the context menu.

Parameters:

ox - the horizontal offset

oy - the vertical offset

See Also:

• offsetX
• offsetY

setDelayHide

public void setDelayHide(int delay)

Set delay before hiding the context (sub)menu (in milliseconds) after the pointer has exited the context menu, provided that autoHide is set to true.

Parameters:

delay - the delay for hiding context (sub)menu

See Also:

• delayHide

setLongTouch

public void setLongTouch(int delay)

Set delay (in milliseconds) before showing the context menu after a two finger touch, provided that no other touch events fired during delay.

Parameters:

delay - the delay for showing context menu after two-finger touch

See Also:

• delayHide

getParentMenu

public ContextMenu getParentMenu()

Get the parent menu. The parent can be a submenu or null for the top level context menu.

Returns:

the parent (sub)menu

isSubmenu

public boolean isSubmenu()

Check if this is a submenu. Returns false only for the top level context menu

Returns:

true if this is a submenu

onContextMenu

public void onContextMenu(ContextMenuEvent event)

Specified by:

onContextMenu in interface ContextMenuHandler

onMouseOver

public void onMouseOver(MouseOverEvent event)

Pointer (re-)entered context (sub)menu. Cancel timer to hide (sub)menu, in case it was running.

Specified by:

onMouseOver in interface MouseOverHandler

onMouseOut

public void onMouseOut(MouseOutEvent event)

Pointer exited context (sub)menu. Start timer to hide (sub)menu.

Specified by:

onMouseOut in interface MouseOutHandler

onTouchStart

public void onTouchStart(TouchStartEvent event)

Note: gesture events are proprietary implementations by Apple. Let's try to do without and stick to more primitive touch events.

Specified by:

onTouchStart in interface TouchStartHandler

onTouchMove

public void onTouchMove(TouchMoveEvent event)

One or more touches moved. Cancel request to show context menu (if scheduled).

Note: gesture events are proprietary implementations by Apple. Let's try to do without and stick to more primitive touch events.

Specified by:

onTouchMove in interface TouchMoveHandler

onTouchEnd

public void onTouchEnd(TouchEndEvent event)

One or more touches ended. Cancel request to show context menu (if scheduled).

Note: gesture events are proprietary implementations by Apple. Let's try to do without and stick to more primitive touch events.

Specified by:

onTouchEnd in interface TouchEndHandler

onTouchCancel

public void onTouchCancel(TouchCancelEvent event)

Touch canceled. Cancel request to show context menu (if scheduled).

Note: gesture events are proprietary implementations by Apple. Let's try to do without and stick to more primitive touch events.

Specified by:

onTouchCancel in interface TouchCancelHandler

addFullscreenChangeHandler

public HandlerRegistration addFullscreenChangeHandler(FullscreenChangeHandler handler)

Description copied from interface: HasFullscreenChangeHandlers

Adds a FullscreenChangeEvent handler.

Specified by:

addFullscreenChangeHandler in interface HasFullscreenChangeHandlers

Parameters:

handler - the fullscreenchange handler

Returns:

HandlerRegistration used to remove this handler

onFullscreenChange

public void onFullscreenChange(FullscreenChangeEvent event)

Called when a FullscreenChangeEvent is fired.

Placement of shared context menu element in the DOM needs to be adjusted when entering or exiting fullscreen mode.

Specified by:

onFullscreenChange in interface FullscreenChangeHandler

Parameters:

event - the FullscreenChangeEvent that was fired