widgets/cdatetime/content/patterns.html

<p>
	There are two methods for setting which components of a date and/or a time you want your users
	to be able to select: 1. the easy way; or 2. the other way.
</p>

<h2>1. The Easy Way: Specify a Format, and let the JRE figure out the pattern</h2>
<p>
	CDateTime.setFormat accepts a single bit-wise OR-ed <code>int</code> corresponding to the three types of java.util.DateFormat:
</p>
<table style="margin-left: 10px;">
	<tr><td>CDateTime.setFormat(CDT.DATE_XXX)</td><td><img src="/eclipse.org-common/themes/Phoenix/images/arrow.gif"/>DateFormat.getDateInstance(DateFormat.XXX)</td></tr>
	<tr><td>CDateTime.setFormat(CDT.TIME_XXX)</td><td><img src="/eclipse.org-common/themes/Phoenix/images/arrow.gif"/>DateFormat.getTimeInstance(DateFormat.XXX)</td></tr>
	<tr><td>CDateTime.setFormat(CDT.DATE_XXX | CDT.TIME_YYY)</td><td><img src="/eclipse.org-common/themes/Phoenix/images/arrow.gif"/></td></tr>
	<tr><td></td><td>DateFormat.getDateTimeInstance(DateFormat.XXX, DateFormat.YYY)</td></tr>
</table>
<p>
	CDT.java contains the following style constants:
</p>
<table style="margin:0 0 10px 10px;">
	<tr><td>DATE_SHORT</td><td style="padding-left: 25px;">TIME_SHORT</td></tr>
	<tr><td>DATE_MEDIUM</td><td style="padding-left: 25px;">TIME_MEDIUM</td></tr>
	<tr><td>DATE_LONG</td><td style="padding-left: 25px;"><s>TIME_LONG</s> (there is no corresponding DateFormat)</td></tr>
</table>
<p>
	Example:<br />
	<code style="margin-left: 10px;">CDateTime cdt = new CDateTime(parent, CDT.BORDER | CDT.DROP_DOWN);</code><br />
	<code style="margin-left: 10px;">cdt.setFormat(CDT.TIME_SHORT);</code>
</p>
<img src='images/CDateTime_time_dropped_win32.png' /><br />
<p>
	Note that date and time styles can also be used in the constructor:<br />
</p>
<p>
	<code>new CDateTime(parent, CDT.BORDER | CDT.DROP_DOWN | CDT.TIME_SHORT);</code>
</p>

<h2>2. The Other Way: Specify the exact pattern</h2>
<p>
	Under the covers, CDateTime uses java.text.SimpleDateFormat to format its text and assist in 
	the navigation of its fields.  Because of this, any pattern that can be passed to
	SimpleDateFormat can be used (refer to the
	<a href="http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat Javadoc</a>)
</p>
<p>
	Example:<br />
	<code style="margin-left: 10px;">CDateTime cdt = new CDateTime(parent, CDT.BORDER | CDT.DROP_DOWN);</code><br />
	<code style="margin-left: 10px;">cdt.setPattern("'Meeting on' EEEE, MMMM d '@' h:mm 'in the'a");</code>
</p>
<img src='images/CDateTime_complex_pattern.png' /><br />
<p>
	Caveats and Special Considerations:
</p>
<ul style="margin-left: 10px;">
	<li>Due to the two parameter paradigm of SWT there is no way to pass a pattern into the constructor</li>
	<li>Although inc/dec is supported, typing characters currently is not (ie: typing 'w' above will not select 'wednesday')</li>
	<li><u>Secondary</u> Calendar Fields <em>are</em> linked: changing the 'day of the week' field <em>will</em> change the 'date' field</li>
	<li>There may not be a graphical compliment to every text field! (file an enhancement request)</li>
</ul>