Package com.iizix.prop.content

Class AbstractContentUIContainer<ITEM extends IContentItem,ITEM_CONTENT extends IContentData<ITEM>>

java.lang.Object
com.iizix.prop.GProp<GProp<?>[]>
com.iizix.prop.PropCnr
com.iizix.prop.ui.UIComp
com.iizix.prop.ui.UIContainer
com.iizix.prop.content.AbstractContentUIContainer<ITEM,ITEM_CONTENT>
All Implemented Interfaces:
IBackReferenceProvider, EventListener, IFocusComp, IMessageBox, IComponent, ICustomDataProvider, IGProp<GProp<?>[]>, IPropCnr, IUIActionHolder, IUIComp, IUIContainer, IUIContextMenuOwner, IUIFocusComp, IUIIndexedSelectionComp, IUISelectionComp, IUISingleIndexedSelectionComp, IVSColumnBestValueListener, IVSComponentListener, IVSComponentState, IVSFieldListener, IVSGenericComponentListener, IVSTableColumnReferenceOwner, IVSTableListener, Cloneable
Direct Known Subclasses:
MapMarkers, MLGroup
public abstract class AbstractContentUIContainer<ITEM extends IContentItem,ITEM_CONTENT extends IContentData<ITEM>> extends UIContainer implements IVSTableListener, IVSTableColumnReferenceOwner, IVSColumnBestValueListener, IUISingleIndexedSelectionComp, IUIActionHolder
A property container that handles content and has custom content provider support. The container can contain only a specific class of items in a PropCnr. It implements single, multiple selection or has no selection at all.
Author:
Christopher Mindus

  • Field Details

    • TABLE_REF_PROP_NAME

      public static final String TABLE_REF_PROP_NAME
      Property name for VSTableReference.
      See Also:

    • USE_CONTENT_PROVIDER_PROP_NAME

      public static final String USE_CONTENT_PROVIDER_PROP_NAME
      Property name for the setting of "use content provider" (defaults to "false").
      See Also:

    • PN_SELECTION_TYPE

      protected static final String PN_SELECTION_TYPE
      The property name: selection type "selType".
      See Also:

  • Constructor Details

    • AbstractContentUIContainer

      public AbstractContentUIContainer()
      Creates the content property container.

    • AbstractContentUIContainer

      public AbstractContentUIContainer(Atom atom)
      Creates the content property container.
      Parameters:
      atom - The atom name.

  • Method Details

    • getPredefinedProps

      public void getPredefinedProps()
      Gets potential references to predefined properties for this container. This method is called once just after cloning of the property container.

      The method should get reference to using the getProp(...) methods. This allows the subclass to be able to retrieve the new instances to the properties created during addPredefinedProps() if stored in instance variables.

      Subclasses must override this method to do the appropriate initialization, as this method does nothing for the PropCnr class implementation.

      Overrides:
      getPredefinedProps in class UIContainer

    • equalsTree

      protected Object equalsTree(PropCnr pc2, int how)
      Checks for equality in the whole container structure.

      NOTE: This method should not be overridden except in extreme situations, e.g. for MememtoPropCnr.

      Overrides:
      equalsTree in class PropCnr
      Parameters:
      pc2 - The property value to compare with.
      how - Flags EQC_* values for equal checking.
      Returns:
      Both atom and value are equal on all levels.

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

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

    • getOnUISelectionMethod

      public final Method getOnUISelectionMethod()
      Returns the method to use for onUISelection notifications that is attached to this selection component. The method name is not important, but must have the annotation and signature:

      @OnUISelection(name = "some/property")
      public void onUISelection(UISelectionEvent event)

      Specified by:
      getOnUISelectionMethod in interface IUISelectionComp
      Returns:
      The method, or null if none is registered.

    • getOnUIActionMethod

      public final Method getOnUIActionMethod()
      Gets the method for the OnUIAction event at runtime. The method can be stored in another instance, e.g. a group holding multiple action items.
      Specified by:
      getOnUIActionMethod in interface IUIActionHolder
      Returns:
      The method for OnUIAction event, null for none.

    • isBackReferenceValid

      public String isBackReferenceValid(AnnotationType annotationType, String name, boolean isRefOnly)
      Validates if the back-reference specified is referenced in the first place, i.e. is valid or not.
      Specified by:
      isBackReferenceValid in interface IBackReferenceProvider
      Parameters:
      annotationType - The annotation type.
      name - The class or method name.
      isRefOnly - Flag indicating the back reference is not required, but must be valid otherwise.
      Returns:
      null for valid, otherwise an error message.

    • clone

      public AbstractContentUIContainer<ITEM,ITEM_CONTENT> clone()
      Clones this instance.
      Overrides:
      clone in class UIContainer
      Returns:
      The new cloned instance.

    • onVirtualizationCompleted

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

      Overriding classes must call super.onVirtualizationCompleted(IAppSessionGyro appGyro,IClientSessionGyro clientGyro,VirtualSpace virtualSpace,boolean isPostResolve) if they override this method.

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

      Overrides:
      onVirtualizationCompleted in class PropCnr
      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.
      isPostResolve - Flag indicating this call is done after references are attempted to be resolved.

    • onPropParentChanged

      protected void onPropParentChanged(PropCnr oldParent, PropCnr newParent)
      Called when the parent is changed for this class. The default implementation does nothing and must be overridden by subclasses.
      Overrides:
      onPropParentChanged in class GProp<GProp<?>[]>
      Parameters:
      oldParent - The old parent (or null if none).
      newParent - The new parent (or null if none).

    • onPropDispose

      protected void onPropDispose()
      Called when disposed of.
      Overrides:
      onPropDispose in class UIComp

    • onEventSelf

      public void onEventSelf(GEvent event)
      Event checking to clear cache.
      Specified by:
      onEventSelf in interface IGProp<ITEM extends IContentItem>
      Overrides:
      onEventSelf in class UIComp
      Parameters:
      event - The property event.

    • onItemAdded

      protected void onItemAdded(ITEM item)
      Item added event.

      Subclasses can implements its routine to initialize the required object that governs the API behavior of the property.

      Do not forget to FIRST call the super.onItemAdded(item) if overridden.

      Parameters:
      item - The item added.

    • onItemRemoved

      protected void onItemRemoved(ITEM item)
      Item removed event.

      Subclasses can implements its routine to clean-up a potentially required object that governs the API behavior of the property.

      Do not forget to FIRST call the super.onItemRemoved(item) if overridden.

      Parameters:
      item - The item removed.

    • getItems

      public ITEM[] getItems()
      Gets the container items.
      Returns:
      A cached array of items, DO NOT MODIFY the array.

    • refresh

      public void refresh()
      This method is called from any thread to trigger a refresh of the contents of all the container items. This method should be also be called when the item count has changed.

    • refresh

      public void refresh(ITEM_CONTENT item)
      This method is called from any thread when an item property container has been changed.
      Parameters:
      item - The item to refresh.

    • getVSTableReferenceOwnerData

      public VSReferenceOwnerData<VSTable,VSTableReference> getVSTableReferenceOwnerData()
      Gets the table reference owner data for the table column reference.
      Specified by:
      getVSTableReferenceOwnerData in interface IVSTableColumnReferenceOwner
      Returns:
      The VSReferenceOwnerData instance, always non-null.

    • getVSTable

      public final VSTable getVSTable()
      Gets the VSTable.
      Returns:
      The table for the reference, or null if not found.

    • getVSTable

      public final VSTable getVSTable(VSTableColumnReference ref)
      Gets the VSTable for a VSTableColumnReference instance.
      Specified by:
      getVSTable in interface IVSTableColumnReferenceOwner
      Parameters:
      ref - The reference instance, null when property-editing the reference in the Designer.
      Returns:
      The table for the reference, or null if not found.

    • getContentTable

      public VSTable getContentTable()
      Gets the VS table that is associated with the container to provide the items.
      Returns:
      The table connected, or null for none.

    • getContentTableColumns

      public int[] getContentTableColumns()
      Gets the connected VS table columns in the table.
      Returns:
      The array of VS table column indicies, or null if a content provider is not used. Note that an instance in the array may be -1 if not connected.

      Note: this array is cached AND SHOULD NOT BE MODIFIED.

    • onResolved

      public void onResolved(VSRelativeReference<?> reference, VSTable table)
      Called when the property reference has been resolved. UI components use this method to set its state according to the field.
      Specified by:
      onResolved in interface IVSTableListener
      Parameters:
      reference - The VSRelativeReference instance holding the reference.
      table - The target reference.

    • onBroken

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

    • onStateChanged

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

    • onSingleSelectionChanged

      public void onSingleSelectionChanged(VSTable table, int index)
      Called when the single selection changes.
      Specified by:
      onSingleSelectionChanged in interface IVSTableListener
      Parameters:
      table - The table.
      index - The row index, -1 if table is unselected.

    • onParentStateChanged

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

    • onRowAdded

      public void onRowAdded(VSRow row, int index)
      Called when a row is added.
      Specified by:
      onRowAdded in interface IVSTableListener
      Parameters:
      row - The row.
      index - The index.

    • onRowRemoved

      public void onRowRemoved(VSRow row, int index)
      Called when a row is removed.
      Specified by:
      onRowRemoved in interface IVSTableListener
      Parameters:
      row - The row.
      index - The index.

    • onRowStateChanged

      public void onRowStateChanged(VSRow row, IVSComponentState.State state, boolean on)
      Called when a row selection state changed.
      Specified by:
      onRowStateChanged in interface IVSTableListener
      Parameters:
      row - The row.
      state - The state change.
      on - New state.

    • onCellStateChanged

      public void onCellStateChanged(VSField cell, IVSComponentState.State state, boolean on)
      Called when the cell changes state.

      Subclasses may override this method to not perform the default action, i.e. to call refresh(REFRESH_CONTENTS) and perform a more efficient update of the VSField updated cell state.

      Specified by:
      onCellStateChanged in interface IVSTableListener
      Parameters:
      cell - The VS cell.
      state - The state change.
      on - New state.

    • onCellValueChanged

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

      Subclasses may override this method to not perform the default action, i.e. to call refresh(REFRESH_CONTENTS) and perform a more efficient update of the VSField cell updated.

      Specified by:
      onCellValueChanged in interface IVSTableListener
      Parameters:
      cell - 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.

    • getBestVSColumnHeaderValueType

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

    • useContentProvider

      public boolean useContentProvider()
      Returns the flag to use the content provider.
      Returns:
      true if the content provider is used with API or VirtualSpace support, false if items are as defined in the Designer.

    • setContentProvider

      public boolean setContentProvider(IContentProvider<ITEM,ITEM_CONTENT> customContentProvider)
      Sets a custom content provider to be used. A full refresh will automatically be done.
      Parameters:
      customContentProvider - The custom content provider.
      Returns:
      true for success, false if content provider support is not enabled for the container due to the settings, or the same content provider is set twice.

    • getItemCount

      public int getItemCount()
      Returns the item count.
      Returns:
      The current count of items.

    • getItem

      public ITEM getItem(int index)
      Gets an item at specified index.
      Parameters:
      index - The index of the item property.
      Returns:
      The property at specified index, null if not found.

    • createContentProvider

      protected IContentProvider<ITEM,ITEM_CONTENT> createContentProvider()
      Creates the content provider.
      Returns:
      The created content provider.

    • getContentProvider

      protected IContentProvider<ITEM,ITEM_CONTENT> getContentProvider()
      Gets the or created content provider to use.
      Returns:
      A content provider, custom if defined and successfully created.

    • getVSColumnIndex

      protected int getVSColumnIndex(Object nameOrAtom)
      Gets the table column reference property with the String or Atom. This call makes it possible to redirect the reference into another container, e.g. for the MList default item. By default, the property is taken from this container.
      Parameters:
      nameOrAtom - The String name or Atom name.
      Returns:
      The VS table column index found, or -1 for none.

    • hasDiscreteContentChanges

      public boolean hasDiscreteContentChanges(boolean reset)
      Flag for contents changes for API when content provider is using discrete components added by the user.
      Parameters:
      reset - Flag to reset changes.
      Returns:
      true if the contents array is changes since last call (that was reset), false otherwise.

    • getAPIContentProvider

      public IContentProviderAPI<ITEM,ITEM_CONTENT> getAPIContentProvider()
      Gets the content provider for the API.
      Returns:
      The content provider, or null if API is not supported or none is set.

    • refresh

      protected final void refresh(int dirty)
      Requests a refresh of the contents depending on the flag.

      This method is called e.g. when a new column is added to rebuild the table contents. Be careful when calling this method as it may cause a lot of processing at a later stage, triggering new contents to be sent to the client side. The content is not refreshed upon returning from the call, it is done at a later stage.

      Parameters:
      dirty - The dirty flags.

    • update

      protected void update()
      Called to update the contents if required with new data. The method does nothing if e.g. a call to refresh(int) hasn't been called.

    • isUpdatingInCurrentThread

      public boolean isUpdatingInCurrentThread(boolean refreshVS)
      Checks if the current thread is currently in updates mode (with updates from VS).
      Parameters:
      refreshVS - Flag indicating only VS refreshing must be tested, not other changes in e.g. the UI.
      Returns:
      true If updates are currently being done, false otherwise.

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

      Overrides:
      addMappings in class UIComp
      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.

    • addMappingsTable

      protected void addMappingsTable(String uiRef, VSMappings mappings, VSComponent vsStateFocus)
      Gets the VSTable mappings of a VirtualSpace to the panel components. Override this method to add mappings when the contents is connected to a table and the items are perhaps not yet created.

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

      Parameters:
      uiRef - The reference property name of "uiComp", null if not yet retrieved.
      mappings - The mappings instance to fill in.
      vsStateFocus - Do not go past this component when going up in the parent tree, null for none.

    • isEmptyContainerAllowed

      public boolean isEmptyContainerAllowed()
      Returns whether the container should have children in a normal conditions, i.e. a warning message should be displayed in the Designer when it is empty. This is intended to be used to avoid use of empty containers. Some containers, e.g. the mobile heading is allowed to be empty.
      Overrides:
      isEmptyContainerAllowed in class UIContainer
      Returns:
      true if a VS table is connected and the content provider is set, false otherwise.

    • verify

      public boolean verify(PropVerification verification)
      Verifies this property container. The check performed is the extension of classes and that no circular reference is present.
      Specified by:
      verify in interface IGProp<ITEM extends IContentItem>
      Overrides:
      verify in class UIContainer
      Parameters:
      verification - The property verification class.
      Returns:
      true if verification should proceed, false if disposed of and verification should not take place.

    • getItemClass

      public abstract Class<ITEM> getItemClass()
      Return the class of items stored in the container.
      Returns:
      The property container class for items.

    • getItemContentClass

      public abstract Class<ITEM_CONTENT> getItemContentClass()
      Return the class of content items stored in the container.
      Returns:
      The property container class for content items.

    • createItem

      protected abstract ITEM createItem(Atom atom, ITEM_CONTENT data)
      Creates a new property item from an item data holder and initializes the property.
      Parameters:
      atom - The name of the item property.
      data - The data to initialize the item property with.
      Returns:
      The item property.

    • createDefaultContentProvider

      protected abstract IContentProvider<ITEM,ITEM_CONTENT> createDefaultContentProvider()
      Creates and returns a new instance of a default content provider.
      Returns:
      The default content provider to use.

    • getContentTableColumnReferenceNames

      protected abstract Object[] getContentTableColumnReferenceNames()
      Gets the atoms of the references that are used to specify the VS column header connections for the VS table.
      Returns:
      The array of atoms or Strings.

    • getBestVSColumnHeaderValueTypes

      protected abstract Value.Type[] getBestVSColumnHeaderValueTypes()
      Gets the value type that would best suit the for the columns.
      Returns:
      null if none is available.

    • getSelectionPropAtom

      public Atom getSelectionPropAtom()
      Returns the selection property atom for verification of selection changes.

      This method is used by the framework in UIComp to fire selection events when the property value changes.

      Specified by:
      getSelectionPropAtom in interface IUISelectionComp
      Returns:
      null, as the selection property is not property based.

    • getSelectionListenerHandler

      public GenericListener<IUISelectionListener> getSelectionListenerHandler(boolean doCreate)
      Returns the generic selection listener.
      Specified by:
      getSelectionListenerHandler in interface IUISelectionComp
      Parameters:
      doCreate - Create the listener handler if it doesn't exist, false not to.
      Returns:
      The selection listener handler, or null if not created.

    • add

      public void add(ITEM_CONTENT item)
      Adds a new item to the end of the list. Duplicates are not allowed.
      Parameters:
      item - The item to insert.
      Throws:
      IllegalStateException - When the VirtualSpace is connected and changes must be done from there and not by means of API functions, or if the item already is present in the list. This exception is also thrown if the content provider is not used or does not support API usage.

    • add

      public void add(int index, ITEM_CONTENT item)
      Inserts a new item before the specified index. Duplicates are not allowed.
      Parameters:
      index - The insertion point index, -1 for last.
      item - The item to insert.
      Throws:
      IndexOutOfBoundsException - If the index is not valid.
      IllegalStateException - When the VirtualSpace is connected and changes must be done from there and not by means of API functions, or if the item already is present in the list. This exception is also thrown if the content provider is not used or does not support API usage.

    • remove

      public ITEM_CONTENT remove(int index)
      Removes an item at the specified index.
      Parameters:
      index - The item to remove.
      Returns:
      The removed item, null if a content provider is not present.
      Throws:
      IndexOutOfBoundsException - If the index is not valid.
      IllegalStateException - When the VirtualSpace is connected and changes must be done from there and not by means of API functions. This exception is also thrown if the content provider is not used or does not support API usage.

    • remove

      public boolean remove(ITEM_CONTENT item)
      Removes an item.
      Parameters:
      item - The item to remove.
      Returns:
      true for success, false if not found.
      Throws:
      IllegalStateException - When the VirtualSpace is connected and changes must be done from there and not by means of API functions. This exception is also thrown if the content provider is not used or does not support API usage.

    • removeAll

      public boolean removeAll()
      Removes all items.
      Returns:
      true for changed, false when no items were present.
      Throws:
      IllegalStateException - When the VirtualSpace is connected and changes must be done from there and not by means of API functions. This exception is also thrown if the content provider is not used or does not support API usage.

    • get

      public ITEM_CONTENT get(int index)
      Gets an item at the specified index.
      Parameters:
      index - The index of the item.
      Returns:
      The item.
      Throws:
      IndexOutOfBoundsException - If the index is not valid.
      IllegalStateException - When the VirtualSpace is connected and changes must be done from there and not by means of API functions. This exception is also thrown if the content provider is not used or does not support API usage.

    • getAll

      public ITEM_CONTENT[] getAll()
      Gets all items.
      Returns:
      The array of items.
      Throws:
      IllegalStateException - This exception is also thrown if the content provider is not used.

    • indexOf

      public int indexOf(ITEM_CONTENT item)
      Returns the index of an item.
      Parameters:
      item - The item to look-up.
      Returns:
      The index of the item, or -1 if not found.
      Throws:
      IllegalStateException - When the VirtualSpace is connected and changes must be done from there and not by means of API functions.

    • getSelectionType

      public int getSelectionType()
      Gets the selection type of the component.
      Specified by:
      getSelectionType in interface IUISelectionComp
      Returns:
      A value indicating the selection capability as the SELECTION_TYPE_* values define.

    • 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).
      Overrides:
      onSelectionChanged in class UIContainer
      Parameters:
      event - The event that causes the selection change.

    • onSelectionChanged

      public void onSelectionChanged(ITEM_CONTENT item, boolean on)
      Callback when an item is selected or unselected.

      This method should not be called! It is intended for the frameworks item setSelection(boolean) method.

      Parameters:
      item - The item who's selection state changed.

    • isSelected

      public boolean isSelected()
      Returns the selection of state of the component.

      For a multiple-selection capable component, this indicates any selection, i.e. true is returned as soon as at least one element is selected, false for none.

      The checkbox for example has two "selected states": checked and third state: in this case, true is returned for the third state as well as the checked state.

      Specified by:
      isSelected in interface IUISelectionComp
      Returns:
      true if the component is selected, false otherwise.

    • getSelectedIndex

      public int getSelectedIndex()
      Gets the first selected index.
      Specified by:
      getSelectedIndex in interface IUISingleIndexedSelectionComp
      Returns:
      The first index in the current selection, or -1 for none.

    • getSelectedIndicies

      public int[] getSelectedIndicies()
      Gets the selected indicies.
      Specified by:
      getSelectedIndicies in interface IUIIndexedSelectionComp
      Specified by:
      getSelectedIndicies in interface IUISingleIndexedSelectionComp
      Returns:
      A new array of the selected indices (that may be modified to your liking), or a static zero in length array for no selection.

    • getSelection

      public IUISelection getSelection()
      Gets the current selection of the component.
      Specified by:
      getSelection in interface IUISelectionComp
      Returns:
      The current selection of the component.

    • setSelection

      public String setSelection(int index)
      Sets the selection as a single selected item at specified index.
      Specified by:
      setSelection in interface IUIIndexedSelectionComp
      Parameters:
      index - The single item to select at index, negative value to clear the selection.
      Returns:
      null for success, otherwise an error message why the selection failed.

    • clearSelection

      public String clearSelection()
      Clear the selection.
      Specified by:
      clearSelection in interface IUIIndexedSelectionComp
      Returns:
      null for OK.