Difference between revisions of "ZVDateTimeControls Package"

From Lazarus wiki
Jump to navigationJump to search
(Link to forum post with utility which makes conversion to new DateTimeCtrls)
 
(27 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=== About ===
 
  
The ZVDateTimeControls package contains two controls:
 
  
[[Image:TZVDateTimePicker.png]] [[#TZVDateTimePicker|TZVDateTimePicker]]
+
'''From Lazarus version 1.4, this package should be replaced with [[DateTimeCtrls Package]], which is included in Lazarus distribution.'''
and
 
[[Image:TDBZVDateTimePicker.png]][[#TDBZVDateTimePicker|TDBZVDateTimePicker]]
 
  
 
+
The controls in DateTimeCtrls package replace controls from old ZVDateTimeCtrls. ZVDateTimeCtrls package will be no longer updated, so please switch to [[DateTimeCtrls Package]]. If you have many ZVDateTimePickers or DBZVDateTimePickers in your project, I created a tool which helps replacing all these old "ZV" controls with new DateTimeCtrls - it is attached to this forum post: [http://forum.lazarus.freepascal.org/index.php/topic,31846.msg205038.html#msg205038] (you have to be logged in the forum to see attachement!).
Delphi's VCL has a control named [http://docwiki.embarcadero.com/VCL/en/ComCtrls.TDateTimePicker TDateTimePicker], which I find very useful for editing dates. LCL, however, does not have this control. Instead, for editing dates LCL has a control named [http://lazarus-ccr.sourceforge.net/docs/lcl/editbtn/tdateedit.html TDateEdit], but I prefer the VCL's TDateTimePicker.
 
 
 
 
 
Therefore, I tried to create a cross-platform Lazarus control which would resemble VCL's TDateTimePicker as much as possible.
 
 
 
 
 
The TZVDateTimePicker does not use [http://msdn.microsoft.com/en-us/library/system.windows.forms.datetimepicker.aspx native Win control]. It descends from LCL-s TCustomControl to be cross-platform. It has been written and initially tested on Windows XP with Win widgetset, but then tested on Ubuntu Linux 9.10 with gtk2 widgetset.
 
 
 
 
 
Note that the TDatePicker control does not descend from TEdit, so it does not have unnecessary caret. The VCL's control doesn't have caret either.
 
 
 
=== Author ===
 
:[[User:Zoran| Zoran Vučenović]]
 
 
 
=== License ===
 
Modified LGPL (same as the FPC RTL and the Lazarus LCL).
 
 
 
=== Download and Installation ===
 
 
 
Lazarus package ZVDateTimeControls.lpk can be downloaded [http://sourceforge.net/projects/lazarus-ccr/files/Time%20and%20Date/ZVDateTimeControls%20Pack from Lazarus-ccr], packed in zip format.
 
 
 
After downloaded, unzip the package.
 
 
 
To install the package in Lazarus IDE follow these steps:
 
 
 
# Open the package in Package Editor (in Lazarus' main menu click ''Package'', then ''Open package file...'' locate the file ''zvdatetimecontrols.lpk'' and click ''Open'').
 
# Compile the package (click ''Compile'' in Package Editor's tool bar).
 
# Install the package in the IDE (click ''Install'' – you will be asked if you want to rebuild Lazarus, click ''Yes''. Wait until Lazarus rebuilds and restarts itself. The new tab ''Date and Time Ctrls'' appears on the component palette with TZVDateTimePicker and TDBZVDateTimePicker controls.
 
 
 
== TZVDateTimePicker [[Image:TZVDateTimePicker.png]] ==
 
 
 
=== properties ===
 
 
 
I'll explain some properties of TZVDateTimePicker control:
 
 
 
==== DateTime: TDateTime (public) ====
 
 
 
:The DateTime value displayed on the control. This property is not published in object inspector, but its value is actually the same as Date and Time properties composed in one value. This property is provided to allow setting or reading of both date and time value at once in program code. In design time, Date and Time can be set in object inspector. [[#ZVDateTimePicker Editor|There is also component editor]] which provides easy way of setting this property in design time.
 
 
 
==== Date: TDate ====
 
 
 
:The date displayed on the control which the user can edit.
 
 
 
==== Time: TTime ====
 
 
 
:The time displayed on the control which the user can edit.
 
 
 
==== MinDate: TDate ====
 
 
 
:The minimal date user can enter.
 
 
 
==== MaxDate: TDate ====
 
 
 
:The maximal date user can enter.
 
 
 
==== NullInputAllowed: Boolean ====
 
 
 
:When True, the user can set the date to NullDate constant by pressing N key.
 
 
 
==== CenturyFrom: Word ====
 
 
 
:When user enters the year in two-digit format, then the CenturyFrom property is used to determine which century the year belongs to. The default is 1941, which means that when two digit year is entered, it falls in interval 1941 – 2040. Note that [[#MinDate: TDateTime|MinDate]] and [[#MaxDate: TDateTime|MaxDate]] properties can also have influence on the decision – for example, if the CenturyFrom is set to 1941 and MaxDate to 31. 12. 2010, if user enters year 23, it will be set to 1923, because it can’t be 2033, due to MaxDate limit.
 
 
 
==== Kind: TDateTimeKind ====
 
 
 
:'''type''' TDateTimeKind = (dtkDate, dtkTime, dtkDateTime);
 
 
 
:The control displays only date, only time or both.
 
:[[Image:ZVDateControls03.PNG]]
 
 
 
==== DateMode: TDTDateMode ====
 
 
 
:'''type''' TDTDateMode = (dmComboBox, dmUpDown, dmNone)
 
 
 
:When DateMode is set to dmComboBox, there is a button on the right side of the control. When user clicks the button, [http://lazarus-ccr.sourceforge.net/docs/lcl/calendar/tcalendar.html the calendar control] is shown, allowing the user to pick the date. When set to dmUpDown, then UpDown buttons are shown.
 
 
 
:In my opinion the UpDown buttons aren't really useful in this control, they are provided for compatibility with Delphi's TDateTimePicker. Up and down keys can always serve for same purpose, so can mouse wheel.
 
 
 
:In the picture the first control's DateMode is set to dmComboBox and the second control's to dmUpDown:
 
:[[Image:ZVDateControls01.PNG]]
 
 
 
==== ShowCheckBox: Boolean ====
 
 
 
:When set, there is a check box on the left side of the control. When unchecked, the display appears grayed and user interaction with the date is not possible. (The control is still enabled, though, only in sense that the check box remains enabled).
 
:[[Image:ZVDateControls02.PNG]]
 
 
 
==== Checked: Boolean ====
 
 
 
:If [[#ShowCheckBox: Boolean|ShowCheckBox]] is set to True, this property determines whether the check box is checked or not. If ShowCheckBox is False, this property has no purpose and is automatically set to True.
 
 
 
==== DateDisplayOrder: TDateDisplayOrder ====
 
 
 
:'''type''' TDateDisplayOrder = (ddoDMY, ddoMDY, ddoYMD, ddoTryDefault);
 
 
 
:Defines the order for displaying day, month and year part of the date. When ddoTryDefault is set, then the controls tries to determine the order from [http://lazarus-ccr.sourceforge.net/docs/rtl/sysutils/shortdateformat.html ShortDateFormat global variable].
 
:This is similar to DateEdit's [http://lazarus-ccr.sourceforge.net/docs/lcl/editbtn/tdateedit.dateorder.html DateOrder] property.
 
 
 
==== DateSeparator: UTF8String ====
 
 
 
:Defines the string used to separate date, month and year date parts. Setting this property automatically sets the [[#UseDefaultSeparators: Boolean|UseDefaultSeparators]] property to False. To ensure that date and time separators are set to user's system defaults, set UseDefaultSeparators property to True.
 
 
 
==== TimeSeparator: UTF8String ====
 
 
 
:Defines the string used to separate hour, minute, second and millisecond time parts. Setting this property automatically sets the [[#UseDefaultSeparators: Boolean|UseDefaultSeparators]] property to False. To ensure that date and time separators are set to user's system defaults, set UseDefaultSeparators property to True.
 
 
 
==== UseDefaultSeparators: Boolean ====
 
 
 
:When this property is set to True, then the [[#DateSeparator: UTF8String|DateSeparator]] and  [[#TimeSeparator: UTF8String|TimeSeparator]] properties will be set to [http://lazarus-ccr.sourceforge.net/docs/rtl/sysutils/dateseparator.html DateSeparator] and [http://lazarus-ccr.sourceforge.net/docs/rtl/sysutils/timeseparator.html TimeSeparator] global variables, which are set to user system defaults when application initializes.
 
 
 
==== TrailingSeparator: Boolean ====
 
 
 
:When set to True, then TheDateSeparator is shown once more, after the last date part. This property exists because in some languages the correct format is 31. 1. 2010. including the last point, after the year.
 
 
 
==== LeadingZeros: Boolean ====
 
 
 
:Determines whether the date parts are displayed with or without leading zeros (this actually affects day, month and hour parts of date and time display).
 
 
 
==== TimeDisplay: TTimeDisplay ====
 
 
 
:'''type''' TTimeDisplay = (tdHM, tdHMS, tdHMSMs);
 
 
 
:If Kind is dtkTime or dtkDateTime, then TimeDisplay value of tdHM means that only hours and minutes are displayed, tdHMS adds displaying of seconds and value of tdHMSMs means that milliseconds are displayed too.
 
 
 
==== TimeFormat: TTimeFormat ====
 
 
 
:'''type'''  TTimeFormat = (tf12, tf24);
 
 
 
:The value of tf12 sets the display of time to 12 hours format, with AM/PM string and tf24 sets to 24 hours format.
 
 
 
==== TextForNullDate: UTF8String ====
 
 
 
:Text which appears when the null date is set and control does not have focus. When control is focused, the text changes to defined format, but displaying zeros, which is appropriate to user input. User can set the date to NullDate by pressing N key, provided [[#NullInputAllowed: Boolean|NullInputAllowed]] property is True.
 
 
 
 
 
== TDBZVDateTimePicker [[Image:TDBZVDateTimePicker.png]] ==
 
 
 
:TDBZVDateTimePicker is a data-aware version of TZVDateTimePicker, with nice way of handling null database values.
 
 
 
=== Handling of null values ===
 
 
 
==== Displaying null values ====
 
 
 
:When the underlying DB field has null value, then:
 
 
 
::If the control is not focused, then it displays the text defined in [[#TextForNullDate: UTF8String|TextForNullDate]] property. The default is "NULL".
 
 
 
::When the control gets focus, the text changes to defined format, but displaying zeros for date parts and nines for time parts (for example "00/00/0000 99:99:99"), which is appropriate to user input.
 
 
 
==== Setting the field value to null ====
 
 
 
::If [[#NullInputAllowed: Boolean|NullInputAllowed]] property is True, the user can set the date and time to null, by pressing N key.
 
 
 
 
 
== ZVDateTimePicker Editor ==
 
 
 
[[Image:ZVDateTimePickerEditor.PNG]]
 
 
 
:ZVDateTimePicker Editor is a dialog which provides easy way to edit Date, Time, MinDate and MaxDate properties in design time. It is invoked when ZVDateTimePicker control is double-clicked in form designer. It is also shown when the elipsis (…) button shown in Date, Time, MinDate and MaxDate properties in Object inspector gets clicked.
 

Latest revision as of 15:27, 10 March 2016


From Lazarus version 1.4, this package should be replaced with DateTimeCtrls Package, which is included in Lazarus distribution.

The controls in DateTimeCtrls package replace controls from old ZVDateTimeCtrls. ZVDateTimeCtrls package will be no longer updated, so please switch to DateTimeCtrls Package. If you have many ZVDateTimePickers or DBZVDateTimePickers in your project, I created a tool which helps replacing all these old "ZV" controls with new DateTimeCtrls - it is attached to this forum post: [1] (you have to be logged in the forum to see attachement!).