All Superinterfaces:: IComponent, IHtmlBasedComponent

All Known Subinterfaces:: IA, IAbsolutechildren, IAbsolutelayout, IAnchornav, IAudio, IAuxhead, IAuxheader, IAvatar, IAvatargroup, IBadge, IBandbox, IBandpopup, IBarcode, IBarcodescanner, IBiglistbox, IBorderlayout, IBreadcrumb, IBreadcrumbitem, IButton, IButtonBase, ICalendar, ICamera, ICaption, ICardlayout, ICarousel, ICarouselitem, ICell, ICenter, ICheckbox, ICheckboxBase, IChip, ICoachmark, ICodeeditor, IColorbox, IColumn, IColumnchildren, IColumnlayout, IColumns, ICombobox, ICombobutton, IComboitem, IConfirmpopup, IDatebox, IDaterangebox, IDateTimeFormatInputElement, IDecimalbox, IDetail, IDetailChild, IDiv, IDoublebox, IDoublespinner, IDrawer, IDropupload, IEast, IFileupload, IFisheye, IFisheyebar, IFoot, IFooter, IFooterElement, IFormatInputElement<I,ValueTypeT>, IFrozen, IGoldenLayout, IGoldenPanel, IGrid, IGroup, IGroupbox, IGroupChild, IGroupfoot, IGroupfootChild, IHeaderElement, IHeadersElement, IHlayout, IHtml, IImage, IImageBase, IImagemap, IInputElement<I,ValueTypeT>, IInputgroup, IIntbox, ILabel, ILabelElement, ILabelImageElement, ILayout, ILayoutRegion, ILineitem, ILinelayout, IListbox, IListcell, IListfoot, IListfooter, IListgroup, IListgroupChild, IListgroupfoot, IListgroupfootChild, IListhead, IListheader, IListitem, IListitemBase, ILongbox, IMenu, IMenubar, IMenuitem, IMenupopup, IMenuseparator, IMeshElement, IMultislider, INav, INavbar, INavitem, INavseparator, INorth, INumberInputElement<I,ValueTypeT>, IOrganigram, IOrgchildren, IOrgitem, IOrgnode, IPaging, IPanel, IPanelchildren, IPdfviewer, IPopup, IPopupBase, IPortalchildren, IPortallayout, IProgressmeter, IRadio, IRadiogroup, IRangeslider, IRangesliderBase, IRow, IRowBase, IRowchildren, IRowlayout, IRows, IScrollview, ISeparator, ISeparatorBase, ISignature, ISlider, ISliderbuttons, ISouth, ISpace, ISpan, ISpinner, ISplitlayout, IStep, IStepbar, ITab, ITabbox, ITablechildren, ITablelayout, ITabpanel, ITabpanels, ITabs, ITbeditor, ITextbox, ITextboxBase, ITimebox, ITimepicker, IToolbar, IToolbarbutton, ITrack, ITree, ITreecell, ITreechildren, ITreecol, ITreecols, ITreefoot, ITreefooter, ITreeitem, ITreerow, IVideo, IVlayout, IWest, IWindow

public interface IXulElement extends IHtmlBasedComponent

Immutable XulElement interface.

Support @Action

Name	Action Type
onCtrlKey	ActionData: `KeyData` Represents an action triggered by the user presses the `ctrlKeys` on a component.

Keystroke Handling

To handle the control keys, you have to specify the keystrokes you want to handle with withCtrlKeys(String). Then, if any child component gains the focus and the user presses a keystroke matches the combination, the onCtrlKey action will be triggered to the component with an instance of KeyData. Like ENTER and ESC, you could specify the listener and the ctrlKeys attribute in one of the ancestors. ZK will search the component having the focus, its parent, its parent's parent and so on to find if any of them specifies the ctrlKeys attribute that matches the keystroke.

For example,

 @RichletMapping("/keystrokeHandling")
 public IComponent keystrokeHandling() {
     return IVlayout.of(ITextbox.DEFAULT, IDatebox.DEFAULT)
         .withCtrlKeys("@c^a#f10^#f3").withAction(this::doKeystrokeHandling);
 }

 @Action(type = Events.ON_CTRL_KEY)
 public void doKeystrokeHandling(KeyData data) {
     Clients.log(data.getKeyCode());
 }

As shown, you could use KeyData.getKeyCode() to know which key was pressed.

Author:: jumperchen

Method Summary

