widgets/cdatetime/content/operation.html

<h2>Selection versus 'Full' Selection</h2>
<p>
	A java.util.Date object may encapsulate a moment in time, but specifying it may take several steps as
	a user sets each field individually.  A java.util.Calendar object is a little closer to what we are used
	to using in the real-world, and is therefore closer to how a Date is selected with the CDateTime widget.<br/>
	Consider how a user may navigate a table with the cursor: selection moves between rows and/or cells
	until it reaches the one the user wants to activate, at which point they press (for example) <code>ENTER</code>.
	Likewise, a user may navigate past severals dates/times before reaching the one they are really
	trying to select.  When the user reaches this selection, they will indicate it by what I've called
	a 'Full' selection, meaning that every field is being selected.<br/>
	Different components of the CDateTime
	widget consider a 'Full' selection differently simply because users interact with them differently.
	A 'Full' selection notifies listeners via the widgetDefaultSelected interface and their occurence will 
	be pointed out in the following text.
</p>

<h2>Text Operation</h2>
<div style="margin-left: 10px;">
	<p>
		Depending upon the pattern, or format, set on the CDateTime widget, the textual selector allows the
		user to select any form of date and/or time.
	</p>
	<table width='100%' style="margin-bottom:5px">
		<tr align='center'>
			<td><img src="images/CDateTime_text.png"></td>
			<td><img src="images/CDateTime_text_spinner.png"></td>
			<td><img src="images/CDateTime_text_dropdown.png"></td>
		</tr>
		<tr align='center'>
			<td>As plain as it gets</td>
			<td>ooo, that's exciting</td>
			<td>And a button!</td>
		</tr>
	</table>
	<p>
		When the CDateTime gains focus by a means other than a mouse click (such as tabbing through
		a form), its entire text area is selected.  The intent is to allow it to be copied and has the
		side affect that no field is actually selected, and thus the CDateTime cannot be 
		edited.  When the CDateTime looses focus, by any means, all fields are unselected and again,
		the CDateTime cannot be edited.  Before editing, an individual field must be selected.<br>
	<div>
		<p>Field Selection via Mouse:</p>
		<ul style="margin-left: 30px;">
			<li>Select any field with a direct mouse click</li>
			<li>Clicking the center mouse button will cycle through the fields</li>
		</ul>	
	</div>
	<div>
		<p>Field Selection via Keyboard:</p>
		<ul style="margin-left: 30px;">
			<li>The left and right arrow keys move one field at time</li>
			<li>If the style TAB_FIELDS is set, then the Tab key will move to the next field (and from
			the last field to the next widget)</li>
			<li>Typing the first character of the next separation sequence will move to the next field.<div>
			For example, given the pattern "MM/dd/yy", pressing the '/' key will move to the next field.</div>
			Likewise, given the pattern "MM'long separation sequence'dd'another long sequence'yy",
			typing 'l' when on the "MM" field will move to the "dd" field, and then typing 'a' will
			move to the last field.</li>
			<li>If the user is entering the value of the field via the keyboard and the maximum number of
			digits for that field have been typed, selection is automatically moved to the next field.</li>
		</ul>
	</div>
	<div>
		<p>Field Editing via Mouse:</p>
		<ul style="margin-left: 30px;">
			<li>Scrolling with the mouse wheel will increment and decrement the field</li>
		</ul>
		<p>Field Editing via Keyboard:</p>
		<ul style="margin-left: 30px;">
			<li>The Up and Down arrow keys will increment and decrement the field</li>
			<li>The "+" and "-" keys will increment and decrement the field</li>
			<li>The "=" key will increment the field (i18n problem?)</li>
			<li>Enter the numerical value directly with the keyboard
			<div>Note that the text of the field will convert to a 2 digit number (except for year, which will become
			4 digits) while being edited.  This allows for consistent behavious regardless of the set pattern.</div></li>
			<li>If the style DROP_DOWN is not set and SPINNER is, then a Spinner widget can be used to increment and decrement the field</li>
		</ul>
	</div>
	<div>
		<p>Full Selection:</p>
		<ul style="margin-left: 30px;">
			<li>When the user presses the <code>ENTER</code> key (like a normal SWT Text widget)</li>
		</ul>
	</div>
	<div>
		<p>Null Values:</p>
		<p>
		When the selection is set to null, the text shows a translatable string as shown below.<br/>
		The biggest problem with a null value in a date/time selector is how go back to an actual value.
		This is because it cannot always be done in a single user action and the value of the selection could 
		be left in an undefined state.  CDateTime deals with this by simply holding on to the value of the 
		selection before it was set to null, and restores it upon any user interaction.  This way, there will
		be a value which is always valid and can be modified one field at a time; it is also the most relative
		value to start from rather than always resetting to the current date/time.
		</p>
		<div align="center">
			<img src="images/CDateTime_text_null.png"><br>
			CDateTime displaying a null selection value
		</div>
	</div>
</div>

