Package com.luciad.view.lightspeed.controller.manipulation

Class ALspInteractiveLabelProvider

java.lang.Object
com.luciad.view.lightspeed.controller.manipulation.ALspInteractiveLabelProvider
public abstract class ALspInteractiveLabelProvider extends Object

An ALspInteractiveLabelProvider can provide a java.awt.Component that can be shown to the user so he can modify the properties of the object. One can think of this Component as a rich, interactive label.

This provider is used by TLspInteractiveLabelsController to provide an interactive label when the user moves his mouse cursor over one of its labels. This provider is asked if it can provide a Component for the label with the canStartInteraction method, and if it can it is then asked to provide Component for it with the startInteraction method.

At all times there will be at most one interactive label active from a single ALspInteractiveLabelProvider. This means implementations can return the same java.awt.Component instance every time they are asked to provide an interactive label.

Between two calls to startInteraction, the label interaction will always be stopped, either with stopInteraction or otherwise with cancelInteraction.

When it is needed to update an interactive labels during interaction, it is possible to adjust the interactive label returned by startInteraction. For example when an interactive label contains a field with the location of its (moving) object, this label can be updated by registering a model listener, listening to changes, and adjusting the location text field when needed.

After modifying the interactive label during interaction, it is possible that its size has changed. Implementations of this class should send a notification of this. This can be done by calling fireInteractiveLabelChangedEvent. To make sure that interactive labels are properly updated because of a model change, updateInteractiveLabel() is called. The implementation of this call should make sure that interactive labels are properly updated, and that a change event if fired.

Since:
2012.0
See Also:

  • Constructor Details

    • ALspInteractiveLabelProvider

      public ALspInteractiveLabelProvider()

  • Method Details

    • canStartInteraction

      public abstract boolean canStartInteraction(TLspLabelID aLabel, TLspContext aContext)

      This method determines whether or not this ALspInteractiveLabelProvider can provide a Component for the specified label. This method should be called before calling startInteraction.

      Parameters:
      aLabel - The label for which to determine if a Component can be provided.
      aContext - The context.
      Returns:
      true if this ALspInteractiveLabelProvider can provide a Component for the specified identifier, false otherwise.

    • startInteraction

      public abstract Component startInteraction(TLspLabelID aLabel, TLspContext aContext)

      Returns a component, configured to display or edit the properties of the given view identifier. Before this method is called again, either stopInteraction or cancelInteraction will be called - depending on user interaction - allowing the implementation to perform any necessary cleanup operations.

      This method will not be called unless canStartInteraction returns true for the same arguments.

      Parameters:
      aLabel - The label for which the Component is requested.
      aContext - The context.
      Returns:
      A Component, configured to display or edit the properties of the given label.

    • canStopInteraction

      public abstract boolean canStopInteraction()

      Returns whether or not the interactive label that was last provided can be stopped. For instance, if the interactive label is in a non-valid state, this method should return false.

      Returns:
      true if the interactive label can be stopped, false otherwise.
      See Also:

    • stopInteraction

      public abstract boolean stopInteraction()

      Tells the interactive label that was last provided to stop editing. Any outstanding changes should be persisted when this method is called.

      This method is always called after the call to startInteraction and before the provided component is removed from the user interface.

      This method returns a boolean indicating whether or not the interactive label could be stopped. If the interactive label could not be stopped, this provider could choose to change the interactive label to visually indicate what prevents it from being stopped. For instance, if a text field in the interactive label contained invalid text, the text in the text field could be shown in red.

      This method should return the same value as the canStopInteraction method. The reason that method exists is that that method does not imply that the client actually wants to stop, whereas this method does.

      Returns:
      true if the interactive label could be stopped, false otherwise.
      See Also:

    • cancelInteraction

      public abstract void cancelInteraction()

      Cancels the interaction with the interactive label that was last provided. Any outstanding changes should be discarded when this method is called.

      This method is always called after the call to startInteraction and before the provided component is removed from the user interface.

    • updateInteractiveLabel

      public void updateInteractiveLabel()

      Updates the label while it is interactive. This can for example be needed when the domain object changes. In that case, this method should be overridden. The implementation should:

      • Update the currently interactive label, for example by updating its JLabels or other Swing components.
      • Call super.updateInteractiveLabel() at the end. This will make sure that a change event is fired.

      This method is automatically called by ALspSwingLabelStyler when a model change event occurs for the currently interactive label. Because this method causes a change event to be fired, TLspInteractiveLabelsController is notified as well.

      On the other hand, when a user action (for example a click on a button) causes the interactive label to be changed, this method can be called to make the actual change. Because this method should fire a change event, the styler and the TLspInteractiveLabelsController are notified of the change.

      Since:
      2016.0

    • addLabelInteractionListener

      public void addLabelInteractionListener(ILspInteractiveLabelListener aListener)
      Adds a LabelInteractionListener. This listener should be used to notify when interaction with an interactive label was stopped or cancelled.
      Parameters:
      aListener - a LabelInteractionListener.

    • removeLabelInteractionListener

      public void removeLabelInteractionListener(ILspInteractiveLabelListener aListener)
      Removes the given LabelInteractionListener. After calling this method, the given listener will not be notified when interaction with an interactive label was stopped or cancelled anymore.
      Parameters:
      aListener - a LabelInteractionListener.

    • fireInteractionStartedEvent

      protected final void fireInteractionStartedEvent(TLspLabelID aLabel, TLspContext aContext, Component aInteractiveLabel)
      This method should be called to fire an 'interaction started' event. This method will call all listeners that were registered using addLabelInteractionListener. Implementations should call this method when interaction has started.
      Parameters:
      aLabel - the label.
      aContext - the context.
      aInteractiveLabel - the component used for the interactive label.
      See Also:

    • fireInteractionStoppedEvent

      protected void fireInteractionStoppedEvent()
      This method should be called to fire an 'interaction stopped' event. This method will call all listeners that were registered using addLabelInteractionListener. Implementations should call this method when interaction has stopped.
      See Also:

    • fireInteractionCancelledEvent

      protected void fireInteractionCancelledEvent()
      This method should be called to fire an 'interaction cancelled' event. This method will call all listeners that were registered using addLabelInteractionListener. Implementations should call this method when interaction has been cancelled.
      See Also:

    • addInteractiveLabelChangeListener

      public void addInteractiveLabelChangeListener(ILcdChangeListener aListener)
      Adds a change listener that is notified if an interactive label has changed.
      Parameters:
      aListener - a change listener
      See Also:

    • removeInteractiveLabelChangeListener

      public void removeInteractiveLabelChangeListener(ILcdChangeListener aListener)
      Removes a given change listener.
      Parameters:
      aListener - a change listener
      See Also:

    • fireInteractiveLabelChangedEvent

      protected final void fireInteractiveLabelChangedEvent()
      Fire an event to notify that the interactive label has changed. This can for example be used when the interactive label is modified at runtime.