Modifier and Type

Method

Description

String

getContext()

Returns the ID of the popup that should appear when the user right-clicks on the element (a.k.a., context menu).

String

getCtrlKeys()

Returns what keystrokes to intercept when a user presses the key on the component.

String

getPopup()

Returns the ID of the popup that should appear when the user clicks on the component.

String

getTooltip()

Returns the ID of the popup (IPopup) that should be used as a tooltip window when the mouse hovers over the component for a moment.

I

withContext(String context)

Returns a copy of this immutable component with the specified context.

I

withCtrlKeys(String ctrlKeys)

Returns a copy of this immutable component with the specified ctrlKeys.

I

withPopup(String popup)

Returns a copy of this immutable component with the specified popup.

I

withTooltip(String tooltip)

Returns a copy of this immutable component with the specified tooltip.

Methods inherited from interface org.zkoss.stateless.sul.IComponent
getAction, getActions, getClientAttributes, getId, getMold, getWidgetClass, getWidgetListeners, getWidgetOverrides, isVisible, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withActions, withActions, withClientAttribute, withClientAttributes, withId, withMold, withVisible, withWidgetClass, withWidgetListener, withWidgetListeners, withWidgetOverride, withWidgetOverrides

Methods inherited from interface org.zkoss.stateless.sul.IHtmlBasedComponent
getClientAction, getDraggable, getDroppable, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getSkeleton, getStyle, getTabindex, getTooltiptext, getTop, getVflex, getWidth, getZclass, getZIndex, isFocus, withClientAction, withDraggable, withDroppable, withFocus, withHeight, withHflex, withLeft, withRenderdefer, withSclass, withSkeleton, withStyle, withTabindex, withTabindex, withTooltiptext, withTop, withVflex, withWidth, withZclass, withZIndex

Method Details

getCtrlKeys

@Nullable String getCtrlKeys()

Returns what keystrokes to intercept when a user presses the key on the component.
Default: null.

withCtrlKeys

I withCtrlKeys(@Nullable String ctrlKeys)

Returns a copy of this immutable component with the specified ctrlKeys.

Sets what keystrokes to intercept.

The string could be a combination of the following:

Key	Syntax	Description
Control	`^[?]`	`[?]` can be a~z, 0~9, #[?], e.g. `^k` represents `Ctrl+k`
Alt	`@[?]`	`[?]` can be a~z, 0~9, #[?], e.g. `@k` represents `Alt+k`
Shift	`$[?]`	`[?]` can be #[?]. Note: $a ~ $z are not supported. e.g. `$#down` represents `Shift+↓`
Mac command(⌘)	`%[?]`	`[?]` can be a~z, 0~9, #[?]. e.g. `%k` represents `command+k`
Navigation key	`#[?]`	the supported value of `[?]` are listed below:
Home	`#home`
End	`#end`
Insert	`#ins`
Delete	`#del`
←	`#left`
→	`#right`
↑	`#up`
↓	`#down`
PgUp	`#pgup`
PgDn	`#pgdn`
Backspace	`#bak`
function key (F1, F2,... F12)	`#f1, #f2, ... #f12`
Tab	`#tab`

For example,

^a^d@c#f10#left#right: It means you want to intercept Ctrl+A, Ctrl+D, Alt+C, F10, Left and Right.
^#left: It means Ctrl+Left.
^#f1: It means Ctrl+F1.
@#f3: It means Alt+F3.

Note: it doesn't support Ctrl+Alt, Shift+Ctrl, Shift+Alt or Shift+Ctrl+Alt.

Parameters:: ctrlKeys - The expression of the keystroke combination to intercept with.
Returns:: A modified copy of the this object

getContext

@Nullable String getContext()

Returns the ID of the popup that should appear when the user right-clicks on the element (a.k.a., context menu).
Default: null (no context menu).
withContext

I withContext(@Nullable String context)
Returns a copy of this immutable component with the specified context.
Sets the ID of the popup that should appear when the user right-clicks on the element (a.k.a., context menu).
An onOpen action is triggered to the context menu if it is going to appear. Therefore, developers can manipulate it dynamically (perhaps based on OpenData.getReference()) by listening to the onOpen action.
The context menu can be shown by a position or the location of x and y, you can specify the following format:
- id, position
- id, position=before_start
- id, x=15, y=20
For example,
```
 .withContext("id, start_before")
 
```
The context menu can also be shown on customized location of x and y by adding parentheses "()", for example,
```
 .withContext("id, x=(zk.currentPointer[0] + 10), y=(zk.currentPointer[1] - 10)")
 
```
Possible values for the position attribute are:
- before_start
  the popup appears above the anchor, aligned to the left.