<h2>Combo Operation</h2>
<div style="margin-left: 10px;">
	<div>
		<p>Opening the Drop Shell:</p>
		<ul style="margin-left: 30px;">
			<li>Mouse - when the drop button is clicked</li>
			<li>Keyboard - when &lt;CTRL-SPACE&gt; key combination is typed</li>
		</ul>
	</div>
	<div>
		<p>Full Selection:</p>
		<ul style="margin-left: 30px;">
			<li>When a Full Selection is made on the Graphical component</li>
			<li>When the drop button is clicked</li>
		</ul>
	</div>
	<div>
		<p>Cancellation:</p>
		When the graphical selector is dropped, the current selection is saved.<br/>
		While the user is editing the selection, regular selection events will be fired and
		the textual selector will be updated to reflect these changes.  If the user closes
		the graphcial selector in a way that does not fire a Full Selection, then this will 
		be interpretted as a cancallation and the selection will be restored to its previous 
		value (this will fire a regular selection so external listeners may be restored as well).
	</div>
</div>
<h2>Graphical Operation</h2>
<h2>Calendar</h2>
<div style="margin-left: 10px;">
	<p>The user is able to select a date (year, month, and day) by selecting a day on the calendar.</p>
	<table width='100%'>
		<tr align='center'>
			<td><img src="images/CDateTime_calendar.png"></td>
			<td><img src="images/CDateTime_calendar_compact.png"></td>
		</tr>
		<tr align='center'>
			<td>Standard Calendar</td>
			<td>Compact style Calendar</td>
		</tr>
	</table>
	<div>
		<p>Navigation via Mouse:</p>
		<ol>
			<li>Clicking the Left and Right Arrows in the upper left increments/decrements the Month</li>
			<li>Clicking the Round Button between the Arrows set the selection to the Current Date</li>
			<li>Clicking the Month Label brings up a Context Menu with all 12 months</li>
			<li>Scrolling the mouse wheel over the Month Label increments/decrements the Month</li>
			<li>Scrolling the mouse wheel over the Year Label increments/decrements the Year</li>
			<li>Scrolling the mouse wheel over the Days scrolls the visible dates by 1 Week</li>
			<li>Alt-Clicking the Days brings up a Context Menu to set selection to the Current Date</li>
		</ol>
		<p>Navigation via Keyboard:</p>
		<ol>
			<li>The Left and Right Arrow Keys (on the keyboard) increment/decrement the selected Day</li>
			<li>The Up and Down Arrow Keys (on the keyboard) increment/decrement the selected Week</li>
			<li>The Page UP and Page Down Keys scrolls the visible dates by 4 weeks</li>
			<li>The Home and End Keys scrolls the visible dates by 52 weeks</li>
			<li>Selecting the Year Label switches to Year Edit Mode where the year can be entered via the
			keyboard - clicking anywhere other than on the Accept button will cancel the edit (Escape and
			Carriage Return work as expected).
			<div align="center">
				<img src="images/CDateTime_header-editYear_gtk.png"><br>
				The CDateTime Header when editing the Year via Keyboard
			</div>
		</ol>
	</div>
	<div>
		<p>Full Selection via Mouse:</p>
		<ul style="margin-left: 30px;">
			<li>When a day button has the focus and the user presses the <code>ENTER</code> key</li>
		</ul>
		<p>Full Selection via Keyboard:</p>
		<ul style="margin-left: 30px;">
			<li>When the user clicks a day button with the primary mouse button</li>
			<li>When the user clicks the "Today" menu option (shown by alt-mouse clicking on a day button)</li>
			<li>When the user clicks the "Today" button with the primary mouse button</li>
		</ul>
	</div>
</div>

<h2>Analog Clock</h2>
<div style="margin-left: 10px;">
	<div>
		<p>The user is able to select a time (hour, minute, and second) by dragging the hands of the clock with the mouse.</p>
		<table width='100%'>
			<tr align='center'>
				<td><img src="images/CDateTime_clock_spinner.png"></td>
				<td><img src="images/CDateTime_clock_24_compact_spinner.png"></td>
			</tr>
			<tr align='center'>
				<td>Digital Readout with Spinner</td>
				<td>Compact, 24 Hour style with Spinner</td>
			</tr>
		</table>
	</div>
	<div>
		<p>The user may also set the selection in other ways:</p>
		<ol>
			<li>If the clock is of 12 Hour style, then the AM_PM field may toggled by the button on the dial</li>
			<li>If the SPINNER style was set, then the spinner can be used to increment and decrement the time</li>
			<li>The time can also be incremented and decremented by scrolling the mouse wheel over the dial</li>
			<li>The time can be set current by clicking the "Now" button</li>
		</ol>
		<p>Full Selection:</p>
		<ul style="margin-left: 30px;">
			<li>When the user selects the "Now" menu option (shown by alt-mouse clicking on the clock dial)</li>
			<li>When the user clicks the "Now" button</li>
		</ul>
	</div>
</div>		

<h2>Discrete Clock</h2>
<div style="margin-left: 10px;">
	<p align="center">
		<img src="images/CDateTime_clock_discrete.png"><br>
		The Discrete Clock (held open for the screen-shot with <code>setHoldOpen(true)</code>)
	</p>
	<p align="center">
		<img src="images/CDateTime_clock_24_discrete.png"><br>
		The 24 Hour style (Romanian Locale) Discrete Clock
	</p>
	<p>
		Full Selection:
		<ul style="margin-left: 30px;">
			<li>When the button for the last unselected field is selected</li>
		</ul>
	</p>
</div>