Function Repository Resource:

TimeSetter

Source Notebook

A control to set a time

Contributed by: Kevin Daily

ResourceFunction["TimeSetter"][]

represents an interactive TimeObject expression initialized to Now.

ResourceFunction["TimeSetter"][t]

is initialized to the time t.

ResourceFunction["TimeSetter"][Dynamic[x]]

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

ResourceFunction["TimeSetter"][d,gran]

represents an interactive TimeObject expression at the time granularity gran.

Details and Options

The time t can follow any time specification recognized by TimeObject.
The time granulairty gran must be any of "Hour", "Minute", "Second" or ""Instant"".
The default granularity is "Instant".
The dynamic setting for ResourceFunction["TimeSetter"] 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 TimeObject expression:
TimeZoneAutomatictime zone being used
The following options only affect the ResourceFunction["TimeSetter"] interface:
AppearanceAutomaticthe overall appearance of the time setter
BackgroundAutomatictime setter's background color
BaseStyle{}base style specifications for the time setter
EnabledAutomaticwhether the individual controls are active
ImageMarginsAutomaticmargins around the time setter
ImageSizeAutomaticthe overall size of the time 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 #Hour, are automatically converted to the corresponding granularity control.
LabelingFunction defaults to Tooltip. Using None suppresses all control labeling.

Examples

Basic Examples (3) 

Display a time setter control:

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

Dynamically update the value of x:

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

Display a TimeObject to a specific granularity:

In[3]:=
ResourceFunction["TimeSetter"][Now, "Hour"]
Out[3]=
In[4]:=
ResourceFunction["TimeSetter"][Now, "Minute"]
Out[4]=

Scope (2) 

Initialize the interface using a supported time specification:

In[5]:=
ResourceFunction["TimeSetter"]["8am"]
Out[5]=
In[6]:=
ResourceFunction["TimeSetter"][{8}]
Out[6]=

Use TimeSetter as a control within Manipulate:

In[7]:=
Manipulate[
 DateValue[x, {"Hour", "Minute", "Second", "Millisecond"}],
 {{x, Now, "Time"}, ResourceFunction["TimeSetter"][##] &}]
Out[7]=

Options (20) 

Appearance (7) 

Set the appearance to match a DateString specification:

In[8]:=
ResourceFunction["TimeSetter"][Now, Appearance -> "Time"]
Out[8]=

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

In[9]:=
ResourceFunction["TimeSetter"][
 Appearance -> {"Hour: ", "Hour12", "AMPM"}]
Out[9]=

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

In[10]:=
ResourceFunction["TimeSetter"][
 Appearance -> {"Hour" -> None, ":", "Minute"}]
Out[10]=

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

In[11]:=
ResourceFunction["TimeSetter"][
 Appearance -> {"Hour", ":", "Minute" -> PopupMenu}]
Out[11]=

Use "Clock" to create an analog clock control with adjustable hands:

In[12]:=
ResourceFunction["TimeSetter"][Appearance -> "Clock"]
Out[12]=

The clock appearance derives from ClockGauge. Specify options of ClockGauge to change the analog clock appearance:

In[13]:=
ResourceFunction["TimeSetter"][
 Appearance -> "Clock" -> {PlotTheme -> "Web", GaugeStyle -> "Pastel", GaugeLabels -> "Value"}]
Out[13]=

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

In[14]:=
restrictedHours = PopupMenu[#1, Range[1, 5], FrameMargins -> Automatic] &;
ResourceFunction["TimeSetter"][
 Appearance -> {"Hour" -> restrictedHours, ":", "Minute"}]
Out[15]=

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

In[16]:=
appearance = Grid[{{"Hour:", #Hour}, {"Minute:", #Minute -> PopupMenu}}, Alignment -> Left] &;
ResourceFunction["TimeSetter"][Appearance -> appearance]
Out[17]=

Background (2) 

Change the background color:

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

Background is ignored if the Appearance is a pure function:

In[19]:=
ResourceFunction["TimeSetter"][Background -> Red, Appearance -> (Row[{#Hour, ":", #Minute}] &)]
Out[19]=

BaseStyle (2) 

Use a named style:

In[20]:=
ResourceFunction["TimeSetter"][BaseStyle -> "Section"]
Out[20]=

Use box options to style specific controls:

In[21]:=
bs = {
   FontFamily -> "Bahnschrift", FontColor -> Red, FontSize -> 20,
   FrameBoxOptions -> {FrameStyle -> Black},
   InputFieldBoxOptions -> {Background -> LightBlue, Appearance -> "Frameless"},
   PopupMenuBoxOptions -> {Appearance -> "Button"}};
ResourceFunction["TimeSetter"][BaseStyle -> bs]
Out[22]=

Enabled (2) 

By default, TimeSetter is enabled:

In[23]:=
ResourceFunction["TimeSetter"][]
Out[23]=

By setting EnabledFalse, the interface is disabled but visible in its current state:

In[24]:=
ResourceFunction["TimeSetter"][Enabled -> False]
Out[24]=

ImageMargins (1) 

Add margins outside the time setter:

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

ImageSize (2) 

Set the width of the time setter:

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

The display clips if ImageSize is too small:

In[27]:=
ResourceFunction["TimeSetter"][ImageSize -> 50]
Out[27]=

LabelingFunction (3) 

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

In[28]:=
ResourceFunction["TimeSetter"][]
Out[28]=

Use LabelingFunctionNone to suppress all labels:

In[29]:=
ResourceFunction["TimeSetter"][LabelingFunction -> None]
Out[29]=

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

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

TimeZone (1) 

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

In[31]:=
x9 = Now;
{ResourceFunction["TimeSetter"][Dynamic[x9], "Hour", TimeZone -> "Pacific/Guadalcanal"], Dynamic[x9]}
Out[32]=

Applications (1) 

Create a full 12-hour analog clock display:

In[33]:=
ResourceFunction["TimeSetter"][Now, Appearance -> {"Clock" -> {ImageSize -> 100}, "AMPM"}, LabelingFunction -> None]
Out[33]=

Properties and Relations (3) 

The InputField controls default to 2-digit displays, prepending single-digit values with "0":

In[34]:=
ResourceFunction["TimeSetter"][TimeObject[{1, 1, 1}]]
Out[34]=

Each granularity control effectively uses DatePlus to update the TimeObject:

In[35]:=
x11 = TimeObject[{1, 59, 1}];
ResourceFunction["TimeSetter"][Dynamic[x11]]
Out[36]=

Coarser granularities update if finer granularities exceed their granularity range:

In[37]:=
Button["Advance minute", x11 = DatePlus[x11, Quantity[1, "Minutes"]]]
Out[37]=

Possible Issues (3) 

TimeSetter only accepts allowed time granularities:

In[38]:=
ResourceFunction["TimeSetter"][Now, "Unknown"]
Out[38]=

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

In[39]:=
ResourceFunction["TimeSetter"][Appearance -> {"hour", ":", "Mnute"}]
Out[39]=

Correct any spelling mistakes to fix the display:

In[40]:=
ResourceFunction["TimeSetter"][Appearance -> {"Hour", ":", "Minute"}]
Out[40]=

Improperly specified Appearance components display as a warning:

In[41]:=
ResourceFunction["TimeSetter"][Appearance -> {1, ":", "Minute"}]
Out[41]=

Correct any mistakes in the indicated component:

In[42]:=
ResourceFunction["TimeSetter"][Appearance -> {"1", ":", "Minute"}]
Out[42]=

Publisher

Kevin Daily

Version History

  • 1.0.0 – 27 January 2023

Related Resources

License Information