Package com.luciad.view.lightspeed.painter.grid

Class TLspXYGridStyle.Builder<B extends TLspXYGridStyle.Builder<B>>

java.lang.Object
com.luciad.view.lightspeed.painter.grid.TLspXYGridStyle.Builder<B>
Enclosing class:
TLspXYGridStyle
public static class TLspXYGridStyle.Builder<B extends TLspXYGridStyle.Builder<B>> extends Object
Builder for XY grid styles.
Since:
2016.0

  • Method Summary

    Modifier and Type
    Method
    Description
    B
    all(TLspXYGridStyle aStyle)
    Sets all parameters on the builder based on the given grid style.
    B
    axes(EnumSet<TLspXYGridStyle.Axis> aAxes)
    This method specifies to which axes the subsequent calls are applied.
    B
    body(double aSpacing)
    This method defines a level for which grid lines, separated by the given spacing, are added.
    TLspXYGridStyle
    build()
    Creates a new TLspXYGridStyle from this builder.
    B
    clampToBounds(ILcdBounds aBounds)
    When called with a non-null value, this grid layer will restrict the grid lines to the given bounds.
    B
    customizableStyles(TLspCustomizableStyle... aStyles)
    This method specifies the customizable styles to use for the current spacing/interval combination.
    B
    customizableStyles(Collection<TLspCustomizableStyle> aStyles)
    This method specifies the customizable styles to use for the current spacing/interval combination.
    B
    defaultXYGridStyle()
    Configures this builder with a default xy grid style.
    B
    format(Format aFormat)
    This method specifies the format to use for the labels of the current spacing/interval combination.
    B
    interval(double aMinScale, double aMaxScale)
    This method specifies when grid lines or its labels are visible using an interval of scales.
    B
    label(double aSpacing)
    This method defines a level for which labels of grid lines, separated by the given spacing, are added.
    B
    labelEdgeOffset(double aEdgeOffset)
    This method specifies the offset of the label, away from the edge of the view.
    B
    labelEdgeOffset(double aEdgeOffsetLeft, double aEdgeOffsetRight, double aEdgeOffsetBottom, double aEdgeOffsetTop)
    This method specifies the offsets of the label, away from the edges of the view, one offset for each side of the view.
    B
    labelGridOffset(double aGridOffset)
    This method specifies the offset of the label, away from the grid line to which it is attached.
    B
    labelLinePosition(TLspXYGridStyle.LinePosition aLinePosition)
    This method specifies the position of the line labels of the current spacing/interval combination with respect to the line.
    B
    labelOrientation(TLspXYGridStyle.Orientation aOrientation)
    This method specifies the orientation to use for the labels of the current spacing/interval combination.
    B
    labelPosition(TLspXYGridStyle.LabelPosition aLabelPosition)
    This method specifies the position of the line labels of the current spacing/interval combination with respect to the view.
    B
    origin(ILcdPoint aOrigin)
    When called with a non-null value, this grid layer will map its origin (0, 0) to the given point on the map.
    B
    overlay()
    After calling this method, all subsequent interval(), styles(), customizableStyles(), … calls will only apply to all overlay labels.
    B
    styles(ALspStyle... aStyles)
    This method specifies the styles to use for the current spacing/interval combination.
    B
    styles(Collection<ALspStyle> aStyles)
    This method specifies the styles to use for the current spacing/interval combination.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • defaultXYGridStyle

      public B defaultXYGridStyle()
      Configures this builder with a default xy grid style.
      Returns:
      this builder.

    • clampToBounds

      public B clampToBounds(ILcdBounds aBounds)
      When called with a non-null value, this grid layer will restrict the grid lines to the given bounds. The clamping will happen for all grid lines.
      Parameters:
      aBounds - the bounds to which the grid is clamped.
      Returns:
      this builder.

    • origin

      public B origin(ILcdPoint aOrigin)
      When called with a non-null value, this grid layer will map its origin (0, 0) to the given point on the map.
      Parameters:
      aOrigin - the origin, defined in the reference of the grid.
      Returns:
      this builder
      Since:
      2020.1

    • axes

      public B axes(EnumSet<TLspXYGridStyle.Axis> aAxes)

      This method specifies to which axes the subsequent calls are applied. This method can be used anywhere, but its behavior depends on which method is called right after it. Some examples are given below. If this method is never called, the other method calls apply to all axes.

      It can be used to specify spacings that are only used on one of the axes. To do this, this method should be called before calling the body or label method:

      
   // The grid will contain lines with a spacing of 5000.0, 1000.0 and 100.0 for the X
   // axis, and with a spacing of 5000.0, 2000.0 and 100.0 for the Y axis.
   TLspXYGridStyle.Builder builder = TLspXYGridStyle.newBuilder();
   builder.body(5000.0).interval(...)...;
   builder.axis(EnumSet.of(Axis.X)).body(1000.0).interval(...)...;
   builder.axis(EnumSet.of(Axis.Y)).body(2000.0).interval(...)...;
   builder.axis(EnumSet.of(Axis.X, Axis.Y)).body(100.0).interval(...)...;

      It can be used to specify intervals that are only used on one of the axes. To do this, this method should be called before calling the interval method:

      
   // The grid will contain lines with a spacing of 1000.0. For the X axis, these line will be displayed
   // in the 'interval1' scale interval and in the 'interval2' scale interval for the Y axis.
   TLspXYGridStyle.Builder builder = TLspXYGridStyle.newBuilder();
   builder.body(1000);
   builder.axis(EnumSet.of(Axis.X)).interval(interval1)...;
   builder.axis(EnumSet.of(Axis.Y)).interval(interval2)...;

      It can be used to specify styling options that are only used on one of the axes. To do this, this method should be called before one of the style related method (e.g. styles, customizableStyles, format, ...):

      
   // The grid will contain labels with a spacing of 1000.0, visible in the given scale 'interval'.
   // For the X axis, the labels will be formatted differently from the Y axis labels. Both axes will use the
   // same styles.
   TLspXYGridStyle.Builder builder = TLspXYGridStyle.newBuilder();
   builder.label(1000).interval(interval);
   builder.styles(style1, style2);
   builder.axis(EnumSet.of(Axis.X)).format(formatX);
   builder.axis(EnumSet.of(Axis.Y)).format(formatY);
      Parameters:
      aAxes - the axes for which the subsequent calls are applied.
      Returns:
      this builder.

    • body

      public B body(double aSpacing)

      This method defines a level for which grid lines, separated by the given spacing, are added. This spacing is a double value, expressed in the units of the xy grid reference. When using a spacing with a certain value, grid lines with coordinates that are a multiple of this values are added to the grid. You can for example use a spacing of 100 kilometers by supplying a value of 100000.0. As a result, grid lines with coordinates of -100000.0, 0.0, 100000.0, 200000.0, and so one, are added.

      After calling this method, all subsequent interval(), styles(), customizableStyles(), … calls will apply to all grid lines with the given spacing. E.g. to all 100000 meter lines.

      When no subsequent interval() or styles() call is done, a default interval and default styles are chosen. Note that the default interval might not be a good default. See interval() for more information.

      For more information on how to use this method, see TLspXYGridStyle.

      Parameters:
      aSpacing - the spacing between the grid lines (expressed in the unit of measure of the reference)
      Returns:
      this builder

    • label

      public B label(double aSpacing)

      This method defines a level for which labels of grid lines, separated by the given spacing, are added. This spacing is a double value, expressed in the units of the xy grid reference. When using a spacing with a certain value, labels for grid lines with coordinates that are a multiple of this values are added to the grid. You can for example use a spacing of 100 kilometers by supplying a value of 100000.0. As a result, labels of grid lines with coordinates of -100000.0, 0.0, 100000.0, 200000.0, and so one, are added.

      After calling this method, all subsequent interval(), styles(), customizableStyles(), … calls will apply to all labels of the grid lines with the given spacing. E.g. to all 100000 meter line labels.

      When no subsequent interval() or styles() call is done, a default interval and default styles are chosen. Note that the default interval might not be a good default. See interval for more information.

      For more information on how to use this method, see TLspXYGridStyle.

      Parameters:
      aSpacing - the spacing (expressed in the unit of measure of the grid reference) of the grid lines to which the labels are added
      Returns:
      this builder

    • overlay

      public B overlay()

      After calling this method, all subsequent interval(), styles(), customizableStyles(), … calls will only apply to all overlay labels. See also TLspXYGridOverlayLabelBuilder.

      When no subsequent interval() or styles() call is done, a default interval and default styles are chosen.

      For more information on how to use this method, see TLspXYGridStyle.

      Returns:
      this builder

    • interval

      public B interval(double aMinScale, double aMaxScale)

      This method specifies when grid lines or its labels are visible using an interval of scales. Grid lines or labels will be visible whenever the scale of the view lies within this scale interval. This method should be called after calling one of the body, label or overlay methods, so the scale interval will only apply to the lines or labels with the spacing defined in these methods. It is possible to call this method more than once. In that case, the grid lines with a specific spacing or its labels will be visible when the scale of the view is within one of the specified scale intervals. This is especially useful to define different styles at different scales.

      After calling this method, all subsequent styles(), customizableStyles(), … calls will only apply to the given scale interval. It is possible to define multiple scale intervals for every grid line or label spacing. In order to do this, the interval method (and its subsequent calls) can be called multiple times.

      When not calling this method after calling one of the body or label methods, a scale interval from 0 (completely zoomed out) to Double.MAX_VALUE (completely zoomed in) is used. So if you want to use the same styles for every scale, this method should not be called.

      Note that it is important to choose realistic scale intervals for each spacing. Not doing this may cause the grid layer to generate too many lines. This could for example happen when displaying grid lines with a spacing of 1 meter, when viewing the whole world. Note that the grid layer will automatically fall back to a less detailed grid level (if available) to avoid OutOfMemoryErrors. This may or may not be the desired behavior though, so it is advised to avoid this problem by using well chosen scale intervals.

      When specifying overlapping scale intervals, it's undefined which styles will be used. It is advised to only specify non-overlapping scale intervals for the same (spacing / body or label) combination.

      For more information on how to use this method, see TLspXYGridStyle.

      Parameters:
      aMinScale - the minimum scale, for example 0.0005 (=50/100000, when 50 pixels correspond to 100000 meters in the view)
      aMaxScale - the maximum scale, typically Double.MAX_VALUE (to make sure grid lines always remain visible when zooming in)
      Returns:
      this builder

    • styles

      public B styles(Collection<ALspStyle> aStyles)

      This method specifies the styles to use for the current spacing/interval combination. The given styles are only applied to grid lines or labels with the spacing defined in a previous body, label call. They are also only used when the view scale lies within the scale interval defined in a previous interval call.

      Note that not all styles are supported (see TLspXYGridStyle for more information).

      Either this method or the customizableStyles method should be called at least once after calling one of the body, label or interval methods. Otherwise, default styling is used.

      The difference between the styles() and customizableStyles() method is that the latter accepts TLspCustomizableStyle instances which will be exposed through the ILspStyler which is set on the resulting layer. That styler will implement the ILspCustomizableStyler interface and expose those customizable styles. The styles passed in the styles() method will not be exposed. The benefit of the customizableStyles() method is that it is possible to customize the styles later on (for example through a user interface). If no customization is needed afterwards, the styles() method has the advantage to skip the overhead of creating TLspCustomizableStyle instances.

      For more information on how to use this method, see TLspXYGridStyle.

      Parameters:
      aStyles - the styles to use.
      Returns:
      this builder

    • styles

      public B styles(ALspStyle... aStyles)

      This method specifies the styles to use for the current spacing/interval combination. For more information, see styles(Collection).

      Parameters:
      aStyles - the styles to use
      Returns:
      this builder

    • customizableStyles

      public B customizableStyles(Collection<TLspCustomizableStyle> aStyles)

      This method specifies the customizable styles to use for the current spacing/interval combination. The given styles are only applied to grid lines or labels with the spacing defined in a previous body, label call. They are also only used when the view scale lies within the scale interval defined in a previous interval call.

      Note that not all styles are supported (see TLspXYGridStyle for more information).

      Either this method or the styles method should be called at least once after calling one of the body, label or interval methods. Otherwise, default styling is used.

      The difference between the styles() and customizableStyles() method is that the latter accepts TLspCustomizableStyle instances which will be exposed through the ILspStyler which is set on the resulting layer. That styler will implement the ILspCustomizableStyler interface and expose those customizable styles. The styles passed in the styles() method will not be exposed. The benefit of the customizableStyles() method is that it is possible to customize the styles later on (for example through a user interface). If no customization is needed afterwards, the styles() method has the advantage to skip the overhead of creating TLspCustomizableStyle instances.

      For more information on how to use this method, see TLspXYGridStyle.

      Parameters:
      aStyles - the styles to use.
      Returns:
      this builder

    • customizableStyles

      public B customizableStyles(TLspCustomizableStyle... aStyles)

      This method specifies the customizable styles to use for the current spacing/interval combination. For more information, see customizableStyles(Collection).

      Parameters:
      aStyles - the styles to use
      Returns:
      this builder

    • format

      public B format(Format aFormat)

      This method specifies the format to use for the labels of the current spacing/interval combination. The given format is only applied to grid labels with the spacing defined in a previous label call. It is also only used when the view scale lies within the scale interval defined in a previous interval call. This method has no effect for bodies.

      This method is also used to specify the format used by the overlay labels. The given format is then only applied to the overlay label if overlay was called before.

      For labels, this Format should be able to format double values. TLcdDistanceFormat can be used for example. For overlay labels, this Format should be able to format ILcdPoint objects, for example GridPointFormat.

      If this method is not called, a default format is used.

      Parameters:
      aFormat - the Format used to format the label
      Returns:
      this builder.

    • labelOrientation

      public B labelOrientation(TLspXYGridStyle.Orientation aOrientation)

      This method specifies the orientation to use for the labels of the current spacing/interval combination. This method will only work when it is called after one of the label() methods. The given format is only applied to grid labels with the spacing defined in a previous label call. It is also only used when the view scale lies within the scale interval defined in a previous interval call. This method has no effect for bodies.

      If this method is not called, a default orientation is used, ALONG_LINE.

      Parameters:
      aOrientation - the orientation to use.
      Returns:
      this builder.

    • labelPosition

      public B labelPosition(TLspXYGridStyle.LabelPosition aLabelPosition)

      This method specifies the position of the line labels of the current spacing/interval combination with respect to the view. They can for example be placed at the left or at the right edge of the view, or both. For example, when a label is placed at the east or south side of a line, it will be placed at the left or lower edge of the view when using a rectangular projection like mercator.

      If this method is not called, a default label position is used, WEST_AND_SOUTH.

      Parameters:
      aLabelPosition - the label position to use.
      Returns:
      this builder
      Since:
      2017.0

    • labelLinePosition

      public B labelLinePosition(TLspXYGridStyle.LinePosition aLinePosition)

      This method specifies the position of the line labels of the current spacing/interval combination with respect to the line. They can for example be placed at the left or at the right of the line.

      If this method is not called, a default label position is used, ABOVE_OR_RIGHT.

      Parameters:
      aLinePosition - the line position to use.
      Returns:
      this builder
      Since:
      2017.0

    • labelGridOffset

      public B labelGridOffset(double aGridOffset)
      This method specifies the offset of the label, away from the grid line to which it is attached. It is applied for the labels of the current spacing/interval combination. This method will only work when it is called after one of the label() methods. It will throw an exception otherwise.

      If this method is not called, a default offset is used, 3.0.

      Parameters:
      aGridOffset - the line offset to use.
      Returns:
      this builder

    • labelEdgeOffset

      public B labelEdgeOffset(double aEdgeOffset)
      This method specifies the offset of the label, away from the edge of the view. It is applied for the labels of the current spacing/interval combination. This method will only work when it is called after one of the label() methods. It will throw an exception otherwise.

      If this method is not called, a default offset is used, 6.0.

      Parameters:
      aEdgeOffset - the border offset to use.
      Returns:
      this builder

    • labelEdgeOffset

      public B labelEdgeOffset(double aEdgeOffsetLeft, double aEdgeOffsetRight, double aEdgeOffsetBottom, double aEdgeOffsetTop)
      This method specifies the offsets of the label, away from the edges of the view, one offset for each side of the view. It is applied for the labels of the current spacing/interval combination. This method will only work when it is called after one of the label() methods. It will throw an exception otherwise.

      If this method is not called, a default offset is used, 6.0.

      Parameters:
      aEdgeOffsetLeft - the offset of the label from the left edge of the view.
      aEdgeOffsetRight - the offset of the label from the right edge of the view.
      aEdgeOffsetBottom - the offset of the label from the bottom edge of the view.
      aEdgeOffsetTop - the offset of the label from the top edge of the view.
      Returns:
      this builder
      Since:
      2018.0

    • all

      public B all(TLspXYGridStyle aStyle)

      Sets all parameters on the builder based on the given grid style.

      This is useful for example to create a new style that has almost all properties equal to another style.

      Parameters:
      aStyle - the grid style to copy
      Returns:
      this styler

    • build

      public TLspXYGridStyle build()
      Creates a new TLspXYGridStyle from this builder.
      Returns:
      a new TLspXYGridStyle