Package org.zkoss.zul

Class Carousel

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.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:
    10.4.0
    Author:
    yuehfeng
    See Also:
    Serialized Form

    • 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

      All Methods Instance Methods Concrete Methods 
      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.
      java.lang.String getEffect()
      Returns the transition effect used when moving between slides.
      int getInterval()
      Returns the autoplay interval in milliseconds.
      java.lang.String getOrient()
      Returns the orientation along which the slides advance.
      Carouselitem getSelectedItem()
      Returns the currently active item, or null when there are no slides.
      java.lang.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​(java.lang.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​(java.lang.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.zk.ui.HtmlBasedComponent

        addSclass, evalCSSFlex, focus, getAction, getClientAction, getDraggable, getDroppable, getExtraCtrl, getHeight, getHflex, getLeft, getRenderdefer, getSclass, 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, 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 Detail

      • Carousel

        public Carousel()

    • Method Detail

      • 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 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]. Setting a different value pushes the new value to the client via smartUpdate.
        Throws:
        org.zkoss.zk.ui.WrongValueException - if activeIndex is negative, or is not less than the current number of slides.

      • isAutoplay

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

        Default: false.

        Since:
        10.4.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:
        10.4.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:
        10.4.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:
        10.4.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:
        10.4.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:
        10.4.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:
        10.4.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 java.lang.String getOrient()
        Returns the orientation along which the slides advance.

        Default: "horizontal".

        Since:
        10.4.0

      • setOrient

        public void setOrient​(java.lang.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 java.lang.String getEffect()
        Returns the transition effect used when moving between slides.

        Default: "slide".

        Since:
        10.4.0

      • setEffect

        public void setEffect​(java.lang.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 java.lang.String getZclass()
        Overrides:
        getZclass in class org.zkoss.zk.ui.HtmlBasedComponent

      • renderProperties

        protected void renderProperties​(org.zkoss.zk.ui.sys.ContentRenderer renderer)
                         throws java.io.IOException
        Overrides:
        renderProperties in class XulElement
        Throws:
        java.io.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.