com.miginfocom.calendar.grid
Class DateGrid

java.lang.Object
  extended by com.miginfocom.calendar.grid.AbstractGrid
      extended by com.miginfocom.calendar.grid.DateGrid
All Implemented Interfaces:
Grid, java.beans.PropertyChangeListener, java.util.EventListener

public class DateGrid
extends AbstractGrid

Adds date and time handling to AbstractGrid. Every cell has a span in time, so has also the grid lines.

This class is immutable once created and should be recreated if data on which it is build changes.


Field Summary
protected  long primDimCellSpanMillis
          How many millis one cell span in the primary dimension (e.g.
protected  long secDimCellSpanMillis
          How many millis one cell span in the secondary dimension (always >= cellSpanMillisPrimDim).
 
Fields inherited from interface com.miginfocom.calendar.grid.Grid
OUTLINE_SHAPE_MODE_EXACT, OUTLINE_SHAPE_MODE_EXACT_CLIPPED, OUTLINE_SHAPE_MODE_POLYGON, OUTLINE_SHAPE_MODE_RECTANGLE, PRIMARY_DIMENSION, SECONDARY_DIMENSION, SIZE_MODE_INSIDE, SIZE_MODE_MIDDLE, SIZE_MODE_OUTSIDE, SIZE_MODE_UPPER_LEFT
 
Constructor Summary
DateGrid(ImmutableDateRange dateRange, int primDim, int primDimCellCount, int secDimCellCount, GridLineSpecification gridLineSpec, SubRowCreator subRowCreator)
          Constructor.
 
Method Summary
protected  void createGridLinesAndCellRows()
          Implement this to create the cell rows and grid lines.
 java.awt.Rectangle getBoundingBoxForDateRange(DateRangeI range, int cellSizeMode)
          Returns the smallest bounding box that includes all of range.
 java.awt.Rectangle getBoundingBoxForDateRange(DateRangeI range, int cellSizeMode, boolean forDraw)
          Returns the smallest bounding box that includes all of range.
 java.awt.Rectangle[] getBoundsForDateRange(DateRangeI range, int cellSizeMode)
          Returns the bounds that exactly contains the dateBounds.
 java.awt.Rectangle[] getBoundsForDateRange(DateRangeI range, int cellSizeMode, boolean rowExpand, boolean forDraw)
          Returns the bounds that exactly contains the dateBounds.
 java.awt.Point getCell(long millis, java.util.TimeZone timeZone, boolean lenient)
          Returns the grid cell that contains date (which must be within the grids date span)
 int getCellDSTChangeType(int row, int col)
          Returns -1 if the cell is in a cell that visually will be in the hour where DST is in effect and the shift will move the clock backwards, normally one hour.
 java.awt.Point[] getCellsForDateRange(DateRangeI range)
          Returns start and end cell for a date range.
 ImmutableDateRange getCellTrimmedDateRange(ImmutableDateRange dateRange)
          Rounds the start and end date to the start and end bounds (respectively) of the cell that they are in.
 ImmutableDateRange getDateRange()
          Returns the date range that this date grid is spanning.
 ImmutableDateRange getDateRangeForCell(int row, int col)
          Returns the date range a cells is spanning.
 MutableDateRange getDateRangeForRect(java.awt.Rectangle rect)
          Returns a new date range that at least contains the whole of rect.
 java.awt.Polygon getOutlineForDateRange(DateRangeI range, int cellSizeMode, boolean forDraw)
          Returns the outline for a date range.
 int getPrimaryDimensionPosition(long millis, java.util.TimeZone timeZone, java.lang.Integer forceSecDimCell)
          Returns the position that date corresponds to in the primary dimension.
 
Methods inherited from class com.miginfocom.calendar.grid.AbstractGrid
addPropertyListener, addPropertyListener, assertSize, firePropertyChangeEvent, getAbsolutePreferredHeight, getAbsolutePreferredWidth, getBoundingBox, getBoundsOfCell, getCell, getCellCount, getCellNumber, getCellsOutline, getColumnCount, getColumnDimIx, getColumnForX, getColumnGridLines, getColumns, getGridLines, getGridLineSpecification, getGridRows, getHeight, getMaximumHeight, getMaximumWidth, getMinimumHeight, getMinimumWidth, getOrientationForDimIx, getPercentInsideColumn, getPercentInsideRow, getPrimaryDimension, getPrimaryDimensionLayout, getRelPos, getRowAt, getRowAt, getRowCount, getRowDimIx, getRowForY, getRowGridLines, getRowIndexForPos, getRows, getSecondaryDimensionLayout, getSize, getSize, getWidth, getX, getY, isIgnorePropertyEvents, layout, propertyChange, removePropertyListener, setCellRows, setGridLines, setIgnorePropertyEvents, setPrimaryDimensionLayout, setSecondaryDimensionLayout, setSize, toPos
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

primDimCellSpanMillis

protected final long primDimCellSpanMillis
How many millis one cell span in the primary dimension (e.g. 30 minutes in a days view where there are 48 rows)


secDimCellSpanMillis

protected final long secDimCellSpanMillis
How many millis one cell span in the secondary dimension (always >= cellSpanMillisPrimDim). I.e. millis spanned before the grid "wraps" to another row/column

Constructor Detail

DateGrid

public DateGrid(ImmutableDateRange dateRange,
                int primDim,
                int primDimCellCount,
                int secDimCellCount,
                GridLineSpecification gridLineSpec,
                SubRowCreator subRowCreator)
Constructor. Note that the grid still don't have a valid bounds after creation. This constructor creates a grid which contains all possible dates/times within dateRange.

Parameters:
dateRange - The date range which the grid spans. From start of first to end of last cell. Cloned for local storage.
primDim - The dimensions the cells should be laid out if they where sequental. e.g. code>SwingConstants.HORIZONTAL means that the "next" cell if normally to the right, if not reached the last column, where it wraps to next row.
primDimCellCount - The number of cells in the primary dimension.
secDimCellCount - The number of cells in the secondary dimension.
gridLineSpec - The specification for the grid lines in the primary, secondary and for all sub dimensins. Not null.
subRowCreator - The object responsible fro creating sub grid rows. If null no sub grid rows will be created
See Also:
AbstractGrid.setSize(java.awt.Dimension)
Method Detail

getDateRange

public ImmutableDateRange getDateRange()
Returns the date range that this date grid is spanning.

Returns:
The date range that this date grid is spanning.

getDateRangeForCell

public ImmutableDateRange getDateRangeForCell(int row,
                                              int col)
Returns the date range a cells is spanning. Results are cached since they will always be the same.

The date range for cells that is in DST change in a day is undefined. Call getCellDSTChangeType(int, int) to know if the cell is in the DST shift.

Parameters:
row - The row
col - The column
Returns:
The date range a cells is spanning. Null if the row or column doesn't exist.

getCellDSTChangeType

public int getCellDSTChangeType(int row,
                                int col)
Returns -1 if the cell is in a cell that visually will be in the hour where DST is in effect and the shift will move the clock backwards, normally one hour.

Returns 1 if the cell is in a cell that visually will be in the hour where DST is in effect and the shift will move the clock forwards, normally one hour.

Returns 0 for any other cell.

Parameters:
row - The row
col - The column.
Returns:
-1, 0 or 1.
Since:
3.7

getCellTrimmedDateRange

public ImmutableDateRange getCellTrimmedDateRange(ImmutableDateRange dateRange)
Rounds the start and end date to the start and end bounds (respectively) of the cell that they are in.

Parameters:
dateRange - The date range. Must be sorted and not null.
Returns:
A new date range rounded to the cells.

getDateRangeForRect

public MutableDateRange getDateRangeForRect(java.awt.Rectangle rect)
Returns a new date range that at least contains the whole of rect. Can be used to know what needs to be rapainted (e.g. which activities) if a rectangle is repainted.

Parameters:
rect - The rectangle to return the date range for. Only the part that is within this grid's bounds is considered.
Returns:
The date range. Can be null if the rectangle doesn't overlap the grid. Free to use.

getCell

public java.awt.Point getCell(long millis,
                              java.util.TimeZone timeZone,
                              boolean lenient)
Returns the grid cell that contains date (which must be within the grids date span)

Parameters:
millis - The date/time.
timeZone - The time zone to use. null uses the zone for the grid.
lenient - If false the method returns null if date is outside the visual range. If true the method returns either the first or last cell depending on if date is before or after the visual range.
Returns:
The cell. point.x is the column and point.y is the row. Can be null if lenient == false

getPrimaryDimensionPosition

public int getPrimaryDimensionPosition(long millis,
                                       java.util.TimeZone timeZone,
                                       java.lang.Integer forceSecDimCell)
Returns the position that date corresponds to in the primary dimension. Wraps the position if forceSecDimCell == null so that is is always inside the bounds.

Parameters:
millis - The date/time that are to be translated into a position. Can be outside of the grid's date range.
timeZone - The time zone to use. null uses the zone for the grid.
forceSecDimCell - If non-null disables secondary dimention wrap and returns a position relative to forceSecDim row/column. Thus if date is outside of the date range that this row/column spans, the returned postions will be < bounds.x or > (bounds.x + bounds.width).
Returns:
The position that corresponds to date.

getBoundsForDateRange

public java.awt.Rectangle[] getBoundsForDateRange(DateRangeI range,
                                                  int cellSizeMode)
Returns the bounds that exactly contains the dateBounds.

Will return the bounds with forDraw set to false which means that the bounds are as they would be for filling a shape, not one pixel less as it would be if it was for drawing (Java2D).

Parameters:
range - The date range for which to return the "wrapped" bounds. end date must be same of after start date (i.e. sorted). If null return the bounds for "now". The date range will be cut but the grids date bounds so the returned rectangles will all be within this grid's bounds.
cellSizeMode - The size and placement of the returned outline. Eg. Grid.SIZE_MODE_INSIDE
Returns:
One rectangle for every row/column depending on if the primary dimension is horizontal or vertical, respectively. For instance if dateBounds only spans one row/column the length of the returned array will be 1. Never null but length can be 0 if range does not overlap the date range of the grid.

getBoundsForDateRange

public java.awt.Rectangle[] getBoundsForDateRange(DateRangeI range,
                                                  int cellSizeMode,
                                                  boolean rowExpand,
                                                  boolean forDraw)
Returns the bounds that exactly contains the dateBounds.

Parameters:
range - The date range for which to return the "wrapped" bounds. end date must be same of after start date (i.e. sorted). If null the bounds for "now" will be returned. The date range will be cut but the grids date bounds so the returned rectangles will all be within this grid's bounds.
cellSizeMode - The size and placement of the returned outline. Eg. Grid.SIZE_MODE_INSIDE
rowExpand - If true the rectangle for every row in the secondary dimension will be expanded to the size it would get if not clipped for the grid bounds and the row/column would not wrap. To compare to with text, it is the same thing as to return the bounds for every text row that would be if all text was unwrapped to only be on that row.
forDraw - If the bounds are for drawing, in which case it will normally be one pixel smaller due to the stoke paint algorithm in Java2D.
Returns:
One rectangle for every row/column depending on if the primary dimension is horizontal or vertical, respectively. For instance if dateBounds only spans one row/column the length of the returned array will be 1. Never null but length can be 0 if range does not overlap the date range of the grid.
Since:
6.0

getBoundingBoxForDateRange

public java.awt.Rectangle getBoundingBoxForDateRange(DateRangeI range,
                                                     int cellSizeMode)
Returns the smallest bounding box that includes all of range. If range is outside of this grid's date range it will be cut of by it.

Will return the bounds with forDraw set to false which means that the bounds are as they would be for filling a shape, not one pixel less as it would be if it was for drawing (Java2D). Only if range does not overlap the date range of thid grid null will be returned.

Parameters:
range - The date range to return the bounding box for. If null return the cell outline for "now".
cellSizeMode - The size and placement of the returned outline. Eg. Grid.SIZE_MODE_INSIDE
Returns:
The bounds or null if range does not overlap the date range of the grid.
See Also:
getOutlineForDateRange(com.miginfocom.util.dates.DateRangeI, int, boolean)

getBoundingBoxForDateRange

public java.awt.Rectangle getBoundingBoxForDateRange(DateRangeI range,
                                                     int cellSizeMode,
                                                     boolean forDraw)
Returns the smallest bounding box that includes all of range. If range is outside of this grid's date range it will be cut of by it. Only if range does not overlap the date range of thid grid null will be returned.

Parameters:
range - The date range to return the bounding box for. If null return the cell outline for "now".
cellSizeMode - The size and placement of the returned outline. Eg. Grid.SIZE_MODE_INSIDE
forDraw - If the bounds are for drawing, in which case it will normally be one pixel smaller due to the stoke paint algorithm in Java2D.
Returns:
The bounds or null if range does not overlap the date range of the grid.
Since:
6.0
See Also:
getOutlineForDateRange(com.miginfocom.util.dates.DateRangeI, int, boolean)

getOutlineForDateRange

public java.awt.Polygon getOutlineForDateRange(DateRangeI range,
                                               int cellSizeMode,
                                               boolean forDraw)
Returns the outline for a date range. Always on the cell edges in the grid.

Parameters:
range - The date range. If null return the cell outline for "now". Cut to be within the grids date range.
cellSizeMode - The size and placement of the returned outline. Eg. Grid.SIZE_MODE_INSIDE
forDraw - If the bounds are for drawing, in which case it will normally be one pixel smaller due to the stoke paint algorithm in Java2D.
Returns:
The outline for a date range. Always on the cell edges in the grid. null if dateRange does not overlap the grid's date range.
Since:
6.0
See Also:
getBoundingBoxForDateRange(com.miginfocom.util.dates.DateRangeI, int)

getCellsForDateRange

public java.awt.Point[] getCellsForDateRange(DateRangeI range)
Returns start and end cell for a date range.

Parameters:
range - The date range. If null return the cells for "now". Cut to be within the grids date range.
Returns:
Start and end cell for a date range or null if range does not overlap the date range of the grid.
Since:
6.0
See Also:
getBoundingBoxForDateRange(com.miginfocom.util.dates.DateRangeI, int), getOutlineForDateRange(com.miginfocom.util.dates.DateRangeI, int, boolean)

createGridLinesAndCellRows

protected void createGridLinesAndCellRows()
Description copied from class: AbstractGrid
Implement this to create the cell rows and grid lines. This method will be called the first time setBounds is called and MUST initialize cells and gridRows to the correct sizes.

Set cellRows and gridLines with AbstractGrid.setCellRows(int, GridRow[]) and AbstractGrid.setGridLines(int, GridLine[]).

Specified by:
createGridLinesAndCellRows in class AbstractGrid


Copyright © 2009 MiG InfoCom AB. All Rights Reserved.