Package org.zkoss.zul

Class Carousel

java.lang.Object
org.zkoss.zk.ui.AbstractComponent
org.zkoss.zk.ui.HtmlBasedComponent
org.zkoss.zul.impl.XulElement
org.zkoss.zul.Carousel
All Implemented Interfaces:
Serializable, Cloneable, org.zkoss.zk.ui.Component, org.zkoss.zk.ui.ext.Scope, org.zkoss.zk.ui.sys.ComponentCtrl
public class Carousel extends XulElement
A carousel (slideshow) container. Children must be Carouselitem.

Default getZclass(): "z-carousel".

Since:
11.0.0
Author:
yuehfeng
See Also:

  • Nested Class Summary

    Nested classes/interfaces inherited from class org.zkoss.zk.ui.HtmlBasedComponent

    org.zkoss.zk.ui.HtmlBasedComponent.ExtraCtrl

    Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent

    org.zkoss.zk.ui.AbstractComponent.Children, org.zkoss.zk.ui.AbstractComponent.ForwardInfo, org.zkoss.zk.ui.AbstractComponent.TargetInfo

  • Field Summary

    Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent

    _zclass

    Fields inherited from interface org.zkoss.zk.ui.Component

    APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE

    Fields inherited from interface org.zkoss.zk.ui.sys.ComponentCtrl

    AFTER_CHILD_ADDED, AFTER_CHILD_REMOVED, AFTER_CLONED, AFTER_PAGE_ATTACHED, AFTER_PAGE_DETACHED, AFTER_PARENT_CHANGED, CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE

  • Constructor Summary

    Constructors
    Constructor
    Description
    Carousel()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    beforeChildAdded(org.zkoss.zk.ui.Component child, org.zkoss.zk.ui.Component refChild)
     
    int
    getActiveIndex()
    Returns the index of the currently active slide.
    String
    getEffect()
    Returns the transition effect used when moving between slides.
    int
    getInterval()
    Returns the autoplay interval in milliseconds.
    String
    getOrient()
    Returns the orientation along which the slides advance.
    Carouselitem
    getSelectedItem()
    Returns the currently active item, or null when there are no slides.
    String
    getZclass()
     
    boolean
    isAutoplay()
    Returns whether the carousel advances through its slides automatically.
    boolean
    isKeyboard()
    Whether the carousel reacts to left/right arrow keys when focused.
    boolean
    isLoop()
    Returns whether the carousel wraps around from the last slide back to the first (and vice versa).
    boolean
    isPause()
    Whether autoplay pauses while the cursor hovers over the carousel.
    boolean
    isShowArrows()
    Returns whether the previous/next navigation arrows are shown.
    boolean
    isShowIndicators()
    Returns whether the slide indicators (the position dots) are shown.
    void
    onChildAdded(org.zkoss.zk.ui.Component child)
     
    void
    onChildRemoved(org.zkoss.zk.ui.Component child)
     
    protected void
    renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer)
     
    void
    service(org.zkoss.zk.au.AuRequest request, boolean everError)
     
    void
    setActiveIndex(int activeIndex)
    Sets the index of the currently active slide.
    void
    setAutoplay(boolean autoplay)
    Sets whether the carousel advances through its slides automatically.
    void
    setEffect(String effect)
    Sets the transition effect used when moving between slides.
    void
    setInterval(int interval)
    Sets the autoplay interval in milliseconds.
    void
    setKeyboard(boolean keyboard)
    Sets whether the carousel reacts to left/right arrow keys when focused.
    void
    setLoop(boolean loop)
    Sets whether the carousel wraps around from the last slide back to the first (and vice versa).
    void
    setOrient(String orient)
    Sets the orientation along which the slides advance.
    void
    setPause(boolean pause)
    Sets whether autoplay pauses while the cursor hovers over the carousel.
    void
    setShowArrows(boolean showArrows)
    Sets whether the previous/next navigation arrows are shown.
    void
    setShowIndicators(boolean showIndicators)
    Sets whether the slide indicators (the position dots) are shown.

    Methods inherited from class org.zkoss.zul.impl.XulElement

    clone, getContext, getCtrlKeys, getPopup, getPropertyAccess, getTooltip, setContext, setContext, setContextAttributes, setCtrlKeys, setPopup, setPopup, setPopupAttributes, setTooltip, setTooltip, setTooltipAttributes

    Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent

    addSclass, evalCSSFlex, focus, getAction, getClientAction, getDraggable, getDroppable, getExtraCtrl, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getSkeleton, getStyle, getTabindex, getTabindexInteger, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, removeSclass, removeSclass, setAction, setClass, setClientAction, setDraggable, setDroppable, setFocus, setHeight, setHeight0, setHeightDirectly, setHflex, setHflex0, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setSkeleton, setStyle, setTabindex, setTabindex, setTooltiptext, setTop, setTopDirectly, setVflex, setVflex0, setVflexDirectly, setWidth, setWidth0, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly

    Methods inherited from class org.zkoss.zk.ui.AbstractComponent

    addAnnotation, addCallback, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildRemoved, beforeParentChanged, destroyIndexCacheMap, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableBindingAnnotation, disableClientUpdate, disableHostChanged, enableBindingAnnotation, enableHostChanged, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getCallback, getChildren, getClientAttribute, getClientDataAttribute, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getForwards, getId, getIndexCacheMap, getLastChild, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRedrawCallback, getRoot, getShadowFellowIfAny, getShadowRoots, getShadowVariable, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, initIndexCacheMap, insertBefore, invalidate, isChildable, isDisabledHostChanged, isInitialized, isInvalidated, isListenerAvailable, isVisible, onPageAttached, onPageDetached, onParentChanged, onWrongValue, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeCallback, removeChild, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, renderPropertiesOnly, replace, response, response, response, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setClientAttribute, setClientDataAttribute, setDefinition, setDefinition, setId, setMold, setPage, setPageBefore, setParent, setStubonly, setStubonly, setSubBindingAnnotationCount, setTemplate, setVisible, setVisibleDirectly, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, updateSubBindingAnnotationCount, willPassivate, willPassivate, willSerialize, willSerialize

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Carousel

      public Carousel()

  • Method Details

    • getActiveIndex

      public int getActiveIndex()
      Returns the index of the currently active slide.

      Matches what renderProperties(org.zkoss.zk.ui.sys.ContentRenderer) actually sends to the client: when the stored _activeIndex exceeds the current child count (e.g. ZUL set activeIndex='5' before adding children), the value is clamped to count - 1 — or 0 when there are no slides — for both render and getter so callers never observe an index that doesn't correspond to a real slide.

    • setActiveIndex

      public void setActiveIndex(int activeIndex) throws org.zkoss.zk.ui.WrongValueException
      Sets the index of the currently active slide.
      Parameters:
      activeIndex - the zero-based index of the slide to activate; must be in [0, slideCount-1] once the carousel has rendered. Setting a different value pushes the new value to the client via smartUpdate.
      Throws:
      org.zkoss.zk.ui.WrongValueException - if the carousel has already rendered and activeIndex is outside [0, slideCount-1]. Before the first render the value is stored unchecked, because a ZUL page may set it above the carousel's own carouselitem children.

    • isAutoplay

      public boolean isAutoplay()
      Returns whether the carousel advances through its slides automatically.

      Default: false.

      Since:
      11.0.0

    • setAutoplay

      public void setAutoplay(boolean autoplay)
      Sets whether the carousel advances through its slides automatically.
      Parameters:
      autoplay - true to start advancing slides automatically (using the interval), false to leave navigation manual.

    • getInterval

      public int getInterval()
      Returns the autoplay interval in milliseconds.

      Default: 5000.

      Since:
      11.0.0

    • setInterval

      public void setInterval(int interval) throws org.zkoss.zk.ui.WrongValueException
      Sets the autoplay interval in milliseconds.
      Throws:
      org.zkoss.zk.ui.WrongValueException - if interval is less than 500ms — the animation cannot reliably finish (and screen readers cannot announce the slide change) inside a tighter window.

    • isShowArrows

      public boolean isShowArrows()
      Returns whether the previous/next navigation arrows are shown.

      Default: true.

      Since:
      11.0.0

    • setShowArrows

      public void setShowArrows(boolean showArrows)
      Sets whether the previous/next navigation arrows are shown.
      Parameters:
      showArrows - true to display the navigation arrows, false to hide them.

    • isShowIndicators

      public boolean isShowIndicators()
      Returns whether the slide indicators (the position dots) are shown.

      Default: true.

      Since:
      11.0.0

    • setShowIndicators

      public void setShowIndicators(boolean showIndicators)
      Sets whether the slide indicators (the position dots) are shown.
      Parameters:
      showIndicators - true to display the indicators, false to hide them.

    • isLoop

      public boolean isLoop()
      Returns whether the carousel wraps around from the last slide back to the first (and vice versa).

      Default: true.

      Since:
      11.0.0

    • setLoop

      public void setLoop(boolean loop)
      Sets whether the carousel wraps around from the last slide back to the first (and vice versa).
      Parameters:
      loop - true to wrap around continuously, false to stop at the ends.

    • isPause

      public boolean isPause()
      Whether autoplay pauses while the cursor hovers over the carousel. Mirrors Bootstrap's data-bs-pause="hover" behavior.

      Default: true.

      Since:
      11.0.0

    • setPause

      public void setPause(boolean pause)
      Sets whether autoplay pauses while the cursor hovers over the carousel.
      Parameters:
      pause - true to pause autoplay on hover, false to keep advancing.

    • isKeyboard

      public boolean isKeyboard()
      Whether the carousel reacts to left/right arrow keys when focused. Mirrors Bootstrap's keyboard option.

      Default: true.

      Since:
      11.0.0

    • setKeyboard

      public void setKeyboard(boolean keyboard)
      Sets whether the carousel reacts to left/right arrow keys when focused.
      Parameters:
      keyboard - true to enable arrow-key navigation, false to disable it.

    • getOrient

      public String getOrient()
      Returns the orientation along which the slides advance.

      Default: "horizontal".

      Since:
      11.0.0

    • setOrient

      public void setOrient(String orient) throws org.zkoss.zk.ui.WrongValueException
      Sets the orientation along which the slides advance.
      Parameters:
      orient - one of "horizontal" or "vertical"; a null value is treated as "horizontal".
      Throws:
      org.zkoss.zk.ui.WrongValueException - if orient is neither "horizontal" nor "vertical".

    • getEffect

      public String getEffect()
      Returns the transition effect used when moving between slides.

      Default: "slide".

      Since:
      11.0.0

    • setEffect

      public void setEffect(String effect) throws org.zkoss.zk.ui.WrongValueException
      Sets the transition effect used when moving between slides.
      Parameters:
      effect - one of "slide", "fade" or "none"; a null value is treated as "slide".
      Throws:
      org.zkoss.zk.ui.WrongValueException - if effect is none of "slide", "fade" or "none".

    • getZclass

      public String getZclass()
      Overrides:
      getZclass in class org.zkoss.zk.ui.HtmlBasedComponent

    • renderProperties

      protected void renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer) throws IOException
      Overrides:
      renderProperties in class XulElement
      Throws:
      IOException

    • beforeChildAdded

      public void beforeChildAdded(org.zkoss.zk.ui.Component child, org.zkoss.zk.ui.Component refChild)
      Specified by:
      beforeChildAdded in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      beforeChildAdded in class org.zkoss.zk.ui.AbstractComponent

    • onChildAdded

      public void onChildAdded(org.zkoss.zk.ui.Component child)
      Specified by:
      onChildAdded in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      onChildAdded in class org.zkoss.zk.ui.AbstractComponent

    • onChildRemoved

      public void onChildRemoved(org.zkoss.zk.ui.Component child)
      Specified by:
      onChildRemoved in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      onChildRemoved in class org.zkoss.zk.ui.AbstractComponent

    • service

      public void service(org.zkoss.zk.au.AuRequest request, boolean everError)
      Specified by:
      service in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      service in class org.zkoss.zk.ui.HtmlBasedComponent

    • getSelectedItem

      public Carouselitem getSelectedItem()
      Returns the currently active item, or null when there are no slides.

      The lookup uses the same clamped index as getActiveIndex() so the two getters stay in agreement when _activeIndex was set out of range before any child was attached.