From 05f60addce85e71665e07f5336fae561dd323dc7 Mon Sep 17 00:00:00 2001 From: zoran-vucenovic Date: Mon, 16 Jun 2014 11:29:33 +0000 Subject: [PATCH] Setting version to 1.5 and updating documentation accordingly git-svn-id: https://svn.code.sf.net/p/lazarus-ccr/svn@3171 8e941d3f-bd1b-0410-a28a-d453659cc2b4 --- .../ZVDateTimeCtrls/trunk/ChangeLog.txt | 17 +- components/ZVDateTimeCtrls/trunk/manual.htm | 902 +++++++++--------- .../ZVDateTimeCtrls/trunk/zvdatetimectrls.lpk | 2 +- .../trunk/zvdatetimepicker.pas | 9 +- 4 files changed, 472 insertions(+), 458 deletions(-) diff --git a/components/ZVDateTimeCtrls/trunk/ChangeLog.txt b/components/ZVDateTimeCtrls/trunk/ChangeLog.txt index 83a6cfd23..431851cbb 100644 --- a/components/ZVDateTimeCtrls/trunk/ChangeLog.txt +++ b/components/ZVDateTimeCtrls/trunk/ChangeLog.txt @@ -1,4 +1,4 @@ -=================================================== +=================================================== Version 1.0 -- 27. Feb. 2010. Initial release @@ -65,4 +65,17 @@ These are main changes: In Qt ws, the client rect of the control was not calculated correctly. Fixed now. - Plus many internal changes... \ No newline at end of file + Plus many internal changes... + +=================================================== + +Version 1.5 -- 16. June 2014. + +These are main changes: + + New properties added: AutoAdvance, Cascade, AutoButtonSize, HideDateTimeParts, CalendarWrapperClass (public), ShowMonthNames, MonthNames. + + Showing month names instead of numbers is possible now, with new properties ShowMonthNames and MonthNames. + + Now possible to use some other calendar control instead of LCL's TCalendar, with CalendarWrapperClass property. + diff --git a/components/ZVDateTimeCtrls/trunk/manual.htm b/components/ZVDateTimeCtrls/trunk/manual.htm index 174863992..299f80291 100644 --- a/components/ZVDateTimeCtrls/trunk/manual.htm +++ b/components/ZVDateTimeCtrls/trunk/manual.htm @@ -1,543 +1,537 @@ - - - - - - - - - - - -

ZVDateTimeControls -Package for Lazarus

-


-

-

http://wiki.lazarus.freepascal.org/ZVDateTimeControls_Package

-


-

-


-

-

The -ZVDateTimeControls package contains two controls:

-


-

-

-TZVDateTimePicker

-


-

-

-TDBZVDateTimePicker

-


-

-

Author

-

Zoran -Vuenovi

-


-

-

License

-

-Modified LGPL, same as Lazarus -component library.

-


-

-

Introduction

-

Delphi's -VCL has a -control named TDateTimePicker, which I find very useful for + + + +

ZVDateTimeControls +Package for Lazarus

+


+

+

http://wiki.lazarus.freepascal.org/ZVDateTimeControls_Package

+


+

+


+

+

The +ZVDateTimeControls package contains two controls:

+


+

+

+TZVDateTimePicker

+


+

+

+TDBZVDateTimePicker

+


+

+

Author

+

Zoran +Vučenović

+


+

+

License

+

+Modified LGPL, same as Lazarus +component library.

+


+

+

Introduction

+

Delphi's +VCL has a +control named 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 TDateEdit, but I prefer the VCL's -TDateTimePicker.

-


-

-

Therefore, +editing dates LCL +has a control named 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 control does not use native -Win control. It descends from LCL's TCustomControl to be +resemble VCL's TDateTimePicker as much as possible.

+


+

+

The +TZVDateTimePicker control does not use native +Win control. It descends from LCL's TCustomControl to be cross-platform. It has been tested on Windows with win32/64 and qt -widgetsets, as well as on Linux with qt and gtk2 widgetsets.

-


-

-

Note +widgetsets, as well as on Linux with qt and gtk2 widgetsets.

+


+

+

Note that the TZVDateTimePicker control does not descend from TEdit, so it does not have unnecessary caret. The VCL's control doesn't have caret -either.

-


-

-

Installation

-

To -install the package in Lazarus IDE follow these steps:

-


-

