Package org.zkoss.zul.impl

## Class LabelImageElement

- java.lang.Object
- - org.zkoss.zk.ui.AbstractComponent
  - - org.zkoss.zk.ui.HtmlBasedComponent
    - - org.zkoss.zul.impl.XulElement
      - - org.zkoss.zul.impl.LabelElement
        - - org.zkoss.zul.impl.LabelImageElement

- All Implemented Interfaces:
    `java.io.Serializable`, `java.lang.Cloneable`, `Component`, `Scope`, `ComponentCtrl`
  Direct Known Subclasses:
    `A`, `Button`, `Caption`, `Checkbox`, `Comboitem`, `Fisheye`, `FooterElement`, `HeaderElement`, `Listcell`, `Menu`, `Menuitem`, `Nav`, `Navitem`, `Orgnode`, `Tab`, `Treecell`

      public abstract class LabelImageElement
      extends LabelElement

  A XUL element with a label (`LabelElement.getLabel()`) and an image (`getImage()`).

  [Since 6.0.0]

  To turn on the preload image function for this component, you have to specify the component's attribute map with key "org.zkoss.zul.image.preload" to true. That is, for example, if in a zul file, you shall specify <custom-attributes> of the component like this:

       <button ...>
           <custom-attributes org.zkoss.zul.image.preload="true"/>
       </button>

  Or specify it onto the root component. For example,

       <window ...>
           <custom-attributes org.zkoss.zul.image.preload="true"/>
           <button .../>
       </window>

  [Since 6.5.2]

  Preload image function is also configurable from zk.xml by setting library properties. For example,

       <library-property/>
           <name>org.zkoss.zul.image.preload</name/>
           <value>true</value/>
       </library-property/>

  Author:
    tomyeh
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `protected class` | `LabelImageElement.ExtraCtrl` | A utility class to implement `HtmlBasedComponent.getExtraCtrl()`.

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

      `AbstractComponent.Children, AbstractComponent.ForwardInfo, 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
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `LabelImageElement()` |
    `protected` | `LabelImageElement​(java.lang.String label)` |
    `protected` | `LabelImageElement​(java.lang.String label, java.lang.String image)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.Object` | `clone()` | Clones the component.
    `java.lang.Object` | `getExtraCtrl()` | Returns the client control for this component.
    `java.lang.String` | `getHoverImage()` | Returns the URI of the hover image.
    `Image` | `getHoverImageContent()` | Returns the content of the hover image set by `setHoverImageContent(Image)` or `setHoverImageContent(RenderedImage)`.
    `java.lang.String` | `getIconSclass()` | Returns the icon font
    `java.lang.String[]` | `getIconSclasses()` | Returns the icon font String array
    `java.lang.String` | `getIconTooltip()` | Returns the iconTooltip content
    `java.lang.String[]` | `getIconTooltips()` | Returns the iconTooltip content String array
    `java.lang.String` | `getImage()` | Returns the image URI.
    `Image` | `getImageContent()` | Returns the image content set by `setImageContent(Image)` or `setImageContent(RenderedImage)`.
    `PropertyAccess` | `getPropertyAccess​(java.lang.String prop)` | Returns the corresponding property access object from the given property name, if any.
    `boolean` | `isImageAssigned()` | Returns whether the image is available.
    `protected void` | `renderProperties​(ContentRenderer renderer)` | Renders the content of this component, excluding the enclosing tags and children.
    `void` | `setHoverImage​(java.lang.String src)` | Sets the image URI.
    `void` | `setHoverImageContent​(java.awt.image.RenderedImage image)` | Sets the content of the hover image directly with the rendered image.
    `void` | `setHoverImageContent​(Image image)` | Sets the content of the hover image directly.
    `void` | `setIconSclass​(java.lang.String iconSclass)` | Sets the icon font, if iconSclasses is set, iconSclass will be ignored, iconSclasses will take precedence over iconSclass
    `void` | `setIconSclasses​(java.lang.String[] iconSclasses)` | Sets multiple icons font, if iconSclasses is set, iconSclass will be ignored, iconSclasses will take precedence over iconSclass
    `void` | `setIconTooltip​(java.lang.String iconTooltip)` | Sets the iconTooltip, if iconTooltips is set, iconTooltip will be ignored, iconTooltips will take precedence over iconTooltip
    `void` | `setIconTooltips​(java.lang.String[] iconTooltips)` | Sets multiple iconTooltips, if iconTooltips is set, iconTooltip will be ignored, iconTooltips will take precedence over iconTooltip
    `void` | `setImage​(java.lang.String src)` | Sets the image URI.
    `void` | `setImageContent​(java.awt.image.RenderedImage image)` | Sets the content directly with the rendered image.
    `void` | `setImageContent​(Image image)` | Sets the content directly.

    - ### Methods inherited from class org.zkoss.zul.impl.LabelElement

      `getLabel, renderCrawlable, setLabel`

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

      `getContext, getCtrlKeys, getPopup, 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, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTabindex, getTabindexInteger, getTooltiptext, getTop, getVflex, getWidth, getZclass, getZindex, getZIndex, removeSclass, removeSclass, service, 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, beforeChildAdded, 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, onChildAdded, onChildRemoved, 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

    - #### LabelImageElement

          protected LabelImageElement()

    - #### LabelImageElement

          protected LabelImageElement​(java.lang.String label,
                                      java.lang.String image)

      Since:
        5.0.0

    - #### LabelImageElement

          protected LabelImageElement​(java.lang.String label)

      Since:
        5.0.0

  - ### Method Detail

    - #### setIconSclass

          public void setIconSclass​(java.lang.String iconSclass)

      Sets the icon font, if iconSclasses is set, iconSclass will be ignored, iconSclasses will take precedence over iconSclass
      Parameters:
        `iconSclass` - a CSS class name for the icon font
      Since:
        7.0.0

    - #### setIconSclasses

          public void setIconSclasses​(java.lang.String[] iconSclasses)

      Sets multiple icons font, if iconSclasses is set, iconSclass will be ignored, iconSclasses will take precedence over iconSclass
      Parameters:
        `iconSclasses` - a CSS class name String array for the icon font
      Since:
        10.0.0

    - #### getIconSclass

          public java.lang.String getIconSclass()

      Returns the icon font
      Since:
        7.0.0

    - #### getIconSclasses

          public java.lang.String[] getIconSclasses()

      Returns the icon font String array
      Since:
        10.0.0

    - #### setIconTooltip

          public void setIconTooltip​(java.lang.String iconTooltip)

      Sets the iconTooltip, if iconTooltips is set, iconTooltip will be ignored, iconTooltips will take precedence over iconTooltip
      Parameters:
        `iconTooltip` - a content String for iconTooltip
      Since:
        10.0.0

    - #### setIconTooltips

          public void setIconTooltips​(java.lang.String[] iconTooltips)

      Sets multiple iconTooltips, if iconTooltips is set, iconTooltip will be ignored, iconTooltips will take precedence over iconTooltip
      Parameters:
        `iconTooltips` - a content String array for iconTooltip
      Since:
        10.0.0

    - #### getIconTooltip

          public java.lang.String getIconTooltip()

      Returns the iconTooltip content
      Since:
        10.0.0

    - #### getIconTooltips

          public java.lang.String[] getIconTooltips()

      Returns the iconTooltip content String array
      Since:
        10.0.0

    - #### getImage

          public java.lang.String getImage()

      Returns the image URI.

      Default: null.

    - #### setImage

          public void setImage​(java.lang.String src)

      Sets the image URI.

      Calling this method implies setImageContent(null). In other words, the last invocation of `setImage(java.lang.String)` overrides the previous `setImageContent(org.zkoss.image.Image)`, if any. The image would hide if src == null

      See Also:
        `setImageContent(Image)`, `setImageContent(RenderedImage)`

    - #### setImageContent

          public void setImageContent​(Image image)

      Sets the content directly.

      Default: null.

      Calling this method implies setImage(null). In other words, the last invocation of `setImageContent(org.zkoss.image.Image)` overrides the previous `setImage(java.lang.String)`, if any.

      Parameters:
        `image` - the image to display.
      See Also:
        `setImage(java.lang.String)`

    - #### setImageContent

          public void setImageContent​(java.awt.image.RenderedImage image)

      Sets the content directly with the rendered image. It actually encodes the rendered image to an PNG image (`Image`) with `Images.encode(java.lang.String, java.awt.image.RenderedImage, float, boolean)`, and then invoke `setImageContent(org.zkoss.image.Image)`.

      If you want more control such as different format, quality, and naming, you can use `Images` directly.

      Since:
        3.0.7

    - #### getImageContent

          public Image getImageContent()

      Returns the image content set by `setImageContent(Image)` or `setImageContent(RenderedImage)`.

      Note: it won't load the content specified by `setImage(java.lang.String)`. Actually, it returns null if `setImage(java.lang.String)` was called.

    - #### getHoverImage

          public java.lang.String getHoverImage()

      Returns the URI of the hover image. The hover image is used when the mouse is moving over this component.

      Default: null.

      Since:
        3.5.0

    - #### setHoverImage

          public void setHoverImage​(java.lang.String src)

      Sets the image URI. The hover image is used when the mouse is moving over this component.

      Calling this method implies setHoverImageContent(null). In other words, the last invocation of `setHoverImage(java.lang.String)` overrides the previous `setHoverImageContent(org.zkoss.image.Image)`, if any.

      Since:
        3.5.0

    - #### getHoverImageContent

          public Image getHoverImageContent()

      Returns the content of the hover image set by `setHoverImageContent(Image)` or `setHoverImageContent(RenderedImage)`.

      Note: it won't load the content specified by `setImage(java.lang.String)`. Actually, it returns null if `setImage(java.lang.String)` was called.

      Since:
        5.0.8

    - #### setHoverImageContent

          public void setHoverImageContent​(Image image)

      Sets the content of the hover image directly. The hover image is used when the mouse is moving over this component.

      Default: null.

      Calling this method implies setHoverImage(null). In other words, the last invocation of `setHoverImageContent(org.zkoss.image.Image)` overrides the previous `setHoverImage(java.lang.String)`, if any.

      Parameters:
        `image` - the image to display.
      Since:
        3.5.0

    - #### setHoverImageContent

          public void setHoverImageContent​(java.awt.image.RenderedImage image)

      Sets the content of the hover image directly with the rendered image. The hover image is used when the mouse is moving over this component.

      It actually encodes the rendered image to an PNG image (`Image`) with `Images.encode(java.lang.String, java.awt.image.RenderedImage, float, boolean)`, and then invoke `setHoverImageContent(org.zkoss.image.Image)`.

      If you want more control such as different format, quality, and naming, you can use `Images` directly.

      Since:
        3.5.0

    - #### isImageAssigned

          public boolean isImageAssigned()

      Returns whether the image is available. In other words, it return true if `setImage(java.lang.String)` or `setImageContent(org.zkoss.image.Image)` is called with non-null.

    - #### renderProperties

          protected void renderProperties​(ContentRenderer renderer)
                                   throws java.io.IOException

      Description copied from class: `HtmlBasedComponent`
      Renders the content of this component, excluding the enclosing tags and children.

      See also ZK Client-side Reference: Property Rendering

      Overrides:
        `renderProperties` in class `LabelElement`
      Throws:
        `java.io.IOException`

    - #### getExtraCtrl

          public java.lang.Object getExtraCtrl()

      Description copied from class: `HtmlBasedComponent`
      Returns the client control for this component. It is used only by component developers.

      Default: creates an instance of `HtmlBasedComponent.ExtraCtrl`.

      Specified by:
        `getExtraCtrl` in interface `ComponentCtrl`
      Overrides:
        `getExtraCtrl` in class `HtmlBasedComponent`
      Returns:
        null if no special handling required. If the component requires some special controls, it could return an object that implements one or several interfaces in the org.zkoss.zk.ui.ext.render package. For example, `Cropper`.
      See Also:
        `ComponentCtrl.getExtraCtrl()`

    - #### getPropertyAccess

          public PropertyAccess getPropertyAccess​(java.lang.String prop)

      Description copied from interface: `ComponentCtrl`
      Returns the corresponding property access object from the given property name, if any.
      Specified by:
        `getPropertyAccess` in interface `ComponentCtrl`
      Overrides:
        `getPropertyAccess` in class `LabelElement`
      Parameters:
        `prop` - the name of the property
      Returns:
        null it means not to support for the property name.

    - #### clone

          public java.lang.Object clone()

      Description copied from interface: `Component`
      Clones the component. All of its children and descendants are cloned. Also, ID are preserved.
      Specified by:
        `clone` in interface `Component`
      Overrides:
        `clone` in class `XulElement`
      Returns:
        the new component. Notice that it doesn't belong to any page, nor desktop. It doesn't have a parent, either.