- before_center
  the popup appears above the anchor, aligned to the center.
- before_end
  the popup appears above the anchor, aligned to the right.
- after_start
  the popup appears below the anchor, aligned to the left.
- after_center
  the popup appears below the anchor, aligned to the center.
- after_end
  the popup appears below the anchor, aligned to the right.
- start_before
  the popup appears to the left of the anchor, aligned to the top.
- start_center
  the popup appears to the left of the anchor, aligned to the middle.
- start_after
  the popup appears to the left of the anchor, aligned to the bottom.
- end_before
  the popup appears to the right of the anchor, aligned to the top.
- end_center
  the popup appears to the right of the anchor, aligned to the middle.
- end_after
  the popup appears to the right of the anchor, aligned to the bottom.
- overlap/top_left
  the popup overlaps the anchor, with anchor and popup aligned at top-left.
- top_center
  the popup overlaps the anchor, with anchor and popup aligned at top-center.
- overlap_end/top_right
  the popup overlaps the anchor, with anchor and popup aligned at top-right.
- middle_left
  the popup overlaps the anchor, with anchor and popup aligned at middle-left.
- middle_center
  the popup overlaps the anchor, with anchor and popup aligned at middle-center.
- middle_right
  the popup overlaps the anchor, with anchor and popup aligned at middle-right.
- overlap_before/bottom_left
  the popup overlaps the anchor, with anchor and popup aligned at bottom-left.
- bottom_center
  the popup overlaps the anchor, with anchor and popup aligned at bottom-center.
- overlap_after/bottom_right
  the popup overlaps the anchor, with anchor and popup aligned at bottom-right.
- at_pointer
  the popup appears with the upper-left aligned with the mouse cursor.
- after_pointer
  the popup appears with the top aligned with the bottom of the mouse cursor, with the left side of the popup at the horizontal position of the mouse cursor.
Note: The position will be ignored if coordinates are set.
Parameters:

context - The ID of IPopup

Returns:

A modified copy of the this object
getPopup

@Nullable String getPopup()

Returns the ID of the popup that should appear when the user clicks on the component.
Default: null (no popup).
withPopup

I withPopup(@Nullable String popup)
Returns a copy of this immutable component with the specified popup.
Sets the ID of the popup that should appear when the user clicks on the component.
An onOpen action is triggered to the popup menu if it is going to appear. Therefore, developers can manipulate it dynamically (perhaps based on OpenData.getReference()) by listening to the onOpen action.
The popup can be shown by a position or the location of x and y, you can specify the following format:
- id, position
- id, position=before_start
- id, x=15, y=20
For example,
```
 .withPopup("id, start_before")
 
```
The popup can also be shown on customized location of x and y by adding parentheses "()", for example,
```
 .withPopup("id, x=(zk.currentPointer[0] + 10), y=(zk.currentPointer[1] - 10)")
 
```
Possible values for the position attribute are:
- before_start
  the popup appears above the anchor, aligned to the left.
- before_center
  the popup appears above the anchor, aligned to the center.
- before_end
  the popup appears above the anchor, aligned to the right.
- after_start
  the popup appears below the anchor, aligned to the left.
- after_center
  the popup appears below the anchor, aligned to the center.
- after_end
  the popup appears below the anchor, aligned to the right.
- start_before
  the popup appears to the left of the anchor, aligned to the top.
- start_center
  the popup appears to the left of the anchor, aligned to the middle.
- start_after
  the popup appears to the left of the anchor, aligned to the bottom.
- end_before
  the popup appears to the right of the anchor, aligned to the top.
- end_center
  the popup appears to the right of the anchor, aligned to the middle.
- end_after
  the popup appears to the right of the anchor, aligned to the bottom.
- overlap/top_left
  the popup overlaps the anchor, with anchor and popup aligned at top-left.
- top_center
  the popup overlaps the anchor, with anchor and popup aligned at top-center.
- overlap_end/top_right
  the popup overlaps the anchor, with anchor and popup aligned at top-right.
- middle_left
  the popup overlaps the anchor, with anchor and popup aligned at middle-left.
