Calendar Blocks Design Spec

CollectionCanvas, wxCollectionCanvas, CanvasItem

This base class might be abstract, but provides common functionality for blocks that want to present an ItemCollection in a format that requires custom drawing. The base class manages basic interaction with the block's contents, an ItemCollection.

• Responsibilities
  • manages selection
  • responds to selection events, generates selection events (CollectionCanvas)
  • manages a current range, the index into the collection
  • manages a list of elements (bounds + an item reference) to handle hit testing
  • manages drag and drop
  • handles paint events (wxCollectionCanvas)

• wxCollectionCanvas: a base class for the widget used to draw the items, a subclass of wxScrolledWindow.
  • key methods of wxCollectionCanvas
    • OnPaint (which calls DrawBackground and DrawCells)
  • methods subclasses of wxCollectionCanvas need to define:
    • DrawBackground
    • DrawCells

• CollectionCanvas: a base class for blocks that want to present an item collection. Keeps track of the selection and the current index.
  • Block Events (CollectionCanvas)
    • posts SelectionChanged events
    • responds to SelectionChanged events

• CanvasItem: helper class used to manage the bounds of an Item in the canvas, and a reference to that item. This object is not responsible for drawing the item, but used for hit testing. In many of our use cases, the drawing code needs access to multiple Items at once. This minimal class is not abstract, and as long as a rect is enough for hit testing, this class can be used directly.

CalendarBlock, wxCalendarBlock

These classes also might be abstract. They CollectionCanvas and wxCollectionCanvas, and provide common functionality for blocks that want to present an ItemCollection that requires custom drawing and is browsed by time range.

• Responsibilities
  • all of the responsibilities of the CollectionCanvas classes
  • managing a selected date range

• wxCalendarBlock: the widget
  • responsibilities
    • manages buttons and handlers to move around in time (next, prev, go to today, etc.)
  • key methods
    • OnNext
    • OnPrev
    • OnToday

• CalendarBlock: the block
  • key attributes:
    • rangeStart: the start of the range
    • rangeIncrement: the increment used when moving to the "next" or "previous" unit of time
  • key methods:
    • incrementRange
    • decrementRange
    • isDateInRange
    • setRange: Sets the current date range to include the given date. In practice, overridden by subclasses to pick the start of the range appropriately.
    • getItems: gets items from the collection by date (may be moved into the collection api, currently scaffolding)
  • Block Events (CalendarBlock)
    • posts SelectedDateChanged events
    • responds to SelectedDateChanged events

WeekBlock, wxWeekBlock

These classes implement the block that displays a week of items. The block can be parameterized to be a different # of days, including just one day. A wireframe of the block: week block wireframe

• wxWeekBlock
  • notes
    • the week block widget is a parent widget that contains two separate subwidgets, each of which needs to scroll independently.
  • key methods
    • _doDrawingCalculations: sets common drawing calculations based on the current size of the view.
    • DrawBackground: Draws the background for the whole week.
    • DrawCells: Sets up a cell for each day. Calculates the rect for each cell (day), and calls DrawDay for each cell (day).
    • DrawDay: Responsible for drawing one day. Is given a rect in which to draw the day. Asks the item collection for all of the items on this day. Is responsible for creating a CanvasItem (bounds rect) for each item placed on the calendar during the day. Note that this method is called during the paint cycle, as the widget is responding to a paint event.

• WeekBlock
  • key methods:
    • setRange: overrides this method to pick the first day of the week that includes the given day as the start of the range.

MonthBlock, wxMonthBlock

These classes implement the block that displays a month of items. A wireframe of the block: month block wireframe

• wxMonthBlock
  • notes
    • the month block does not scroll (but subclassed from wxScrolledWindow)
  • key methods
    • _doDrawingCalculations: sets common drawing calculations based on the current size of the view.
    • DrawBackground: Draws the background for the whole month.
    • DrawCells: Sets up a cell for each day. Calculates the rect for each cell (day), and calls DrawDay for each cell (day).
    • DrawDay: Responsible for drawing one day. Is given a rect in which to draw the day. Asks the item collection for all of the items on this day. Is responsible for creating a CanvasItem (bounds rect) for each item placed on the calendar during the day. Note that this method is called during the paint cycle, as the widget is responding to a paint event.

• MonthBlock
  • key methods:
    • setRange: overrides this method to pick the first day of the month that includes the given day as the start of the range.

CanvasTextButton, CanvasBitmapButton

The calendar blocks need to make use of very flat looking buttons, some with dynamic text and others with images. We've created two button subclasses (both are actually subclasses of wx.BitmapButton) to get the appropriate functionality. The text button creates an empty bitmap on the fly, and uses wx.MemoryDC to write the text into the bitmap.

-- KatieCappsParlante - 18 Jul 2004