Package org.zkoss.zul

## Class Captcha

- java.lang.Object
- - org.zkoss.zk.ui.AbstractComponent
  - - org.zkoss.zk.ui.HtmlBasedComponent
    - - org.zkoss.zul.impl.XulElement
      - - org.zkoss.zul.Image
        - - org.zkoss.zul.Captcha

- All Implemented Interfaces:
    `java.io.Serializable`, `java.lang.Cloneable`, `Component`, `Scope`, `ComponentCtrl`

      public class Captcha
      extends Image

  The generic captcha component.

  Captcha requires an implementation of an engine (`CaptchaEngine`). The default engine is based on JHLabs and available in ZK PE and ZK EE.

  Author:
    henrichen
  See Also:
    Serialized Form

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.zkoss.zul.Image

      `Image.ExtraCtrl`

    - ### 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
    Constructor | Description
    --- | ---
    `Captcha()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addFont​(java.awt.Font font)` | Add fonts into fonts list.
    `java.lang.String` | `getBgColor()` | Get the background color of the captcha box (in string as #RRGGBB).
    `int` | `getBgRGB()` | Get the background color in int array (0: red, 1: green, 2:blue).
    `CaptchaEngine` | `getCaptchaEngine()` | Get the captcha engine.
    `java.awt.Font[]` | `getDefaultFonts()` | Gets the default font list.
    `java.lang.String` | `getExclude()` | Get exclude characters.
    `java.awt.Font` | `getFont​(int j)` | Get nth Font.
    `java.lang.String` | `getFontColor()` | Gets font color.
    `int` | `getFontRGB()` | Get the font color in int array (0: red, 1: green, 2:blue).
    `java.util.List<java.awt.Font>` | `getFonts()` | Gets fonts list, default provide two fonts.
    `int` | `getIntHeight()` | Get the captcha int height in pixel; to be used by the derived subclass.
    `int` | `getIntWidth()` | Get the captcha int width in pixel; to be used by the derived subclass.
    `int` | `getLength()` | Get length of the autogenerated text value; default to 5.
    `java.lang.String` | `getValue()` | Returns the text value of this captcha.
    `boolean` | `isFrame()` | Returns whether generate border.
    `boolean` | `isNoise()` | Returns whether generate noise; default to false.
    `protected CaptchaEngine` | `newCaptchaEngine()` | Instantiates the default captcha engine.
    `java.lang.String` | `randomValue()` | Regenerates new captcha text value and redraw.
    `void` | `setBgColor​(java.lang.String color)` | Set the background color of the chart.
    `void` | `setEngine​(java.lang.String clsnm)` | Sets the captcha engine by use of a class name.
    `void` | `setEngine​(CaptchaEngine engine)` | Set the captcha engine.
    `void` | `setExclude​(java.lang.String exclude)` | Set exclude characters that will not be generated.
    `void` | `setFontColor​(java.lang.String color)` | Set font color.
    `void` | `setFrame​(boolean frame)` | Sets whether generate border.
    `void` | `setHeight​(java.lang.String h)` | Override super class to prepare the int height.
    `void` | `setHflex​(java.lang.String flex)` | Overrides the method in HtmlBasedComponent, not to check using hflex and width at the same time
    `void` | `setLength​(int len)` | Set length of the autogenerated text value; default to 5.
    `void` | `setNoise​(boolean b)` | Sets whether generate noise; default to false.
    `void` | `setValue​(java.lang.String text)` | Sets the text value to be shown as the distortion captcha.
    `void` | `setVflex​(java.lang.String flex)` | Overrides the method in HtmlBasedComponent, not to check using vflex and height at the same time
    `void` | `setWidth​(java.lang.String w)` | Override super class to prepare the int width.
    `protected void` | `smartDrawCaptcha()` | mark a draw flag to inform that this Chart needs update.

    - ### Methods inherited from class org.zkoss.zul.Image

      `getContent, getExtraCtrl, getHover, getSrc, isChildable, renderProperties, setContent, setContent, setHover, setHoverContent, setHoverContent, setSrc`

    - ### 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, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTabindex, getTabindexInteger, getTooltiptext, getTop, getVflex, getWidth, getZclass, getZindex, getZIndex, removeSclass, removeSclass, service, setAction, setClass, setClientAction, setDraggable, setDroppable, setFocus, setHeight0, setHeightDirectly, setHflex0, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTabindex, setTabindex, setTooltiptext, setTop, setTopDirectly, setVflex0, setVflexDirectly, 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, 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

    - #### Captcha

          public Captcha()

  - ### Method Detail

    - #### getFonts

          public java.util.List<java.awt.Font> getFonts()

      Gets fonts list, default provide two fonts.

    - #### getDefaultFonts

          public java.awt.Font[] getDefaultFonts()

      Gets the default font list.

    - #### getFont

          public java.awt.Font getFont​(int j)

      Get nth Font.

    - #### addFont

          public void addFont​(java.awt.Font font)

      Add fonts into fonts list. If you did not add fonts, the default implementation would use the default fonts; i.e. bold Arial 35, and bold courier 35.

    - #### setFontColor

          public void setFontColor​(java.lang.String color)

      Set font color. Allowed value format: #RRGGBB

    - #### getFontColor

          public java.lang.String getFontColor()

      Gets font color.

    - #### getFontRGB

          public int getFontRGB()

      Get the font color in int array (0: red, 1: green, 2:blue).

    - #### setBgColor

          public void setBgColor​(java.lang.String color)

      Set the background color of the chart.
      Parameters:
        `color` - in #RRGGBB format (hexadecimal).

    - #### getBgColor

          public java.lang.String getBgColor()

      Get the background color of the captcha box (in string as #RRGGBB). null means default.

    - #### getBgRGB

          public int getBgRGB()

      Get the background color in int array (0: red, 1: green, 2:blue). null means default.

    - #### setWidth

          public void setWidth​(java.lang.String w)

      Override super class to prepare the int width.
      Overrides:
        `setWidth` in class `HtmlBasedComponent`
      See Also:
        `HtmlBasedComponent.setWidthDirectly(java.lang.String)`, `AbstractComponent.disableClientUpdate(boolean)`

    - #### setHflex

          public void setHflex​(java.lang.String flex)

      Overrides the method in HtmlBasedComponent, not to check using hflex and width at the same time
      Overrides:
        `setHflex` in class `HtmlBasedComponent`
      Parameters:
        `flex` - horizontal flex hint of this component.
      Since:
        8.0.1
      See Also:
        `HtmlBasedComponent.setVflex(java.lang.String)`, `HtmlBasedComponent.getHflex()`

    - #### getIntWidth

          public int getIntWidth()

      Get the captcha int width in pixel; to be used by the derived subclass.

    - #### setHeight

          public void setHeight​(java.lang.String h)

      Override super class to prepare the int height.
      Overrides:
        `setHeight` in class `HtmlBasedComponent`

    - #### setVflex

          public void setVflex​(java.lang.String flex)

      Overrides the method in HtmlBasedComponent, not to check using vflex and height at the same time
      Overrides:
        `setVflex` in class `HtmlBasedComponent`
      Parameters:
        `flex` - the vertical flex hint.
      Since:
        8.0.1
      See Also:
        `HtmlBasedComponent.setHflex(java.lang.String)`, `HtmlBasedComponent.getVflex()`

    - #### getIntHeight

          public int getIntHeight()

      Get the captcha int height in pixel; to be used by the derived subclass.

    - #### getValue

          public java.lang.String getValue()

      Returns the text value of this captcha.

      Default: an empty string.

      Deriving class can override it to return whatever it wants other than null.

    - #### setValue

          public void setValue​(java.lang.String text)
                        throws WrongValueException

      Sets the text value to be shown as the distortion captcha.
      Parameters:
        `text` - the captcha text value
      Throws:
        `WrongValueException`

    - #### setLength

          public void setLength​(int len)

      Set length of the autogenerated text value; default to 5.

    - #### getLength

          public int getLength()

      Get length of the autogenerated text value; default to 5.

    - #### setExclude

          public void setExclude​(java.lang.String exclude)

      Set exclude characters that will not be generated. Note that only digit and character is used in generating text value. If you leave exclude null, the default exclude list will be applied; i.e., 0123456789IilOo (only character (no digits) are used except I, i, l, O(big O), o(small o))

    - #### getExclude

          public java.lang.String getExclude()

      Get exclude characters.

    - #### setNoise

          public void setNoise​(boolean b)

      Sets whether generate noise; default to false. (@since 5.0.0)

    - #### isNoise

          public boolean isNoise()

      Returns whether generate noise; default to false. (@since 5.0.0)

    - #### setFrame

          public void setFrame​(boolean frame)

      Sets whether generate border.

      Default to false.

      Since:
        5.0.4

    - #### isFrame

          public boolean isFrame()

      Returns whether generate border.

      Default to false.

      Since:
        5.0.4

    - #### randomValue

          public java.lang.String randomValue()

      Regenerates new captcha text value and redraw.

    - #### setEngine

          public void setEngine​(java.lang.String clsnm)
                         throws java.lang.ClassNotFoundException,
                                java.lang.NoSuchMethodException,
                                java.lang.IllegalAccessException,
                                java.lang.InstantiationException,
                                java.lang.reflect.InvocationTargetException

      Sets the captcha engine by use of a class name. It creates an instance automatically.
      Throws:
        `java.lang.ClassNotFoundException`
        `java.lang.NoSuchMethodException`
        `java.lang.IllegalAccessException`
        `java.lang.InstantiationException`
        `java.lang.reflect.InvocationTargetException`

    - #### setEngine

          public void setEngine​(CaptchaEngine engine)

      Set the captcha engine.

    - #### getCaptchaEngine

          public CaptchaEngine getCaptchaEngine()
                                         throws UiException

      Get the captcha engine.
      Throws:
        `UiException` - if failed to load the engine.

    - #### newCaptchaEngine

          protected CaptchaEngine newCaptchaEngine()
                                            throws UiException

      Instantiates the default captcha engine. It is called, if `setEngine(java.lang.String)` is not called with non-null engine.

      By default, it looks up the library property called org.zkoss.zul.captcha.engine.class. If found, the value is assumed to be the class name of the captcha engine (it must implement `CaptchaEngine`. If not found, `UiException` is thrown.

      Derived class might override this method to provide your own default class.

      Throws:
        `UiException` - if failed to instantiate the engine
      Since:
        3.0.0

    - #### smartDrawCaptcha

          protected void smartDrawCaptcha()

      mark a draw flag to inform that this Chart needs update.