DateTime controls

Use a DateTime control to provide a formatted date field that allows easy date selection. In addition, the DateTime control displays a drop-down calender that can be used to select a date.

DateTime controls are represented by Control objects in the ArcPad object model and by DATETIME elements in ArcPad Extensible Markup Language (XML).

Attributes

DateTime control attributes are set at design time in ArcPad Studio on the Control Properties dialog box. They cannot be changed at run time (some attributes have corresponding properties that can be accessed and changed at run time). For more information, see Attributes vs. properties.

Attributes beginning with "on" (for example, onchange) are used to specify the script to run when an event occurs. These attributes are set in the Events page on the Control Properties dialog box. Attributes are written to the customization file (layer definition, applet, default configuration) in ArcPad XML format.

The following table shows the available DateTime control attributes and descriptions:

Attributes	Descriptions
name	The DateTime control name. Used to reference the DateTime control in scripts.
width	The control's width.
height	The controls's height.
x	The x-coordinate of the upper left corner of the control.
y	The y-coordinate of the upper left corner of the control.
sip	Specifies if the soft input panel (SIP) displays on pen devices when the control gets the focus.
required	Specifies if the user must select a date for the control.
allownulls	Specifies if the control can accept a null value.
defaultvalue	A simple expression that specifies the default value for the control.
tabstop	Specifies if the TAB key can be used to move the focus to the control.
group	Specifies if the control starts a new group of controls.
border	Specifies if the control has a border.
readonly	Specifies if the control's value can be modified by the user.
field	The field of the shapefile's database file format (DBF) table that is linked to the control.
backgroundcolor	The background color to use for the control. If not specified, this value is inherited from the page's backgroundcolor attribute.
color	The color to use for the control's text. If not specified, this value is inherited from the page's color attribute.
font	The font to use for the control's text. If not specified, this value is inherited from the page's font attribute.
fontsize	The font size to use for the control's text. If not specified, this value is inherited from the page's fontsize attribute.
fontstyle	The font style to use for the control's text. If not specified, this value is inherited from the page's fontstyle attribute.
onchange	The script to run when an OnChange event occurs.
oncloseup	The script to run when an OnCloseUp event occurs.
ondropdown	The script to run when an OnDropDown event occurs.
onsetfocus	The script to run when an OnSetFocus event occurs.
onkillfocus	The script to run when an OnKillFocus event occurs.
onvalidate	The script to run when an OnValidate event occurs.

Events

DateTime controls generate a range of events as they are operating. You can specify a script to run when any of these events occur in the Events page on the Control Properties dialog box.

The following table shows the available DateTime control events and descriptions:

Events	Descriptions
OnChange	Occurs when the user selects a date in the control.
OnCloseUp	Occurs when the drop-down calender is closed.
OnDropDown	Occurs when the drop-down calender is displayed.
OnKillFocus	Occurs when the control loses the focus.
OnSetFocus	Occurs when the control gets the focus.
OnValidate	Occurs when the control is validated.

Properties

DateTime control properties can be read and set at run time via scripts.

The following table shows the available DateTime control properties and descriptions:

Properties	Descriptions
DefaultValue	Returns or sets the default value expression for the control.
Enabled	Returns or sets a value that determines if the control is enabled.
Field	Returns a reference to the feature attribute field to which the control is bound.
hWnd	Returns the control's window handle.
Index	Returns the control's index.
Name	Returns the control's name.
Parent	Returns a reference to the page that contains the control.
Text	Returns the date currently displayed in the control.
Type	Returns the control type ("DATETIME" for a DateTime control).
Value	Returns the date currently displayed in the control.
Visible	Returns or sets a value that determines if the control is visible.

Methods

DateTime control methods can be called at run time via scripts.

The following table shows the available DateTime control method and description:

Method	Description
SetFocus	Sets the focus to the control.

Referencing a DateTime control

You can only reference a DateTime control in a form that is currently displayed. Attempting to reference a DateTime control in a form that is not currently displayed results in a runtime error. The following discusses the approaches (Direct and Event) to referencing a DateTime control.

Direct reference

