com.dlsc.flexgantt.swing.timeline

## Class TimeGranularityDatelineModel

- java.lang.Object
- - com.dlsc.flexgantt.model.dateline.AbstractDatelineModel<TimeGranularity>
  - - com.dlsc.flexgantt.swing.timeline.TimeGranularityDatelineModel

- All Implemented Interfaces:
    IDatelineModel<TimeGranularity>

      public class TimeGranularityDatelineModel
      extends AbstractDatelineModel<TimeGranularity>

  A dateline model implementation based on the `TimeGranularity` enumerator. The model tries to return major time points that are intuitive for the current minor time points. If, for example, the minor time points are days (Mo, Tu, We, ...) then the major time points will be the beginning of each week (Jan 1st, Jan 8th, Jan 15th, ...).
  Since:
    1.0
  Author:
    Dirk Lemmermann
  See Also:
    `TimeGranularity`, `TimeGranularityDatelineRenderer`, `TimeGranularityGridPolicy`

- - ### Field Summary

    - ### Fields inherited from class com.dlsc.flexgantt.model.dateline.AbstractDatelineModel

      `datelineWidth, granularity, selectedTimeSpan, spreadsheetCellWidth, timeSpan, timeZone, zoom`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TimeGranularityDatelineModel(Dateline dateline)` Constructs a new dateline model.
    `TimeGranularityDatelineModel(Dateline dateline, ITimeSpan timeSpan)` Constructs a new dateline model.
    `TimeGranularityDatelineModel(Dateline dateline, ITimeSpan timeSpan, TimeGranularity tg)` Constructs a new dateline model.
    `TimeGranularityDatelineModel(Dateline dateline, ITimeSpan timeSpan, TimeGranularity tg, TimeZone zone)` Constructs a new dateline model.
    `TimeGranularityDatelineModel(Dateline dateline, ITimeSpan timeSpan, TimeZone zone)` Constructs a new dateline model.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `calculateDatelineWidth()` Calculates the required width of the dateline based on the total time span and some additional information that needs to be provided by the subclasses.
    `int` | `getGap()` The gap (in pixel) that will be added twice to each granularity width so that there will be some space between the text and the grid lines.
    `List<GridLine>` | `getGrid(int x1, int x2, boolean major)` Returns a list of grid line coordinates for the given coordinate interval.
    `MessageFormat` | `getHalfYearFormat()` Returns the format used for displaying the halfs of a year.
    `DateFormat` | `getMajorDateFormat(TimeGranularity granularity)` Returns the date formatter used for the given time granularity, when formatting time in the major part of the dateline (the upper part).
    `String` | `getMajorDateString(TimeGranularity level, long date)` Returns a string representation of a time point based on the given time granularity.
    `TimeGranularity` | `getMajorTimeGranularity()` Returns the major time granularity, which is based on the currently used (minor) time granularity.
    `DateFormat` | `getMinorDateFormat(TimeGranularity granularity)` Returns the date formatter used for the given time granularity, when formatting time in the minor part of the dateline (the lower part).
    `String` | `getMinorDateString(TimeGranularity level, long date)` Returns a string representation of a time point based on the given time granularity.
    `MessageFormat` | `getQuarterYearFormat()` Returns the format used for displaying the quarters of a year.
    `long` | `getTimeAt(int x)` Returns the time unit specified by the given pixel location.
    `long` | `getTimeDuration(int width)` Returns the duration in milliseconds represented by the given width.
    `TimeGranularity` | `getTimeGranularity(ITimeSpan span, int width)` Returns a suitable time granularity that can be used to display the given time span in the given width.
    `int` | `getTimeLocation(long time)` Returns the location of the given time point.
    `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.
    `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` | `setGap(int gap)` Sets the gap (in pixel) that will be added twice to each granularity width so that there will be some space between the text and the grid lines.
    `void` | `setHalfYearFormat(MessageFormat format)` Sets the format used for displaying the halfs of a year.
    `void` | `setMajorDateFormat(TimeGranularity granularity, DateFormat format)` Sets the date formatter used for the given time granularity, when formatting time in the major part of the dateline (the upper part).
    `void` | `setMinorDateFormat(TimeGranularity granularity, DateFormat format)` Sets the date formatter used for the given time granularity, when formatting time in the minor part of the dateline (the lower part).
    `void` | `setQuarterYearFormat(MessageFormat format)` Sets the format used for displaying the quarters of a year.

    - ### Methods inherited from class com.dlsc.flexgantt.model.dateline.AbstractDatelineModel

      `addDatelineModelListener, fireDatelineModelChangeEvent, fireDatelineModelWillChangeEvent, getDatelineWidth, getGranularity, getSelectedTimeSpan, getSpreadsheetCellWidth, getTimeSpan, getTimeZone, getZoom, removeDatelineModelListener, setGranularity, setSelectedTimeSpan, setSpreadsheetCellWidth, setTimeSpan, setTimeZone, setZoom`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### TimeGranularityDatelineModel

          public TimeGranularityDatelineModel(Dateline dateline,
                                              ITimeSpan timeSpan,
                                              TimeGranularity tg,
                                              TimeZone zone)
                                       throws DatelineModelException

      Constructs a new dateline model.
      Parameters:
        `dateline` - the dateline to which the model belongs
        `timeSpan` - the total time span covered (the planning horizon)
        `tg` - the initial time granularity
        `zone` - the time zone represented by the model
      Throws:
        `DatelineModelException` - if the requested time span can not be visualized with the requested granularity
      Since:
        1.0

    - #### TimeGranularityDatelineModel

          public TimeGranularityDatelineModel(Dateline dateline,
                                              ITimeSpan timeSpan,
                                              TimeGranularity tg)
                                       throws DatelineModelException

      Constructs a new dateline model. The time zone defaults to `TimeZone.getDefault()`
      Parameters:
        `dateline` - the dateline to which the model belongs
        `timeSpan` - the total time span covered (the planning horizon)
        `tg` - the initial time granularity
      Throws:
        `DatelineModelException` - if the requested time span can not be visualized with the requested granularity
      Since:
        1.0

    - #### TimeGranularityDatelineModel

          public TimeGranularityDatelineModel(Dateline dateline,
                                              ITimeSpan timeSpan,
                                              TimeZone zone)
                                       throws DatelineModelException

      Constructs a new dateline model. The initial time span is [0, 1000], the initial granularity is `TimeGranularity.DAY_SHORT` and the time zone defaults to `TimeZone.getDefault()`
      Parameters:
        `dateline` - the dateline to which the model belongs
        `timeSpan` - the total time span covered (the planning horizon)
        `zone` - the time zone represented by the model
      Throws:
        `DatelineModelException` - if the requested time span can not be visualized with the requested granularity
      Since:
        1.0

    - #### TimeGranularityDatelineModel

          public TimeGranularityDatelineModel(Dateline dateline,
                                              ITimeSpan timeSpan)
                                       throws DatelineModelException

      Constructs a new dateline model. The time zone defaults to `TimeZone.getDefault()`
      Parameters:
        `dateline` - the dateline to which the model belongs
        `timeSpan` - the total time span covered (the planning horizon)
      Throws:
        `DatelineModelException` - if the requested time span can not be visualized with the requested granularity
      Since:
        1.0

    - #### TimeGranularityDatelineModel

          public TimeGranularityDatelineModel(Dateline dateline)
                                       throws DatelineModelException

      Constructs a new dateline model. The initial time span is [0, 1000], the initial granularity is `SimpleGranularity.ONE`, and the time zone defaults to `TimeZone.getDefault()`
      Parameters:
        `dateline` - the dateline to which the model belongs
      Throws:
        `DatelineModelException` - if the requested time span can not be visualized with the requested granularity
      Since:
        1.0

  - ### Method Detail

    - #### getGap

          public int getGap()

      The gap (in pixel) that will be added twice to each granularity width so that there will be some space between the text and the grid lines.
      Returns:
        the text gap in pixel
      Since:
        1.0

    - #### setGap

          public void setGap(int gap)

      Sets the gap (in pixel) that will be added twice to each granularity width so that there will be some space between the text and the grid lines.
      Parameters:
        `gap` - the text gap in pixel
      Since:
        1.0

    - #### getGrid

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

      Description copied from interface: `IDatelineModel`
      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
      See Also:
        `GridLayer`

    - #### getMajorTimeGranularity

          public TimeGranularity getMajorTimeGranularity()

      Returns the major time granularity, which is based on the currently used (minor) time granularity. If for example the minor time granularity equals MILLISECOND, TEN_MILLISECONDS or HUNDRED_MILLISECONDS then the major time granularity will be SECOND. If the minor time granularity is WEEK then the major granularity will be MONTH.
      Returns:
        the major time granularity based on the currently used minor time granularity
      Since:
        1.0

    - #### getTimeGranularity

          public TimeGranularity getTimeGranularity(ITimeSpan span,
                                                    int width)

      Returns a suitable time granularity that can be used to display the given time span in the given width.
      Parameters:
        `span` - the time span in need of rendering
        `width` - the available width for displaying the given time span
      Returns:
        a suitable time granularity for the given span and width
      Since:
        1.0

    - #### getTimeLocation

          public int getTimeLocation(long time)

      Description copied from interface: `IDatelineModel`
      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 `IDatelineModel.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
      See Also:
        `IDatelineModel.getTimeAt(int)`

    - #### getTimeAt

          public long getTimeAt(int x)

      Returns the time unit specified by the given pixel location.
      Parameters:
        `x` - int
      Returns:
        long
      See Also:
        `getTimeAt(int)`

    - #### getTimeSpanAt

          public ITimeSpan getTimeSpanAt(int x,
                                         boolean major)

      Description copied from interface: `IDatelineModel`
      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

    - #### getTimeDuration

          public long getTimeDuration(int width)

      Returns the duration in milliseconds represented by the given width.
      Parameters:
        `width` - the width (in pixel) for which to return the duration
      Returns:
        the duration (in milliseconds) represented by the given width
      Since:
        1.0

    - #### calculateDatelineWidth

          protected void calculateDatelineWidth()
                                         throws DatelineModelException

      Description copied from class: `AbstractDatelineModel`
      Calculates the required width of the dateline based on the total time span and some additional information that needs to be provided by the subclasses.
      Specified by:
        `calculateDatelineWidth` in class `AbstractDatelineModel<TimeGranularity>`
      Throws:
        `DatelineModelException` - if the calculated width exceeds the maximum width that is equal to `Integer.MAX_VALUE`

    - #### getMajorDateString

          public String getMajorDateString(TimeGranularity level,
                                           long date)

      Returns a string representation of a time point based on the given time granularity. The text can be used in the upper part of the dateline (the major time). If the time granularity is `TimeGranularity.YEAR` then the text will be something like "2006", "2007", etc...
      Parameters:
        `level` - the time granularity shown in the major part of the dateline
        `date` - the date for which to return a text representation
      Returns:
        a text for the given time based on the given time granularity
      Since:
        1.0

    - #### getMinorDateString

          public String getMinorDateString(TimeGranularity level,
                                           long date)

      Returns a string representation of a time point based on the given time granularity. The text can be used in the lower part of the dateline (the minor time). Example: if the time granularity is equal to `TimeGranularity.MONTH_SHORT` then the text will be something like "Jan", "Feb", "Mar", etc...
      Parameters:
        `level` - the time granularity shown in the minor part of the dateline
        `date` - the date for which to return a text representation
      Returns:
        a text for the given time based on the given time granularity
      Since:
        1.0

    - #### getQuarterYearFormat

          public MessageFormat getQuarterYearFormat()

      Returns the format used for displaying the quarters of a year. The default is "Q1", "Q2", "Q3", "Q4". A special formatter is required as quarters can not be formatted with a standard `DateFormat` object.
      Returns:
        the format used for displaying the quarters of a year
      Since:
        1.0

    - #### setQuarterYearFormat

          public void setQuarterYearFormat(MessageFormat format)

      Sets the format used for displaying the quarters of a year. The default is "Q1", "Q2", "Q3", "Q4". A special formatter is required as quarters can not be formatted with a standard `DateFormat` object.
      Parameters:
        `format` - the format used for displaying the quarters of a year
      Since:
        1.0

    - #### getHalfYearFormat

          public MessageFormat getHalfYearFormat()

      Returns the format used for displaying the halfs of a year. The default is "H1", "H2". A special formatter is required as the halfs of a year can not be formatted with a standard `DateFormat` object.
      Returns:
        the format used for displaying the halfs of a year
      Since:
        1.0

    - #### setHalfYearFormat

          public void setHalfYearFormat(MessageFormat format)

      Sets the format used for displaying the halfs of a year. The default is "H1", "H2". A special formatter is required as the halfs of a year can not be formatted with a standard `DateFormat` object.
      Parameters:
        `format` - the format used for displaying the halfs of a year
      Since:
        1.0

    - #### getMajorDateFormat

          public DateFormat getMajorDateFormat(TimeGranularity granularity)

      Returns the date formatter used for the given time granularity, when formatting time in the major part of the dateline (the upper part).
      Parameters:
        `granularity` - the time granularity for which to return a date formatting object
      Returns:
        a date formatter for the given time granularity
      Since:
        1.0

    - #### setMajorDateFormat

          public void setMajorDateFormat(TimeGranularity granularity,
                                         DateFormat format)
                                  throws DatelineModelException

      Sets the date formatter used for the given time granularity, when formatting time in the major part of the dateline (the upper part).
      Parameters:
        `granularity` - the time granularity for which to return a date formatting object
        `format` - a date formatter for the given time granularity
      Throws:
        `DatelineModelException` - if the dateline width becomes too large because of the new format
      Since:
        1.0

    - #### getMinorDateFormat

          public DateFormat getMinorDateFormat(TimeGranularity granularity)

      Returns the date formatter used for the given time granularity, when formatting time in the minor part of the dateline (the lower part).
      Parameters:
        `granularity` - the time granularity for which to return a date formatting object
      Returns:
        a date formatter for the given time granularity
      Since:
        1.0
      See Also:
        `getQuarterYearFormat()`, `getHalfYearFormat()`

    - #### setMinorDateFormat

          public void setMinorDateFormat(TimeGranularity granularity,
                                         DateFormat format)
                                  throws DatelineModelException

      Sets the date formatter used for the given time granularity, when formatting time in the minor part of the dateline (the lower part).
      Parameters:
        `granularity` - the time granularity for which to return a date formatting object
        `format` - a date formatter for the given time granularity
      Throws:
        `DatelineModelException` - if the dateline width becomes too large because of the new format
      Since:
        1.0
      See Also:
        `setQuarterYearFormat(MessageFormat)`, `setHalfYearFormat(MessageFormat)`

    - #### requestVisibleTimeSpan

          public void requestVisibleTimeSpan(ITimeSpan span)
                                      throws DatelineModelException

      Description copied from interface: `IDatelineModel`
      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

    - #### getTimeString

          public String getTimeString(long time)

      Description copied from interface: `IDatelineModel`
      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

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