- middle_center
  the popup overlaps the anchor, with anchor and popup aligned at middle-center.
- middle_right
  the popup overlaps the anchor, with anchor and popup aligned at middle-right.
- overlap_before/bottom_left
  the popup overlaps the anchor, with anchor and popup aligned at bottom-left.
- bottom_center
  the popup overlaps the anchor, with anchor and popup aligned at bottom-center.
- overlap_after/bottom_right
  the popup overlaps the anchor, with anchor and popup aligned at bottom-right.
- at_pointer
  the popup appears with the upper-left aligned with the mouse cursor.
- after_pointer
  the popup appears with the top aligned with the bottom of the mouse cursor, with the left side of the popup at the horizontal position of the mouse cursor.
Note: The position will be ignored if coordinates are set.
Parameters:

popup - The ID of IPopup

Returns:

A modified copy of the this object
getTooltip

@Nullable String getTooltip()

Returns the ID of the popup (IPopup) that should be used as a tooltip window when the mouse hovers over the component for a moment. The tooltip will automatically disappear when the mouse is moved away.
Default: null (no tooltip).
withTooltip

I withTooltip(@Nullable String tooltip)
Returns a copy of this immutable component with the specified tooltip.
Sets the ID of the popup that should be used as a tooltip window when the mouse hovers over the component for a moment.
An onOpen action is triggered to the tooltip if it is going to appear. Therefore, developers can manipulate it dynamically (perhaps based on OpenData.getReference()) by listening to the onOpen action.
The tooltip can be shown by a position or the location of x and y, and can be specified with a delay time (in millisecond), you can specify the following format:
- id, position
- id, position=before_start, delay=500
- id, x=15, y=20
For example,
```
 .withTooltip("id, start_before")
 
```
The tooltip can also be shown on customized location of x and y by adding parentheses "()", for example,
```
 .withTooltip("id, x=(zk.currentPointer[0] + 10), y=(zk.currentPointer[1] - 10)")
 
```
Possible values for the position attribute are:
- before_start
  the popup appears above the anchor, aligned to the left.
- before_center
  the popup appears above the anchor, aligned to the center.
- before_end
  the popup appears above the anchor, aligned to the right.
- after_start
  the popup appears below the anchor, aligned to the left.
- after_center
  the popup appears below the anchor, aligned to the center.
- after_end
  the popup appears below the anchor, aligned to the right.
- start_before
  the popup appears to the left of the anchor, aligned to the top.
- start_center
  the popup appears to the left of the anchor, aligned to the middle.
- start_after
  the popup appears to the left of the anchor, aligned to the bottom.
- end_before
  the popup appears to the right of the anchor, aligned to the top.
- end_center
  the popup appears to the right of the anchor, aligned to the middle.
- end_after
  the popup appears to the right of the anchor, aligned to the bottom.
- overlap/top_left
  the popup overlaps the anchor, with anchor and popup aligned at top-left.
- top_center
  the popup overlaps the anchor, with anchor and popup aligned at top-center.
- overlap_end/top_right
  the popup overlaps the anchor, with anchor and popup aligned at top-right.
- middle_left
  the popup overlaps the anchor, with anchor and popup aligned at middle-left.
- middle_center
  the popup overlaps the anchor, with anchor and popup aligned at middle-center.
- middle_right
  the popup overlaps the anchor, with anchor and popup aligned at middle-right.
- overlap_before/bottom_left
  the popup overlaps the anchor, with anchor and popup aligned at bottom-left.
- bottom_center
  the popup overlaps the anchor, with anchor and popup aligned at bottom-center.
- overlap_after/bottom_right
  the popup overlaps the anchor, with anchor and popup aligned at bottom-right.
- at_pointer
  the popup appears with the upper-left aligned with the mouse cursor.
- after_pointer
  the popup appears with the top aligned with the bottom of the mouse cursor, with the left side of the popup at the horizontal position of the mouse cursor.
Note: The position will be ignored if coordinates are set.
Parameters:

tooltip - The ID of IPopup

Returns:

A modified copy of the this object

Interface IXulElement<I extends IXulElement>

Support @Action

Keystroke Handling

Method Summary

Methods inherited from interface org.zkoss.stateless.sul.IComponent

Methods inherited from interface org.zkoss.stateless.sul.IHtmlBasedComponent

Method Details

getCtrlKeys

withCtrlKeys

getContext

withContext

getPopup

withPopup

getTooltip

withTooltip