Package com.luciad.view

Class ALcdLabelLocations

java.lang.Object
com.luciad.view.ALcdLabelLocations
Direct Known Subclasses:
TLcdLabelLocations
public abstract class ALcdLabelLocations extends Object

ALcdLabelLocations is the central place where information is kept about the position of labels and whether or not they were drawn. It is specific to a single ILcdLayer, for example a ILcdGXYEditableLabelsLayer. Refer to the documentation of that class how this information is used in other classes.

For a single label, this information is updated and retrieved using the methods putLabelLocation and getLabelLocationSFCT respectively. It is also possible to consult all stored label location information using the methods applyOnAllLabelLocations and applyOnPaintedLabelLocations

It is up to the implementation of this class how this information is stored. One implementation may store the information inside the domain objects, while another implementation may store this information external to the domain object in some sort of a map.

All classes that contain label painting logic, such as the implementations of ILcdGXYLayer, ILcdGXYLayerLabelPainter and ILcdGXYViewLabelPainter, must inform this information store on which labels have been painted.

Implementations can use TLcdLabelLocationEventSupport to facilitate the handling of events.

Since:
7.0
See Also:

  • Constructor Details

    • ALcdLabelLocations

      public ALcdLabelLocations()

  • Method Details

    • addLabelLocationListener

      public abstract void addLabelLocationListener(ILcdLabelLocationListener aListener)
      Adds the specified listener to this information store. This listener will be notified of changes in the label information.
      Parameters:
      aListener - The listener that should be informed when there are changes in the label information.
      See Also:

    • removeLabelLocationListener

      public abstract void removeLabelLocationListener(ILcdLabelLocationListener aListener)
      Removes the specified listener. This listener will no longer be notified of changes in the label information.
      Parameters:
      aListener - The listener to remove.

    • addLabelPaintedListener

      public abstract void addLabelPaintedListener(ILcdLabelPaintedListener aListener)
      Adds the specified listener to this information store. The listener will be notified of changes in the label painted status with a TLcdLabelPaintedEvent.
      Parameters:
      aListener - The listener that should be informed when there are changes in the painted status of a label.
      See Also:

    • removeLabelPaintedListener

      public abstract void removeLabelPaintedListener(ILcdLabelPaintedListener aListener)
      Removes the specified listener. This listener will no longer be notified of changes in the painted label information.
      Parameters:
      aListener - The listener to remove.

    • fireCollectedChanges

      public abstract void fireCollectedChanges(ILcdView aView)

      Informs the label location listeners of the changes that were collected in putLabelLocation. These changes were only collected when the aEventMode parameter of this method was ILcdFireEventMode#FIRE_LATER.

      The queue of collected changes is empty when this method returns.

      Parameters:
      aView - The ILcdView for which to fire the collected changes.
      See Also:

    • putLabelLocation

      public abstract void putLabelLocation(Object aObject, int aLabelIndex, int aSubLabelIndex, ILcdView aView, TLcdLabelLocation aLocation, int aFireEventMode)

      Stores the given information so it can be retrieved later on.

      This method also allows to remove the information: just let the TLcdLabelLocation be null.

      If you specify ILcdFireEventMode#FIRE_LATER for aEventMode, you must either call fireCollectedChanges(ILcdView) sometime afterward or call this method with ILcdFireEventMode#FIRE_NOW as event mode. This allows you to make multiple changes to the label locations and inform the listeners afterward in one go, which can be more efficient than informing them at each change.

      Before storing the given label location, one should make sure that the bounds of the parent label are set (see TLcdLabelLocation.setParentBounds(java.awt.Rectangle, double). Examples of code that should do this are the label placer (see ILcdGXYViewLabelPlacer), the label editor, or other code that manually adjusts offset labels.

      *
      Parameters:
      aObject - The domain object to which this label information applies. This object should be contained in the ILcdModel of the associated ILcdLayer
      aLabelIndex - The label to which this label information applies.
      aSubLabelIndex - The sub label to which this label information applies.
      aView - The view for which the location applies.
      aLocation - The label information. No reference to this object is kept within the implementations of this class. This allows the client of this class to reuse the same object. If this location is null, any label information already present in this instance about the given domain object, label index and sublabel index is removed from this class.
      aFireEventMode - A code indicating if and when the listeners should be informed of this change. This code should be one of ILcdFireEventMode.FIRE_NOW, ILcdFireEventMode.FIRE_LATER or ILcdFireEventMode.NO_EVENT
      See Also:

    • getLabelLocationSFCT

      public abstract boolean getLabelLocationSFCT(Object aObject, int aLabelIndex, int aSubLabelIndex, ILcdView aView, TLcdLabelLocation aLocationSFCT)
      Retrieves the label location information of the specified label and puts that information in aLocationSFCT. The return value indicates whether or not the requested information was available in this store.

      aObject should be contained in the ILcdModel of the ILcdLayer to which this ALcdLabelLocations belongs.

      Parameters:
      aObject - The domain object for which you want to retrieve the label location information.
      aLabelIndex - The label for which you want to retrieve the label location information.
      aSubLabelIndex - The sub label for which you want to retrieve the label location information.
      aView - The view for which the location is retrieved.
      aLocationSFCT - The TLcdLabelLocation instance that will be updated with the label location information. It is up to the implementation of this class to decide what happens when the information was not available. One should use createLabelLocation to create a valid instance for this parameter.
      Returns:
      true if the requested label location information was available, false otherwise.

    • getDefaultLabelLocationSFCT

      public void getDefaultLabelLocationSFCT(Object aObject, int aLabelIndex, int aSubLabelIndex, ILcdView aView, TLcdLabelLocation aLocationSFCT)
      Retrieves the default label location information of the specified label and puts that information in aLocationSFCT.

      aObject should be contained in the ILcdModel of the ILcdLayer to which this ALcdLabelLocations belongs.

      Parameters:
      aObject - The domain object for which you want to retrieve the label location information.
      aLabelIndex - The label for which you want to retrieve the label location information.
      aSubLabelIndex - The sub label for which you want to retrieve the label location information.
      aView - The view for which the location is retrieved.
      aLocationSFCT - The TLcdLabelLocation instance that will be updated with the default label location information. One should use createLabelLocation to create a valid instance for this parameter.

    • applyOnAllLabelLocations

      public abstract void applyOnAllLabelLocations(ILcdView aView, ALcdLabelLocations.LabelLocationFunction aLabelLocationFunction)

      Iterates over all stored label locations by calling applyOnLabelLocation for every label location.

      If applyOnLabelLocation returns true, the iteration continues, if it returns false the iteration is aborted.

      Parameters:
      aView - Iterate over the labels for this view.
      aLabelLocationFunction - The label iterator. This label iterator contains the logic of what to do with each label.

    • applyOnPaintedLabelLocations

      public abstract void applyOnPaintedLabelLocations(ILcdView aView, ALcdLabelLocations.LabelLocationFunction aLabelLocationFunction)

      Iterates over all label locations for the labels that were painted by calling applyOnLabelLocation for every painted label location. The iteration order is preferably the order in which they were marked as painted.

      If applyOnLabelLocation returns true, the iteration continues, if it returns false the iteration is aborted.

      Parameters:
      aView - Iterate over the labels painter for this view.
      aLabelLocationFunction - The label iterator. This label iterator contains the logic of what to do with each label.

    • fireCollectedLabelPaintedChanges

      public abstract void fireCollectedLabelPaintedChanges(ILcdView aView)

      Informs the listeners registered using addLabelPaintedListener(ILcdLabelPaintedListener) of the changes that were collected in setPainted(Object, int, int, ILcdView, boolean, int) and clearAllPainted(ILcdView, int). These changes were only collected when the aEventMode parameter of this method was ILcdFireEventMode#FIRE_LATER.

      The queue of collected changes is empty when this method returns.

      Parameters:
      aView - The ILcdView for which to fire the collected changes.
      See Also:

    • setPainted

      public abstract void setPainted(Object aObject, int aLabelIndex, int aSubLabelIndex, ILcdView aView, boolean aPainted, int aFireEventMode)

      Marks the specified label as painted or not painted according to aPainted.

      All code that paints a label should call this method when they actually paint a label. For instance implementations of ILcdGXYEditableLabelsLayer, ILcdGXYLayerLabelPainter and ILcdGXYViewLabelPainter should call this method when they paint a label.

      Parameters:
      aObject - The domain object for which the label was painted.
      aLabelIndex - The label index of the label that was painted.
      aSubLabelIndex - The sub label index of the label that was painted.
      aView - Mark the label painted or not painted on this view, according to aPainted.
      aPainted - Whether or not the label should be marked as painted.
      aFireEventMode - A code indicating if and when the listeners should be informed of this change. This code should be one of ILcdFireEventMode.FIRE_NOW, ILcdFireEventMode.FIRE_LATER or ILcdFireEventMode.NO_EVENT
      See Also:

    • isPainted

      public abstract boolean isPainted(Object aObject, int aLabelIndex, int aSubLabelIndex, ILcdView aView)
      Returns whether or not the specified label is currently painted.
      Parameters:
      aObject - The domain object
      aLabelIndex - The label index of the label for which you want to know if it was painted.
      aSubLabelIndex - The sub label index of the label for which you want to know if it was painted.
      aView - The view for which we want to know if the label was painted on it.
      Returns:
      Whether or not the specified label was marked as painted for the given ILcdView.
      See Also:

    • clearAllPainted

      public abstract void clearAllPainted(ILcdView aView, int aFireEventMode)
      Clears the painted status of all labels for the given ILcdView. This is typically done right before a layer (or layer label painter or view label painter etc) starts painting the labels.
      Parameters:
      aView - The view for which to clear all painted labels, or null to clear the status for all views.
      aFireEventMode - A code indicating if and when the listeners should be informed of this change. This code should be one of ILcdFireEventMode.FIRE_NOW, ILcdFireEventMode.FIRE_LATER or ILcdFireEventMode.NO_EVENT

    • getLayer

      public abstract ILcdLayer getLayer()
      Returns the layer to which this ALcdLabelLocations instance belongs.
      Returns:
      The layer to which this ALcdLabelLocations instance belongs.

    • createLabelLocation

      public abstract TLcdLabelLocation createLabelLocation()
      Creates a new instance of (an extension of) TLcdLabelLocation. Use this method to have a working TLcdLabelLocation instance that can for example be passed to getLabelLocationSFCT.
      Returns:
      A new TLcdLabelLocation instance.
      See Also: