Function Repository Resource:

DateSetter

Source Notebook

Create a control for choosing a date

Contributed by: Kevin Daily

ResourceFunction["DateSetter"][]

represents an interactive DateObject expression initialized to Today.

ResourceFunction["DateSetter"][d]

is initialized to the date d.

ResourceFunction["DateSetter"][Dynamic[x]]

takes the setting to be the dynamically updated current value of x, with the value of x being reset if a different date is chosen.

ResourceFunction["DateSetter"][d,gran]

represents an interactive DateObject expression at the calendar granularity gran.

Details and Options

The date d can follow any date specification recognized by DateObject.
The calendar granularity gran must be an available granularity for the indicated CalendarType.
The default granularity is "Day".
Use CalendarData[cal,"Granularities"] to list the available granularities for the calendar cal.
The dynamic setting for ResourceFunction["DateSetter"] is not updated until interacting with one of the adjustable granularities.
For controls like PopupMenu and SetterBar, the setting updates after selecting a value. For InputField, the setting updates after pressing  or by moving focus away from the InputField.
The following options affect the underlying DateObject expression:
CalendarTypeAutomaticcalendar system being used
DateFormatAutomaticformat used to display the date
TimeZoneAutomatictime zone being used
CalendarType may also affect the automatic appearance of ResourceFunction["DateSetter"].
Possible CalendarType specifications are: Automatic, "Gregorian" and "Julian", with additional calendar types as given by CalendarData.
The default CalendarType is "Gregorian".
The automatic appearance of ResourceFunction["DateSetter"] closely follows the appearance of DateObject following the format provided by $DateStringFormat.
The following options only affect the ResourceFunction["DateSetter"] interface:
AppearanceAutomaticthe overall appearance of the date setter
BackgroundAutomaticdate setter's background color
BaseStyle{}base style specifications for the date setter
EnabledAutomaticwhether the individual controls are active
ImageMarginsAutomaticmargins around the date setter
ImageSizeAutomaticthe overall size of the date detter
LabelingFunctionAutomatichow to label the individual controls
Values for Appearance can be any element or a list of elements as specified in DateString.
Granularities in the Appearance specification automatically convert to default control types.
The appearance of individual granularity controls within the Appearance setting can be modified using Rule.
The Appearance setting can be a pure function. Slot instances named with an available granularity, such as #Month, are automatically converted to the corresponding granularity control.
LabelingFunction defaults to Tooltip. Using None suppresses all control labeling.

Examples

Basic Examples (3) 

Display a date setter control:

In[1]:=
ResourceFunction["DateSetter"][]
Out[1]=

Dynamically update the value of x:

In[2]:=
{ResourceFunction["DateSetter"][Dynamic[x]], Dynamic[x]}
Out[2]=

Display a DateObject to a specific granularity:

In[3]:=
ResourceFunction["DateSetter"][Today, "Month"]
Out[3]=
In[4]:=
ResourceFunction["DateSetter"][Today, "Minute"]
Out[4]=

Scope (4) 

Initialize the interface using a supported date specification:

In[5]:=
ResourceFunction["DateSetter"]["2020 1 1 8am"]
Out[5]=
In[6]:=
ResourceFunction["DateSetter"][{2020, 1, 1, 8}]
Out[6]=
In[7]:=
ResourceFunction["DateSetter"][3786854400, "Hour"]
Out[7]=

Use DateSetter as a control within Manipulate:

