Package org.zkoss.zk.ui.sys

Interface ComponentCtrl

All Known Implementing Classes:
AbstractComponent, HtmlBasedComponent, HtmlMacroComponent, HtmlNativeComponent, HtmlShadowElement, StubComponent, StubsComponent
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 Details

  • Method Details

    • 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:
      IllegalArgumentException - if compdef is null

    • setDefinition

      void setDefinition(String defname)
      Sets the component definition by specifying the name.
      Parameters:
      defname - the name of the component definition
      Throws:
      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(String evtnm)
      Returns the event listener of the specified name, or null if not found.
      See Also:

    • addEventHandler

      void addEventHandler(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:

    • 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:

    • getEventHandlerNames

      Set<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:

    • getClientEvents

      Map<String,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(String propName, 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

      Collection<Annotation> getAnnotations(String propName, 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:

    • getAnnotations

      Collection<Annotation> getAnnotations(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

      List<String> getAnnotatedPropertiesBy(String annotName)
      Returns a read-only list of the names of the properties that are associated with the specified annotation (never null).

    • getAnnotatedProperties

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

    • addAnnotation

      void addAnnotation(String propName, String annotName, Map<String,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

      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(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(Writer out) throws 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:
      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:

    • service

      void service(Event event, Scope scope) throws 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:
      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> 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(String name, Callback callback)
      Adds a callback at component in specific name
      Parameters:
      name -
      callback -
      Since:
      8.0.2

    • removeCallback

      boolean removeCallback(String name, Callback callback)
      Removes a callback for component by specific name.
      Parameters:
      name -
      callback -
      Since:
      8.0.2

    • getCallback

      Collection<Callback> getCallback(String name)
      Returns all of callbacks by specific name
      Parameters:
      name -
      Since:
      8.0.2

    • getShadowFellowIfAny

      ShadowElement getShadowFellowIfAny(String id)
      Returns the shadow element under this shadow host.
      Parameters:
      id -
      Returns:
      ShadowElement or null
      Since:
      8.0.1

    • getForwards

      default Map<String,AbstractComponent.ForwardInfo> getForwards()
      Returns the forwards info if any. Never null.
      Since:
      10.0.0

    • renderPropertiesOnly

      void renderPropertiesOnly(ContentRenderer renderer) throws IOException
      Renders the component properties only
      Parameters:
      renderer -
      Throws:
      IOException
      Since:
      10.0.0