This involves referencing a DateTime control via its name, page's name, form's name, and form's parent object. For example, use the following code to reference a DateTime control with the name "dtDateAdded" on a page with the name "pgPage1" in a form with the name "frmSettings" that is present in an applet with the name "Custom Settings":

VBScript

Dim objForm 
Set objForm = Applet.Forms("frmSettings")
Dim objPage
Set objPage = objForm.Pages("pgPage1")
Dim objDateTime
Set objDateTime = objPage.Controls("dtDateAdded")

JScript

var objForm = Applet.Forms("frmSettings");
var objPage = objForm.Pages("pgPage1");
var objDateTime = objPage.Controls("dtDateAdded");

Python

objForm = Applet.Forms("frmSettings")
objPage = objForm.Pages("pgPage1")
objDateTime = objPage.Controls("dtDateAdded")

The previous code assumes that it is present in the applet (that is, in the .apa file or its associated script file). If you need to reference the same DateTime control from a different applet or other customization file, explicitly reference the applet. See the following code:

VBScript

Dim objApplet
Set objApplet = Application.Applets("Custom Settings")
Dim objForm 
Set objForm = objApplet.Forms("frmSettings")
Dim objPage
Set objPage = objForm.Pages("pgPage1")
Dim objDateTime
Set objDateTime = objPage.Controls("dtDateAdded")

JScript

var objApplet = Application.Applets("Custom Settings");
var objForm = objApplet.Forms("frmSettings");
var objPage = objForm.Pages("pgPage1");
var objDateTime = objPage.Controls("dtDateAdded");

Python

objApplet = Application.Applets("Custom Settings")
objForm = objApplet.Forms("frmSettings")
objPage = objForm.Pages("pgPage1")
objDateTime = objPage.Controls("dtDateAdded")

Event reference

This involves referencing a DateTime control in an event handling script. For example, use the following code to reference a DateTime control in its OnChange event handler:

VBScript

Dim objDateTime
Set objDateTime = ThisEvent.Object

JScript

var objDateTime = ThisEvent.Object;

Python

objDateTime = ThisEvent.Object

Use the following code to reference a DateTime control with the name "dtDateAdded" on a page with the name "pgPage1" in the OnLoad event handler of its form:

VBScript

Dim objPage
Set objPage = ThisEvent.Object.Pages("pgPage1")
Dim objDateTime 
Set objDateTime = objPage.Controls("dtDateAdded")

JScript

var objPage = ThisEvent.Object.Pages("pgPage1");
var objDateTime = objPage.Controls("dtDateAdded");

Python

objPage = ThisEvent.Object.Pages("pgPage1")
objDateTime = objPage.Controls("dtDateAdded")

Initializing a DateTime control

DateTime control initialization involves setting particular DateTime properties when the control first displays. Generally, the OnLoad event handler of the page or form is the most appropriate place to do this. For example, the following code displays a DateTime control with the name "dtDateAdded" with today's date when called in the page's OnLoad event handler:

VBScript

Dim objControls
Set objControls = ThisEvent.Object.Controls 
objControls("dtDateAdded").Enabled = Now

JScript

var objControls = ThisEvent.Object.Controls;
var dtDate = new Date();
var strToday = (dtDate.getMonth() + 1) + "/";
strToday += dtDate.getDate() + "/";
strToday += dtDate.getYear();
objControls("dtDateAdded").Value = strToday;

Python

objControls = ThisEvent.Object.Controls
objControls("dtDateAdded").Enabled = datetime.date.today()

The following code displays a DateTime control with the name "dtDateAdded" with the date April 20th, 2001 when called in the page's OnLoad event handler:

VBScript

Dim objControls
Set objControls = ThisEvent.Object.Controls 
objControls("dtDateAdded").Value = CDate(#04/20/2001#)

JScript

var objControls = ThisEvent.Object.Controls; 
var dtDate = new Date("4/20/2001");
objControls("dtDateAdded").Value = dtDate.getVarDate();

Python

objControls = ThisEvent.Object.Controls
objControls("dtDateAdded").Value = datetime.date(2001, 4, 20)