






DPCPTimeChooser
Component for Adobe® Flex 2.0.1



Instructions




Prepared by: 	Patrick J. Winter, Deer Park Central Projects (DPCP)
		www.dpcp.ca/flex



Date:		2008-02-14



Contents

1.	INTRODUCTION	3
1.1.	DOCUMENT PURPOSE	3
1.2.	AUDIENCE	3
1.3.	DISCLAIMER, LICENSE & WARRANTY INFO	3
1.3.1.	Summary	3
1.3.2.	All-caps pompous legal verbiage	3
1.4.	PRICE	4
2.	REQUIREMENTS	4
3.	DESCRIPTION AND USE	5
4.	FILES	6
5.	INSTRUCTIONS	7
5.1.	RUNNING THE DEMO APP: FLEX BUILDER	7
5.2.	RUNNING THE DEMO APP: MXMLC COMMAND LINE	10
5.3.	USE THE COMPONENT IN YOUR OWN APP	11







Document Revision History

Last printed 2008-02-14 12:21 PM

Version       1.0                                     1.0b                                                                          
Date          2008-01-31                              2008-02-14                                                                    
Author        Patrick J. Winter                       "                                                                             
Distribution  General                                 "                                                                             
Notes         Initial version for component 1.1.0     Update disclaimer & license section; add warranty; misc. instruction touch-ups


1. Introduction
1.1. Document Purpose
This document explains how to use the DPCPTimeChooser, a user interface component (or control) built for Adobe® Flex 2.0.1 that provides a simple way for users to select the time of day.

This document outlines the following:
* How the DPCPTimeChooser component looks and behaves
* The files included in the DPCPTimeChooser download .zip file
* How to use the included files
* How to use the DPCPTimeChooser in your own application

1.2. Audience
This document’s intended audience is developers experienced in Adobe® Flex 2.0.1, both using the Flex SDK and Flex Builder.

1.3. Disclaimer, License & Warranty Info
1.3.1. Summary
Use entirely at your own risk (“your” being your own and your organization’s, if applicable).

Do not distribute or make available to others, except compiled into your own applications after a license has been purchased.

90-day money-back guarantee (less intermediary transaction fees).
1.3.2. All-caps pompous legal verbiage

“YOU” AND “YOUR” MEAN “YOU AND YOUR ORGANIZATION” AND “YOUR OWN AND YOUR ORGANIZATION’S” RESPECTIVELY.

“THE COMPONENT” MEANS THE DPCPTIMECHOOSER COMPONENT (INCLUDING THE .SWC FILE AND ALL OTHER FILES PROVIDED IN THE DOWNLOAD .ZIP FILE) IN ALL ITS VERSIONS (PAST, CURRENT, AND FUTURE).

THE COMPONENT IS PROVIDED AS-IS, AND IS USED BY YOU ENTIRELY AT YOUR OWN RISK. BY USING THE COMPONENT YOU ALSO ASSUME ALL RESPONSIBILITY FOR ANY AND ALL SOFTWARE CREATED USING THE COMPONENT, INCLUDING ANY AND ALL DAMAGES TO ANY AND ALL PARTIES RESULTING FROM THAT SOFTWARE’S USE OR MISUSE, WHETHER CAUSED BY THE COMPONENT OR OTHERWISE.

BY DOWNLOADING AND/OR USING THE COMPONENT YOU AGREE TO NOW AND FOREVER ABSOLVE DEER PARK CENTRAL PROJECTS (DPCP) AND ITS OWNERS, PARTNERS, EMPLOYEES, ASSOCIATES, AND AFFILIATES OF ANY AND ALL DAMAGES ARISING THROUGH THE USE OR MISUSE OF THE COMPONENT, DIRECTLY OR INDIRECTLY, HOWSOEVER CAUSED. 

YOU ALSO AGREE NOT TO DISTRIBUTE OR MAKE AVAILABLE TO OTHERS ANY VERSIONS OF THE COMPONENT, EXCEPT COMPILED INTO YOUR OWN APPLICATIONS. YOU AGREE NOT TO DECOMPILE, REVERSE ENGINEER, OR OTHERWISE “HACK” THE COMPONENT SO AS TO ALTER THE COMPONENT FOR DISTRIBUTION AND/OR REPRESENTATION AS YOUR OWN WORK.