In[8]:=
Manipulate[
 DateValue[x, {"Year", "Month", "Day", "DayName", "MonthName"}],
 {{x, Today, "Date"}, ResourceFunction["DateSetter"][##] &}]
Out[8]=

Make an interface for controlling AbsoluteTime:

In[9]:=
x2 = AbsoluteTime[Today];
ResourceFunction["DateSetter"][
 Dynamic[DateObject[x2], (x2 = AbsoluteTime[#]) &]]
Out[10]=
In[11]:=
Dynamic[x2]
Out[11]=

Make an interface for controlling a DateString expression:

In[12]:=
x3 = DateString[Now, "ISODateTime"];
ResourceFunction["DateSetter"][
 Dynamic[DateObject[
   x3], (x3 = DateString[#, "ISODateTime"]) &], "Instant"]
Out[13]=
In[14]:=
Dynamic[x3]
Out[14]=

Options (28) 

Appearance (10) 

Set the appearance to match a DateString specification:

In[15]:=
ResourceFunction["DateSetter"][Now, Appearance -> "DateTime"]
Out[15]=

Use a list of DateString specifications. Valid granularities automatically become controls while other strings display as written:

In[16]:=
ResourceFunction["DateSetter"][
 Appearance -> {"Year", " \[LongDash] ", "Month"}]
Out[16]=

Use Rule to suggest the control type. None suppresses the control:

In[17]:=
ResourceFunction["DateSetter"][
 Appearance -> {"Year" -> None, " \[LongDash] ", "Month"}]
Out[17]=

Use a control like SetterBar or PopupMenu instead of the default:

In[18]:=
ResourceFunction["DateSetter"][
 Appearance -> {"Year", " \[LongDash] ", "Month" -> SetterBar}]
Out[18]=

The DateString specification "MonthName" and its short variants are special cases. They provide a labeled control to set the month value:

In[19]:=
ResourceFunction["DateSetter"][
 Appearance -> {"Year", " / ", "MonthName" -> PopupMenu}]
Out[19]=
In[20]:=
ResourceFunction["DateSetter"][
 Appearance -> {"Year", " / ", "MonthNameShort" -> SetterBar}]
Out[20]=

Use "Calendar" to create a day calendar control:

In[21]:=
ResourceFunction["DateSetter"][Appearance -> "Calendar"]
Out[21]=

Use PopupMenu to hide the day calendar until you click the control:

In[22]:=
ResourceFunction["DateSetter"][
 Appearance -> {"Calendar" -> PopupMenu}]
Out[22]=

Use a pure function to specify the appearance of an individual control. The first Slot is automatically filled with the appropriate Dynamic expression:

In[23]:=
restrictedYears = PopupMenu[#1, Range[1990, 2000], FrameMargins -> Automatic] &;
ResourceFunction["DateSetter"][
 Appearance -> {"Year" -> restrictedYears, " / ", "Month"}]
Out[24]=

For date elements that have a finite number of values, like the months, use a second Slot to indicate labeled date elements:

In[25]:=
radioButtonMonthSelector = RadioButtonBar[#1, #2, Method -> "Active", Appearance -> "Horizontal" -> {Automatic, 4}] &;
ResourceFunction["DateSetter"][
 Appearance -> {"Year", " / ", "MonthName" -> radioButtonMonthSelector}]
Out[26]=

Use a pure function for the Appearance option to set the overall appearance. Named slots with date elements are replaced with the corresponding granularity control:

In[27]:=
appearance = Grid[{{#Year}, {#Month -> PopupMenu}}, Alignment -> Left] &;
ResourceFunction["DateSetter"][Appearance -> appearance]
Out[28]=

Background (2) 

Change the background color:

In[29]:=
Table[ResourceFunction["DateSetter"][
  Background -> b], {b, {Pink, Gray, Yellow, Purple}}]
Out[29]=

Background is ignored if the Appearance is a pure function:

In[30]:=
ResourceFunction["DateSetter"][Background -> Red, Appearance -> (Row[{#Year, " \[LongDash] ", #Month}] &)]
Out[30]=

BaseStyle (2) 

Use a named style:

In[31]:=
ResourceFunction["DateSetter"][BaseStyle -> "Section"]
Out[31]=

Affect the specific control types using their box options:

In[32]:=
bs = {
   FontFamily -> "Times", FontColor -> Red, FontSize -> 20,
   FrameBoxOptions -> {FrameStyle -> Black},
   InputFieldBoxOptions -> {Background -> LightBlue, Appearance -> "Frameless"},
   PopupMenuBoxOptions -> {Appearance -> "Button"}};
ResourceFunction["DateSetter"][BaseStyle -> bs]
Out[33]=

CalendarType (1) 

Use CalendarType to set the calendar:

In[34]:=
x4 = CalendarConvert[Today, "ArithmeticFrench"];
ResourceFunction["DateSetter"][Dynamic[x4], CalendarType -> "ArithmeticFrench"]
Out[35]=

DateFormat (4) 

DateFormat only affects the underlying DateObject expression:

In[36]:=
x5 = Today;
ResourceFunction["DateSetter"][Dynamic[x5], DateFormat -> {"Year", "/", "Month"}]
Out[37]=
In[38]:=
Dynamic[x5]
Out[38]=

If specifying individual DateString elements then the delimiter is automatically chosen:

In[39]:=
x6 = Today;
ResourceFunction["DateSetter"][Dynamic[x6], DateFormat -> {"Month", "Day", "Year"}]
Out[40]=
In[41]:=
Dynamic[x6]
Out[41]=

Use an Association to specify both the elements and delimiters. The "Elements" key is used to list the DateString elements and specify the delimiter with the "Delimiters" key:

In[42]:=
x7 = Today;
ResourceFunction["DateSetter"][Dynamic[x7], DateFormat -> <|"Delimiters" -> "\[LongDash]", "Elements" -> {"Month", "Day", "Year"}|>]
Out[43]=
In[44]:=
Dynamic[x7]
Out[44]=

Use Appearance to alter the automatic appearance of the interface without affecting the underlying DateObject:

In[45]:=
x8 = Today;
ResourceFunction["DateSetter"][Dynamic[x8], Appearance -> {"Year", "/", "Month"}]
Out[46]=
In[47]:=
Dynamic[x8]
Out[47]=

Enabled (2) 

By default, DateSetter is enabled:

In[48]:=
ResourceFunction["DateSetter"][]
Out[48]=

Be setting Enabled False, the interface is disabled but visible in its current state:

In[49]:=
ResourceFunction["DateSetter"][Enabled -> False]
Out[49]=

ImageMargins (1) 

Add margins outside the date setter:

In[50]:=
Table[Framed@
  ResourceFunction["DateSetter"][ImageMargins -> m], {m, {0, 30, 50}}]
Out[50]=

ImageSize (2) 

Set the width of the date setter:

In[51]:=
Framed[ResourceFunction["DateSetter"][ImageSize -> {200, 100}]]
Out[51]=

The display clips if ImageSize is too small:

In[52]:=
ResourceFunction["DateSetter"][ImageSize -> 50]
Out[52]=

LabelingFunction (3) 

The individual granularity controls are automatically labeled using Tooltip. Hover over the individual controls to see the calendar granularity that they affect:

In[53]:=
ResourceFunction["DateSetter"][]
Out[53]=

Use LabelingFunctionNone to suppress all labels:

In[54]:=
ResourceFunction["DateSetter"][LabelingFunction -> None]
Out[54]=

Use directions Left, Right, Above and Below to insert granularity control labels within the interface:

In[55]:=
Table[ResourceFunction["DateSetter"][
  LabelingFunction -> lab], {lab, {Below, Above, Left, Right}}]
Out[55]=

TimeZone (1) 

Use TimeZone to set the time zone specification of the underlying DateObject:

In[56]:=
x9 = Today;
ResourceFunction["DateSetter"][Dynamic[x9], "Hour", TimeZone -> "Pacific/Guadalcanal"]
Out[57]=
In[58]:=
Dynamic[x9]
Out[58]=

Applications (1) 

Create a full calendar display:

In[59]:=
fullCalendarAppearance = Column[{Grid[{{
        Button["\[LeftSkeleton]", x10 = DatePlus[x10, Quantity[-1, "Years"]]],
        Button["<", x10 = DatePlus[x10, Quantity[-1, "Months"]]], #Year, #MonthName -> PopupMenu, Button[">", x10 = DatePlus[x10, Quantity[1, "Months"]]], Button["\[RightSkeleton]", x10 = DatePlus[x10, Quantity[1, "Years"]]]}}], #Calendar}, Alignment -> Center] &;
In[60]:=
x10 = Today;
ResourceFunction["DateSetter"][Dynamic[x10], Appearance -> fullCalendarAppearance, LabelingFunction -> None]
Out[61]=

Properties and Relations (2) 

Each granularity control effectively uses DatePlus to update the DateObject:

In[62]:=
x11 = DateObject[{2021, 12, 31}];
ResourceFunction["DateSetter"][Dynamic[x11]]
Out[63]=

Coarser granularities update if finer granularities exceed their granularity range:

In[64]:=
Button["Advance month", x11 = DatePlus[x11, Quantity[1, "Months"]]]
Out[64]=

Possible Issues (6) 

DateSetter only accepts allowed granularities for the CalendarType option:

In[65]:=
ResourceFunction["DateSetter"][Today, "Unknown"]
Out[65]=

Use CalendarData to find available granularities for the given calendar:

In[66]:=
CalendarData["Gregorian", "Granularities"]
Out[66]=

Appearance components are case-sensitive. Any misspelled components pass through as written:

In[67]:=
ResourceFunction["DateSetter"][Today, Appearance -> {"year", " \[LongDash] ", "Mnth"}]
Out[67]=

Correct any spelling mistakes to fix the display:

In[68]:=
ResourceFunction["DateSetter"][Today, Appearance -> {"Year", " \[LongDash] ", "Month"}]
Out[68]=

Improperly specified Appearance components display as a warning:

In[69]:=
ResourceFunction["DateSetter"][Today, Appearance -> {1, " \[LongDash] ", "Month"}]
Out[69]=

Correct any mistakes in the indicated component:

In[70]:=
ResourceFunction["DateSetter"][Today, Appearance -> {"1", " \[LongDash] ", "Month"}]
Out[70]=

Publisher

Kevin Daily

Version History

  • 1.0.0 – 17 January 2023

Related Resources

License Information