7 datetime

The datetime object (class name dmw_datetime) provides a simple and intuitive way to enter dates and times. It can display date or time values or both in different formats. Besides keyboard input, the user can change the values, for example by selecting a date from a calendar (upper datetime object in “Figure 13-4”) or using spin buttons (lower datetime object in “Figure 13-4”). In addition, the user can be enabled to set the value to indefinite using a checkbox (right part of “Figure 13-4”).

Figure 13-4: datetime objects

“Figure 13-5” shows a datetime object with the calendar unfolded. The appearance of the calendar can be adjusted by several attributes. For example, in the right part of “Figure 13-5”, the numbers of the calendar weeks and the current date are displayed in the calendar.

Figure 13-5: datetime object with opened calendar

The presentation of the date and time values can be controlled using a format string. You can use predefined system formats or define own display formats using the corresponding formatting characters. In both cases, the language and region settings of the system are taken into account (for example, for the month names). “Figure 13-6” shows datetime objects with formats that contain extra, non-editable text in addition to parts of the date or time.

Figure 13-6: datetime objects with different formats

Availability

Microsoft Windows only.
Can only be used with the USW option of the ISA Dialog Manager.
The idmwidgets.dll must be in the USW class path (default: <IDM installation directory>\uswclasses).

7.1 Definition

{ export | reexport } { model } dmw_datetime { <Identifier> }
{
  <standard attributes>
  <geometry attributes>
  <hierarchy attributes>
  <layout attributes>
  <text attributes>
  <object-specific attributes>
}

Events	changed	deselect	extevent
Events	focus	help	select
Children	None
Parent	groupbox	layoutbox	notepage
Parent	splitbox	toolbar	window
Menu	Pop-up Menu

7.2 Description of Events

7.2.1 deselect

The deselect event occurs when the datetime has lost the focus. This is an indication that the user has completed entering or selecting the date or time. However, it should be noted that this event is not only triggered by direct user actions, but may also occur as a side effect of other actions:

The user sets the focus with the mouse or keyboard to another object.
The user activates another application or another application pushes itself into the foreground and captures the focus.

Note

Opening a menu or pop-up does not necessarily move the focus. Therefore, it cannot be predicted whether a deselect event will occur for these actions. For example, a deselect event may not be triggered until the select event rule of a menuitem is executed, if it is triggered at all.

7.2.2 select

The select event will occur each time the content of the .value attribute changes. The event can be triggered by various actions of the user:

The user edits the value in the input field of the datetime.
The user navigates in the calendar to reach a specific date.
The user selects a value with mouse or keyboard.
The user scrolls the spinbox of the datetime.

This means that multiple select events will typically occur before the user has entered, set or selected the final value. Therefore, the event rule for the select event should not perform any extensive actions.

The .real_modified attribute can be used to check whether the value of the datetime has actually changed due to the user actions, compared to the value of the datetime when it received the focus.

The select event may also occur if .minvalue or .maxvalue are violated. This depends on the system object, but here too a content change of .value must be present.

7.3 Inherited Attributes

Attribute	Data Type	Notes
.accelerator	object
.bgc	object	is ignored
.borderraster	boolean
.control	object
.count[attribute]	anyvalue
.cursor	object
.cut_pending	boolean
.cut_pending_changed	boolean
.dialog	object
.document[integer]	object
.export	boolean
.fgc	object	is ignored
.firstrecord	object
.focus	boolean
.focus_on_click	boolean
.font	object
.function	object
.function[integer]	object
.groupbox	object
.height	integer
.help	string
.index	index
.label	string
.lastrecord	object
.mapped	boolean
.menu[integer]	object
.model	object
.module	object
.navigable	boolean
.notepage	object
.parent	object
.posraster	boolean
.real_height	integer
.real_path[string]	string
.real_sensitive	boolean
.real_visible	boolean
.real_width	integer
.record[integer]	object
.recordcount	object
.reexport	object
.scope	object
.sensitive	boolean
.sizeraster	boolean
.source	object
.statushelp	string
.target	object
.toolbar	object
.toolhelp	object
.transformer[integer]	object
.type[anyvalue]	datatype
.userdata	anyvalue
.visible	boolean
.width	integer
.window	object
.xauto	integer
.xleft	integer
.xright	integer
.yauto	integer
.ybottom	integer
.ytop	integer

7.4 Specific Attributes

Attribute	Short Description	Data Type	Default	Access		C	I
Attribute	Short Description	Data Type	Default	get	set	C	I
.allowundefined	acceptance of indefinite values	boolean	false	x	x	x	x
.calendaralignment	position of the calendar	integer (-1, 0, 1)	1	x	x	x	x
.format	display format	string	""	x	x	x	x
.maxvalue	maximum value	string	""	x	x	x	x
.minvalue	minimum value	string	""	x	x	x	x
.real_modified	indicates actual change of .value	boolean		x	–	–	–
.shortdaynames	display of short weekday names	boolean	false	x	x	x	x
.style	value input through a fold-out calendar or a spinbox	class (poptext, spinbox)	poptext	x	x	x	x
.today	display of current date	boolean	true	x	x	x	x
.todaymarker	highlighting of current date	boolean	true	x	x	x	x
.trailingdates	display days of previous and next month	boolean	true	x	x	x	x
.value	date and/or time value	string	""	x	x	x	x
.weeknumbers	display of calendar week	boolean	false	x	x	x	x
C	changed event on modification	I	Attribute is inherited