THE COMPONENT IS NOT FREE. YOU MAY USE THE COMPONENT FOR AN EVALUATION PERIOD OF THIRTY (30) DAYS FROM THE TIME OF FIRST DOWNLOAD, AFTER WHICH YOU MUST PURCHASE A LICENSE TO CONTINUE USING IT.

DEER PARK CENTRAL PROJECTS WARRANTS TO LICENSEES THAT THE COMPONENT WILL PERFORM SUBSTANTIALLY IN ACCORDANCE WITH THE DOCUMENTATION, AND TO LICENSEES’ SATISFACTION, FOR THE NINETY (90) DAY PERIOD FOLLOWING LICENSE PURCHASE WHEN USED ON A SYSTEM MEETING THE SPECIFIED REQUIREMENTS. YOU ARE ENCOURAGED TO MAKE USE OF THE EVALUATION PERIOD IN DETERMINING THE COMPONENT’S SUITABILITY FOR YOUR PURPOSES, BEFORE PURCHASING A LICENSE. ALL WARRANTY CLAIMS MUST BE MADE WITHIN SUCH NINETY (90) DAY PERIOD. IF THE COMPONENT DOES NOT PERFORM AS WARRANTED ABOVE, THE ENTIRE LIABILITY OF DEER PARK CENTRAL PROJECTS AND LICENSEES’ EXCLUSIVE REMEDIES SHALL BE LIMITED TO THE REFUND OF THE LICENSE FEE PAID TO DEER PARK CENTRAL PROJECTS FOR THE COMPONENT, WHERE SUCH REFUND CAN BE MADE THROUGH THE SAME INTERMEDIARY AS ORIGINAL PAYMENT WAS RECEIVED (E.G. PAYPAL), LESS ANY INTERMEDIARY TRANSACTION FEES (E.G. PAYPAL, TYPICALLY 2.9% OR LESS). UPON RECEIPT OF SUCH REFUND, LICENSE IS REVOKED AND FORMER LICENSEES AGREE TO IMMEDIATELY DELETE AND CEASE USING ALL COPIES OF THE COMPONENT, WHETHER OR NOT THE INITIAL EVALUATION PERIOD HAS EXPIRED.

1.4. Price
The DPCPTimeChooser component is not free.
You may use it for an evaluation period of 30 days from the time of first download, after which you must purchase a license to continue using it.

For further information please visit:
www.dpcp.ca/flex
2. Requirements
DPCPTimeChooser was built using the Flex 2.0.1 SDK. It may work with other versions (e.g. 2.0, 3.0) but has not been tested.

SWF files using the DPCPTimeChooser play in Flash Player 9. They may work with other versions (e.g. 7, 8) but have not been tested.

3. Description and use
The DPCPTimeChooser provides a simple way for users to select the time of day. It works in both 12-hour (with AM/PM) and 24-hour modes.

In its unset state, the component looks like this:


Clicking either the clock or the dropdown box shows a list of times in half-hour intervals:


Once a time has been selected, the component looks like this:


At this point the user can interact with the component in several ways:
* Changing the hour via the numeric stepper (values from 1 to 12)
* Changing the minutes via the input field (including all values from 00 through 59)
* Changing AM/PM via the radio buttons
* Selecting a time directly by clicking on the clock (which reveals the dropdown list), or selecting the “none” (no time selected) option from the list


Behaviour in 24-hour mode is similar, except that there is no AM/PM option and the hours numeric stepper goes from 0 to 23:



4. Files
The following files are included in the DPCPTimeChooser .ZIP file:

#
Name
Purpose
1.
dpcpTimeChooser.swc
The DPCPTimeChooser’s compiled component .SWC file for use in compiling your apps
2.
DPCPTimeChooser.properties
Resource file containing language/locale specific strings and settings (e.g. 12-hour or 24-hour, hour/minute separator ‘:’ or ‘.’, etc.)
Documentation
3.
dpcpTimeChooser_Instructions.pdf
Instructions (this file)
4.
dpcpTimeChooser_Instructions.txt
Text version of the above
5.
asdoc-output/
Directory containing DPCPTimeChooser class documentation (HTML)
6.
asdoc-output/index.html
Start page of DPCPTimeChooser class documentation
Samples
7.
demo_timechooser.mxml
Demo Flex app showing ways to use the DPCPTimeChooser
8.
demo_timechooser-flex-config_SAMPLE.xml
Sample config file for use with mxmlc command line compiler
9.
demo_timechooser.htm
HTML wrapper file for viewing compiled demo app .SWF
10.
AC_OETags.js
Standard JavaScript file used by HTML wrapper

5. 
Instructions
Unzip the contents of the DPCPTimeChooser .ZIP file to a directory of your choice. (If you’re reading this you’ve probably already done that.)
5.1. Running the demo app: Flex Builder
If you use the Flex Builder IDE:

1.) In Flex Builder, create a new project:

a.) Select File > New > Flex Project.

b.) Leave the “Basic” radio button selected, and click Next.

c.) Enter a project name, e.g. “Demo TimeChooser”, and use either the default location or specify your own location as desired.

d.) In Windows Explorer, copy demo_timechooser.mxml file into the new project's location (directory). In this example we use C:\flex.

e.) Back in Flex Builder, in the New Flex Project window, for Main Application File click Browse and select demo_timechooser.mxml.


f.) On the Source Path tab, click Add Folder and add the location of the DPCPTimeChooser.properties file.




g.) On the Library Path tab, click Add SWC and select the dpdpTimeChooser.swc file.


h.) Click Finish.

2.) Once it has finished building the workspace, select Run > Run demo_timechooser (or hit Ctrl+F11) to run the project. It should look like the one at:
www.dpcp.ca/flex/DPCPTimeChooser/demo

3.) NOTE: If you edit the .PROPERTIES file, for the updates to be reflected you may need to remove its location from the project's Source Path and then re-add it:
a.) Project > Properties > Flex Build Path > Source Path tab: click Remove, then OK
b.) Project > Properties > Flex Build Path > Source Path tab: click Add Folder, then re-specify the folder.


5.2. Running the demo app: mxmlc command line
If you use the Flex SDK command line compiler (mxmlc):

1.) Edit the sample config file provided (demo_timechooser-flex-config_SAMPLE.xml) and update all the items marked TODO to reflect the directories of your own Flex installation.

2.) Open a Flex SDK command prompt window, change to the directory where you unzipped the files, and build the project: 
mxmlc -load-config demo_timechooser-flex-config_SAMPLE.xml -output demo_timechooser.swf -- demo_timechooser.mxml


3.) View the .SWF result by opening the HTML wrapper file demo_timechooser.htm (or opening the .SWF directly in the browser). It should look like the one at:
www.dpcp.ca/flex/DPCPTimeChooser/demo

5.3. Use the component in your own app

1.) Add the dpcpTimeChooser.swc file to your project’s Library Path: select 
Project > Properties > Flex Build Path > Library Path tab: click Add SWC and browse to the file.

2.) Add the location (path) of the DPCPTimeChooser.properties file to your project’s Source Path: select Project > Properties > Flex Build Path > Source Path tab: click Add Folder and browse to the location of the file.

3.) In your MXML or ActionScript code file that will be using the DPCPTimeChooser, add an import statement (this may be done automatically for you):
import ca.dpcp.components.DPCPTimeChooser;

4.) Add code to instantiate and use one or more DPCPTimeChooser components, e.g.:
var tc : DPCPTimeChooser = new DPCPTimeChooser();
this.addChild( tc );
See the ActionScript code in  demo_timechooser.mxml for examples of use.

5.) See the documentation for method and property explanations, also available at: 
www.dpcp.ca/flex/DPCPTimeChooser/docs
DPCPTimeChooser component instructions				DPCP

Document Version 1.0b, 2008-02-14	Page 9 of 11

C:\_pjw\_dpcp\dev\flex\comp\dpcpTimeChooser\docs\dpcpTimeChooser_Instructions.doc	

Deer Park Central Projects		Document  Version 1.0b
2008-02-14
www.dpcp.ca

