Package com.luciad.view.lightspeed.style.styler

Class ALspLabelStyleCollector

java.lang.Object
com.luciad.view.lightspeed.style.styler.ALspStyleCollector
com.luciad.view.lightspeed.style.styler.ALspLabelStyleCollector
Direct Known Subclasses:
ALspLabelStyleCollectorWrapper
public abstract class ALspLabelStyleCollector extends ALspStyleCollector

This class is used in combination with an ILspStyler to define the label location details of a group of objects, in addition to styling. It offers the implementer of ILspStyler a variety of methods that can be used to define the location. Users that wish to retrieve the location information for a given object from an ILspStyler need to create a custom extension of this class specific to their needs.

An ALspLabelStyleCollector allows you to configure several labeling aspects:

See ILspStyler for more information. Also note that the ALspStyler or TLspStyler convenience classes can be used to style labels.

Since:
2012.0
See Also:

  • Constructor Details

    • ALspLabelStyleCollector

      protected ALspLabelStyleCollector(Collection<?> aObjectsToStyle)
      Default constructor, the objects to be styled are provided, which allows the collector to do basic error checking.
      Parameters:
      aObjectsToStyle - The collection of objects for which this style collector will be used. This has to be the collection of objects that is passed to ILspStyler.style(Collection, ALspStyleCollector, TLspContext)

  • Method Details

    • isAllLabels

      protected boolean isAllLabels()
      Returns if the style information is specified for all labels of the objects.
      Returns:
      if the style information is specified for all labels of the objects.

    • destroy

      protected void destroy()
      Cleanup method for label location collector. Specific implementations are encouraged to call this method when styling is done. This allows to check whether the collector was used correctly by the ALspLabelStyler.
      Overrides:
      destroy in class ALspStyleCollector

    • getLabels

      protected Collection<Object> getLabels()
      Returns the label sublabel IDs that have been specified for the current set of objects.

      Returns null if the information applies to all labels of the given domain objects.

      Returns:
      A list of sublabel IDs, can be empty if a default sublabel ID can be used.

    • getAnchorLabel

      protected Object getAnchorLabel()
      Returns the sublabel ID of the label to anchor a label to for the current set of labels.
      Returns:
      An anchor object, can be null if the default anchor can be used.

    • getAnchorLabelPaintRepresentation

      protected TLspPaintRepresentation getAnchorLabelPaintRepresentation()
      Returns the paint representation of the label to anchor a label to for the current set of labels.
      Returns:
      An anchor object, can be null if the 'current' anchor can be used.

    • getPriorityProvider

      protected ILspLabelPriorityProvider getPriorityProvider()
      Returns the priority provider that can be used to query the priority of the labels part of this submit() call.
      Returns:
      A priority provider, or null if none was set.

    • getGroup

      protected String getGroup()
      Returns the group ID for the labels part of this submit() call.
      Returns:
      A declutter group ID, or null if none was set.
      See Also:

    • getAlgorithmProvider

      protected ILspLabelingAlgorithmProvider getAlgorithmProvider()
      Returns the labeling algorithm provider that can be used for the labels part of this submit() call.
      Returns:
      An algorithm provider, or null if none was set.

    • geometry

      public ALspLabelStyleCollector geometry(ILcdShape aGeometry)
      Specifies the geometry on which the style should be applied. Preferably, this method should only be used if the domain object uses a unique style, that is different from the style of all other objects.

      The aGeometry argument allows you to specify a particular geometry to which the styling should be applied, that is different from the object itself.

      Example usage:
      myCollector.object(myObject).geometry(myObjectAsILcdPoint).style(myIconStyle).submit()

      For labels, this call specifies a geometry used to calculate the label's position. Use this if the domain object itself is not a shape, or if you need different geometry.

      If not set, the domain object itself is used.

      Exactly how to geometry is used to determine the label location depends on the algorithm itself.

      See also ILspLabelPainter.getAnchorObject.

      Overrides:
      geometry in class ALspStyleCollector
      Parameters:
      aGeometry - The geometry to which the styling should be applied
      Returns:
      this style collector

    • geometry

      public ALspLabelStyleCollector geometry(ALspStyleTargetProvider aStyleTargetProvider)
      Specifies an ALspStyleTargetProvider that should be used to convert objects into a collection of objects on which the style can be applied. This method can be used if multiple objects share the same style.

      The ALspStyleTargetProvider can be used in a number of cases:

      • Styling of objects that do not implement a known interface
      • Styling of particular parts of an object, such as a specific shape in an ILcdShapeList, or a point of a point list.
      • Conversion of the geometry of the object into a geometry that is more appropriate to achieve the desired visualization.

      Example usage:
      myCollector.objects(Arrays.asList(myObject1,myObject2)).geometry(myObjectToPointConverter).style(myIconStyle).submit()

      For labels, this call specifies the geometry used to calculate the label's position. Use this if the domain object itself is not a shape, or if you need different geometry. The object returned by the style target provider must be an ILcdShape or it must have a shape.

      If not set, the domain object itself is used. In the latter case, the domain object must be an ILcdShape or it must have a shape.

      Exactly how to geometry is used to determine the label location depends on the algorithm itself.

      See also ILspLabelPainter.getAnchorObject.

      If the style target provider returns multiple geometries for a label, only the first ILcdShape is used.

      Overrides:
      geometry in class ALspStyleCollector
      Parameters:
      aStyleTargetProvider - The target provider.
      Returns:
      this style collector

    • hide

      public ALspLabelStyleCollector hide()
      Description copied from class: ALspStyleCollector
      Hides the specified objects. A call to this method has to be preceded by a call that specifies objects such as ALspStyleCollector.object(Object) or ALspStyleCollector.objects(Collection).

      Example usage:
      myCollector.object(myObject).hide().submit()

      Overrides:
      hide in class ALspStyleCollector
      Returns:
      This style collector

    • label

      public ALspLabelStyleCollector label(Object aSublabelID)

      Specifies an object that identifies a label for an object. This is necessary for different labels per domain object.

      Notes:

      • This call is optional if you need just one label: a default sublabel ID of "single" will be used.
      • The sublabel ID must be equal for the same label on subsequent styling calls.
      • The sublabel ID must not be equal for different labels on the same domain object.
      • The sublabel ID can be shared between different domain objects.

      A typical usage would be to have a fixed set of different sublabel IDs, for example an enum, or a series of integers.

      Parameters:
      aSublabelID - The sublabel ID
      Returns:
      this style collector

    • object

      public ALspLabelStyleCollector object(Object aObject)
      Specifies a single Object to be styled. Preferably, this method should only be used if the given object uses a unique style, that is different from the style of all other objects.

      Example usage:
      myCollector.object(myILcdPoint).style(myIconStyle).submit()

      The object must be an object that is part of the collection that has been passed as an argument in ILspStyler.style(Collection, ALspStyleCollector, TLspContext).

      Specifying other objects after a call to this method will invalidate the result of this call.

      When you don't call the geometry(ILcdShape) or geometry(ALspStyleTargetProvider) method, this domain object is also used to retrieve the shape to which the labels is anchored. The domain object must then be an ILcdShape or it must have a shape.

      Overrides:
      object in class ALspStyleCollector
      Parameters:
      aObject - The object to style.
      Returns:
      this style collector

    • objects

      public ALspLabelStyleCollector objects(Collection<?> aObjects)
      Specifies a collection of objects to be styled. This method can be used if multiple objects share the same style.

      Example usage:
      myCollector.objects(Arrays.asList(myILcdPoint1,myILcdPoint2)).style(myIconStyle).submit()

      The objects must all be contained in the collection that has been passed as an argument in ILspStyler.style(Collection, ALspStyleCollector, TLspContext).

      Specifying other objects after a call to this method will invalidate the result of this call.

      When you don't call the geometry(ILcdShape) or geometry(ALspStyleTargetProvider) method, these domain objects are also used to retrieve the shape to which the labels are anchored. The domain objects must then be an ILcdShape or they must have a shape.

      Overrides:
      objects in class ALspStyleCollector
      Parameters:
      aObjects - The objects to style.
      Returns:
      this style collector

    • style

      public ALspLabelStyleCollector style(ALspStyle aStyle)

      Applies the style to the specified labels.

      Example usage:

      myCollector.object( myObject ).label( myLabelID ).style( myTextStyle ).submit()

      Specifying other styles after a call to this method will invalidate the result of this call.

      Styles that are supported for labels are:

      See TLspLabelPainter for more information.
      Overrides:
      style in class ALspStyleCollector
      Parameters:
      aStyle - The style to apply.
      Returns:
      This style collector.

    • styles

      public ALspLabelStyleCollector styles(ALspStyle... aStyles)

      Applies the given list of styles to the specified labels.

      Example usage:

      myCollector.object( myObject ).label( myLabelID ).styles( myTextStyle, myTextProviderStyle ).submit()

      Specifying other styles after a call to this method will invalidate the result of this call.

      Styles that are supported for labels are:

      See TLspLabelPainter for more information.
      Overrides:
      styles in class ALspStyleCollector
      Parameters:
      aStyles - The styles to apply.
      Returns:
      This style collector.

    • styles

      public ALspLabelStyleCollector styles(List<? extends ALspStyle> aStyles)

      Applies the given list of styles to the specified labels.

      Example usage:

      myCollector.object( myObject ).label( myLabelID ).styles( myTextStyle, myTextProviderStyle ).submit()

      Specifying other styles after a call to this method will invalidate the result of this call.

      Styles that are supported for labels are:

      See TLspLabelPainter for more information.
      Overrides:
      styles in class ALspStyleCollector
      Parameters:
      aStyles - The styles to apply.
      Returns:
      This style collector.

    • anchorLabel

      public ALspLabelStyleCollector anchorLabel(Object aSublabelID)

      Specify the label to anchor a label to. The given Object is the sublabel ID for an other label of the same layer, paint representation and domain object. See also ILspLabelPainter.getAnchorObject.

      If no label with the specified sublabel ID can be found, the label will be anchored to the domain object.

      Parameters:
      aSublabelID - The anchor sublabel to use.
      Returns:
      this collector

    • anchorLabel

      public ALspLabelStyleCollector anchorLabel(TLspPaintRepresentation aPaintRepresentation, Object aSublabelID)

      Specify the label to anchor a label to. The given Object is the sublabel ID for an other label of the same layer and domain object, but possibly a different paint representation. This makes it possible to make labels depend on labels from other painters. See also ILspLabelPainter.getAnchorObject.

      If no label with the specified sublabel ID can be found, the label will be anchored to the domain object.

      Parameters:
      aPaintRepresentation - The paint representation of the anchor.
      aSublabelID - The anchor label to use.
      Returns:
      this collector

    • priority

      public ALspLabelStyleCollector priority(int aPriority)
      Specifies a fixed priority for the label(s) part of this submit() call.

      By default, labels have priority Integer.MAX_VALUE, low priority.

      Parameters:
      aPriority - The desired priority, 0 being highest priority
      Returns:
      this collector

    • priority

      public ALspLabelStyleCollector priority(ILspLabelPriorityProvider aPriorityProvider)
      Specifies a priority provider for the label(s) part of this submit() call.
      Parameters:
      aPriorityProvider - The priority provider that can specify priorities.
      Returns:
      this collector

    • group

      public ALspLabelStyleCollector group(String aGroup)
      Specifies the declutter group the label(s) should be in.

      By default, TLspLabelPlacer.DEFAULT_DECLUTTER_GROUP is used.

      Parameters:
      aGroup - The desired declutter group
      Returns:
      this collector
      See Also:

    • algorithm

      public ALspLabelStyleCollector algorithm(ILspLabelingAlgorithm aAlgorithm)

      Specifies the labeling algorithm to be used for the label(s) part of this submit() call.

      By default, an algorithm is used based on the geometry of the domain object.

      To avoid having to iterate over all objects in ALspLabelStyler because of different labeling algorithms being used for different objects, it is possible to use the algorithm(ILspLabelingAlgorithmProvider) method instead. That method allows to use 1 instance of ILspLabelingAlgorithmProvider for all objects. This algorithm provider can then calculate which algorithm to use for an object.

      Parameters:
      aAlgorithm - The algorithm to be used
      Returns:
      this collector

    • algorithm

      public ALspLabelStyleCollector algorithm(ILspLabelingAlgorithmProvider aAlgorithmProvider)
      Specifies the labeling algorithm provider to be used for the label(s) part of this submit() call.

      By default, an algorithm is used based on the geometry of the domain object.

      Parameters:
      aAlgorithmProvider - The algorithm provider to be used
      Returns:
      this collector

    • locations

      public ALspLabelStyleCollector locations(int aShift, TLspLabelLocationProvider.Location... aLocations)

      Specifies a set of fixed locations to be used for the label(s).

      This method is a convenience method. It is the same as calling algorithm(new TLspLabelingAlgorithm(new TLspLabelLocationProvider(aShift, aLocations)).

      To avoid having to iterate over all objects in ALspLabelStyler because of different locations being used for different objects, it is possible to use the algorithm(ILspLabelingAlgorithmProvider) method instead. That method allows to use 1 instance of ILspLabelingAlgorithmProvider for all objects. This algorithm provider can then calculate which algorithm to use for an object.

      Parameters:
      aShift - the amount of pixels the labels must be removed from the object anchor point.
      aLocations - a list of possible locations to place the labels.
      Returns:
      this builder.

    • submit

      public void submit()
      Submits the currently specified objects and location information. A call to this method has to be preceded by a call that specifies information such as geometry(com.luciad.shape.ILcdShape) or algorithm(com.luciad.view.lightspeed.label.algorithm.ILspLabelingAlgorithm). This mandatory method commits and links the location information provided to the domain object(s) and label(s).

      Example usage:
      myCollector.object(myObject).label(1).geometry(myShape1).submit();
      myCollector.object(myObject).label(2).geometry(myShape2).submit();

      Not calling this method will result in no information being specified at all. Calling any other method after already having provided objects and/or information will result in invalidating those previous calls. Also note that subsequent calls for the same labels override the information previously specified.

      Overrides:
      submit in class ALspStyleCollector

    • submitImpl

      protected abstract void submitImpl()
      This method is called by the submit() method. Implementers of this class should not override submit() directly, but should implement this method instead.

      The information that has been specified before calling submit(), is provided through a number of protected getters of this class. After the call to submit(), this information will be cleared.

      Specified by:
      submitImpl in class ALspStyleCollector
      See Also: