Package com.iizix.prop.ui

Class UIComp

    • Field Detail

      • REMOTE_FOCUS_EVENT

        protected static final int REMOTE_FOCUS_EVENT
        Remote event for focus.
        See Also:
        Constant Field Values

      • EMPTY

        public static final UIComp[] EMPTY
        Empty array of components.

      • styles

        protected Styles styles
        The style container.

      • vsField

        protected VSField vsField
        The connected field, null for none.

        Note: use thread-safe code when working with this variable as it can become unresolved, thus null.

    • Constructor Detail

      • UIComp

        public UIComp()
        Creates a property container with the specified name with a null value.

      • UIComp

        public UIComp​(Atom propertyAtom)
        Creates a property container with the specified name with a null value.
        Parameters:
        propertyAtom - the property atom.

      • UIComp

        public UIComp​(Atom propertyAtom,
              GProp<?>[] properties)
       throws PropException
        Creates a property container with the specified name and properties.
        Parameters:
        propertyAtom - the property atom.
        properties - the property array value for the property.
        Throws:
        PropException - as structural changes in containers on client is prohibited.

    • Method Detail

      • getPredefinedProps

        public void getPredefinedProps()
        Gets the references to predefined properties. If the Styles is created, make sure to get it.
        Overrides:
        getPredefinedProps in class PropCnr

      • forbiddenGetCustomDataMap

        @Deprecated
