Package com.iizix.prop.ui

Class UIComp

java.lang.Object
com.iizix.prop.GProp<GProp<?>[]>
com.iizix.prop.PropCnr
com.iizix.prop.ui.UIComp
All Implemented Interfaces:
EventListener, IMessageBox, IComponent, ICustomDataProvider, IGProp<GProp<?>[]>, IPropCnr, IUIComp, IVSComponentListener, IVSComponentState, IVSFieldListener, Cloneable
Direct Known Subclasses:
AbstractUIAction, CalendarEvent, MapMarkerProp, MUISwitch, UIAbstractListChoice, UICalendar, UIChart, UICheckBox, UICheckedMenuItem, UIContainer, UIDateTime, UIEmpty, UIGauge, UIImage2, UILabel, UIMedia, UIMenuSeparator, UIOutput, UIProgress, UIRadioButton, UIRadioMenuItem, UISlider, UITableColumn, UIText
public abstract class UIComp extends PropCnr implements IUIComp
The UIComp class is the basic implementation of a single user interface component.

The component has a data container that is not persistent, i.e. is not written e.g. to disk.

Author:
Christopher Mindus

  • Field Details

    • REMOTE_FOCUS_EVENT

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

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

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

    • initPropCnr

      protected final void initPropCnr()
      Method called at the earliest possible stage in the constructor of a container property or it's extending classes, before possible initialization of other properties, etc.

      UI components use the named property hash map for lookup of properties fast.

      Overrides:
      initPropCnr in class PropCnr

    • 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 Map<String,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.

    • getUIPanel

      public final UIPanelBase getUIPanel()
      Gets the UIPanel.
      Specified by:
      getUIPanel 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:
      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:
      IllegalStateException - If called outside of the Designer.

    • getApproximateSize

      public abstract Size getApproximateSize() throws 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:
      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(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 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(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(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(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 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.

    • onStateChanged

      public void onStateChanged(VSField field, IVSComponentState.State state, boolean on)
      Called when the field changes state.
      Specified by:
      onStateChanged in interface IVSFieldListener
      Parameters:
      field - The VS field.
      state - The state change.
      on - New state.

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

    • exitVSProcessing

      public final void exitVSProcessing()
      Call this routine to exit VSField processing routine that was entered using enterVSProcessing(VSComponent).
      Throws:
      InternalError - If the enterVSProcessing(VSComponent) wasn't called.

    • 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 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 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, 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 String getErrorMessageStringEx(ILocaleString localeString, 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(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 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(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(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 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(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 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 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 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 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 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 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 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 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 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, 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, List<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, List<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.

    • invokeOnUICreateTree

      protected void invokeOnUICreateTree(UIPanelBase panel)
      Invokes the onUICreate method for the component if a panel is present. This method should only be invoked when a component is resolved during the post-resolve virtualization process, or when a component is added into an already virtualized UI component tree.

      The onUICreate method is called first for the parents, then its children recursively.

      Parameters:
      panel - The panel in which the component is a child of (or the panel itself).
      Throws:
      NullPointerException - If the panel is null.

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

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

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

    • 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(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.