MiG InfoCom Calendar Tutorial User Manual
MiG InfoCom AB
MiG Calendar™ Tutorial
______________________________________________________________
Release 6
MiG Calendar Tutorial Page 1 / 24
MiG InfoCom AB
MiG InfoCom AB
S:t Olofsgatan 28a
753 32 Uppsala
Sweden
www.miginfocom.com
COPYRIGHT © MiG InfoCom AB.
All rights reserved.
Java is a trademark registered ® to Sun Microsystems.
http://java.sun.com
MiG Calendar Tutorial Page 2 / 24
MiG InfoCom AB
Table of Contents
MiG Calendar Tutorial......................................................... 5
Preface.......................................................................................................... 5
Resources and Developer Support............................................................. 5
Contacting Support via Email............................................................... 5
Contacting support via online forums................................................... 5
World Wide Web.................................................................................. 6
Bug Reports......................................................................................... 6
Class hierarchy design notes..................................................................... 6
Easy to Extend..................................................................................... 6
Method Signatures............................................................................... 6
Immutability.......................................................................................... 6
Return type philosophy........................................................................ 6
Theme Implementation........................................................................ 7
Rows vs Rows & Columns................................................................... 7
Date Ranges........................................................................................ 7
The DateAreaContainer – keeps it all together.......................................... 7
Scroll pane........................................................................................... 7
Mix in components anywhere............................................................... 8
Calendar Combo Box................................................................................... 8
Date picker........................................................................................... 8
Date Spinners............................................................................................... 8
Headers – labeling the Date Area................................................................ 9
Primary and secondary dimension....................................................... 9
Themes................................................................................................ 9
DateArea....................................................................................................... 9
The heart.............................................................................................. 9
The Grid and its GridRows........................................................................ 10
Grid and DateGrid.............................................................................. 10
MiG Calendar Tutorial Page 3 / 24
MiG InfoCom AB
GridRows........................................................................................... 10
GridSegments.................................................................................... 10
Grid lines............................................................................................ 11
Sub grid rows..................................................................................... 11
Activities and ActivityViews...................................................................... 11
Activity class....................................................................................... 11
ActivityView class............................................................................... 12
Activity views are expendables.......................................................... 12
More than one bounds....................................................................... 12
Time Zones................................................................................................. 12
ActivityDepository...................................................................................... 13
Where Activities are found................................................................. 13
Subscriptions..................................................................................... 13
ActivityIOFilters.................................................................................. 14
Resolving version conflicts................................................................. 14
Laying out the ActivityViews..................................................................... 14
Point to time to pixels......................................................................... 14
More than one layout simultaneously................................................. 14
More then one level............................................................................15
Decorators – layered painting................................................................... 16
AShape – attributed graphics graph......................................................... 16
Interactions – how the user interacts....................................................... 18
Geometry Package and Coordinates........................................................ 19
Categories – hierarchical tags for Activities............................................ 20
Themes – advanced hierarchical properties............................................ 21
Theme Editor – GUI for Themes................................................................ 22
Utility Classes – things you may find useful...........................................23
Putting it all together................................................................................. 24
MiG Calendar Tutorial Page 4 / 24
MiG InfoCom AB
MiG Calendar Tutorial
Preface
This document describes the main parts that makes out the MiG
Calendar component. Is does not go into great detail of every function,
it aims to give a thorough understanding how the different packages
and classes relate to each other and what is their purpose.
The Technical Specification is more suited for details and should be
used as a reference. It can be found at the web site indicated below
and should also normally be installed adjacent to this document.
Currently the UML JavaDoc is used a the technical specification. It will
be converted to a PDF at a later time.
For a getting started fast please see the Getting Started Guide which is
normally co-located at the same places as described above. The
Getting Stated Guide has code examples on how to get up and
running.
Many IDE:s (Integrated Development Environment) of today have
good support for inline help using javadocs. The standard HTML
javadocs for the MiG Calendar component is installed by default and
can also be obtained from the site as described above and below. We
highly recommend using this feature as it increases productively when
creating applications with this component.
Although all developers independent of prior experience can benefit
from reading this document, general knowledge of the standard Java
API and OOP (Object Oriented Programming) will help understanding
some of details, or why they are implemented in a certain way.
Resources and Developer Support
MiG InfoCom AB provides support through email and the online
forums. Information and updated tutorials will be made available on
the MiG Calendar product site
Contacting Support directly via Email
support@miginfocom.com
Submit a support ticket
http://www.migcalendar.com/support.php
MiG Calendar Tutorial Page 5 / 24
MiG InfoCom AB
MiG Calendar Product Site
www.migcalendar.com
Bug Reports
Please submit a support ticket.
Class hierarchy design notes
Easy to Extend
MiG Calendar has been developed to be easy to extend and still easy
to understand. Class design at large is similar to that of Swing’s.
Interfaces are used for places where the implementation should be
able to be switched and abstract base classes normally implements
boiler plate functionality giving the user the option to re-implement
everything by using the interface or just what matters by extending the
abstract base class.
Method Signatures
You will notice that the method signatures normally are a bit longer
that usual, with more options and boolean flags in them. Having one
method with more options compared to one method per option will
make extending that class easier since there is only one method to
override rather than many chained ones.
There is usually more than one way to change the behavior of some
class. There are the normal get/set methods that are used for simple
properties. Often the classes can be overridden to change the
behavior and for the bigger changes the implementations can be
exchanged via ‘add/remove concrete implementation’ pattern.
Immutability
Immutable objects are used extensively in MiG Calendar. Immutable
objects can not change once created and are therefore thread safe
and less bug prone due to accidental changes. The downside is that
the constructors can be rather lengthy, but that is a price we are willing
to pay for stability and simplicity.
Return type philosophy
Defensive copying (cloning) of objects returned from method calls is
normally the case, but not always. For instance getting the bounds of
an ActivityView returns the ‘live’ object. The reason for this is
performance. The bounds will be read thousands of times per second
MiG Calendar Tutorial Page 6 / 24
MiG InfoCom AB
in high activity count date areas and making a copy for every call will
produce too much garbage and the garbage collector will introduce
‘hiccups’. The javadoc documentation will clearly state when a
returned object should be treated as read only.
Theme Implementation
Themes are implemented in MiG Calendar by sub classes to the
themed classes. For instance there is a ThemeDateArea that
extends DefaultDateArea and imposes the indicated properties
in the provided theme on its base class. This is normally the design
pattern for themes, extend and configure. This way the MiG Calendar
component can be used just as easily with and without theme support.
Rows vs Rows & Columns
The term rows is used for denoting something one dimensional, it
does necessarily mean that it is horizontal. The reason for this is the
fact that for instance the Grid object can have either a horizontal or
vertical primary dimension. Which dimension is the primary is a
property of the Grid and if it would have been mutable the grid could
be transposed just by changing the primary dimension. Therefore it
would be very confusing to try to use the terms rows and columns.
The terms primary and secondary are used to express which of the
dimensions you mean.
Date Ranges
Date range and DateRange are used throughout this tutorial and
everywhere else in the MiG Calendar nomenclature. Even though
'date' is the word used, time is also always included unless explicitly
said otherwise. There are no classes in the MiG Calendar component
that only handles whole dates and thus discards time-of-day.
The DateAreaContainer – keeps it all together
The DateAreaContainer is handling Headers, a date area and
corner components. The four headers are on every side around the
DateArea and typically contains dates, times or other labeling
information. The headers can extend into zero, one or both of its
adjacent corners. The four corners can be used for any
JComponent making it easy for the user to customize the container.
Scroll pane
The scroll pane from the DateArea is the actual component residing
in the middle of the date container, though it is rarely any need to
MiG Calendar Tutorial Page 7 / 24
MiG InfoCom AB
address it explicitly for layout purposes. The scroll bars for that scroll
pane is relocated from the scroll pane to outside the right and lower
header respectively.
Mix in components anywhere
The container is using GridBagLayout and the javadoc for
DateAreaContainer contains the grid rows and columns used for
positioning the contained headers, corners and the DateArea.
This makes it very easy to add you own components anywhere within
the container, even between the header and DateArea if you like.
You can put the anywhere.
Calendar Combo Box
Date picker
A combo box that inherits from JPanel but look much like a normal
JComboBox. It tries to tweak parts of it's visual appearance to blend
in with the most common Look&Feels. It contains a
DateAreaContainer and shows it in the popup window, just like a
regular JComboBox would. It is created from scratch rather than
extend JComboBox due to experienced troubles when trying to
extend JComboBox.
The combo supports plus/minus buttons as well as a 'go to today'
button. The date format for the editor is exchangeable and is
implemented as a JFormattedTextField. The editor's text field
can be used to edit a to/from date range.
Date Spinners
The included date spinners vastly surpasses what is available in the
standard J2SE SDK. Multiple spinners can be combined and coupled
to express one date/time or one spinner can be used to edit a
complex date format.
The spinners are simple to use and are located int the
calendar.spinner package.
Headers – labeling the Date Area
A header is comparable to a normal table header in that it decorates
and labels the DateArea. The Header interface is very small, it
MiG Calendar Tutorial Page 8 / 24
Loading...