com.github.fluorumlabs.disconnect.vaadin.ContextMenu Maven / Gradle / Ivy
Show all versions of disconnect-vaadin Show documentation
package com.github.fluorumlabs.disconnect.vaadin;
import com.github.fluorumlabs.disconnect.core.annotations.WebComponent;
import com.github.fluorumlabs.disconnect.polymer.mixins.HasGestureEventListeners;
import com.github.fluorumlabs.disconnect.polymer.types.BooleanPropertyChangeEvent;
import com.github.fluorumlabs.disconnect.vaadin.elements.ContextMenuElement;
import com.github.fluorumlabs.disconnect.vaadin.mixins.HasElementMixin;
import com.github.fluorumlabs.disconnect.vaadin.mixins.HasItemsMixin;
import com.github.fluorumlabs.disconnect.vaadin.mixins.HasThemePropertyMixin;
import com.github.fluorumlabs.disconnect.vaadin.renderers.ContextMenuRenderer;
import com.github.fluorumlabs.disconnect.vaadin.types.MenuItem;
import com.github.fluorumlabs.disconnect.zero.component.AbstractComponent;
import com.github.fluorumlabs.disconnect.zero.component.Component;
import com.github.fluorumlabs.disconnect.zero.component.HasComponents;
import com.github.fluorumlabs.disconnect.zero.component.HasStyle;
import com.github.fluorumlabs.disconnect.zero.observable.ObservableEvent;
import js.web.dom.CustomEvent;
import js.web.dom.Event;
import js.web.dom.HTMLElement;
import javax.annotation.Nullable;
/**
* <vaadin-context-menu> is a Web Component for creating context menus. The content of the
* menu can be populated in three ways: imperatively by using the items API or a renderer callback function and
* declaratively by using Polymer's Templates.
*
* Items
* Items is a higher level convenience API for defining a (hierarchical) menu structure for the component.
* If a menu item has a non-empty children set, a sub-menu with the child items is opened
* next to the parent menu on mouseover, tap or a right arrow keypress.
*
* When an item is selected, <vaadin-context-menu> dispatches an "item-selected" event
* with the selected item as event.detail.value property.
*
*
contextMenu.items = [
* {text: 'Menu Item 1', children:
* [
* {text: 'Menu Item 1-1', checked: true},
* {text: 'Menu Item 1-2'}
* ]
* },
* {component: 'hr'},
* {text: 'Menu Item 2', children:
* [
* {text: 'Menu Item 2-1'},
* {text: 'Menu Item 2-2', disabled: true}
* ]
* },
* {text: 'Menu Item 3', disabled: true}
* ];
*
* contextMenu.addEventListener('item-selected', e => {
* const item = e.detail.value;
* console.log(`${item.text} selected`);
* });
*
* NOTE: when the items array is defined, the renderer or a template cannot be used.
*
* Rendering
* The renderer function provides root, contextMenu, model arguments when
* applicable.
* Generate DOM content by using model object properties if needed, append it to the root
* element and control the state of the host element by accessing contextMenu. Before generating
* new content, the renderer function should check if there is already content in root for reusing it.
*
* <vaadin-context-menu id="contextMenu">
* <p>This paragraph has a context menu.</p>
* </vaadin-context-menu>
*
* const contextMenu = document.querySelector('#contextMenu');
* contextMenu.renderer = (root, contextMenu, context) => {
* let listBox = root.firstElementChild;
* if (!listBox) {
* listBox = document.createElement('vaadin-list-box');
* root.appendChild(listBox);
* }
*
* let item = listBox.querySelector('vaadin-item');
* if (!item) {
* item = document.createElement('vaadin-item');
* listBox.appendChild(item);
* }
* item.textContent = 'Content of the selector: ' + context.target.textContent;
* };
*
* You can access the menu context inside the renderer using
* context.target and context.detail.
*
* Renderer is called on the opening of the context-menu and each time the related context is updated.
* DOM generated during the renderer call can be reused
* in the next renderer call and will be provided with the root argument.
* On first call it will be empty.
*
* NOTE: when the renderer function is defined, the template content
* is not in use.
*
*
Polymer Templates
* Alternatively to using the renderer, you can populate
* the menu content using Polymer's Templates:
*
* <vaadin-context-menu>
* <template>
* <vaadin-list-box>
* <vaadin-item>First menu item</vaadin-item>
* <vaadin-item>Second menu item</vaadin-item>
* </vaadin-list-box>
* </template>
* </vaadin-context-menu>
*
* “vaadin-contextmenu” Gesture Event
* vaadin-contextmenu is a gesture event (a custom event),
* which is dispatched after either contextmenu and long touch events.
* This enables support for both mouse and touch environments in a uniform way.
*
* <vaadin-context-menu> opens the menu overlay on the vaadin-contextmenu
* event by default.
*
* Menu Listener
* By default, the <vaadin-context-menu> element listens for the menu opening
* event on itself. In order to have a context menu on your content, wrap
* your content with the <vaadin-context-menu> element, and add a template
* element with a menu. Example:
*
* <vaadin-context-menu>
* <template>
* <vaadin-list-box>
* <vaadin-item>First menu item</vaadin-item>
* <vaadin-item>Second menu item</vaadin-item>
* </vaadin-list-box>
* </template>
*
* <p>This paragraph has the context menu provided in the above template.</p>
* <p>Another paragraph with the context menu.</p>
* </vaadin-context-menu>
*
* In case if you do not want to wrap the page content, you can listen for
* events on an element outside the <vaadin-context-menu> by setting the
* listenOn property:
*
* <vaadin-context-menu id="customListener">
* <template>
* <vaadin-list-box>
* ...
* </vaadin-list-box>
* </template>
* </vaadin-context-menu>
*
* <div id="menuListener">The element that listens for the context menu.</div>
*
* const contextMenu = document.querySelector
* ('vaadin-context-menu#customListener');
* contextMenu.listenOn = document.querySelector('#menuListener');
*
* Filtering Menu Targets
* By default, the listener element and all its descendants open the context
* menu. You can filter the menu targets to a smaller set of elements inside
* the listener element by setting the selector property.
*
* In the following example, only the elements matching .has-menu will open the context menu:
*
*
<vaadin-context-menu selector=".has-menu">
* <template>
* <vaadin-list-box>
* ...
* </vaadin-list-box>
* </template>
*
* <p class="has-menu">This paragraph opens the context menu</p>
* <p>This paragraph does not open the context menu</p>
* </vaadin-context-menu>
*
* Menu Context
* You can bind to the following properties in the menu template:
*
*
* target is the menu opening event target, which is the element that
* the user has called the context menu fordetail is the menu opening event detail
* In the following example, the menu item text is composed with the contents
* of the element that opened the menu:
*
* <vaadin-context-menu selector="li">
* <template>
* <vaadin-list-box>
* <vaadin-item>The menu target: [[target.textContent]]</vaadin-item>
* </vaadin-list-box>
* </template>
*
* <ul>
* <li>Foo</li>
* <li>Bar</li>
* <li>Baz</li>
* </ul>
* </vaadin-context-menu>
*
* Styling
* <vaadin-context-menu> uses <vaadin-context-menu-overlay> internal
* themable component as the actual visible context menu overlay. See
* See
* <vaadin-overlay> documentation
* for <vaadin-context-menu-overlay> parts.
*
* See
* ThemableMixin – how to apply styles for shadow parts
*
* Note: the theme attribute value set on <vaadin-context-menu> is
* propagated to the internal <vaadin-context-menu-overlay> component.
* In case of using nested menu items, the theme attribute is also propagated
* to internal vaadin-context-menu-list-box and vaadin-context-menu-item's.
*/
@WebComponent
public class ContextMenu extends AbstractComponent
implements HasElementMixin,
HasThemePropertyMixin,
HasItemsMixin,
HasGestureEventListeners,
HasStyle, HasComponents> {
public ContextMenu() {
super(ContextMenuElement.TAGNAME());
}
/**
* CSS selector that can be used to target any child element
* of the context menu to listen for openOn events.
*/
@Nullable
public String selector() {
return getNode().getSelector();
}
/**
* CSS selector that can be used to target any child element
* of the context menu to listen for openOn events.
*/
public ContextMenu selector(String selector) {
getNode().setSelector(selector);
return this;
}
/**
* True if the overlay is currently displayed.
*/
public boolean opened() {
return getNode().isOpened();
}
/**
* Event name to listen for opening the context menu.
*/
@Nullable
public String openOn() {
return getNode().getOpenOn();
}
/**
* Event name to listen for opening the context menu.
*/
public ContextMenu openOn(String openOn) {
getNode().setOpenOn(openOn);
return this;
}
/**
* The target element that's listened to for context menu opening events.
* By default the vaadin-context-menu listens to the target's vaadin-contextmenu
* events.
*/
public HTMLElement listenOn() {
return getNode().getListenOn();
}
/**
* The target element that's listened to for context menu opening events.
* By default the vaadin-context-menu listens to the target's vaadin-contextmenu
* events.
*/
public ContextMenu listenOn(HTMLElement listenOn) {
getNode().setListenOn(listenOn);
return this;
}
/**
* Event name to listen for closing the context menu.
*/
@Nullable
public String closeOn() {
return getNode().getCloseOn();
}
/**
* Event name to listen for closing the context menu.
*/
public ContextMenu closeOn(String closeOn) {
getNode().setCloseOn(closeOn);
return this;
}
/**
* Custom function for rendering the content of the menu overlay.
* Receives three arguments:
*
*
* root The root container DOM element. Append your content to it.contextMenu The reference to the <vaadin-context-menu> element.context The object with the menu context, contains:
*
* context.target the target of the menu opening event,context.detail the menu opening event detail.
*
*/
@Nullable
public ContextMenuRenderer renderer() {
return getNode().getRenderer();
}
/**
* Custom function for rendering the content of the menu overlay.
* Receives three arguments:
*
*
* root The root container DOM element. Append your content to it.contextMenu The reference to the <vaadin-context-menu> element.context The object with the menu context, contains:
*
* context.target the target of the menu opening event,context.detail the menu opening event detail.
*
*/
public ContextMenu renderer(ContextMenuRenderer renderer) {
getNode().setRenderer(renderer);
return this;
}
/**
* Manually invoke existing renderer.
*/
public void render() {
getNode().render();
}
/**
* Closes the overlay.
*/
public void close() {
getNode().close();
}
/**
* Opens the overlay.
*
* @param e used as the context for the menu. Overlay coordinates are taken from this event.
*/
public void open(Event e) {
getNode().open(e);
}
/**
* Fired when an item is selected when the context menu is populated using the `items` API.
*/
public ObservableEvent> itemSelectedEvent() {
return createEvent("item-selected");
}
/**
* Fired when the `opened` property changes.
*/
public ObservableEvent openedChangedEvent() {
return createEvent("opened-changed");
}
}