-
    -
      -

    1. Open - the package in Package Editor (in Lazarus' main menu click Package, - then Open package file... locate the file - zvdatetimectrls.lpk and click Open).

      -

    2. Compile - the package (click Compile in Package Editor's tool bar).

      -

    3. 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.

      -
    -
-


-

-

Change -Log

-

-For more details about changes, see -ChangeLog.txt

-


-

-

-Version 1.0 – 27. February 2010.

-

-Version 1.1 – 17. April 2010.

-

-Version 1.2 – 12. May 2010.

-

-Version 1.3 – 1. April 2011.

-

-Version 1.4 – 4. September 2012.

-


-

-

TZVDateTimePicker -

-

-Properties:

-

-I'll explain some properties of -TZVDateTimePicker control: -

-


-

-

-DateTime: TDateTime (public)

-

-The DateTime value +either.

+


+

+

Installation

+

To +install the package in Lazarus IDE follow these steps:

+


+

+
    +
      +

    1. Open + the package in Package Editor (in Lazarus' main menu click Package, + then Open package file... locate the file + zvdatetimectrls.lpk and click Open).

      +

    2. Compile + the package (click Compile in Package Editor's tool bar).

      +

    3. 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.

      +
    +
+


+

+

Change +Log

+

+For more details about changes, see +ChangeLog.txt

+


+

+

+Version 1.0 – 27. February 2010.

+

+Version 1.1 – 17. April 2010.

+

+Version 1.2 – 12. May 2010.

+

+Version 1.3 – 1. April 2011.

+

+Version 1.4 – 4. September 2012.

+

+Version 1.5 – 16. June 2014.

+


+

+

TZVDateTimePicker +

+

+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. -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 +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 years is entered, it falls in interval 1941 – -2040. Note that MinDate and 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.

-

-

-


-

-

-DateMode: TDTDateMode

-

-type TDTDateMode = -(dmComboBox, dmUpDown, dmNone);

-

-When DateMode is +when two digit years is entered, it falls in interval 1941 – 2040. +Note that MinDate and 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.

+

+

+


+

+

+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, 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 +control. When user clicks the button, 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 next picture the first +always serve for same purpose, so can mouse wheel.

+

+In the next picture the first control's DateMode is set to dmComboBox and the second control's to -dmUpDown.

-

-

-

-If DateMode is dmComboBox, when the +dmUpDown.

+

+

+

+If DateMode is dmComboBox, when the user clicks on the button a calendar drops down, allowing the user to -pick a date.

-


-

-

-Note: if Kind property is set +pick a date.

+


+

+

+Note: if Kind property is set to dtkTime, the calendar control is pointless. Therefore, if DateMode -is dmComboBox, the UpDown is shown instead.

-


-

-

-ShowCheckBox: Boolean

-

-When set, there is a check box on the +is dmComboBox, the UpDown is shown instead.

+


+

+

+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 or time is not possible. (The control is still enabled, though, only in sense that the check box -remains enabled).

-

-



-

-

-Checked: Boolean

-

-If ShowCheckBox is set to True, this +remains enabled).

+

+



+

+

+Checked: Boolean

+

+If 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 +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 ShortDateFormat -global variable.

-

-This is similar to -DateEdit's -DateOrder property.

-


-

-

-DateSeparator: String

-

-Defines the string used to separate +from ShortDateFormat +global variable.

+

+This is similar to +DateEdit's +DateOrder property.

+


+

+

+DateSeparator: String

+

+Defines the string used to separate date, month and year date parts. Setting this property automatically sets the UseDefaultSeparators property to False. To ensure that date and time separators are set to user's system defaults, set -UseDefaultSeparators property to True.

-


-

-

-TimeSeparator: String

-

-Defines the string used to separate +UseDefaultSeparators property to True.

+


+

+

+TimeSeparator: String

+

+Defines the string used to separate hour, minute, second and millisecond time parts. Setting this property automatically sets the 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 +system defaults, set UseDefaultSeparators property to True.

+


+

+

+UseDefaultSeparators: Boolean

+

+When this property is set to True, then the DateSeparator and TimeSeparator properties -will be set to DateSeparator -and TimeSeparator +will be set to DateSeparator +and TimeSeparator global variables, which are set to user system defaults when -application initializes.

-


-

-

-TrailingSeparator: Boolean

-

-When set to True, then the +application initializes.

+


+

+

+TrailingSeparator: Boolean

+

+When set to True, then the DateSeparator is shown once more, after the last date part. This property exists because in some languages the correct date format is -31. 1. 2010. including the last point, after the year.

-


-

-

-LeadingZeros: Boolean

-

-Determines whether the date and time +31. 1. 2010. including the last point, after the year.

+


+

+

+LeadingZeros: Boolean

+

+Determines whether the date and time 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, +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 +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: String

-

-Text which appears +format.

+


+

+

+TextForNullDate: String

+

+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 for date, and nines for time (for example "00/00/0000 99:99:99"), which is appropriate to user input. User can set the date to NullDate by pressing N key, provided -NullInputAllowed -property is True.

-

-When TextForNullDate is set to empty +NullInputAllowed +property is True.

+

+When TextForNullDate is set to empty string, zeros/nines format is displayed even when control does not have focus. If you want empty display, this can be achieved by -setting TextForNullDate to one or more space characters.

-


-

-

-AutoAdvance: Boolean

-

-When true, then when user is entering +setting TextForNullDate to one or more space characters.

+


+

+

+AutoAdvance: Boolean

+

+When true, then when user is entering valid text, the selection automatically advances to next part of date/time. The default is False because of compatibility with previous version, but switching on this option makes user interaction easier, this is a useful option and I recommend setting this property -to true.

-


-

-

-Cascade: Boolean

-

-When true, then when user is +to true.

+


+

+

+Cascade: Boolean

+

+When true, then when user is increasing or decreasing one date/time part (using up-down keys or mouse wheel), it can increase or decrease by one another date/time part. For example, when date is 31.08.2013. and user increases the day, the day becomes 1 and month increases by one and becomes 9, so the date becomes 01.09.2013. If Cascade were set to False, the month -would not change and the date would become 01.08.2013.

-


-

-

-AutoButtonSize: Boolean

-

-When true, the width of the arrow +would not change and the date would become 01.08.2013.

+


+

+

+AutoButtonSize: Boolean

+

+When true, the width of the arrow button (or up-down control, if it is shown instead) is automatically -adjusted proportionally to the height.

-


-

-

-HideDateTimeParts: TDateTimeParts

-

-type

-

-TDateTimePart = (dtpDay, +adjusted proportionally to the height.

+


+

+

+HideDateTimeParts: TDateTimeParts

+

+type

+

+TDateTimePart = (dtpDay, dtpMonth, dtpYear, dtpHour, dtpMinute, dtpSecond, dtpMiliSec, -dtpAMPM);

-

-TDateTimeParts = set of -dtpDay..dtpMiliSec;

-

-With -HideDateTimeParts property, +dtpAMPM);

+

+TDateTimeParts = set of +dtpDay..dtpMiliSec;

+

+With +HideDateTimeParts property, you can chose which date/time parts will not be shown. Most of the time you do not need to use this property and you can get the format -you want by using other properties (see Kind, -TimeDisplay). However, if +you want by using other properties (see Kind, +TimeDisplay). However, if you need more control (for example, you might want to let user edit only days, months and hours), you can additionally hide any date/time parts with this control. Keep in mind that, with this property, you cannot show any date/time part which is hidden by another property (for example, if TimeDisplay is tdHM, the second part is not shown, -regardless of this property).

-


-

-

-CalendarWrapperClass: -TCalendarControlWrapperClass (public)

-

-When assigned, this property +regardless of this property).

+


+

+

+CalendarWrapperClass: +TCalendarControlWrapperClass (public)

+

+When assigned, this property determines the type of the calendar control used for drop-down calendar. When set to nil, which is the default, the value of global -variable DefaultCalendarWrapperClass is used.

-


-

-

-ShowMonthNames: Boolean

-

-When this property -is set to True, month names, set in MonthNames -property, will be displayed instead of numbers.

-


-

-

-MonthNames: -String

-

-When ShowMonthNames +variable DefaultCalendarWrapperClass is used.

+


+

+

+ShowMonthNames: Boolean

+

+When this property +is set to True, month names, set in MonthNames +property, will be displayed instead of numbers.

+


+

+

+MonthNames: +String

+

+When ShowMonthNames is set to True, this property determines which month names should appear. If MonthNames is set to 'Short' or 'Long', then month names -are set to ShortMonthNames -or LongMonthNames +are set to ShortMonthNames +or LongMonthNames respectively. To set the month names explicitly, this property should be set to string which starts with a character which will be used to separate months and then twelve names separated by this character. -For example ',I,II,III,IV,V,VI,VII,VIII,IX,X,XI,XII' — roman -numbers are used for months — the first character is comma, -which means that comma is used to separate the months. Another valid +For example ',I,II,III,IV,V,VI,VII,VIII,IX,X,XI,XII' — roman +numbers are used for months — the first character is comma, which +means that comma is used to separate the months. Another valid example ';jan;feb;mar;apr;maj;jun;jul;avg;sep;okt;nov;dec'. So, the separator should be the first character, before the first month name, and then only if there are twelve month names separated by that separator, the format is valid. The default value of this property is -'Long'.

-


-

-

-TDBZVDateTimePicker -

-

-TDBZVDateTimePicker is a data-aware +'Long'.

+


+

+

+TDBZVDateTimePicker +

+

+TDBZVDateTimePicker is a data-aware version of TZVDateTimePicker, with nice way of handling null database -values.

-


-

-

-Displaying null values -

-
-
-
When - the underlying DB field has null value, then:
-
- +

+Setting the field value to null +

+
If +NullInputAllowed +property is True, the user can set the date and time to null, by +pressing N key. +

+ZVDateTimePicker +Editor

+

+

+

+ZVDateTimePicker Editor is a dialog which provides easy way to set 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 -ellipsis (…) button, shown in Date, Time, MinDate and MaxDate -properties in Object inspector, gets clicked.

-



-

-

Tips

-

-Q: When the date/time value is +ellipsis (…) button, shown in Date, Time, MinDate and MaxDate +properties in Object inspector, gets clicked.

+



+

+

Tips

+

+Q: When the date/time value is null, how to display zeros/nines in user format, no matter whether -the control is focused or not?

-

-A: -Set TextForNullDate +the control is focused or not?

+

+A: +Set TextForNullDate property to empty string. If TextForNullDate is set to empty string, -then zeros/nines are displayed, same as when the control has focus.

-

-
-

-

-Q: -When the date/time -value is null, If empty string in TextForNullDate +then zeros/nines are displayed, same as when the control has focus.

+

+
+

+

+Q: +When the date/time +value is null, If empty string in TextForNullDate property actually sets the display to zeros/nines format, how to set -the control to display nothing?

-

-A: -Set TextForNullDate -property to one space character, you will get the empty display.

- - \ No newline at end of file +the control to display nothing?

+

+A: +Set TextForNullDate +property to one space character, you will get the empty display.

+ + \ No newline at end of file diff --git a/components/ZVDateTimeCtrls/trunk/zvdatetimectrls.lpk b/components/ZVDateTimeCtrls/trunk/zvdatetimectrls.lpk index 1f3c9fb08..d1108ff5e 100644 --- a/components/ZVDateTimeCtrls/trunk/zvdatetimectrls.lpk +++ b/components/ZVDateTimeCtrls/trunk/zvdatetimectrls.lpk @@ -26,7 +26,7 @@ - + diff --git a/components/ZVDateTimeCtrls/trunk/zvdatetimepicker.pas b/components/ZVDateTimeCtrls/trunk/zvdatetimepicker.pas index 722f796bd..a0c139df5 100644 --- a/components/ZVDateTimeCtrls/trunk/zvdatetimepicker.pas +++ b/components/ZVDateTimeCtrls/trunk/zvdatetimepicker.pas @@ -46,9 +46,16 @@ uses clocale, // needed to initialize default locale settings on Linux. {$endif} Classes, SysUtils, Controls, LCLType, Graphics, Math, StdCtrls, Buttons, - ExtCtrls, Forms, ComCtrls, Types, LMessages, LazUTF8, CalendarControlWrapper; + ExtCtrls, Forms, ComCtrls, Types, LMessages, LazUTF8, CalendarControlWrapper, + LCLVersion; const +{ With future Lazarus 1.4, use DateTimeCtrls package: } +{$if lcl_fullversion >= 01040000} +{$Hint From Lazarus version 1.4, package ZVDateTimeCtrls should be replaced by + package DateTimeCtrls, which is included in Lazarus distribution.} +{$endif} + { We will deal with the NullDate value the special way. It will be especially useful for dealing with null values from database. } NullDate = TDateTime(Math.MaxDouble);