com.dlsc.flexgantt.model.dateline

## Interface IDatelineModel<T extends IGranularity>

- Type Parameters:
    `T` - the type of the granularity object
  All Known Implementing Classes:
    AbstractDatelineModel, SimpleGranularityDatelineModel, TimeGranularityDatelineModel

      public interface IDatelineModel<T extends IGranularity>

  A dateline model provides essential information for the dateline, the dateline renderer, the grid layer. The model can be queried to translate coordinates to time points and time points to coordinates. The time span in combination with the dateline width are used as a basis for the calculations required to perform the translations. The time zone is used to calculate the offset between the data stored on the Gantt chart nodes (each node can have its own time zone) and the time that is shown in the dateline.
  Since:
    1.0
  Version:
    $Revision: 1.20 $
  Author:
    Dirk Lemmermann

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addDatelineModelListener(IDatelineModelListener l)` Adds a listener to the dateline model.
    `int` | `getDatelineWidth()` Returns the width of the dateline that is required based on the current settings of the dateline model.
    `T` | `getGranularity()` Returns the time granularity that the dateline model is using for calculating its minor grid.
    `List<GridLine>` | `getGrid(int x1, int x2, boolean major)` Returns a list of grid line coordinates for the given coordinate interval.
    `ITimeSpan` | `getSelectedTimeSpan()` Returns the currently selected time span.
    `int` | `getSpreadsheetCellWidth()` Returns the width used for spreadsheet cells.
    `long` | `getTimeAt(int x)` Returns the time for the given x-coordinate.
    `int` | `getTimeLocation(long time)` Returns the location of the given time point.
    `ITimeSpan` | `getTimeSpan()` Returns the total time span covered by the model / dateline.
    `ITimeSpan` | `getTimeSpanAt(int x, boolean major)` Returns the time span that gets defined by the grid lines to the left and the right of the given x-coordinate.
    `String` | `getTimeString(long time)` Returns a textual representation for the givent time point.
    `TimeZone` | `getTimeZone()` Returns the time zone represented by the dateline.
    `double` | `getZoom()` Returns the zoom factor of the model / dateline.
    `void` | `removeDatelineModelListener(IDatelineModelListener l)` Removes a listener from the dateline model.
    `void` | `requestVisibleTimeSpan(ITimeSpan span)` A request that asks the model to change its settings in such a way that the requested time span will become visible in the viewport on the right-hand side of the Gantt chart.
    `void` | `setGranularity(T granularity)` Specifies the time granularity that the dateline model should use for calculating its minor grid.
    `void` | `setSelectedTimeSpan(ITimeSpan span)` Sets a time span selection.
    `void` | `setSpreadsheetCellWidth(int width)` Sets the width used for spreadsheet cells.
    `void` | `setTimeSpan(ITimeSpan span)` Sets the total time span covered by the model / dateline.
    `void` | `setTimeZone(TimeZone timeZone)` Sets the time zone represented by the dateline.
    `void` | `setZoom(double zoom)` Sets a zoom factor on the model / dateline.

- - ### Method Detail

    - #### getTimeSpan

          ITimeSpan getTimeSpan()

      Returns the total time span covered by the model / dateline. The width of the dateline gets calculated based on the time span plus some additional information. The additional information can vary depending on the dateline model implementation. The `TimeGranularityDatelineModel` for example uses the currently used `TimeGranularity` while the `SimpleGranularityDatelineModel` uses the currently active `SimpleGranularity`.
      Returns:
        the total time span covered by the dateline
      Since:
        1.0
      See Also:
        `setTimeSpan(ITimeSpan)`

    - #### setTimeSpan

          void setTimeSpan(ITimeSpan span)
                    throws DatelineModelException

      Sets the total time span covered by the model / dateline. The width of the dateline gets calculated based on the time span plus some additional information. The additional information can vary depending on the dateline model implementation. The `TimeGranularityDatelineModel` for example uses the currently used `TimeGranularity` while the `SimpleGranularityDatelineModel` uses the currently active `SimpleGranularity`.
      Parameters:
        `span` - the total time span covered by the dateline
      Throws:
        `DatelineModelException`
      Since:
        1.0
      See Also:
        `getTimeSpan()`

    - #### setGranularity

          void setGranularity(T granularity)
                       throws DatelineModelException

      Specifies the time granularity that the dateline model should use for calculating its minor grid.
      Parameters:
        `granularity` - the granularity requested for the minor time grid
      Throws:
        `DatelineModelException` - if the requested time granularity can not be applied
      Since:
        1.0

    - #### getGranularity

          T getGranularity()

      Returns the time granularity that the dateline model is using for calculating its minor grid.
      Returns:
        the granularity of the minor grid
      Since:
        1.0

    - #### getTimeZone

          TimeZone getTimeZone()

      Returns the time zone represented by the dateline. The time zone is required for calculating the offset of the data provided by the Gantt chart model. Each tree node in the Gantt chart can represent its own time zone and the data stored on the node needs to be translated to the dateline's coordinate system via the time zone offsets.
      Returns:
        the time zone represented by the dateline
      Since:
        1.0
      See Also:
        `setTimeZone(TimeZone)`

    - #### setTimeZone

          void setTimeZone(TimeZone timeZone)
                    throws DatelineModelException

      Sets the time zone represented by the dateline. The time zone is required for calculating the offset of the data provided by the Gantt chart model. Each tree node in the Gantt chart can represent its own time zone and the data stored on the node needs to be translated to the dateline's coordinate system via the time zone offsets.
      Parameters:
        `timeZone` - the time zone represented by the dateline (model)
      Throws:
        `DatelineModelException`
      Since:
        1.0
      See Also:
        `getTimeZone()`

    - #### getDatelineWidth

          int getDatelineWidth()

      Returns the width of the dateline that is required based on the current settings of the dateline model. The width gets calculated based on the total time span covered by the model and some additional information provided by the individual dateline implementations.
      Returns:
        the width of the dateline
      Since:
        1.0

    - #### setZoom

          void setZoom(double zoom)
                throws DatelineModelException

      Sets a zoom factor on the model / dateline. This way the currently used granularity can be shown with a larger width than the default.
      Parameters:
        `zoom` - the zoom factor
      Throws:
        `DatelineModelException` - if the requested zoom factor can not be applied
      Since:
        1.0
      See Also:
        `getZoom()`

    - #### getZoom

          double getZoom()

      Returns the zoom factor of the model / dateline.
      Returns:
        the zoom factor
      Since:
        1.0
      See Also:
        `setZoom(double)`

    - #### setSpreadsheetCellWidth

          void setSpreadsheetCellWidth(int width)
                                throws DatelineModelException

      Sets the width used for spreadsheet cells.
      Parameters:
        `width` - the cell width used when showing a spreadsheet
      Throws:
        `DatelineModelException` - if the cell width causes a conflict
      Since:
        2.1

    - #### getSpreadsheetCellWidth

          int getSpreadsheetCellWidth()

      Returns the width used for spreadsheet cells.
      Returns:
        the cell width used when showing a spreadsheet
      Since:
        2.1

    - #### getTimeLocation

          int getTimeLocation(long time)

      Returns the location of the given time point. The location is an x-coordinate within the dateline. Models that are continous will simply calculate the milliseconds per pixel (mpp) and base their calculations on that value (example mpp = 2000, time = 10000 -> x = 5). Discrete models might implement a more sophisticated algorithm to compute the coordinate. The method needs to work symetrically to the `getTimeAt(int)` method (example: `x = getTimeLocation(getTimeAt(x))`).
      Parameters:
        `time` - the time for which to return a coordinate
      Returns:
        the x-coordinate for the given time point
      Since:
        1.0
      See Also:
        `getTimeAt(int)`

    - #### getTimeAt

          long getTimeAt(int x)

      Returns the time for the given x-coordinate.
      Parameters:
        `x` - the x-coordinate for which to return a time point
      Returns:
        the time at the given location
      Since:
        1.0
      See Also:
        `getTimeLocation(long)`

    - #### getTimeSpanAt

          ITimeSpan getTimeSpanAt(int x,
                                  boolean major)

      Returns the time span that gets defined by the grid lines to the left and the right of the given x-coordinate.
      Parameters:
        `x` - the location for which to return a time span
        `major` - a flag controlling whether to return the time span of the major or the minor part of the dateline
      Returns:
        the time span at the given location
      Since:
        1.0

    - #### getTimeString

          String getTimeString(long time)

      Returns a textual representation for the givent time point. If for example the given time is 0 then the text returned might be something like this: "Jan 1st, 1970".
      Parameters:
        `time` - the time for which to return a textual representation
      Returns:
        a textual representation of the given time point
      Since:
        1.0

    - #### getSelectedTimeSpan

          ITimeSpan getSelectedTimeSpan()

      Returns the currently selected time span. The dateline model incorporates selection model behaviour.
      Returns:
        the time span selection
      Since:
        1.0
      See Also:
        `setSelectedTimeSpan(ITimeSpan)`

    - #### setSelectedTimeSpan

          void setSelectedTimeSpan(ITimeSpan span)

      Sets a time span selection.
      Parameters:
        `span` - the selected time span
      Since:
        1.0
      See Also:
        `getSelectedTimeSpan()`

    - #### getGrid

          List<GridLine> getGrid(int x1,
                                 int x2,
                                 boolean major)

      Returns a list of grid line coordinates for the given coordinate interval. The same method gets invoked for major and minor grid lines.
      Parameters:
        `x1` - the start coordinate
        `x2` - the end coordinate
        `major` - if TRUE the method needs to return the major grid lines
      Returns:
        a list of x-coordinates where each coordinate represents one vertical grid line
      Since:
        1.0
      See Also:
        `GridLayer`

    - #### requestVisibleTimeSpan

          void requestVisibleTimeSpan(ITimeSpan span)
                               throws DatelineModelException

      A request that asks the model to change its settings in such a way that the requested time span will become visible in the viewport on the right-hand side of the Gantt chart.
      Parameters:
        `span` - the requested time span
      Throws:
        `DatelineModelException` - if the model can not satisfy the request
      Since:
        1.0

    - #### addDatelineModelListener

          void addDatelineModelListener(IDatelineModelListener l)

      Adds a listener to the dateline model.
      Parameters:
        `l` - the listener to add
      Since:
        1.0
      See Also:
        `removeDatelineModelListener(IDatelineModelListener)`

    - #### removeDatelineModelListener

          void removeDatelineModelListener(IDatelineModelListener l)

      Removes a listener from the dateline model.
      Parameters:
        `l` - the listener to remove
      Since:
        1.0
      See Also:
        `addDatelineModelListener(IDatelineModelListener)`

Copyright © 2006–2020 Dirk Lemmermann Software & Consulting. All rights reserved.