git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

Commit	Line	Data
	1	#----------------------------------------------------------------------------
	2	# Name: timectrl.py
	3	# Author: Will Sadkin
	4	# Created: 09/19/2002
	5	# Copyright: (c) 2002 by Will Sadkin, 2002
	6	# RCS-ID: $Id$
	7	# License: wxWindows license
	8	#----------------------------------------------------------------------------
	9	# NOTE:
	10	# This was written way it is because of the lack of masked edit controls
	11	# in wxWindows/wxPython. I would also have preferred to derive this
	12	# control from a wxSpinCtrl rather than wxTextCtrl, but the wxTextCtrl
	13	# component of that control is inaccessible through the interface exposed in
	14	# wxPython.
	15	#
	16	# TimeCtrl does not use validators, because it does careful manipulation
	17	# of the cursor in the text window on each keystroke, and validation is
	18	# cursor-position specific, so the control intercepts the key codes before the
	19	# validator would fire.
	20	#
	21	# TimeCtrl now also supports .SetValue() with either strings or wxDateTime
	22	# values, as well as range limits, with the option of either enforcing them
	23	# or simply coloring the text of the control if the limits are exceeded.
	24	#
	25	# Note: this class now makes heavy use of wxDateTime for parsing and
	26	# regularization, but it always does so with ephemeral instances of
	27	# wxDateTime, as the C++/Python validity of these instances seems to not
	28	# persist. Because "today" can be a day for which an hour can "not exist"
	29	# or be counted twice (1 day each per year, for DST adjustments), the date
	30	# portion of all wxDateTimes used/returned have their date portion set to
	31	# Jan 1, 1970 (the "epoch.")
	32	#----------------------------------------------------------------------------
	33	# 12/13/2003 - Jeff Grimmett (grimmtooth@softhome.net)
	34	#
	35	# o Updated for V2.5 compatability
	36	# o wx.SpinCtl has some issues that cause the control to
	37	# lock up. Noted in other places using it too, it's not this module
	38	# that's at fault.
	39	#
	40	# 12/20/2003 - Jeff Grimmett (grimmtooth@softhome.net)
	41	#
	42	# o wxMaskedTextCtrl -> MaskedTextCtrl
	43	# o wxTimeCtrl -> TimeCtrl
	44	#
	45
	46	"""<html><body>
	47	<P>
	48	<B>TimeCtrl</B> provides a multi-cell control that allows manipulation of a time
	49	value. It supports 12 or 24 hour format, and you can use wxDateTime or mxDateTime
	50	to get/set values from the control.
	51	<P>
	52	Left/right/tab keys to switch cells within a TimeCtrl, and the up/down arrows act
	53	like a spin control. TimeCtrl also allows for an actual spin button to be attached
	54	to the control, so that it acts like the up/down arrow keys.
	55	<P>
	56	The <B>!</B> or <B>c</B> key sets the value of the control to the current time.
	57	<P>
	58	Here's the API for TimeCtrl:
	59	<DL><PRE>
	60	<B>TimeCtrl</B>(
	61	parent, id = -1,
	62	<B>value</B> = '12:00:00 AM',
	63	pos = wxDefaultPosition,
	64	size = wxDefaultSize,
	65	<B>style</B> = wxTE_PROCESS_TAB,
	66	<B>validator</B> = wxDefaultValidator,
	67	name = "time",
	68	<B>fmt24hr</B> = False,
	69	<B>spinButton</B> = None,
	70	<B>min</B> = None,
	71	<B>max</B> = None,
	72	<B>limited</B> = None,
	73	<B>oob_color</B> = "Yellow"
	74	)
	75	</PRE>
	76	<UL>
	77	<DT><B>value</B>
	78	<DD>If no initial value is set, the default will be midnight; if an illegal string
	79	is specified, a ValueError will result. (You can always later set the initial time
	80	with SetValue() after instantiation of the control.)
	81	<DL><B>size</B>
	82	<DD>The size of the control will be automatically adjusted for 12/24 hour format
	83	if wxDefaultSize is specified.
	84	<DT><B>style</B>
	85	<DD>By default, TimeCtrl will process TAB events, by allowing tab to the
	86	different cells within the control.
	87	<DT><B>validator</B>
	88	<DD>By default, TimeCtrl just uses the default (empty) validator, as all
	89	of its validation for entry control is handled internally. However, a validator
	90	can be supplied to provide data transfer capability to the control.
	91	<BR>
	92	<DT><B>fmt24hr</B>
	93	<DD>If True, control will display time in 24 hour time format; if False, it will
	94	use 12 hour AM/PM format. SetValue() will adjust values accordingly for the
	95	control, based on the format specified.
	96	<BR>
	97	<DT><B>spinButton</B>
	98	<DD>If specified, this button's events will be bound to the behavior of the
	99	TimeCtrl, working like up/down cursor key events. (See BindSpinButton.)
	100	<BR>
	101	<DT><B>min</B>
	102	<DD>Defines the lower bound for "valid" selections in the control.
	103	By default, TimeCtrl doesn't have bounds. You must set both upper and lower
	104	bounds to make the control pay attention to them, (as only one bound makes no sense
	105	with times.) "Valid" times will fall between the min and max "pie wedge" of the
	106	clock.
	107	<DT><B>max</B>
	108	<DD>Defines the upper bound for "valid" selections in the control.
	109	"Valid" times will fall between the min and max "pie wedge" of the
	110	clock. (This can be a "big piece", ie. <b>min = 11pm, max= 10pm</b>
	111	means <I>all but the hour from 10:00pm to 11pm are valid times.</I>)
	112	<DT><B>limited</B>
	113	<DD>If True, the control will not permit entry of values that fall outside the
	114	set bounds.
	115	<BR>
	116	<DT><B>oob_color</B>
	117	<DD>Sets the background color used to indicate out-of-bounds values for the control
	118	when the control is not limited. This is set to "Yellow" by default.
	119	</DL>
	120	</UL>
	121	<BR>
	122	<BR>
	123	<BR>
	124	<DT><B>EVT_TIMEUPDATE(win, id, func)</B>
	125	<DD>func is fired whenever the value of the control changes.
	126	<BR>
	127	<BR>
	128	<DT><B>SetValue(time_string \| wxDateTime \| wxTimeSpan \| mx.DateTime \| mx.DateTimeDelta)</B>
	129	<DD>Sets the value of the control to a particular time, given a valid
	130	value; raises ValueError on invalid value.
	131	<EM>NOTE:</EM> This will only allow mx.DateTime or mx.DateTimeDelta if mx.DateTime
	132	was successfully imported by the class module.
	133	<BR>
	134	<DT><B>GetValue(as_wxDateTime = False, as_mxDateTime = False, as_wxTimeSpan=False, as mxDateTimeDelta=False)</B>
	135	<DD>Retrieves the value of the time from the control. By default this is
	136	returned as a string, unless one of the other arguments is set; args are
	137	searched in the order listed; only one value will be returned.
	138	<BR>
	139	<DT><B>GetWxDateTime(value=None)</B>
	140	<DD>When called without arguments, retrieves the value of the control, and applies
	141	it to the wxDateTimeFromHMS() constructor, and returns the resulting value.
	142	The date portion will always be set to Jan 1, 1970. This form is the same
	143	as GetValue(as_wxDateTime=True). GetWxDateTime can also be called with any of the
	144	other valid time formats settable with SetValue, to regularize it to a single
	145	wxDateTime form. The function will raise ValueError on an unconvertable argument.
	146	<BR>
	147	<DT><B>GetMxDateTime()</B>
	148	<DD>Retrieves the value of the control and applies it to the DateTime.Time()
	149	constructor,and returns the resulting value. (The date portion will always be
	150	set to Jan 1, 1970.) (Same as GetValue(as_wxDateTime=True); provided for backward
	151	compatibility with previous release.)
	152	<BR>
	153	<BR>
	154	<DT><B>BindSpinButton(wxSpinBtton)</B>
	155	<DD>Binds an externally created spin button to the control, so that up/down spin
	156	events change the active cell or selection in the control (in addition to the
	157	up/down cursor keys.) (This is primarily to allow you to create a "standard"
	158	interface to time controls, as seen in Windows.)
	159	<BR>
	160	<BR>
	161	<DT><B>SetMin(min=None)</B>
	162	<DD>Sets the expected minimum value, or lower bound, of the control.
	163	(The lower bound will only be enforced if the control is
	164	configured to limit its values to the set bounds.)
	165	If a value of <I>None</I> is provided, then the control will have
	166	explicit lower bound. If the value specified is greater than
	167	the current lower bound, then the function returns False and the
	168	lower bound will not change from its current setting. On success,
	169	the function returns True. Even if set, if there is no corresponding
	170	upper bound, the control will behave as if it is unbounded.
	171	<DT><DD>If successful and the current value is outside the
	172	new bounds, if the control is limited the value will be
	173	automatically adjusted to the nearest bound; if not limited,
	174	the background of the control will be colored with the current
	175	out-of-bounds color.
	176	<BR>
	177	<DT><B>GetMin(as_string=False)</B>
	178	<DD>Gets the current lower bound value for the control, returning
	179	None, if not set, or a wxDateTime, unless the as_string parameter
	180	is set to True, at which point it will return the string
	181	representation of the lower bound.
	182	<BR>
	183	<BR>
	184	<DT><B>SetMax(max=None)</B>
	185	<DD>Sets the expected maximum value, or upper bound, of the control.
	186	(The upper bound will only be enforced if the control is
	187	configured to limit its values to the set bounds.)
	188	If a value of <I>None</I> is provided, then the control will
	189	have no explicit upper bound. If the value specified is less
	190	than the current lower bound, then the function returns False and
	191	the maximum will not change from its current setting. On success,
	192	the function returns True. Even if set, if there is no corresponding
	193	lower bound, the control will behave as if it is unbounded.
	194	<DT><DD>If successful and the current value is outside the
	195	new bounds, if the control is limited the value will be
	196	automatically adjusted to the nearest bound; if not limited,
	197	the background of the control will be colored with the current
	198	out-of-bounds color.
	199	<BR>
	200	<DT><B>GetMax(as_string = False)</B>
	201	<DD>Gets the current upper bound value for the control, returning
	202	None, if not set, or a wxDateTime, unless the as_string parameter
	203	is set to True, at which point it will return the string
	204	representation of the lower bound.
	205
	206	<BR>
	207	<BR>
	208	<DT><B>SetBounds(min=None,max=None)</B>
	209	<DD>This function is a convenience function for setting the min and max
	210	values at the same time. The function only applies the maximum bound
	211	if setting the minimum bound is successful, and returns True
	212	only if both operations succeed. <B><I>Note: leaving out an argument
	213	will remove the corresponding bound, and result in the behavior of
	214	an unbounded control.</I></B>
	215	<BR>
	216	<DT><B>GetBounds(as_string = False)</B>
	217	<DD>This function returns a two-tuple (min,max), indicating the
	218	current bounds of the control. Each value can be None if
	219	that bound is not set. The values will otherwise be wxDateTimes
	220	unless the as_string argument is set to True, at which point they
	221	will be returned as string representations of the bounds.
	222	<BR>
	223	<BR>
	224	<DT><B>IsInBounds(value=None)</B>
	225	<DD>Returns <I>True</I> if no value is specified and the current value
	226	of the control falls within the current bounds. This function can also
	227	be called with a value to see if that value would fall within the current
	228	bounds of the given control. It will raise ValueError if the value
	229	specified is not a wxDateTime, mxDateTime (if available) or parsable string.
	230	<BR>
	231	<BR>
	232	<DT><B>IsValid(value)</B>
	233	<DD>Returns <I>True</I>if specified value is a legal time value and
	234	falls within the current bounds of the given control.
	235	<BR>
	236	<BR>
	237	<DT><B>SetLimited(bool)</B>
	238	<DD>If called with a value of True, this function will cause the control
	239	to limit the value to fall within the bounds currently specified.
	240	(Provided both bounds have been set.)
	241	If the control's value currently exceeds the bounds, it will then
	242	be set to the nearest bound.
	243	If called with a value of False, this function will disable value
	244	limiting, but coloring of out-of-bounds values will still take
	245	place if bounds have been set for the control.
	246	<DT><B>IsLimited()</B>
	247	<DD>Returns <I>True</I> if the control is currently limiting the
	248	value to fall within the current bounds.
	249	<BR>
	250	</DL>
	251	</body></html>
	252	"""
	253
	254	import copy
	255	import string
	256	import types
	257
	258	import wx
	259
	260	from wx.tools.dbg import Logger
	261	from wx.lib.maskededit import MaskedTextCtrl, Field
	262
	263	dbg = Logger()
	264	dbg(enable=0)
	265
	266	try:
	267	from mx import DateTime
	268	accept_mx = True
	269	except ImportError:
	270	accept_mx = False
	271
	272	# This class of event fires whenever the value of the time changes in the control:
	273	wxEVT_TIMEVAL_UPDATED = wx.NewEventType()
	274	EVT_TIMEUPDATE = wx.PyEventBinder(wxEVT_TIMEVAL_UPDATED, 1)
	275
	276	class TimeUpdatedEvent(wx.PyCommandEvent):
	277	def __init__(self, id, value ='12:00:00 AM'):
	278	wx.PyCommandEvent.__init__(self, wxEVT_TIMEVAL_UPDATED, id)
	279	self.value = value
	280	def GetValue(self):
	281	"""Retrieve the value of the time control at the time this event was generated"""
	282	return self.value
	283
	284
	285	class TimeCtrl(MaskedTextCtrl):
	286
	287	valid_ctrl_params = {
	288	'display_seconds' : True, # by default, shows seconds
	289	'min': None, # by default, no bounds set
	290	'max': None,
	291	'limited': False, # by default, no limiting even if bounds set
	292	'useFixedWidthFont': True, # by default, use a fixed-width font
	293	'oob_color': "Yellow" # by default, the default MaskedTextCtrl "invalid" color
	294	}
	295
	296	def __init__ (
	297	self, parent, id=-1, value = '12:00:00 AM',
	298	pos = wx.DefaultPosition, size = wx.DefaultSize,
	299	fmt24hr=False,
	300	spinButton = None,
	301	style = wx.TE_PROCESS_TAB,
	302	validator = wx.DefaultValidator,
	303	name = "time",
	304	**kwargs ):
	305
	306	# set defaults for control:
	307	dbg('setting defaults:')
	308	for key, param_value in TimeCtrl.valid_ctrl_params.items():
	309	# This is done this way to make setattr behave consistently with
	310	# "private attribute" name mangling
	311	setattr(self, "_TimeCtrl__" + key, copy.copy(param_value))
	312
	313	# create locals from current defaults, so we can override if
	314	# specified in kwargs, and handle uniformly:
	315	min = self.__min
	316	max = self.__max
	317	limited = self.__limited
	318	self.__posCurrent = 0
	319
	320
	321	# (handle positional args (from original release) differently from rest of kwargs:)
	322	self.__fmt24hr = fmt24hr
	323
	324	maskededit_kwargs = {}
	325
	326	# assign keyword args as appropriate:
	327	for key, param_value in kwargs.items():
	328	if key not in TimeCtrl.valid_ctrl_params.keys():
	329	raise AttributeError('invalid keyword argument "%s"' % key)
	330
	331	if key == "display_seconds":
	332	self.__display_seconds = param_value
	333
	334	elif key == "min": min = param_value
	335	elif key == "max": max = param_value
	336	elif key == "limited": limited = param_value
	337
	338	elif key == "useFixedWidthFont":
	339	maskededit_kwargs[key] = param_value
	340	elif key == "oob_color":
	341	maskededit_kwargs['invalidBackgroundColor'] = param_value
	342
	343	if self.__fmt24hr:
	344	if self.__display_seconds: maskededit_kwargs['autoformat'] = 'MILTIMEHHMMSS'
	345	else: maskededit_kwargs['autoformat'] = 'MILTIMEHHMM'
	346
	347	# Set hour field to zero-pad, right-insert, require explicit field change,
	348	# select entire field on entry, and require a resultant valid entry
	349	# to allow character entry:
	350	hourfield = Field(formatcodes='0r<SV', validRegex='0\d\|1\d\|2[0123]', validRequired=True)
	351	else:
	352	if self.__display_seconds: maskededit_kwargs['autoformat'] = 'TIMEHHMMSS'
	353	else: maskededit_kwargs['autoformat'] = 'TIMEHHMM'
	354
	355	# Set hour field to allow spaces (at start), right-insert,
	356	# require explicit field change, select entire field on entry,
	357	# and require a resultant valid entry to allow character entry:
	358	hourfield = Field(formatcodes='_0<rSV', validRegex='0[1-9]\| [1-9]\|1[012]', validRequired=True)
	359	ampmfield = Field(formatcodes='S', emptyInvalid = True, validRequired = True)
	360
	361	# Field 1 is always a zero-padded right-insert minute field,
	362	# similarly configured as above:
	363	minutefield = Field(formatcodes='0r<SV', validRegex='[0-5]\d', validRequired=True)
	364
	365	fields = [ hourfield, minutefield ]
	366	if self.__display_seconds:
	367	fields.append(copy.copy(minutefield)) # second field has same constraints as field 1
	368
	369	if not self.__fmt24hr:
	370	fields.append(ampmfield)
	371
	372	# set fields argument:
	373	maskededit_kwargs['fields'] = fields
	374
	375	# This allows range validation if set
	376	maskededit_kwargs['validFunc'] = self.IsInBounds
	377
	378	# This allows range limits to affect insertion into control or not
	379	# dynamically without affecting individual field constraint validation
	380	maskededit_kwargs['retainFieldValidation'] = True
	381
	382	# allow control over font selection:
	383	maskededit_kwargs['useFixedWidthFont'] = self.__useFixedWidthFont
	384
	385	# allow for explicit size specification:
	386	if size != wx.DefaultSize:
	387	# override (and remove) "autofit" autoformat code in standard time formats:
	388	maskededit_kwargs['formatcodes'] = 'T!'
	389
	390	# Now we can initialize the base control:
	391	MaskedTextCtrl.__init__(
	392	self, parent, id=id,
	393	pos=pos, size=size,
	394	style = style,
	395	validator = validator,
	396	name = name,
	397	setupEventHandling = False,
	398	**maskededit_kwargs)
	399
	400
	401	# This makes ':' act like tab (after we fix each ':' key event to remove "shift")
	402	self._SetKeyHandler(':', self._OnChangeField)
	403
	404
	405	# This makes the up/down keys act like spin button controls:
	406	self._SetKeycodeHandler(wx.WXK_UP, self.__OnSpinUp)
	407	self._SetKeycodeHandler(wx.WXK_DOWN, self.__OnSpinDown)
	408
	409
	410	# This allows ! and c/C to set the control to the current time:
	411	self._SetKeyHandler('!', self.__OnSetToNow)
	412	self._SetKeyHandler('c', self.__OnSetToNow)
	413	self._SetKeyHandler('C', self.__OnSetToNow)
	414
	415
	416	# Set up event handling ourselves, so we can insert special
	417	# processing on the ":' key to remove the "shift" attribute
	418	# before the default handlers have been installed, so
	419	# that : takes you forward, not back, and so we can issue
	420	# EVT_TIMEUPDATE events on changes:
	421
	422	self.Bind(wx.EVT_SET_FOCUS, self._OnFocus ) ## defeat automatic full selection
	423	self.Bind(wx.EVT_KILL_FOCUS, self._OnKillFocus ) ## run internal validator
	424	self.Bind(wx.EVT_LEFT_UP, self.__LimitSelection) ## limit selections to single field
	425	self.Bind(wx.EVT_LEFT_DCLICK, self._OnDoubleClick ) ## select field under cursor on dclick
	426	self.Bind(wx.EVT_KEY_DOWN, self._OnKeyDown ) ## capture control events not normally seen, eg ctrl-tab.
	427	self.Bind(wx.EVT_CHAR, self.__OnChar ) ## remove "shift" attribute from colon key event,
	428	## then call MaskedTextCtrl._OnChar with
	429	## the possibly modified event.
	430	self.Bind(wx.EVT_TEXT, self.__OnTextChange, self ) ## color control appropriately and EVT_TIMEUPDATE events
	431
	432
	433	# Validate initial value and set if appropriate
	434	try:
	435	self.SetBounds(min, max)
	436	self.SetLimited(limited)
	437	self.SetValue(value)
	438	except:
	439	self.SetValue('12:00:00 AM')
	440
	441	if spinButton:
	442	self.BindSpinButton(spinButton) # bind spin button up/down events to this control
	443
	444
	445
	446	def BindSpinButton(self, sb):
	447	"""
	448	This function binds an externally created spin button to the control, so that
	449	up/down events from the button automatically change the control.
	450	"""
	451	dbg('TimeCtrl::BindSpinButton')
	452	self.__spinButton = sb
	453	if self.__spinButton:
	454	# bind event handlers to spin ctrl
	455	self.__spinButton.Bind(wx.EVT_SPIN_UP, self.__OnSpinUp, self.__spinButton)
	456	self.__spinButton.Bind(wx.EVT_SPIN_DOWN, self.__OnSpinDown, self.__spinButton)
	457
	458
	459	def __repr__(self):
	460	return "<TimeCtrl: %s>" % self.GetValue()
	461
	462
	463	def SetValue(self, value):
	464	"""
	465	Validating SetValue function for time values:
	466	This function will do dynamic type checking on the value argument,
	467	and convert wxDateTime, mxDateTime, or 12/24 format time string
	468	into the appropriate format string for the control.
	469	"""
	470	dbg('TimeCtrl::SetValue(%s)' % repr(value), indent=1)
	471	try:
	472	strtime = self._toGUI(self.__validateValue(value))
	473	except:
	474	dbg('validation failed', indent=0)
	475	raise
	476
	477	dbg('strtime:', strtime)
	478	self._SetValue(strtime)
	479	dbg(indent=0)
	480
	481	def GetValue(self,
	482	as_wxDateTime = False,
	483	as_mxDateTime = False,
	484	as_wxTimeSpan = False,
	485	as_mxDateTimeDelta = False):
	486
	487
	488	if as_wxDateTime or as_mxDateTime or as_wxTimeSpan or as_mxDateTimeDelta:
	489	value = self.GetWxDateTime()
	490	if as_wxDateTime:
	491	pass
	492	elif as_mxDateTime:
	493	value = DateTime.DateTime(1970, 1, 1, value.GetHour(), value.GetMinute(), value.GetSecond())
	494	elif as_wxTimeSpan:
	495	value = wx.TimeSpan(value.GetHour(), value.GetMinute(), value.GetSecond())
	496	elif as_mxDateTimeDelta:
	497	value = DateTime.DateTimeDelta(0, value.GetHour(), value.GetMinute(), value.GetSecond())
	498	else:
	499	value = MaskedTextCtrl.GetValue(self)
	500	return value
	501
	502
	503	def SetWxDateTime(self, wxdt):
	504	"""
	505	Because SetValue can take a wxDateTime, this is now just an alias.
	506	"""
	507	self.SetValue(wxdt)
	508
	509
	510	def GetWxDateTime(self, value=None):
	511	"""
	512	This function is the conversion engine for TimeCtrl; it takes
	513	one of the following types:
	514	time string
	515	wxDateTime
	516	wxTimeSpan
	517	mxDateTime
	518	mxDateTimeDelta
	519	and converts it to a wxDateTime that always has Jan 1, 1970 as its date
	520	portion, so that range comparisons around values can work using
	521	wxDateTime's built-in comparison function. If a value is not
	522	provided to convert, the string value of the control will be used.
	523	If the value is not one of the accepted types, a ValueError will be
	524	raised.
	525	"""
	526	global accept_mx
	527	dbg(suspend=1)
	528	dbg('TimeCtrl::GetWxDateTime(%s)' % repr(value), indent=1)
	529	if value is None:
	530	dbg('getting control value')
	531	value = self.GetValue()
	532	dbg('value = "%s"' % value)
	533
	534	if type(value) == types.UnicodeType:
	535	value = str(value) # convert to regular string
	536
	537	valid = True # assume true
	538	if type(value) == types.StringType:
	539
	540	# Construct constant wxDateTime, then try to parse the string:
	541	wxdt = wx.DateTimeFromDMY(1, 0, 1970)
	542	dbg('attempting conversion')
	543	value = value.strip() # (parser doesn't like leading spaces)
	544	checkTime = wxdt.ParseTime(value)
	545	valid = checkTime == len(value) # entire string parsed?
	546	dbg('checkTime == len(value)?', valid)
	547
	548	if not valid:
	549	dbg(indent=0, suspend=0)
	550	raise ValueError('cannot convert string "%s" to valid time' % value)
	551
	552	else:
	553	if isinstance(value, wx.DateTime):
	554	hour, minute, second = value.GetHour(), value.GetMinute(), value.GetSecond()
	555	elif isinstance(value, wx.TimeSpan):
	556	totalseconds = value.GetSeconds()
	557	hour = totalseconds / 3600
	558	minute = totalseconds / 60 - (hour * 60)
	559	second = totalseconds - ((hour * 3600) + (minute * 60))
	560
	561	elif accept_mx and isinstance(value, DateTime.DateTimeType):
	562	hour, minute, second = value.hour, value.minute, value.second
	563	elif accept_mx and isinstance(value, DateTime.DateTimeDeltaType):
	564	hour, minute, second = value.hour, value.minute, value.second
	565	else:
	566	# Not a valid function argument
	567	if accept_mx:
	568	error = 'GetWxDateTime requires wxDateTime, mxDateTime or parsable time string, passed %s'% repr(value)
	569	else:
	570	error = 'GetWxDateTime requires wxDateTime or parsable time string, passed %s'% repr(value)
	571	dbg(indent=0, suspend=0)
	572	raise ValueError(error)
	573
	574	wxdt = wx.DateTimeFromDMY(1, 0, 1970)
	575	wxdt.SetHour(hour)
	576	wxdt.SetMinute(minute)
	577	wxdt.SetSecond(second)
	578
	579	dbg('wxdt:', wxdt, indent=0, suspend=0)
	580	return wxdt
	581
	582
	583	def SetMxDateTime(self, mxdt):
	584	"""
	585	Because SetValue can take an mxDateTime, (if DateTime is importable),
	586	this is now just an alias.
	587	"""
	588	self.SetValue(value)
	589
	590
	591	def GetMxDateTime(self, value=None):
	592	if value is None:
	593	t = self.GetValue(as_mxDateTime=True)
	594	else:
	595	# Convert string 1st to wxDateTime, then use components, since
	596	# mx' DateTime.Parser.TimeFromString() doesn't handle AM/PM:
	597	wxdt = self.GetWxDateTime(value)
	598	hour, minute, second = wxdt.GetHour(), wxdt.GetMinute(), wxdt.GetSecond()
	599	t = DateTime.DateTime(1970,1,1) + DateTimeDelta(0, hour, minute, second)
	600	return t
	601
	602
	603	def SetMin(self, min=None):
	604	"""
	605	Sets the minimum value of the control. If a value of None
	606	is provided, then the control will have no explicit minimum value.
	607	If the value specified is greater than the current maximum value,
	608	then the function returns 0 and the minimum will not change from
	609	its current setting. On success, the function returns 1.
	610
	611	If successful and the current value is lower than the new lower
	612	bound, if the control is limited, the value will be automatically
	613	adjusted to the new minimum value; if not limited, the value in the
	614	control will be colored as invalid.
	615	"""
	616	dbg('TimeCtrl::SetMin(%s)'% repr(min), indent=1)
	617	if min is not None:
	618	try:
	619	min = self.GetWxDateTime(min)
	620	self.__min = self._toGUI(min)
	621	except:
	622	dbg('exception occurred', indent=0)
	623	return False
	624	else:
	625	self.__min = min
	626
	627	if self.IsLimited() and not self.IsInBounds():
	628	self.SetLimited(self.__limited) # force limited value:
	629	else:
	630	self._CheckValid()
	631	ret = True
	632	dbg('ret:', ret, indent=0)
	633	return ret
	634
	635
	636	def GetMin(self, as_string = False):
	637	"""
	638	Gets the minimum value of the control.
	639	If None, it will return None. Otherwise it will return
	640	the current minimum bound on the control, as a wxDateTime
	641	by default, or as a string if as_string argument is True.
	642	"""
	643	dbg(suspend=1)
	644	dbg('TimeCtrl::GetMin, as_string?', as_string, indent=1)
	645	if self.__min is None:
	646	dbg('(min == None)')
	647	ret = self.__min
	648	elif as_string:
	649	ret = self.__min
	650	dbg('ret:', ret)
	651	else:
	652	try:
	653	ret = self.GetWxDateTime(self.__min)
	654	except:
	655	dbg(suspend=0)
	656	dbg('exception occurred', indent=0)
	657	dbg('ret:', repr(ret))
	658	dbg(indent=0, suspend=0)
	659	return ret
	660
	661
	662	def SetMax(self, max=None):
	663	"""
	664	Sets the maximum value of the control. If a value of None
	665	is provided, then the control will have no explicit maximum value.
	666	If the value specified is less than the current minimum value, then
	667	the function returns False and the maximum will not change from its
	668	current setting. On success, the function returns True.
	669
	670	If successful and the current value is greater than the new upper
	671	bound, if the control is limited the value will be automatically
	672	adjusted to this maximum value; if not limited, the value in the
	673	control will be colored as invalid.
	674	"""
	675	dbg('TimeCtrl::SetMax(%s)' % repr(max), indent=1)
	676	if max is not None:
	677	try:
	678	max = self.GetWxDateTime(max)
	679	self.__max = self._toGUI(max)
	680	except:
	681	dbg('exception occurred', indent=0)
	682	return False
	683	else:
	684	self.__max = max
	685	dbg('max:', repr(self.__max))
	686	if self.IsLimited() and not self.IsInBounds():
	687	self.SetLimited(self.__limited) # force limited value:
	688	else:
	689	self._CheckValid()
	690	ret = True
	691	dbg('ret:', ret, indent=0)
	692	return ret
	693
	694
	695	def GetMax(self, as_string = False):
	696	"""
	697	Gets the minimum value of the control.
	698	If None, it will return None. Otherwise it will return
	699	the current minimum bound on the control, as a wxDateTime
	700	by default, or as a string if as_string argument is True.
	701	"""
	702	dbg(suspend=1)
	703	dbg('TimeCtrl::GetMin, as_string?', as_string, indent=1)
	704	if self.__max is None:
	705	dbg('(max == None)')
	706	ret = self.__max
	707	elif as_string:
	708	ret = self.__max
	709	dbg('ret:', ret)
	710	else:
	711	try:
	712	ret = self.GetWxDateTime(self.__max)
	713	except:
	714	dbg(suspend=0)
	715	dbg('exception occurred', indent=0)
	716	raise
	717	dbg('ret:', repr(ret))
	718	dbg(indent=0, suspend=0)
	719	return ret
	720
	721
	722	def SetBounds(self, min=None, max=None):
	723	"""
	724	This function is a convenience function for setting the min and max
	725	values at the same time. The function only applies the maximum bound
	726	if setting the minimum bound is successful, and returns True
	727	only if both operations succeed.
	728	NOTE: leaving out an argument will remove the corresponding bound.
	729	"""
	730	ret = self.SetMin(min)
	731	return ret and self.SetMax(max)
	732
	733
	734	def GetBounds(self, as_string = False):
	735	"""
	736	This function returns a two-tuple (min,max), indicating the
	737	current bounds of the control. Each value can be None if
	738	that bound is not set.
	739	"""
	740	return (self.GetMin(as_string), self.GetMax(as_string))
	741
	742
	743	def SetLimited(self, limited):
	744	"""
	745	If called with a value of True, this function will cause the control
	746	to limit the value to fall within the bounds currently specified.
	747	If the control's value currently exceeds the bounds, it will then
	748	be limited accordingly.
	749
	750	If called with a value of 0, this function will disable value
	751	limiting, but coloring of out-of-bounds values will still take
	752	place if bounds have been set for the control.
	753	"""
	754	dbg('TimeCtrl::SetLimited(%d)' % limited, indent=1)
	755	self.__limited = limited
	756
	757	if not limited:
	758	self.SetMaskParameters(validRequired = False)
	759	self._CheckValid()
	760	dbg(indent=0)
	761	return
	762
	763	dbg('requiring valid value')
	764	self.SetMaskParameters(validRequired = True)
	765
	766	min = self.GetMin()
	767	max = self.GetMax()
	768	if min is None or max is None:
	769	dbg('both bounds not set; no further action taken')
	770	return # can't limit without 2 bounds
	771
	772	elif not self.IsInBounds():
	773	# set value to the nearest bound:
	774	try:
	775	value = self.GetWxDateTime()
	776	except:
	777	dbg('exception occurred', indent=0)
	778	raise
	779
	780	if min <= max: # valid range doesn't span midnight
	781	dbg('min <= max')
	782	# which makes the "nearest bound" computation trickier...
	783
	784	# determine how long the "invalid" pie wedge is, and cut
	785	# this interval in half for comparison purposes:
	786
	787	# Note: relies on min and max and value date portions
	788	# always being the same.
	789	interval = (min + wx.TimeSpan(24, 0, 0, 0)) - max
	790
	791	half_interval = wx.TimeSpan(
	792	0, # hours
	793	0, # minutes
	794	interval.GetSeconds() / 2, # seconds
	795	0) # msec
	796
	797	if value < min: # min is on next day, so use value on
	798	# "next day" for "nearest" interval calculation:
	799	cmp_value = value + wx.TimeSpan(24, 0, 0, 0)
	800	else: # "before midnight; ok
	801	cmp_value = value
	802
	803	if (cmp_value - max) > half_interval:
	804	dbg('forcing value to min (%s)' % min.FormatTime())
	805	self.SetValue(min)
	806	else:
	807	dbg('forcing value to max (%s)' % max.FormatTime())
	808	self.SetValue(max)
	809	else:
	810	dbg('max < min')
	811	# therefore max < value < min guaranteed to be true,
	812	# so "nearest bound" calculation is much easier:
	813	if (value - max) >= (min - value):
	814	# current value closer to min; pick that edge of pie wedge
	815	dbg('forcing value to min (%s)' % min.FormatTime())
	816	self.SetValue(min)
	817	else:
	818	dbg('forcing value to max (%s)' % max.FormatTime())
	819	self.SetValue(max)
	820
	821	dbg(indent=0)
	822
	823
	824
	825	def IsLimited(self):
	826	"""
	827	Returns True if the control is currently limiting the
	828	value to fall within any current bounds. Note: can
	829	be set even if there are no current bounds.
	830	"""
	831	return self.__limited
	832
	833
	834	def IsInBounds(self, value=None):
	835	"""
	836	Returns True if no value is specified and the current value
	837	of the control falls within the current bounds. As the clock
	838	is a "circle", both minimum and maximum bounds must be set for
	839	a value to ever be considered "out of bounds". This function can
	840	also be called with a value to see if that value would fall within
	841	the current bounds of the given control.
	842	"""
	843	if value is not None:
	844	try:
	845	value = self.GetWxDateTime(value) # try to regularize passed value
	846	except ValueError:
	847	dbg('ValueError getting wxDateTime for %s' % repr(value), indent=0)
	848	raise
	849
	850	dbg('TimeCtrl::IsInBounds(%s)' % repr(value), indent=1)
	851	if self.__min is None or self.__max is None:
	852	dbg(indent=0)
	853	return True
	854
	855	elif value is None:
	856	try:
	857	value = self.GetWxDateTime()
	858	except:
	859	dbg('exception occurred', indent=0)
	860
	861	dbg('value:', value.FormatTime())
	862
	863	# Get wxDateTime representations of bounds:
	864	min = self.GetMin()
	865	max = self.GetMax()
	866
	867	midnight = wx.DateTimeFromDMY(1, 0, 1970)
	868	if min <= max: # they don't span midnight
	869	ret = min <= value <= max
	870
	871	else:
	872	# have to break into 2 tests; to be in bounds
	873	# either "min" <= value (<= midnight of next day)
	874	# or midnight <= value <= "max"
	875	ret = min <= value or (midnight <= value <= max)
	876	dbg('in bounds?', ret, indent=0)
	877	return ret
	878
	879
	880	def IsValid( self, value ):
	881	"""
	882	Can be used to determine if a given value would be a legal and
	883	in-bounds value for the control.
	884	"""
	885	try:
	886	self.__validateValue(value)
	887	return True
	888	except ValueError:
	889	return False
	890
	891
	892	#-------------------------------------------------------------------------------------------------------------
	893	# these are private functions and overrides:
	894
	895
	896	def __OnTextChange(self, event=None):
	897	dbg('TimeCtrl::OnTextChange', indent=1)
	898
	899	# Allow wxMaskedtext base control to color as appropriate,
	900	# and Skip the EVT_TEXT event (if appropriate.)
	901	##! WS: For some inexplicable reason, every wxTextCtrl.SetValue()
	902	## call is generating two (2) EVT_TEXT events. (!)
	903	## The the only mechanism I can find to mask this problem is to
	904	## keep track of last value seen, and declare a valid EVT_TEXT
	905	## event iff the value has actually changed. The masked edit
	906	## OnTextChange routine does this, and returns True on a valid event,
	907	## False otherwise.
	908	if not MaskedTextCtrl._OnTextChange(self, event):
	909	return
	910
	911	dbg('firing TimeUpdatedEvent...')
	912	evt = TimeUpdatedEvent(self.GetId(), self.GetValue())
	913	evt.SetEventObject(self)
	914	self.GetEventHandler().ProcessEvent(evt)
	915	dbg(indent=0)
	916
	917
	918	def SetInsertionPoint(self, pos):
	919	"""
	920	Records the specified position and associated cell before calling base class' function.
	921	This is necessary to handle the optional spin button, because the insertion
	922	point is lost when the focus shifts to the spin button.
	923	"""
	924	dbg('TimeCtrl::SetInsertionPoint', pos, indent=1)
	925	MaskedTextCtrl.SetInsertionPoint(self, pos) # (causes EVT_TEXT event to fire)
	926	self.__posCurrent = self.GetInsertionPoint()
	927	dbg(indent=0)
	928
	929
	930	def SetSelection(self, sel_start, sel_to):
	931	dbg('TimeCtrl::SetSelection', sel_start, sel_to, indent=1)
	932
	933	# Adjust selection range to legal extent if not already
	934	if sel_start < 0:
	935	sel_start = 0
	936
	937	if self.__posCurrent != sel_start: # force selection and insertion point to match
	938	self.SetInsertionPoint(sel_start)
	939	cell_start, cell_end = self._FindField(sel_start)._extent
	940	if not cell_start <= sel_to <= cell_end:
	941	sel_to = cell_end
	942
	943	self.__bSelection = sel_start != sel_to
	944	MaskedTextCtrl.SetSelection(self, sel_start, sel_to)
	945	dbg(indent=0)
	946
	947
	948	def __OnSpin(self, key):
	949	"""
	950	This is the function that gets called in response to up/down arrow or
	951	bound spin button events.
	952	"""
	953	self.__IncrementValue(key, self.__posCurrent) # changes the value
	954
	955	# Ensure adjusted control regains focus and has adjusted portion
	956	# selected:
	957	self.SetFocus()
	958	start, end = self._FindField(self.__posCurrent)._extent
	959	self.SetInsertionPoint(start)
	960	self.SetSelection(start, end)
	961	dbg('current position:', self.__posCurrent)
	962
	963
	964	def __OnSpinUp(self, event):
	965	"""
	966	Event handler for any bound spin button on EVT_SPIN_UP;
	967	causes control to behave as if up arrow was pressed.
	968	"""
	969	dbg('TimeCtrl::OnSpinUp', indent=1)
	970	self.__OnSpin(wx.WXK_UP)
	971	keep_processing = False
	972	dbg(indent=0)
	973	return keep_processing
	974
	975
	976	def __OnSpinDown(self, event):
	977	"""
	978	Event handler for any bound spin button on EVT_SPIN_DOWN;
	979	causes control to behave as if down arrow was pressed.
	980	"""
	981	dbg('TimeCtrl::OnSpinDown', indent=1)
	982	self.__OnSpin(wx.WXK_DOWN)
	983	keep_processing = False
	984	dbg(indent=0)
	985	return keep_processing
	986
	987
	988	def __OnChar(self, event):
	989	"""
	990	Handler to explicitly look for ':' keyevents, and if found,
	991	clear the m_shiftDown field, so it will behave as forward tab.
	992	It then calls the base control's _OnChar routine with the modified
	993	event instance.
	994	"""
	995	dbg('TimeCtrl::OnChar', indent=1)
	996	keycode = event.GetKeyCode()
	997	dbg('keycode:', keycode)
	998	if keycode == ord(':'):
	999	dbg('colon seen! removing shift attribute')
	1000	event.m_shiftDown = False
	1001	MaskedTextCtrl._OnChar(self, event ) ## handle each keypress
	1002	dbg(indent=0)
	1003
	1004
	1005	def __OnSetToNow(self, event):
	1006	"""
	1007	This is the key handler for '!' and 'c'; this allows the user to
	1008	quickly set the value of the control to the current time.
	1009	"""
	1010	self.SetValue(wx.DateTime_Now().FormatTime())
	1011	keep_processing = False
	1012	return keep_processing
	1013
	1014
	1015	def __LimitSelection(self, event):
	1016	"""
	1017	Event handler for motion events; this handler
	1018	changes limits the selection to the new cell boundaries.
	1019	"""
	1020	dbg('TimeCtrl::LimitSelection', indent=1)
	1021	pos = self.GetInsertionPoint()
	1022	self.__posCurrent = pos
	1023	sel_start, sel_to = self.GetSelection()
	1024	selection = sel_start != sel_to
	1025	if selection:
	1026	# only allow selection to end of current cell:
	1027	start, end = self._FindField(sel_start)._extent
	1028	if sel_to < pos: sel_to = start
	1029	elif sel_to > pos: sel_to = end
	1030
	1031	dbg('new pos =', self.__posCurrent, 'select to ', sel_to)
	1032	self.SetInsertionPoint(self.__posCurrent)
	1033	self.SetSelection(self.__posCurrent, sel_to)
	1034	if event: event.Skip()
	1035	dbg(indent=0)
	1036
	1037
	1038	def __IncrementValue(self, key, pos):
	1039	dbg('TimeCtrl::IncrementValue', key, pos, indent=1)
	1040	text = self.GetValue()
	1041	field = self._FindField(pos)
	1042	dbg('field: ', field._index)
	1043	start, end = field._extent
	1044	slice = text[start:end]
	1045	if key == wx.WXK_UP: increment = 1
	1046	else: increment = -1
	1047
	1048	if slice in ('A', 'P'):
	1049	if slice == 'A': newslice = 'P'
	1050	elif slice == 'P': newslice = 'A'
	1051	newvalue = text[:start] + newslice + text[end:]
	1052
	1053	elif field._index == 0:
	1054	# adjusting this field is trickier, as its value can affect the
	1055	# am/pm setting. So, we use wxDateTime to generate a new value for us:
	1056	# (Use a fixed date not subject to DST variations:)
	1057	converter = wx.DateTimeFromDMY(1, 0, 1970)
	1058	dbg('text: "%s"' % text)
	1059	converter.ParseTime(text.strip())
	1060	currenthour = converter.GetHour()
	1061	dbg('current hour:', currenthour)
	1062	newhour = (currenthour + increment) % 24
	1063	dbg('newhour:', newhour)
	1064	converter.SetHour(newhour)
	1065	dbg('converter.GetHour():', converter.GetHour())
	1066	newvalue = converter # take advantage of auto-conversion for am/pm in .SetValue()
	1067
	1068	else: # minute or second field; handled the same way:
	1069	newslice = "%02d" % ((int(slice) + increment) % 60)
	1070	newvalue = text[:start] + newslice + text[end:]
	1071
	1072	try:
	1073	self.SetValue(newvalue)
	1074
	1075	except ValueError: # must not be in bounds:
	1076	if not wx.Validator_IsSilent():
	1077	wx.Bell()
	1078	dbg(indent=0)
	1079
	1080
	1081	def _toGUI( self, wxdt ):
	1082	"""
	1083	This function takes a wxdt as an unambiguous representation of a time, and
	1084	converts it to a string appropriate for the format of the control.
	1085	"""
	1086	if self.__fmt24hr:
	1087	if self.__display_seconds: strval = wxdt.Format('%H:%M:%S')
	1088	else: strval = wxdt.Format('%H:%M')
	1089	else:
	1090	if self.__display_seconds: strval = wxdt.Format('%I:%M:%S %p')
	1091	else: strval = wxdt.Format('%I:%M %p')
	1092
	1093	return strval
	1094
	1095
	1096	def __validateValue( self, value ):
	1097	"""
	1098	This function converts the value to a wxDateTime if not already one,
	1099	does bounds checking and raises ValueError if argument is
	1100	not a valid value for the control as currently specified.
	1101	It is used by both the SetValue() and the IsValid() methods.
	1102	"""
	1103	dbg('TimeCtrl::__validateValue(%s)' % repr(value), indent=1)
	1104	if not value:
	1105	dbg(indent=0)
	1106	raise ValueError('%s not a valid time value' % repr(value))
	1107
	1108	valid = True # assume true
	1109	try:
	1110	value = self.GetWxDateTime(value) # regularize form; can generate ValueError if problem doing so
	1111	except:
	1112	dbg('exception occurred', indent=0)
	1113	raise
	1114
	1115	if self.IsLimited() and not self.IsInBounds(value):
	1116	dbg(indent=0)
	1117	raise ValueError (
	1118	'value %s is not within the bounds of the control' % str(value) )
	1119	dbg(indent=0)
	1120	return value
	1121
	1122	#----------------------------------------------------------------------------
	1123	# Test jig for TimeCtrl:
	1124
	1125	if __name__ == '__main__':
	1126	import traceback
	1127
	1128	class TestPanel(wx.Panel):
	1129	def __init__(self, parent, id,
	1130	pos = wx.DefaultPosition, size = wx.DefaultSize,
	1131	fmt24hr = 0, test_mx = 0,
	1132	style = wx.TAB_TRAVERSAL ):
	1133
	1134	wx.Panel.__init__(self, parent, id, pos, size, style)
	1135
	1136	self.test_mx = test_mx
	1137
	1138	self.tc = TimeCtrl(self, 10, fmt24hr = fmt24hr)
	1139	sb = wx.SpinButton( self, 20, wx.DefaultPosition, (-1,20), 0 )
	1140	self.tc.BindSpinButton(sb)
	1141
	1142	sizer = wx.BoxSizer( wx.HORIZONTAL )
	1143	sizer.Add( self.tc, 0, wx.ALIGN_CENTRE\|wx.LEFT\|wx.TOP\|wx.BOTTOM, 5 )
	1144	sizer.Add( sb, 0, wx.ALIGN_CENTRE\|wx.RIGHT\|wx.TOP\|wx.BOTTOM, 5 )
	1145
	1146	self.SetAutoLayout( True )
	1147	self.SetSizer( sizer )
	1148	sizer.Fit( self )
	1149	sizer.SetSizeHints( self )
	1150
	1151	self.Bind(EVT_TIMEUPDATE, self.OnTimeChange, self.tc)
	1152
	1153	def OnTimeChange(self, event):
	1154	dbg('OnTimeChange: value = ', event.GetValue())
	1155	wxdt = self.tc.GetWxDateTime()
	1156	dbg('wxdt =', wxdt.GetHour(), wxdt.GetMinute(), wxdt.GetSecond())
	1157	if self.test_mx:
	1158	mxdt = self.tc.GetMxDateTime()
	1159	dbg('mxdt =', mxdt.hour, mxdt.minute, mxdt.second)
	1160
	1161
	1162	class MyApp(wx.App):
	1163	def OnInit(self):
	1164	import sys
	1165	fmt24hr = '24' in sys.argv
	1166	test_mx = 'mx' in sys.argv
	1167	try:
	1168	frame = wx.Frame(None, -1, "TimeCtrl Test", (20,20), (100,100) )
	1169	panel = TestPanel(frame, -1, (-1,-1), fmt24hr=fmt24hr, test_mx = test_mx)
	1170	frame.Show(True)
	1171	except:
	1172	traceback.print_exc()
	1173	return False
	1174	return True
	1175
	1176	try:
	1177	app = MyApp(0)
	1178	app.MainLoop()
	1179	except:
	1180	traceback.print_exc()