public java.util.Map<java.lang.String,​java.lang.Object> forbiddenGetCustomDataMap​(boolean doCreate)
        Deprecated.
        Gets or creates the provider map. This method is not intended to be called by user code, it is used by the system.

        Do not call this method!

        Specified by:
        forbiddenGetCustomDataMap in interface ICustomDataProvider
        Parameters:
        doCreate - Creates the map if required.
        Returns:
        The map or newly created map, null if not created.

        Note: the map returned is NOT synchronized thus not thread safe. It is up to the caller to synchronize on it to ensure thread safety.

      • clone

        public UIComp clone()
        Creates a clone out of this property. The cloning is overridden by the subclasses in order to handle cloning of its class variables appropriately.

        Cloning is used for "virtualization" of a property tree in the server. Client property classes will therefore throw CloneNotSupportedException.

        Once a tree has been cloned, the change-flag is reset, and the create-flag is set. All listeners are also removed! The new cloned property is an orphan, i.e. has no parent set. All children properties are also (deep) cloned.

        Note that the cloning process is done WITHOUT thread synchronization for performance reasons, thus no modifications should be done to the tree!

        Overrides:
        clone in class PropCnr

      • isMobile

        public boolean isMobile()
        Checks if the panel is of mobile type.
        Specified by:
        isMobile in interface IUIComp
        Returns:
        true if panel is found and it's mobile.

      • getUIParent

        public final UIContainer getUIParent()
        Gets the parent container of this component.
        Specified by:
        getUIParent in interface IComponent
        Returns:
        null if none is present.

      • getVirtualSpace

        public VirtualSpace getVirtualSpace()
        Gets the VirtualSpace of the UI component.
        Specified by:
        getVirtualSpace in interface IUIComp
        Returns:
        The VirtualSpace, or null for none.

      • assignFontInfoResolver

        public static void assignFontInfoResolver​(IFontInfo.Resolver resolver)
        Assigns the IFontInfo resolver.

      • getFontInfo

        public IFontInfo getFontInfo()
        Returns the font information from this component. This call can only be done in the Designer and will throw IllegalStateException in the Server.
        Returns:
        The font information.
        Throws:
        java.lang.IllegalStateException - If called from the Server in runtime (or outside the Designer).

      • hasImplicitAlignFillX

        public boolean hasImplicitAlignFillX()
        Returns if the component has implicit component horizontal fill.
        Returns:
        true means component will always fill the space in X, false otherwise.

      • hasImplicitAlignFillY

        public boolean hasImplicitAlignFillY()
        Returns if the component has implicit component vertical fill.
        Returns:
        true means component will always fill the space in Y, false otherwise.

      • getSize

        public Size getSize()
        Returns the size of the component in pixels. The size is a calculation and does not exactly reflect the real size that may be different due to additional styles not taken into account by this method. The size is calculated from the font of the component and default or defined values (such as character length or number of lines for text area).

        The method attempts to use the bounds settings if available. If not available, the size is retrieved from the potential settings of the layout data, and if that is not provided, the approximate size is used.

        Returns:
        The size of the component.
        Throws:
        java.lang.IllegalStateException - If called outside of the Designer.

      • getApproximateSize

        public abstract Size getApproximateSize()
                                 throws java.lang.IllegalStateException
        Returns the size of the component in pixels. The size is a calculation and does not exactly reflect the real size that may be different due to additional styles not taken into account by this method. The size is calculated from the font of the component and default or defined values (such as character length or number of lines for text area).
        Returns:
        The size of the component.
        Throws:
        java.lang.IllegalStateException - If called outside of the Designer, e.g. from the Server.

      • getPixelWidth

        public int getPixelWidth()
        Returns the width in pixel units of the component from the layout.
        Returns:
        -1 if width is not defined, otherwise the pixel width.

      • getPixelHeight

        public int getPixelHeight()
        Returns the height in pixel units of the component from the layout.
        Returns:
        -1 if height is not defined, otherwise the pixel height.

      • hasImplicitWidth

        public boolean hasImplicitWidth()
        Verifies if the component has a width.

        This means a width that is either present due to the component or that the width has explicitly been set, or that it is in a container that sets the outer bounds of the component.

        Returns:
        true if the width is defined and non-zero, false otherwise.

      • hasImplicitHeight

        public boolean hasImplicitHeight()
        Verifies if the component has an implicit height.

        This means a height that is either present due to the component or that the height has explicitly been set, or that it is in a container that sets the outer bounds of the component.

        Returns:
        true if the height is defined and non-zero, false otherwise.

      • hasExplicitWidth

        public boolean hasExplicitWidth()
        Verifies if the component has a width.

        This means a width that is either present due to the component or that the width has explicitly been set, or that it is in a container that sets the outer bounds of the component.

        Returns:
        true if the width is defined and non-zero, false otherwise.

      • hasExplicitHeight

        public boolean hasExplicitHeight()
        Verifies if the component has an implicit height.

        This means a height that is either present due to the component or that the height has explicitly been set, or that it is in a container that sets the outer bounds of the component.

        Returns:
        true if the height is defined and non-zero, false otherwise.

      • mustHaveWidth

        public boolean mustHaveWidth()
        Does this component require a width?
        Returns:
        true if the width must be defined and non-zero, false otherwise.

      • mustHaveHeight

        public boolean mustHaveHeight()
        Does this component require a height?
        Returns:
        true if the height must be defined and non-zero, false otherwise.

      • mustHaveExplicitWidth

        public boolean mustHaveExplicitWidth()
        Does this component require an explicitly defined width?
        Returns:
        true if the width must be defined and non-zero, false otherwise.

      • mustHaveExplicitHeight

        public boolean mustHaveExplicitHeight()
        Does this component require an explicitly defined height?
        Returns:
        true if the height must be defined and non-zero, false otherwise.

      • canFillX

        public boolean canFillX()
        Returns if the component can fill in X or not.
        Returns:
        true (default) for fill supported, false otherwise (e.g. for a checkbox).

      • canFillY

        public boolean canFillY()
        Returns if the component can fill in Y or not.
        Returns:
        true (default) for fill supported, false otherwise (e.g. for a checkbox).

      • canAlignX

        public boolean canAlignX()
        Returns if the component can be aligned left, right, center, or horizontal fill.
        Returns:
        true by default, components override to return false if they are fixed in width or take up the entire width.

      • canAlignY

        public boolean canAlignY()
        Returns if the component can be aligned top, bottom, middle or vertical fill.
        Returns:
        true by default, components override to return false if they are fixed in height or take up the entire height.

      • getForcedAlignX

        public int getForcedAlignX()
        Gets the default alignment in X when it is not supported, i.e. canAlignX() returns false.
        Returns:
        1=left, 2=center, 3=right, 4=fill (default value), or -1 for failure: align not possible.

      • getForcedAlignY

        public int getForcedAlignY()
        Gets the default alignment in Y when it is not supported, i.e. canAlignY() returns false.
        Returns:
        1=top, 2=middle, 3=bottom, 4=fill (default value), or -1 for failure: align not possible.

      • getFixWidth

        public int getFixWidth()
        Gets the designed fixed width of this component in pixels.
        Specified by:
        getFixWidth in interface IUIComp
        Returns:
        Zero (default) for not fixed.

      • getFixHeight

        public int getFixHeight()
        Gets the designed fixed height of this component in pixels.
        Specified by:
        getFixHeight in interface IUIComp
        Returns:
        Zero (default) for not fixed.

      • getComponentID

        public int getComponentID()
        Creates or gets the unique ID within the panel for a component. This ID can be used as the HTML ID and is used by the LabelForReference.
        Specified by:
        getComponentID in interface IUIComp
        Returns:
        A unique number for a component in a panel.

      • resetComponentID

        public void resetComponentID()
        Resets the component ID, typically when copied or saved in order to add make copies of the (some) component data. The operation is recursive.

      • getStyles

        public final Styles getStyles()
        Gets the Styles property. If it doesn't exist, it is created.
        Specified by:
        getStyles in interface IComponent
        Returns:
        The Styles property container or null for none.

      • getStyles

        public final Styles getStyles​(boolean doCreate)
        Gets the Styles property. If it doesn't exist, it is created depending on the doCreate flag.
        Returns:
        The Styles property container or null for none.

      • createStyles

        protected Styles createStyles()
        Creates the Styles container (can be overridden by Designer to create com.iizigo.style.prop.EditorStyles).

      • setEnabled

        public final boolean setEnabled​(boolean on)
        Sets the enabled state of the component.
        Specified by:
        setEnabled in interface IComponent
        Parameters:
        on - The enabled state.
        Returns:
        true when this property has been changed, false otherwise (or for error).

      • setEnabled

        public final boolean setEnabled​(boolean on,
                                IVSComponent trigger)
        Sets the enabled state of the component.
        Parameters:
        on - The enabled state.
        trigger - The trigger VS component, null for none.
        Returns:
        true when this property has been changed, false otherwise (or for error).

      • isEnabled

        public final boolean isEnabled()
        Get the enabled state of the component.
        Specified by:
        isEnabled in interface IComponent
        Returns:
        true if component is enabled, false otherwise.

      • setReadOnly

        public final boolean setReadOnly​(boolean on)
        Sets the read-only state of the component.

        Note: certain components are always in a "kind of read-only" mode, thus this property doesn't really apply to them.

        Specified by:
        setReadOnly in interface IComponent
        Parameters:
        on - the read-only state.
        Returns:
        true when this property has been changed, false otherwise (or for error).

      • setReadOnly

        public final boolean setReadOnly​(boolean on,
                                 IVSComponent trigger)
        Sets the read-only state of the component.

        Note: certain components are always in a "kind of read-only" mode, thus this property doesn't really apply to them.

        Parameters:
        on - The read-only state.
        trigger - The trigger VS component, null for none.
        Returns:
        true when this property has been changed, false otherwise (or for error).

      • isReadOnly

        public final boolean isReadOnly()
        Get the read-only state of the component.

        Note: certain components are always in a "kind of read-only" mode, thus this property doesn't really apply to them.

        Specified by:
        isReadOnly in interface IComponent
        Returns:
        true if component is read-only, false otherwise.

      • setVisible

        public final boolean setVisible​(boolean on)
        Sets the visibility state of the component.
        Specified by:
        setVisible in interface IComponent
        Parameters:
        on - the visibility state.
        Returns:
        true when this property has been changed, false otherwise (or for error).

      • setVisible

        public final boolean setVisible​(boolean on,
                                IVSComponent trigger)
        Sets the visibility state of the component.
        Parameters:
        on - The visibility state.
        trigger - The trigger VS component, null for none.
        Returns:
        true when this property has been changed, false otherwise (or for error).

      • isVisible

        public final boolean isVisible()
        Get the visibility state of the component.
        Specified by:
        isVisible in interface IComponent
        Returns:
        true if component is visible, false otherwise.

      • getLayout

        public LayoutProp getLayout()
        Gets the layout properties of this component. If the properties are not present, they are created.
        Specified by:
        getLayout in interface IUIComp
        Returns:
        The layout properties.

      • setLayoutMgr

        public final LayoutMgr<?> setLayoutMgr​(LayoutMgr<?> layoutManager)
        Sets the layout manager for the component. If the same layout manager is set twice, there will be no change and the return value is the instance of the layoutManager parameter passed into this method.
        Specified by:
        setLayoutMgr in interface IComponent
        Parameters:
        layoutManager - the layout manager instance, or null to remove the layout manager.
        Returns:
        the previous layout manager instance, or null if none was set.

      • getLayoutMgr

        public LayoutMgr<?> getLayoutMgr()
        Gets the layout manager for the component.
        Specified by:
        getLayoutMgr in interface IComponent
        Returns:
        the layout manager instance, or null if none is set.

      • getLayoutMgr

        public <LAYOUT_MGR extends LayoutMgr<?>> LAYOUT_MGR getLayoutMgr​(java.lang.Class<LAYOUT_MGR> layoutMgrClass)
        Gets the layout manager for the component.
        Specified by:
        getLayoutMgr in interface IUIComp
        Parameters:
        layoutMgrClass - The class of the layout manager.
        Returns:
        the layout manager instance, or null if none is set.

      • add

        public final void add​(UIComp component)
               throws PropException
        Adds a component to the container with a property for the layout manager.
        Parameters:
        component - the component to add.
        Throws:
        PropException - when the container cannot accept the component with the specific layout property.

      • getText

        public final java.lang.String getText()
        Gets the text. The string is retrieved from the Atom.TEXT ($text) property and can be either StringProp or KStringProp.

        If it's a KString, the plain string is returned. It is recommended to use the more accurate text methods getPlainText() or getKStringText() to have better control.

        Specified by:
        getText in interface IComponent
        Returns:
        The plain text string or null if not supported.

      • getKStringText

        public KString getKStringText()
        Gets the text from the control as a KString. This KString can be plain or in HTML depending on the input, but KString provides methods to get text in different ways.

        Components implementing KString support implements the IUIHTMLTextComponent interface.

        Specified by:
        getKStringText in interface IComponent
        Returns:
        The KString of the text if available, or null if none is present or KString is not supported by the component.

      • setText

        public final boolean setText​(java.lang.String text)
        Sets the plain text property without tags processing.

        If the component is connected to a VirtualSpace Field, that text is set instead of the UI component's text.

        Specified by:
        setText in interface IComponent
        Parameters:
        text - The text to set in plain text (no tags and no HTML tags will be processed).
        Returns:
        true for change of text, false for no change or not supported.

      • setText

        public final boolean setText​(KString text)
        Sets the HTML text property KStringProp Atom.TEXT ($text).

        Components implementing KString support implements the IUIHTMLTextComponent interface.

        Specified by:
        setText in interface IComponent
        Parameters:
        text - The text to set.
        Returns:
        true for change of text, false for no change or not supported.

      • setHTMLText

        public final boolean setHTMLText​(java.lang.String text)
        Sets the HTML text property KStringProp without tags processing.

        The KStringException is caught in case of invalid HTML text and logs a warning message.

        Components implementing KString support implements the IUIHTMLTextComponent interface.

        Specified by:
        setHTMLText in interface IComponent
        Parameters:
        text - The text to set.
        Returns:
        true for change of text, false for no change or not supported.

      • getValue

        public Value getValue​(java.lang.String name)
        Gets the value from a property named name.
        Specified by:
        getValue in interface IUIComp
        Parameters:
        name - The name of the property.
        Returns:
        The Value for the property with the specified name, or null if not found.

      • getValue

        public Value getValue​(Atom atom)
        Gets the value from a property named atom.
        Specified by:
        getValue in interface IUIComp
        Parameters:
        atom - The atom name of the property.
        Returns:
        The Value for the property with the specified name, or null if not found.

      • getBestVSFieldValueType

        public Value.Type getBestVSFieldValueType​(VSRelativeReference<?> reference)
        Requests the value type that would best suit the listener.
        Specified by:
        getBestVSFieldValueType in interface IVSFieldListener
        Parameters:
        reference - The VSRelativeReference instance holding the reference.
        Returns:
        null if none is available.

      • getVSField

        public VSField getVSField()
        Gets the connected or disconnected VirtualSpace Field.
        Specified by:
        getVSField in interface IUIComp
        Returns:
        The field, or null if no field resolved (connected or disconnected) is present.

      • isVSFieldDisconnected

        public boolean isVSFieldDisconnected()
        Checks if the connection state to the VirtualSpace Field is disconnected.
        Specified by:
        isVSFieldDisconnected in interface IUIComp
        Returns:
        true if currently disconnected.

      • disconnectVSField

        public boolean disconnectVSField()
        Disconnects from the VirtualSpace Field connection.
        Specified by:
        disconnectVSField in interface IUIComp
        Returns:
        true for success, false if already done or none is connected.

      • reconnectVSField

        public boolean reconnectVSField​(boolean update)
        Reconnects to a previously disconnected VirtualSpace Field connection.

        The method setVSFieldToComponent(VSField) is called if there was a disconnected field set.

        Specified by:
        reconnectVSField in interface IUIComp
        Parameters:
        update - Update flag, i.e. if all states, messages and field contents should be updated to match the field.
        Returns:
        true for success, false if not disconnected.

      • onResolved

        public void onResolved​(VSRelativeReference<?> reference,
                       VSField field)
        Called when the property reference has been resolved. UI components use this method to set its state according to the field, this is handled in by the UIComp class.

        Components must override to provide the implementation for e.g. value contents, styles, etc.

        Specified by:
        onResolved in interface IVSFieldListener
        Parameters:
        reference - The VSRelativeReference instance holding the reference.
        field - The target reference.

      • getMappedVSComponent

        public VSComponent getMappedVSComponent()
        Gets the main component that is used to map the UI component to the VirtualSpace.
        Returns:
        The VS component, or null for none. Default is to return the VSField of UIComp. Override e.g. for actions.

      • getComponentMappings

        public final java.util.List<VSComponent> getComponentMappings()
        Gets the mappings to VSComponent's for this component.

        The VS components are sorted for the deepest first.

        Specified by:
        getComponentMappings in interface IUIComp
        Returns:
        An unmodifiable set of VSComponent's, or null for no VS mappings.

      • getVSStateFocus

        public VSComponent getVSStateFocus()
        Gets the VS component for state and focus of this component (always null) if the component is not a container.
        Returns:
        The component is always null for a non-container UI component.

      • getFirstContainerVSStateFocus

        public VSComponent getFirstContainerVSStateFocus()
        Gets the first VS component encountered for state and focus of this container or in the parent tree up to the panel level.
        Returns:
        The component (generally a VS Group), null if none is set.

      • addMappings

        protected void addMappings​(VSMappings mappings,
                           VSComponent vsStateFocus)
        Gets the mappings of a VirtualSpace to the panel components.

        The default is to find the relative references to VS and add those references. Override to provide other functionality.

        Parameters:
        mappings - The mappings instance to fill in.
        vsStateFocus - Do not go past this component when going up in the parent tree, null for none.

      • setVSFieldToComponent

        public void setVSFieldToComponent​(VSField field)
        Method called when a VirtualSpace Field is resolved or when reconnection is done. Override to provide additional processing. By default all states (enabled, read-only and visible), message and field contents are set from the field to the component.
        Specified by:
        setVSFieldToComponent in interface IUIComp
        Parameters:
        field - The VS field.

      • setVSFieldMessageToComponent

        public boolean setVSFieldMessageToComponent​(VSField field,
                                            boolean clear)
        Sets the VirtualSpace Field's message to this component.
        Specified by:
        setVSFieldMessageToComponent in interface IUIComp
        Parameters:
        field - The VS field.
        clear - Flag to clear the component message if the field hasn't got a message.
        Returns:
        true if changed, false for no change.

      • onBroken

        public void onBroken​(VSRelativeReference<?> reference,
                     VSField field)
        Called when the property reference has been broken, i.e. unresolved.
        Specified by:
        onBroken in interface IVSFieldListener
        Parameters:
        reference - The VSRelativeReference instance holding the reference.
        field - The target reference.

      • onParentStateChanged

        public void onParentStateChanged​(IVSComponent parent,
                                 IVSComponentState.State state,
                                 boolean on)
        Called when the column changes state.
        Specified by:
        onParentStateChanged in interface IVSComponentListener
        Parameters:
        parent - The parent who's state was changed.
        state - The state change, possible values PARENT_ENABLED, PARENT_READONLY, PARENT_VISIBLE.
        on - New state.

      • onValueChanged

        public void onValueChanged​(VSField field,
                           Value value,
                           GProp<?> trigger,
                           IPostEventProcessing postProcessing)
        Called when the field value is set.

        Components must override to provide the implementation when they are not implementing IPlainTextComponent, in this case the default implementation transports the field string value to this text components plain text.

        Specified by:
        onValueChanged in interface IVSFieldListener
        Parameters:
        field - The VS field.
        value - The value, never null, but value.isNull() could be true.
        trigger - The trigger property that may be null.
        postProcessing - Post-processing instance.

      • enterVSProcessing

        public final boolean enterVSProcessing​(VSComponent component)
        Call this method when the VSField or the text will update each other, in order to avoid recursion in event processing.

        Programming note: it is IMPERATIVE that the exitVSProcessing() is called after any kind of call to this routine: surround e.g. with "try-finally" block. If this method returns false the exitVSProcessing() should not be called.

        Parameters:
        component - The VS component that is used for processing.
        Returns:
        true if OK to process, false otherwise.

      • onEventSelf

        public void onEventSelf​(GEvent event)
        Updates a VirtualSpace Field when a component text changes.
        Specified by:
        onEventSelf in interface IGProp<GProp<?>[]>
        Overrides:
        onEventSelf in class GProp<GProp<?>[]>
        Parameters:
        event - The property event.

      • getTrigger

        protected GProp<?> getTrigger​(GEvent event)
        Gets the trigger from an event. If the event is remote induced, it is set to "this" component. Otherwise the value is the event's trigger.
        Parameters:
        event - The event, null for none.
        Returns:
        The trigger, never null (defaults to "this").

      • hasSelectionChanged

        protected boolean hasSelectionChanged()
        Checks if the selection has changed since last call to fireSelection.
        Returns:
        true for changed, false for no changes (or component is not a selection component).

      • fireSelection

        public boolean fireSelection()
        Fires the selection to the listeners if it is changed. The method does not return until it has notified this.onNotifySelectionChanged() method, listeners, and the UI component's onUISelection method.
        Returns:
        true if selection really has changed, false otherwise (or the component is not an instance of IUISelectionComp).

      • fireSelection

        protected boolean fireSelection​(GEvent event)
        Fires the selection to the listeners if it is changed.
        Parameters:
        event - The trigger of the event, MUST be non-null.
        Returns:
        true if selection really has changed, false otherwise (or the component is not an instance of IUISelectionComp).

      • processVSComponentSelection

        protected void processVSComponentSelection​(VSComponent mappedComponent)
        Override to process the VS components selection state when Atom.SELECTED BoolProp changes. Nothing is done by default and must be overridden to process selections by each component.

        Typically, call mappedComponent.setSelected(isSelected(),this);

        Parameters:
        mappedComponent - The matching mapped component.

      • onSelectionChanged

        protected void onSelectionChanged​(GEvent event)
        Method called when the selection of the component changed due to a property change (value changed, property added or removed). Note that this method is allowed to perform actions that changes selection, e.g. if an update to VS failed and the selection is restored or set elsewhere.

        Override the onNotifySelectionChanged() method if you wish to know that the selection really has changed.

        Parameters:
        event - The event that causes the selection change.

      • onNotifySelectionChanged

        protected void onNotifySelectionChanged​(GEvent event)
        Method called when the selection of the component has changed and has been verified to be different from a previous selection. Subclasses can override this method to inform potential listeners.
        Parameters:
        event - The event that causes the selection change, COULD BE NULL!

      • setComponentToVSField

        public int setComponentToVSField()
        Sets the text or value from this text or value component to its VirtualSpace Field, if any.
        Specified by:
        setComponentToVSField in interface IUIComp
        Returns:
        1 for update completed, 0 for nothing done and -1 for error occurred.

      • getErrorMessage

        public KString getErrorMessage​(ValueConversionException exception)
        Gets the localized error message for a validation exception.
        Specified by:
        getErrorMessage in interface IUIComp
        Parameters:
        exception - The exception, or null for no error.
        Returns:
        The error message, e.g. to display in the component, or null for no error present, i.e. the exception is null.

      • getErrorMessage

        public KString getErrorMessage​(ILocaleString localeString,
                               ValueConversionException exception)
        Gets the localized error message for a validation exception.
        Specified by:
        getErrorMessage in interface IUIComp
        Parameters:
        localeString - The localeString instance to used for localization, or null to look it up for the current session.
        exception - The exception, or null for no error.
        Returns:
        The error message, e.g. to display in the component, or null for no error present, i.e. the exception is null.

      • getErrorMessageString

        public java.lang.String getErrorMessageString​(ValueConversionException exception)
        Gets the localized error message for a validation exception.
        Parameters:
        exception - The exception, or null for no error.
        Returns:
        The error message, e.g. to display in the component, or null for no error present, i.e. the exception is null.

      • getErrorMessageString

        public java.lang.String getErrorMessageString​(ILocaleString localeString,
                                              ValueConversionException exception)
        Gets the localized error message for a validation exception.
        Parameters:
        localeString - The localeString instance to used for localization, or null to look it up for the current session.
        exception - The exception, or null for no error.
        Returns:
        The error message, e.g. to display in the component, or null for no error present, i.e. the exception is null.

      • getErrorMessageEx

        public KString getErrorMessageEx​(ILocaleString localeString,
                                 java.lang.Exception exception)
        Gets the localized error message for a validation exception of any kind of exception.
        Parameters:
        localeString - The localeString instance to used for localization, or null to look it up for the current session.
        exception - The exception, or null for no error.
        Returns:
        The error message, e.g. to display in the component, or null for no error present, i.e. the exception is null.

      • getErrorMessageStringEx

        public java.lang.String getErrorMessageStringEx​(ILocaleString localeString,
                                                java.lang.Exception exception)
        Gets the localized error message for a validation exception of any kind of exception.
        Parameters:
        localeString - The localeString instance to used for localization, or null to look it up for the current session.
        exception - The exception, or null for no error.
        Returns:
        The error message, e.g. to display in the component, or null for no error present, i.e. the exception is null.

      • setErrorMessage

        public void setErrorMessage​(ValueConversionException exception)
        Transposes an exception from conversion to the component as an error message.
        Specified by:
        setErrorMessage in interface IUIComp
        Parameters:
        exception - The exception, or null to remove it.

      • setErrorMessage

        public void setErrorMessage​(ILocaleString localeString,
                            ValueConversionException exception)
        Transposes an exception from conversion to the component as an error message.
        Specified by:
        setErrorMessage in interface IUIComp
        Parameters:
        localeString - The localeString instance to used for localization, or null to look it up for the current session.
        exception - The exception, or null to remove it.

      • onComponentSelectedInParent

        public void onComponentSelectedInParent​(boolean on)
        Called by the parent container to inform that this component has been selected in its container. The containers that call this method are typically accordion, swap and tab containers.

        The container processes this method by selecting the VSComponent for state and focus that may be connected.

        Parameters:
        on - The selection state.

      • setTooltip

        public boolean setTooltip​(KTooltip tooltip)
        Sets (or removes) the tooltip for the component.
        Specified by:
        setTooltip in interface IComponent
        Parameters:
        tooltip - The tooltip, or null to remove it.
        Returns:
        true for changed, false for no change.

      • setTooltip

        public boolean setTooltip​(java.lang.String text)
        Sets (or removes) the plain tooltip text for the component.
        Specified by:
        setTooltip in interface IComponent
        Parameters:
        text - The plain tooltip text, or null to remove it.
        Returns:
        true for changed, false for no change.

      • getTooltip

        public KTooltip getTooltip()
        Gets the current tooltip for the component.
        Specified by:
        getTooltip in interface IComponent
        Returns:
        The tooltip, or null for none.

      • getTooltipText

        public java.lang.String getTooltipText()
        Gets the current tooltip text for the component as a plain string.
        Specified by:
        getTooltipText in interface IComponent
        Returns:
        The tooltip as a plain string, or null for none.

      • setErrorMessage

        public boolean setErrorMessage​(java.lang.String errorMessage)
        Sets (or removes) the ERROR message for the component.
        Specified by:
        setErrorMessage in interface IComponent
        Parameters:
        errorMessage - The ERROR message, or null to remove it.
        Returns:
        true for changed, false for no change.

      • setErrorMessage

        public boolean setErrorMessage​(KString errorMessage)
        Sets (or removes) the ERROR message for the component.
        Specified by:
        setErrorMessage in interface IComponent
        Parameters:
        errorMessage - The ERROR message, or null to remove it.
        Returns:
        true for changed, false for no change.

      • clearErrorMessage

        public boolean clearErrorMessage()
        Clears the error message, if any.
        Specified by:
        clearErrorMessage in interface IComponent
        Returns:
        true if changed, false otherwise.

      • setMessage

        public boolean setMessage​(KTooltip message)
        Sets (or removes) the message for the component.
        Specified by:
        setMessage in interface IComponent
        Parameters:
        message - The message, or null to remove it.
        Returns:
        true for changed, false for no change.

      • setMessage

        public boolean setMessage​(java.lang.String message,
                          int category)
        Sets (or removes) a plain message string for the component with specified category.
        Specified by:
        setMessage in interface IComponent
        Parameters:
        message - The message to set, or null to clear it.
        category - The category of the message: IUIComp.NONE, IUIComp.INFORMATION, IUIComp.WARNING or IUIComp.ERROR.
        Returns:
        true for changed, false for no change.

      • getMessage

        public KTooltip getMessage()
        Gets the current message for the component.
        Specified by:
        getMessage in interface IComponent
        Returns:
        The message, or null for none.

      • getMessageText

        public java.lang.String getMessageText()
        Gets the current message text for the component as a plain string.
        Specified by:
        getMessageText in interface IComponent
        Returns:
        The message as a plain string, or null for none.

      • setBadge

        public boolean setBadge​(java.lang.String text)
        Sets a red badge text with default font size for the component as a plain string.
        Specified by:
        setBadge in interface IComponent
        Parameters:
        text - The plain text string, or null to clear it.
        Returns:
        true for changed, false for no change.

      • setBadge

        public boolean setBadge​(GBadge badge)
        Sets or clears the badge of the component.
        Specified by:
        setBadge in interface IComponent
        Parameters:
        badge - The badge to set, or null to clear it.
        Returns:
        true for changed, false for no change.

      • getBadge

        public GBadge getBadge()
        Gets the badge for the component.
        Specified by:
        getBadge in interface IComponent
        Returns:
        The badge, or null if undefined.

      • isRTL

        public boolean isRTL()
        Returns if the component is displayed in RTL or not.
        Specified by:
        isRTL in interface IUIComp

      • canAcceptUIContainerFocus

        public java.lang.String canAcceptUIContainerFocus()
        Returns if this container can accept focus itself or for one of its children components. If this is a component and not a container, this request is redirected to the parent container.

        This method recurses up to the topmost UI container, and all containers must return null for this method to return null.

        Typically, a container returns itself as instance if it is disabled or hidden.

        Specified by:
        canAcceptUIContainerFocus in interface IUIComp
        Returns:
        null if this container (or parent container if this is a component) and all containers up to the topmost level returns null, otherwise an error message why the container that did not accept focus.

      • setUIContainerFocus

        public java.lang.String setUIContainerFocus​(UIComp requestor,
                                            boolean doAnimate)
        Sets the focus to the UI container and all its parents. This method is called when focus is to be set to a component, making it possible for containers such as accordion/swap/tab to change its main container into view.

        Subclasses must override this method to process it, but make sure to call super.setUIContainerFocus(requestor) first!

        Specified by:
        setUIContainerFocus in interface IUIComp
        Parameters:
        requestor - The requestor is a child to this container.
        doAnimate - Flag to enable animation when selection is changed for e.g. accordion, swap or tab containers.
        Returns:
        null for success, otherwise an error message why it failed.

      • canRequestFocus

        public java.lang.String canRequestFocus()
        Returns if this component can receive focus. Focus capable components may override to return null for success, or other error message.

        Default processing is to return "Component not focusable" if the component doesn't implement the IFocusComp interface, "Not virtualized" if the component is not in a virtualized state, "Component is hidden" if isVisible() is false or "Component is disabled" if isEnabled() is false.

        Specified by:
        canRequestFocus in interface IPropCnr
        Returns:
        null focus is possible to this component, or an error message describing why focus cannot be requested.

      • canRequestFocus

        public java.lang.String canRequestFocus​(boolean ignoreVisibleFlag,
                                        boolean ignoreEnabledFlag)
        Returns if this component can receive focus. Focus capable components may override to return null for success, or other error message.

        Default processing is to return "Component not focusable" if the component doesn't implement the IFocusComp interface, "Not virtualized" if the component is not in a virtualized state, "Component is hidden" if isVisible() is false or "Component is disabled" if isEnabled() is false.

        Specified by:
        canRequestFocus in interface IPropCnr
        Overrides:
        canRequestFocus in class PropCnr
        Parameters:
        ignoreVisibleFlag - Flag indicating that the visible state should be ignored. If this flag is false and the component hidden an error message is returned.
        ignoreEnabledFlag - Flag indicating that the enabled state should be ignored. If this flag is false and the component hidden an error message is returned.
        Returns:
        null focus is possible to this component, or an error message describing why focus cannot be requested.

      • couldRequestFocusIfVirtualized

        public java.lang.String couldRequestFocusIfVirtualized​(boolean ignoreVisibleFlag,
                                                       boolean ignoreEnabledFlag)
        Returns if this component could receive focus if it would be virtualized. Focus capable components may override to return null for success, or other error message.

        Default processing is to return "Component not focusable" if the component doesn't implement the IFocusComp interface, "Component is hidden" if isVisible() is false and the ignoreVisibleFlag is false, or "Component is disabled" if isEnabled() is false the ignoreEnabledFlag is false.

        Specified by:
        couldRequestFocusIfVirtualized in interface IPropCnr
        Overrides:
        couldRequestFocusIfVirtualized in class PropCnr
        Parameters:
        ignoreVisibleFlag - Flag indicating that the visible state should be ignored. If this flag is false and the component hidden an error message is returned.
        ignoreEnabledFlag - Flag indicating that the enabled state should be ignored. If this flag is false and the component hidden an error message is returned.
        Returns:
        null focus is possible to this component, or an error message describing why focus cannot be requested.

      • hasFocus

        public boolean hasFocus()
        Returns if the component currently has focus.
        Specified by:
        hasFocus in interface IPropCnr
        Overrides:
        hasFocus in class PropCnr
        Returns:
        true if this component has focus, false otherwise.

      • requestFocus

        public java.lang.String requestFocus()
        Requests focus to this component. This call is redirected to the panel focus engine. The engine may veto the focus change, because it currently cannot change focus, or the request is not virtualized.

        This method is less precise than requestFocusEx(), but avoids try-catching.

        Specified by:
        requestFocus in interface IComponent
        Returns:
        null for success, otherwise an error message indicating why focus was not able to be changed.

      • requestFocusEx

        public boolean requestFocusEx()
                       throws FocusException
        Requests focus to this component. This call is redirected to the panel focus engine. The engine may veto the focus change, because it currently cannot change focus, or the request is not virtualized.
        Specified by:
        requestFocusEx in interface IComponent
        Returns:
        true if focus was changed, false otherwise.
        Throws:
        FocusException - If focus could not be changed.

      • requestFocus

        public java.lang.String requestFocus​(boolean doAnimate)
        Requests focus to this component. This call is redirected to the panel focus engine. The engine may veto the focus change, because it currently cannot change focus, or the request is not virtualized.

        This method is less precise than requestFocusEx(), but avoids try-catching.

        Specified by:
        requestFocus in interface IComponent
        Parameters:
        doAnimate - Flag to enable animation when selection is changed for e.g. accordion, swap or tab containers.
        Returns:
        null for success, otherwise an error message indicating why focus was not able to be changed.

      • requestFocusEx

        public boolean requestFocusEx​(boolean doAnimate)
                       throws FocusException
        Requests focus to this component. This call is redirected to the panel focus engine. The engine may veto the focus change, because it currently cannot change focus, or the request is not virtualized.
        Specified by:
        requestFocusEx in interface IComponent
        Parameters:
        doAnimate - Flag to enable animation when selection is changed for e.g. accordion, swap or tab containers.
        Returns:
        true if focus was changed, false otherwise.
        Throws:
        FocusException - If focus could not be changed.

      • requestFocus

        public java.lang.String requestFocus​(IGProp<?> trigger,
                                     boolean isRemoteInduced)
        Requests focus to this component. This call is redirected to the focus engine for the component type. The engine may veto the focus change, because it currently cannot change focus, or the request is not or cannot be virtualized.

        This method is less precise than PropCnr.requestFocusEx(IGProp, boolean, IFocusVetoListener), but avoids try-catching.

        This method is implemented in PropCnr, but should only be called for IFocusComp implementing property classes. This method will return "Component not focusable" if called on a non-focus component.

        Specified by:
        requestFocus in interface IPropCnr
        Overrides:
        requestFocus in class PropCnr
        Parameters:
        trigger - The trigger property, null for none.
        isRemoteInduced - Flag for remote induced focus.
        Returns:
        null for success, otherwise an error message indicating why focus was not able to be changed.

      • requestFocusEx

        public boolean requestFocusEx​(IGProp<?> trigger,
                              boolean isRemoteInduced)
                       throws FocusException
        Requests focus to this component. This call is redirected to the focus engine for the component type. The engine may veto the focus change, because it currently cannot change focus, or the request is not or cannot be virtualized.

        This method is implemented in PropCnr, but should only be called for IFocusComp implementing property classes. This method will throw FocusException with message "Component not focusable" if called on a non-focus component.

        Specified by:
        requestFocusEx in interface IPropCnr
        Overrides:
        requestFocusEx in class PropCnr
        Parameters:
        trigger - The trigger property, null for none.
        isRemoteInduced - Flag for remote induced focus.
        Returns:
        true if focus was changed, false otherwise.
        Throws:
        FocusException - If focus could not be changed.

      • requestFocus

        public java.lang.String requestFocus​(IGProp<?> trigger,
                                     boolean isRemoteInduced,
                                     boolean doAnimate)
        Requests focus to this component. This call is redirected to the focus engine for the component type. The engine may veto the focus change, because it currently cannot change focus, or the request is not or cannot be virtualized.

        This method is less precise than PropCnr.requestFocusEx(IGProp, boolean, IFocusVetoListener), but avoids try-catching.

        This method is implemented in PropCnr, but should only be called for IFocusComp implementing property classes. This method will return "Component not focusable" if called on a non-focus component.

        Parameters:
        trigger - The trigger property, null for none.
        isRemoteInduced - Flag for remote induced focus.
        Returns:
        null for success, otherwise an error message indicating why focus was not able to be changed.

      • requestFocusEx

        public boolean requestFocusEx​(IGProp<?> trigger,
                              boolean isRemoteInduced,
                              boolean doAnimate)
                       throws FocusException
        Requests focus to this component. This call is redirected to the focus engine for the component type. The engine may veto the focus change, because it currently cannot change focus, or the request is not or cannot be virtualized.

        This method is implemented in PropCnr, but should only be called for IFocusComp implementing property classes. This method will throw FocusException with message "Component not focusable" if called on a non-focus component.

        Parameters:
        trigger - The trigger property, null for none.
        isRemoteInduced - Flag for remote induced focus.
        Returns:
        true if focus was changed, false otherwise.
        Throws:
        FocusException - If focus could not be changed.

      • onFocusGained

        public void onFocusGained​(IFocusComp opposite,
                          IGProp<?> trigger,
                          boolean isRemoteInduced)
        Called to the component when it receives focus. This method will become visible when the interface is added to a component extending UIComp, but it will not be required to provide the code unless specific code is required.

        Focus components override this method if they need to process focus lost.

        Parameters:
        opposite - Component losing focus, null for none.
        trigger - The component triggering the focus, null for none.
        isRemoteInduced - Flag indicating this event is due to a remote event.

      • onRemoteEvent

        public void onRemoteEvent​(RemoteEvent event)
        Called when a remote property event should be processed by this property.

        A subclass can override this method to perform appropriate processing and is not required to call super.onRemoteEvent(e).

        The onRemoteEvent is NOT called when in a proxied property container, but rather the normal onEventSelf method.

        The UIComp implementation processes remote induced focus events.

        Specified by:
        onRemoteEvent in interface IGProp<GProp<?>[]>
        Overrides:
        onRemoteEvent in class GProp<GProp<?>[]>
        Parameters:
        event - The remote event.

      • verify

        public boolean verify​(PropVerification verification)
        Verifies this property container: component type must match panel type (desktop v/s mobile).
        Specified by:
        verify in interface IGProp<GProp<?>[]>
        Overrides:
        verify in class PropCnr
        Parameters:
        verification - The property verification class.
        Returns:
        true if verification should proceed, false if disposed of and verification should not take place.

      • verifyComponentScope

        protected boolean verifyComponentScope​(UIContainer scopeContainer,
                                       java.lang.String what,
                                       PropVerification verification,
                                       VSComponent vsOuter)
        Verifies that this component has it's VS references inside the outer VS reference.
        Parameters:
        scopeContainer - The scope container.
        what - What the scope container is.
        verification - The property verification class.
        vsOuter - The outer VS parent.
        Returns:
        true if OK, false if somehow outside.

      • onPrepare

        protected void onPrepare​(IAppOwner appOwner,
                         IModuleOwner moduleOwner,
                         boolean isPostCall,
                         java.util.List<java.lang.Throwable> errors)
                  throws PropException
        Called when the application is being prepared. The order of onPrepare calls is always parent first, the children. The method is called twice, first time with isPostCall set to false, then a second time with true.
        Overrides:
        onPrepare in class GProp<GProp<?>[]>
        Parameters:
        appOwner - The application owner.
        moduleOwner - The Module owner.
        isPostCall - Flag indicating this is a post-call.
        errors - A list of errors that occurred but did not cause an abort.
        Throws:
        PropException - For property errors during the application preparation to need to abort.

      • onPrepare

        protected void onPrepare​(ClassReference cr,
                         java.util.List<java.lang.Throwable> errors)
        Called to resolve methods for the component from main "onPrepare" once the ClassReference has been found.

        Components should override this method to load it's required methods.

        Parameters:
        cr - The class reference with a valid reference.
        errors - The list of errors that is returned to the caller in case resolving fails.

      • onVirtualizationCompleted

        protected void onVirtualizationCompleted​(IAppSessionGyro appGyro,
                                         IClientSessionGyro clientGyro,
                                         VirtualSpace virtualSpace,
                                         PropCnr virtualizedProp,
                                         boolean isPostResolve)
        Called when virtualization completed.

        This method is called to the entire tree of the newly virtualized property container.

        Overrides:
        onVirtualizationCompleted in class GProp<GProp<?>[]>
        Parameters:
        appGyro - The application gyro instance performing the virtualization.
        clientGyro - The client gyro session, can be null if not initialized from the client gyro.
        virtualSpace - The virtualized VirtualSpace.
        virtualizedProp - The property being virtualized.
        isPostResolve - Flag indicating this call is done after references are attempted to be resolved.

      • onPropDispose

        protected void onPropDispose()
        Called when a property is disposed of by delete/remove in a container, or by the dispose method.

        The Property Container clears the structure of unsent communication requests to clear memory.

        This call is done just at the end of the delete/remove routine in the container, without synchronization.

        During this call, whatever components that e.g. the client needs to disposed of is done.

        Subclasses needing to perform some intelligent operations upon deletion should do it by overloading this method and always call the super.onPropDispose() method.

        Overrides:
        onPropDispose in class PropCnr

      • getTitle

        public java.lang.String getTitle()
        Get the title of the component (i.e. tooltip for mouse hover typically).
        Returns:
        The component title, or null for none.
        See Also:
        getTitlePKS()

      • getTitleKS

        public KString getTitleKS()
        Gets the title of the component as a (Plain) KString (i.e. tooltip for mouse hover typically).

        Note: most components uses PlainKString's but e.g. UIChart supports KString with HTML.

        Returns:
        The component title, or null for none.
        See Also:
        getTitle()

      • getTitlePKS

        public PlainKString getTitlePKS()
        Gets the title of the component as a PlainKString (i.e. tooltip for mouse hover typically).
        Returns:
        The component title, or null for none.
        See Also:
        getTitle()

      • createTitleProp

        protected GProp<?> createTitleProp()
        Creates the title property a StringProp, KStringProp or PlainKStringProp depending on the component.
        Returns:
        A new PlainKStringProp named Atom.TITLE by default, override for other types.

      • setTitle

        public boolean setTitle​(java.lang.String str)
        Get the title of the component (i.e. tooltip for mouse hover typically). Sets the component title.
        Parameters:
        str - The title.
        Returns:
        true for value changed, false for no change.

      • setTitle

        public boolean setTitle​(KString str)
        Get the title of the component (i.e. tooltip for mouse hover typically). Sets the component title.

        Note: only a few components like UIChart supports KString's with HTML, so this method might fail if you attempt to set a KString with HTML type on e.g. a UILabel.

        Parameters:
        str - The KString title.
        Returns:
        true for value changed, false for no change.

      • setTitle

        public boolean setTitle​(PlainKString str)
        Get the title of the component (i.e. tooltip for mouse hover typically). Sets the component title.
        Parameters:
        str - The plain KString title.
        Returns:
        true for value changed, false for no change.