Package org.zkoss.zk.ui.sys

## Interface ComponentCtrl

- All Known Implementing Classes:
    `A`, `A`, `Abbr`, `Absolutechildren`, `Absolutelayout`, `AbstractComponent`, `AbstractTag`, `Address`, `Anchorchildren`, `Anchorlayout`, `Anchornav`, `Apply`, `Area`, `Area`, `Article`, `Aside`, `Audio`, `Audio`, `Auxhead`, `Auxheader`, `B`, `Bandbox`, `Bandpopup`, `Barcode`, `Barcodescanner`, `Base`, `Bdi`, `Bdo`, `Biglistbox`, `Blockquote`, `Body`, `Borderlayout`, `Box`, `Br`, `Button`, `Button`, `Calendar`, `Camera`, `Canvas`, `Captcha`, `Caption`, `Caption`, `Cardlayout`, `Cascader`, `Cell`, `Center`, `Chart`, `Checkbox`, `Choose`, `Chosenbox`, `Cite`, `Coachmark`, `Code`, `Col`, `Colgroup`, `Colorbox`, `Column`, `Columnchildren`, `Columnlayout`, `Columns`, `Combobox`, `Combobutton`, `Comboitem`, `ContentTag`, `Cropper`, `Data`, `Datalist`, `Datebox`, `DateTimeFormatInputElement`, `Dd`, `Decimalbox`, `Del`, `Detail`, `Details`, `Dfn`, `Dialog`, `Div`, `Div`, `Dl`, `Doublebox`, `Doublespinner`, `Drawer`, `Dropupload`, `Dt`, `East`, `Em`, `Embed`, `Fieldset`, `Figcaption`, `Figure`, `Fileupload`, `Fileupload`, `FileuploadDlg`, `Fisheye`, `Fisheyebar`, `Foot`, `Footer`, `Footer`, `FooterElement`, `ForEach`, `Form`, `FormatInputElement`, `Frozen`, `GoldenLayout`, `GoldenPanel`, `Grid`, `Group`, `Groupbox`, `Groupfoot`, `H1`, `H2`, `H3`, `H4`, `H5`, `H6`, `Hbox`, `Head`, `Header`, `HeaderElement`, `HeadersElement`, `Hgroup`, `Hlayout`, `Hr`, `Html`, `Html`, `HtmlBasedComponent`, `HtmlMacroComponent`, `HtmlNativeComponent`, `HtmlShadowElement`, `I`, `Idspace`, `If`, `Iframe`, `Iframe`, `Image`, `Imagemap`, `Img`, `Include`, `Input`, `InputElement`, `Inputgroup`, `Ins`, `Intbox`, `IStubComponent`, `IStubsComponent`, `Jasperreport`, `Kbd`, `Label`, `Label`, `LabelElement`, `LabelImageElement`, `Layout`, `LayoutRegion`, `Legend`, `Li`, `Lineitem`, `Linelayout`, `Link`, `Listbox`, `Listcell`, `Listfoot`, `Listfooter`, `Listgroup`, `Listgroupfoot`, `Listhead`, `Listheader`, `Listitem`, `Longbox`, `Main`, `Map`, `Mark`, `Menu`, `Menu`, `Menubar`, `Menuitem`, `Menupopup`, `Menuseparator`, `MeshElement`, `MeshElement.InternalPaging`, `MessageboxDlg`, `MessageboxDlg.Button`, `Meta`, `Meter`, `Multislider`, `Nav`, `Nav`, `Navbar`, `Navitem`, `Navseparator`, `NoDOM`, `North`, `Noscript`, `NumberInputElement`, `Object`, `Ol`, `Optgroup`, `Option`, `Organigram`, `Orgchildren`, `Orgitem`, `Orgnode`, `Otherwise`, `Output`, `P`, `Paging`, `Panel`, `Panelchildren`, `Pdfviewer`, `Picture`, `Popup`, `Portalchildren`, `Portallayout`, `Pre`, `Progress`, `Progressmeter`, `Q`, `Radio`, `Radiogroup`, `Rangeslider`, `Rating`, `Raw`, `Row`, `Rowchildren`, `Rowlayout`, `Rows`, `Rp`, `Rt`, `Ruby`, `S`, `Samp`, `Script`, `Script`, `Scrollview`, `Searchbox`, `Section`, `Select`, `Selectbox`, `Separator`, `Signature`, `Slider`, `Sliderbuttons`, `Slot`, `Small`, `Source`, `South`, `Space`, `Span`, `Span`, `Spinner`, `Splitlayout`, `Splitter`, `Step`, `Stepbar`, `Strong`, `StubComponent`, `StubsComponent`, `Style`, `Style`, `Sub`, `Summary`, `Sup`, `Tab`, `Tabbox`, `Table`, `Tablechildren`, `Tablelayout`, `Tabpanel`, `Tabpanels`, `Tabs`, `Tbeditor`, `Tbody`, `Td`, `Template`, `TemplateBasedShadowElement`, `Text`, `Textarea`, `Textbox`, `Tfoot`, `Th`, `Thead`, `Time`, `Timebox`, `Timepicker`, `Timer`, `Title`, `Toolbar`, `Toolbarbutton`, `Tr`, `Track`, `Track`, `Transformer`, `Tree`, `Treecell`, `Treechildren`, `Treecol`, `Treecols`, `Treefoot`, `Treefooter`, `Treeitem`, `Treerow`, `U`, `Ul`, `Var`, `Vbox`, `Video`, `Video`, `Vlayout`, `VolatileComponent`, `VolatileIStubsComponent`, `Wbr`, `West`, `When`, `Window`, `XmlMacroComponent`, `XmlNativeComponent`, `XulElement`, `Zkhead`

      public interface ComponentCtrl

  An addition interface to `Component` that is used for implementation or tools.

  Application developers rarely need to access methods in this interface.

  Author:
    tomyeh

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `AFTER_CHILD_ADDED` | For after child added callback, use in `addCallback(String, Callback)`
    `static java.lang.String` | `AFTER_CHILD_REMOVED` | For after child removed callback, use in `addCallback(String, Callback)`
    `static java.lang.String` | `AFTER_CLONED` | For after cloned callback, use in `addCallback(String, Callback)`
    `static java.lang.String` | `AFTER_PAGE_ATTACHED` | For page attached callback, use in `addCallback(String, Callback)`
    `static java.lang.String` | `AFTER_PAGE_DETACHED` | For page detached callback, use in `addCallback(String, Callback)`
    `static java.lang.String` | `AFTER_PARENT_CHANGED` | For after parent changed callback, use in `addCallback(String, Callback)`
    `static int` | `CE_BUSY_IGNORE` | Returned by `getClientEvents()` to indicate the event can be ignored by the server when the server is busy.
    `static int` | `CE_DUPLICATE_IGNORE` | Returned by `getClientEvents()` to indicate the event can be ignored by the server when the server receives the same AU requests but not processed yet.
    `static int` | `CE_IMPORTANT` | Returned by `getClientEvents()` to indicate the event is important and the client must send it back even if no listener is registered.
    `static int` | `CE_NON_DEFERRABLE` | Returned by `getClientEvents()` to indicate the event is no deferrable, i.e., the event has to be sent back immediately.
    `static int` | `CE_REPEAT_IGNORE` | Returned by `getClientEvents()` to indicate the event can be ignored by the server when the server receives the same AU requests consecutively.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addAnnotation​(java.lang.String propName, java.lang.String annotName, java.util.Map<java.lang.String,​java.lang.String[]> annotAttrs)` | Adds an annotation to the specified property of this component.
    `boolean` | `addCallback​(java.lang.String name, Callback callback)` | Adds a callback at component in specific name
    `void` | `addEventHandler​(java.lang.String name, EventHandler evthd)` | Adds an event handler.
    `boolean` | `addShadowRoot​(ShadowElement shadow)` | Adds the given shadow root from this host.
    `boolean` | `addShadowRootBefore​(ShadowElement shadow, ShadowElement insertBefore)` | Adds the given shadow root from this host.
    `void` | `addSharedEventHandlerMap​(EventHandlerMap evthds)` | Adds a map of event handlers which is shared by other components.
    `void` | `beforeChildAdded​(Component child, Component insertBefore)` | Called before adding a child.
    `void` | `beforeChildRemoved​(Component child)` | Called before removing a child.
    `void` | `beforeParentChanged​(Component parent)` | Called before changing the parent.
    `void` | `disableBindingAnnotation()` | Set to disable the component with binding annotation.
    `boolean` | `disableClientUpdate​(boolean disable)` | Sets whether to disable the update of the client widgets of this component and its descendants.
    `void` | `enableBindingAnnotation()` | Set to enable the component with binding annotation.
    `java.util.List<java.lang.String>` | `getAnnotatedProperties()` | Returns a read-only list of the name of properties that are associated at least one annotation (never null).
    `java.util.List<java.lang.String>` | `getAnnotatedPropertiesBy​(java.lang.String annotName)` | Returns a read-only list of the names of the properties that are associated with the specified annotation (never null).
    `Annotation` | `getAnnotation​(java.lang.String propName, java.lang.String annotName)` | Returns the annotation associated with the definition of the specified property, or null if not available.
    `java.util.Collection<Annotation>` | `getAnnotations​(java.lang.String propName)` | Returns a read-only collection of all annotations (`Annotation`) associated with the specified property.
    `java.util.Collection<Annotation>` | `getAnnotations​(java.lang.String propName, java.lang.String annotName)` | Returns the annotations associated with the definition of the specified property.
    `java.util.Collection<Callback>` | `getCallback​(java.lang.String name)` | Returns all of callbacks by specific name
    `java.util.Map<java.lang.String,​java.lang.Integer>` | `getClientEvents()` | Returns a map of event information that the client might send to this component.
    `ZScript` | `getEventHandler​(java.lang.String evtnm)` | Returns the event listener of the specified name, or null if not found.
    `java.util.Set<java.lang.String>` | `getEventHandlerNames()` | Returns a readonly collection of event names (String), or an empty collection if no event name is registered.
    `EventListenerMap` | `getEventListenerMap()` | Returns the map of event handlers and listeners defined in this component.
    `java.lang.Object` | `getExtraCtrl()` | Returns the extra controls that tell ZK how to handle this component specially.
    `default java.util.Map<java.lang.String,​AbstractComponent.ForwardInfo>` | `getForwards()` | Returns the forwards info if any.
    `PropertyAccess` | `getPropertyAccess​(java.lang.String prop)` | Returns the corresponding property access object from the given property name, if any.
    `ShadowElement` | `getShadowFellowIfAny​(java.lang.String id)` | Returns the shadow element under this shadow host.
    `<T extends ShadowElement> java.util.List<T>` | `getShadowRoots()` | Returns a set of shadow elements, if any.
    `int` | `getSubBindingAnnotationCount()` | Returns the count of the component's subtree binding annotation.
    `boolean` | `hasBindingAnnotation()` | Returns whether the component itself has binding annotation or not.
    `boolean` | `hasSubBindingAnnotation()` | Returns whether the component and its children have binding annotation or not.
    `void` | `onChildAdded​(Component child)` | Called when a child is added.
    `void` | `onChildRemoved​(Component child)` | Called when a child is removed.
    `void` | `onPageAttached​(Page newpage, Page oldpage)` | Called when this component is attached to a page.
    `void` | `onPageDetached​(Page page)` | Called when this component is detached from a page.
    `void` | `onParentChanged​(Component parent)` | Called after the parent changed.
    `WrongValueException` | `onWrongValue​(WrongValueException ex)` | Notifies that an `WrongValueException` instance is thrown, and `WrongValueException.getComponent()` is the component causing the exception.
    `void` | `redraw​(java.io.Writer out)` | Render (a.k.a., redraw) this component and all its descendants.
    `boolean` | `removeCallback​(java.lang.String name, Callback callback)` | Removes a callback for component by specific name.
    `boolean` | `removeShadowRoot​(ShadowElement shadow)` | Removes the given shadow root from this host.
    `void` | `renderPropertiesOnly​(ContentRenderer renderer)` | Renders the component properties only
    `void` | `service​(AuRequest request, boolean everError)` | Handles an AU request.
    `void` | `service​(Event event, Scope scope)` | Handles an event.
    `void` | `sessionDidActivate​(Page page)` | Notification that the session, which owns this component, has just been activated (a.k.a., deserialized).
    `void` | `sessionWillPassivate​(Page page)` | Notification that the session, which owns this component, is about to be passivated (a.k.a., serialized).
    `void` | `setDefinition​(java.lang.String defname)` | Sets the component definition by specifying the name.
    `void` | `setDefinition​(ComponentDefinition compdef)` | Sets the component definition.

- - ### Field Detail

    - #### AFTER_PAGE_ATTACHED

          static final java.lang.String AFTER_PAGE_ATTACHED

      For page attached callback, use in `addCallback(String, Callback)`
      See Also:
        Constant Field Values

    - #### AFTER_PAGE_DETACHED

          static final java.lang.String AFTER_PAGE_DETACHED

      For page detached callback, use in `addCallback(String, Callback)`
      See Also:
        Constant Field Values

    - #### AFTER_CHILD_ADDED

          static final java.lang.String AFTER_CHILD_ADDED

      For after child added callback, use in `addCallback(String, Callback)`
      See Also:
        Constant Field Values

    - #### AFTER_CHILD_REMOVED

          static final java.lang.String AFTER_CHILD_REMOVED

      For after child removed callback, use in `addCallback(String, Callback)`
      See Also:
        Constant Field Values

    - #### AFTER_PARENT_CHANGED

          static final java.lang.String AFTER_PARENT_CHANGED

      For after parent changed callback, use in `addCallback(String, Callback)`
      Since:
        10.0.0
      See Also:
        Constant Field Values

    - #### AFTER_CLONED

          static final java.lang.String AFTER_CLONED

      For after cloned callback, use in `addCallback(String, Callback)`
      Since:
        10.1.0
      See Also:
        Constant Field Values

    - #### CE_IMPORTANT

          static final int CE_IMPORTANT

      Returned by `getClientEvents()` to indicate the event is important and the client must send it back even if no listener is registered.
      See Also:
        Constant Field Values

    - #### CE_NON_DEFERRABLE

          static final int CE_NON_DEFERRABLE

      Returned by `getClientEvents()` to indicate the event is no deferrable, i.e., the event has to be sent back immediately. It is meaningful only used with `CE_IMPORTANT`
      See Also:
        Constant Field Values

    - #### CE_BUSY_IGNORE

          static final int CE_BUSY_IGNORE

      Returned by `getClientEvents()` to indicate the event can be ignored by the server when the server is busy.
      See Also:
        Constant Field Values

    - #### CE_DUPLICATE_IGNORE

          static final int CE_DUPLICATE_IGNORE

      Returned by `getClientEvents()` to indicate the event can be ignored by the server when the server receives the same AU requests but not processed yet. In other words, the server will remove the duplicate AU requests if it was queued.
      See Also:
        Constant Field Values

    - #### CE_REPEAT_IGNORE

          static final int CE_REPEAT_IGNORE

      Returned by `getClientEvents()` to indicate the event can be ignored by the server when the server receives the same AU requests consecutively. In other words, the server will remove the first request if it receives an event listed in this map consecutively.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### setDefinition

          void setDefinition​(ComponentDefinition compdef)

      Sets the component definition.

      The component definition affects how a component behaves. Developers rarely need to call this method. If a wrong definition is assigned, the result is unpredictable (and hard to debug). It is mainly designed for developing tools.

      Throws:
        `java.lang.IllegalArgumentException` - if compdef is null

    - #### setDefinition

          void setDefinition​(java.lang.String defname)

      Sets the component definition by specifying the name.
      Parameters:
        `defname` - the name of the component definition
      Throws:
        `java.lang.IllegalArgumentException` - if defname is null
        `DefinitionNotFoundException` - if the component definition not found
      Since:
        5.0.0

    - #### beforeChildAdded

          void beforeChildAdded​(Component child,
                                Component insertBefore)

      Called before adding a child. If a component accepts only certain types of children, it shall override this method and throw an exception for an illegal child.
      Parameters:
        `child` - the child to be added (never null).
        `insertBefore` - another child component that the new child will be inserted before it. If null, the new child will be the last child.
      Since:
        3.6.2

    - #### beforeChildRemoved

          void beforeChildRemoved​(Component child)

      Called before removing a child. If a component denies a certain child to be removed, it shall override this method to avoid it.
      Parameters:
        `child` - the child to be removed (never null)
      Since:
        3.6.2

    - #### beforeParentChanged

          void beforeParentChanged​(Component parent)

      Called before changing the parent. If a component can be a child of certain parents, it shall override this method and throws an exception for an illegal parent.
      Parameters:
        `parent` - the new parent. If null, it means detachment.
      Since:
        3.6.2

    - #### onParentChanged

          void onParentChanged​(Component parent)

      Called after the parent changed. Usually, `onPageDetached(Page)` and `onPageAttached(Page, Page)` cover all the cases, unless its page is not changed.
      Parameters:
        `parent` - the new parent. If null, it means detachment.
      Since:
        10.0.0

    - #### onChildAdded

          void onChildAdded​(Component child)

      Called when a child is added. If a component want to optimize the update, it might do something different. Otherwise, it does nothing.

      Note: `onChildAdded(org.zkoss.zk.ui.Component)` is called in the request-processing phase.

      It is not a good idea to throw an exception in this method, since it is in the middle of modifying the component tree.

      Since:
        3.5.0

    - #### onChildRemoved

          void onChildRemoved​(Component child)

      Called when a child is removed. If a component want to optimize the update, it might do something different. Otherwise, it simply does nothing.

      It is not a good idea to throw an exception in this method, since it is in the middle of modifying the component tree.

      Since:
        3.5.0

    - #### onPageAttached

          void onPageAttached​(Page newpage,
                              Page oldpage)

      Called when this component is attached to a page.

      If a component is moved from one page to another, `onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page)` is called with both pages. Note: `onPageDetached(org.zkoss.zk.ui.Page)` is not called in this case.

      Note: this method is called even if the component is attached to a page implicitly thru, say, `Component.setParent(org.zkoss.zk.ui.Component)`.

      It is not a good idea to throw an exception in this method, since it is in the middle of modifying the component tree.

      Parameters:
        `newpage` - the new page (never null).
        `oldpage` - the previous page, if any, or null if it didn't belong to any page.
      Since:
        3.5.0

    - #### onPageDetached

          void onPageDetached​(Page page)

      Called when this component is detached from a page.

      If a component is moved from one page to another, `onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page)` is called with both pages. Note: `onPageDetached(org.zkoss.zk.ui.Page)` is not called in this case. In other words, `onPageDetached(org.zkoss.zk.ui.Page)` is called only if a component is detached from a page (not belong to any other page).

      Note: this method is called even if the component is detached to a page implicitly thru, say, `Component.setParent(org.zkoss.zk.ui.Component)`.

      It is not a good idea to throw an exception in this method, since it is in the middle of modifying the component tree.

      Parameters:
        `page` - the previous page (never null)
      Since:
        3.5.0

    - #### getEventHandler

          ZScript getEventHandler​(java.lang.String evtnm)

      Returns the event listener of the specified name, or null if not found.
      See Also:
        `Component.getWidgetListener(java.lang.String)`

    - #### addEventHandler

          void addEventHandler​(java.lang.String name,
                               EventHandler evthd)

      Adds an event handler. Note: it is OK to add multiple event handlers to the same event. They are evaluated one-by-one. On the other hand, `Component.setWidgetListener(java.lang.String, java.lang.String)` will overwrite the previous listener if the event name is the same.
      See Also:
        `Component.setWidgetListener(java.lang.String, java.lang.String)`

    - #### addSharedEventHandlerMap

          void addSharedEventHandlerMap​(EventHandlerMap evthds)

      Adds a map of event handlers which is shared by other components. In other words, this component shall have all event handlers defined in the specified map, evthds. Meanwhile, this component shall not modify evthds, since it is shared. The caller shall not change annots after the invocation, too
      Parameters:
        `evthds` - a map of event handler
      See Also:
        `Component.setWidgetListener(java.lang.String, java.lang.String)`

    - #### getEventHandlerNames

          java.util.Set<java.lang.String> getEventHandlerNames()

      Returns a readonly collection of event names (String), or an empty collection if no event name is registered.
      Since:
        3.0.2
      See Also:
        `Component.getWidgetListenerNames()`

    - #### getClientEvents

          java.util.Map<java.lang.String,​java.lang.Integer> getClientEvents()

      Returns a map of event information that the client might send to this component. The key of the returned map is a String instance representing the event name, and the value an integer representing the flags (a combination of `CE_IMPORTANT`, `CE_BUSY_IGNORE`, `CE_DUPLICATE_IGNORE` and `CE_REPEAT_IGNORE`).

      Default: return the collection of events added by `getClientEvents()`.

      Since:
        5.0.0

    - #### getAnnotation

          Annotation getAnnotation​(java.lang.String propName,
                                   java.lang.String annotName)

      Returns the annotation associated with the definition of the specified property, or null if not available.

      If there are multiple annotation with the given name, this method will merge them before return. If you prefer to get all of them without merging, please use `getAnnotations(String, String)` instead. For example,

          <textbox value="@bind(abc, param1=foo1) @bind(xyz, param2=foo2)">

      This method will return a single annotation with three attributes: value=xyz, param1=foo1 and param2=foo2. On the other hand, `getAnnotations(String, String)` will return a two-element collections.

      Notice that the property is not limited the 'real' property. For example, the following statement is correct though `button` doesn't have `setFoo` method. And, you can retrieve it by use of this method (`getAnnotation("foo", "bind")`)

          <button foo="@bind(whatever=123)"/>

      Furthermore, you can declare it as `custom-attribute`. For example, the following is equivalent to the above.

          <button>
            <custom-attribute foo="@bind(whatever=123}">
          </button>

      Parameters:
        `propName` - the property name, e.g., "value". If null, this method returns the annotation(s) associated with this component (rather than a particular property).
        `annotName` - the annotation name
      See Also:
        `getAnnotations(String, String)`

    - #### getAnnotations

          java.util.Collection<Annotation> getAnnotations​(java.lang.String propName,
                                                          java.lang.String annotName)

      Returns the annotations associated with the definition of the specified property. It never returns null.

      Notice that the property is not limited the 'real' property. For example, the following statement is correct though `button` doesn't have `setFoo` method. And, you can retrieve it by use of this method (`getAnnotation("foo", "bind")`)

          <button foo="@bind(whatever=123)"/>

      Furthermore, you can declare it as `custom-attribute`. For example, the following is equivalent to the above.

          <button>
            <custom-attribute foo="@bind(whatever=123}">
          </button>

      Parameters:
        `propName` - the property name, e.g., "value". If null, this method returns the annotation(s) associated with this component (rather than a particular property).
        `annotName` - the annotation name
      Since:
        6.0.0
      See Also:
        `getAnnotation(String, String)`

    - #### getAnnotations

          java.util.Collection<Annotation> getAnnotations​(java.lang.String propName)

      Returns a read-only collection of all annotations (`Annotation`) associated with the specified property. It never returns null.
      Parameters:
        `propName` - the property name, e.g., "value". If null, this method returns the annotation(s) associated with this component (rather than a particular property).

    - #### getAnnotatedPropertiesBy

          java.util.List<java.lang.String> getAnnotatedPropertiesBy​(java.lang.String annotName)

      Returns a read-only list of the names of the properties that are associated with the specified annotation (never null).

    - #### getAnnotatedProperties

          java.util.List<java.lang.String> getAnnotatedProperties()

      Returns a read-only list of the name of properties that are associated at least one annotation (never null).

    - #### addAnnotation

          void addAnnotation​(java.lang.String propName,
                             java.lang.String annotName,
                             java.util.Map<java.lang.String,​java.lang.String[]> annotAttrs)

      Adds an annotation to the specified property of this component.

      If the given property is null, the annotation is associated to this component, rather than a particular property.

      Unlike Java, you can add annotations dynamically, and each component has its own annotations.

      Parameters:
        `propName` - the property name. If null, the annotation is associated with the component (rather than a particular property).
        `annotName` - the annotation name (never null, nor empty).
        `annotAttrs` - a map of attributes, or null if no attribute at all. This method will make a copy of `annotAttrs`, so the caller can use it after the invocation.

    - #### sessionWillPassivate

          void sessionWillPassivate​(Page page)

      Notification that the session, which owns this component, is about to be passivated (a.k.a., serialized).

      Note: only root components are notified by this method.

    - #### sessionDidActivate

          void sessionDidActivate​(Page page)

      Notification that the session, which owns this component, has just been activated (a.k.a., deserialized).

      Note: only root components are notified by this method.

    - #### getExtraCtrl

          java.lang.Object getExtraCtrl()

      Returns the extra controls that tell ZK how to handle this component specially.

      Application developers need NOT to access this method.

      There are a set of extra controls: org.zkoss.zk.ui.ext.render.

      The first package is used if the content of a component can be changed by the user at the client. It is so-called the client controls.

      The second package is used to control how to render a component specially.

      Override this method only if you want to return the extra controls.

      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`.

    - #### getPropertyAccess

          PropertyAccess getPropertyAccess​(java.lang.String prop)

      Returns the corresponding property access object from the given property name, if any.
      Parameters:
        `prop` - the name of the property
      Returns:
        null it means not to support for the property name.
      Since:
        8.0.0

    - #### onWrongValue

          WrongValueException onWrongValue​(WrongValueException ex)

      Notifies that an `WrongValueException` instance is thrown, and `WrongValueException.getComponent()` is the component causing the exception. It is a callback and the component can store the error message, show up the custom information, or even 'eat' the exception.
      Parameters:
        `ex` - the exception being thrown (never null)
      Returns:
        the exception to throw, or null to ignore the exception In most cases, just return ex
      Since:
        2.4.0

    - #### redraw

          void redraw​(java.io.Writer out)
               throws java.io.IOException

      Render (a.k.a., redraw) this component and all its descendants.

      It is called in the redrawing phase by the kernel, so it is too late to call `Component.invalidate()`, `AbstractComponent.smartUpdate(java.lang.String, java.lang.Object)` or `AbstractComponent.response(org.zkoss.zk.au.AuResponse)` in this method.

      Throws:
        `java.io.IOException`
      Since:
        5.0.0

    - #### service

          void service​(AuRequest request,
                       boolean everError)

      Handles an AU request.

      Notice: don't invoke this method directly. Rather, invoke `DesktopCtrl.service(AuRequest, boolean)` instead. This method is designed to be overridden.

      To send responses to the client, use `AbstractComponent.smartUpdate(java.lang.String, java.lang.Object)`, `AbstractComponent.response(org.zkoss.zk.au.AuResponse)` or `Component.invalidate()`. To handle the AU requests sent from the client, override this method.

      Application developer can plug the custom service to handle the AU request by calling `Component.setAuService(org.zkoss.zk.au.AuService)`.

      Parameters:
        `everError` - whether any error ever occurred before processing this request.
      Since:
        5.0.0
      See Also:
        `Component.setAuService(org.zkoss.zk.au.AuService)`

    - #### service

          void service​(Event event,
                       Scope scope)
                throws java.lang.Exception

      Handles an event. This method will invoke the event handlers registered in a ZUML page, the event listeners registered in Java, and the event handlers declared as part of the component.
      Parameters:
        `event` - the event to handle
        `scope` - the scope to evaluate the zscript, if any. (see also `Page.interpret(java.lang.String, java.lang.String, org.zkoss.zk.ui.ext.Scope)`.
      Throws:
        `java.lang.Exception`
      Since:
        6.0.0

    - #### disableClientUpdate

          boolean disableClientUpdate​(boolean disable)

      Sets whether to disable the update of the client widgets of this component and its descendants.

      By default, if a component is attached to a page, modifications that change the visual representation will be sent to the client to ensure the consistency.

      Though rarely needed, you can disable the synchronization of the visual representation, if you prefer to update the client in a batch or the modification is caused by the client.

      Notice:

      - Once disabled, it not only affects the synchronization of this component but also all its descendants.
      - The disable remains until the end of this execution (or the invocation of this method with false). In other words, it is enabled automatically in the next execution.
      - The updates, if any, before calling this method will still be sent to the client.
      - It does nothing, if there is no current execution.

      Also notice that, with `Component.invalidate()`, it is easy to synchronize the content of a component (and its descendants) to the client.

      Returns:
        whether it has been disabled before this invocation, i.e., the previous disable status
      Since:
        3.6.2

    - #### getEventListenerMap

          EventListenerMap getEventListenerMap()

      Returns the map of event handlers and listeners defined in this component. This method is rarely used, but it is useful if you'd like to retrieve the behavior of the event handling of this component (and if you don't have the reference to the component)
      Since:
        6.0.0

    - #### getShadowRoots

          <T extends ShadowElement> java.util.List<T> getShadowRoots()

      Returns a set of shadow elements, if any.
      Since:
        8.0.0

    - #### removeShadowRoot

          boolean removeShadowRoot​(ShadowElement shadow)

      Removes the given shadow root from this host. (Shadow developer use only)
      Parameters:
        `shadow` - a shadow element
      Returns:
        true if child is removed successfully; false if it doesn't have the specified child
      Since:
        8.0.0

    - #### addShadowRoot

          boolean addShadowRoot​(ShadowElement shadow)

      Adds the given shadow root from this host. (Shadow developer use only)
      Parameters:
        `shadow` - a shadow element
      Returns:
        true if child is added successfully
      Since:
        8.0.0

    - #### addShadowRootBefore

          boolean addShadowRootBefore​(ShadowElement shadow,
                                      ShadowElement insertBefore)

      Adds the given shadow root from this host. (Shadow developer use only)
      Parameters:
        `shadow` - a shadow element
        `insertBefore` - the shadow before which you want the new child
      Returns:
        true if child is added successfully
      Since:
        8.0.0

    - #### enableBindingAnnotation

          void enableBindingAnnotation()

      Set to enable the component with binding annotation. (Internal or component developer use only.)
      Since:
        8.0.0

    - #### disableBindingAnnotation

          void disableBindingAnnotation()

      Set to disable the component with binding annotation. (Internal or component developer use only.)
      Since:
        8.0.0

    - #### hasBindingAnnotation

          boolean hasBindingAnnotation()

      Returns whether the component itself has binding annotation or not. (Internal or component developer use only.)
      Returns:
        true if the component itself has binding annotation
      Since:
        8.0.0

    - #### hasSubBindingAnnotation

          boolean hasSubBindingAnnotation()

      Returns whether the component and its children have binding annotation or not. (Internal or component developer use only.)
      Returns:
        true if the component and its children have binding annotation
      Since:
        8.0.0

    - #### getSubBindingAnnotationCount

          int getSubBindingAnnotationCount()

      Returns the count of the component's subtree binding annotation. (Internal or component developer use only.)
      Returns:
        0 if the component and its children have no binding annotation , more than 0 if they have binding annotation
      Since:
        8.0.0

    - #### addCallback

          boolean addCallback​(java.lang.String name,
                              Callback callback)

      Adds a callback at component in specific name
      Parameters:
        `name` -
        `callback` -
      Since:
        8.0.2

    - #### removeCallback

          boolean removeCallback​(java.lang.String name,
                                 Callback callback)

      Removes a callback for component by specific name.
      Parameters:
        `name` -
        `callback` -
      Since:
        8.0.2

    - #### getCallback

          java.util.Collection<Callback> getCallback​(java.lang.String name)

      Returns all of callbacks by specific name
      Parameters:
        `name` -
      Since:
        8.0.2

    - #### getShadowFellowIfAny

          ShadowElement getShadowFellowIfAny​(java.lang.String id)

      Returns the shadow element under this shadow host.
      Parameters:
        `id` -
      Returns:
        ShadowElement or null
      Since:
        8.0.1

    - #### getForwards

          default java.util.Map<java.lang.String,​AbstractComponent.ForwardInfo> getForwards()

      Returns the forwards info if any. Never null.
      Since:
        10.0.0

    - #### renderPropertiesOnly

          void renderPropertiesOnly​(ContentRenderer renderer)
                             throws java.io.IOException

      Renders the component properties only
      Parameters:
        `renderer` -
      Throws:
        `java.io.IOException`
      Since:
        10.0.0