Package org.zkoss.zk.ui.sys

Interface ComponentCtrl

    • 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

      • 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 annotName,
                   java.util.Map<java.lang.String,​java.lang.String[]> annotAttrs)
        Deprecated.
        As of release 6.0.0, replaced with addAnnotation(String, String, Map)

      • 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

      • 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

      • invalidatePartial

        @Deprecated
default void invalidatePartial​(java.lang.String subId)
        Deprecated.
        since 9.0.1. Use invalidatePartial() instead.
        Since:
        9.0.0

      • invalidatePartial

        @Deprecated
void invalidatePartial()
        Deprecated.
        since 9.5.1 it acts just the same as Component.invalidate()
        Invalidates this component by setting the dirty flag such that it will be redraw the partial content of this component and its dependencies later. And, the widget associated with this component and all its descendant at the client will be deleted and recreated, too.

        If the application is totally controlled by the server side (i.e., you don't write client codes), you rarely need to access this method.

        It can be called only in the request-processing and event-processing phases. However, it is NOT allowed in the rendering phase.

        Since:
        9.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