The DIALOG_CALENDAR function displays a dialog that allows the user to interactively select a date.

Examples

Open the Select date dialog. Type:

result = DIALOG_CALENDAR()

This opens the generic Select Date dialog.

Additional Examples

See Additional Examples for additional examples using the DIALOG_CALENDAR function.

Syntax

Result = DIALOG_CALENDAR(ALT_INPUT=variable, ALT_EDITABLE=0|1, CALLBACK=string, DATE_FORMAT=string, DIALOG_PARENT=widget_id, DISABLE_DATES=string or array of string, /DISABLE_[DAY_OF_WEEK], ENABLE_DATES=string or array of string, /ENABLE_TIME, INITIAL_VALUE=string, LOCALE=string, MAX_DATE=string or array of string, MIN_DATE=string or array of string, MODE=0|1|2, /MODAL, TITLE=string, /NO_BLOCK, SCALE=float, SELECTION_BUTTONS=0|1, USER_DATA=variable, /WEEK_NUMBERS, XOFFSET=variable, YOFFSET=variable

Return Value

DIALOG_CALENDAR returns the date that was chosen in the dialog as a string.

Keywords

ALT_INPUT

Set this keyword to enable an additional text input field that displays the currently selected date or dates.

If ALT_EDITABLE is also enabled, the user can manually edit the text field to select date(s).

When this keyword is set, ALT_INPUT will display as 'y-m-d'. You can also set this keyword to a string containing a Valid Date Format which will change the way ALT_INPUT is displayed and how it can be edited.

ALT_EDITABLE

Set this keyword to 0 to disable the user's ability to edit the ALT_INPUT text field. The default value for this keyword is 1.

CALLBACK

Set this keyword to a string containing the name of a user-defined procedure on the IDL path. This procedure will be called in the following cases:

  • When a date is selected in the calendar.

  • When the OK button is pressed to confirm a selection.

  • When the Cancel button is pressed or the widget is otherwise closed.

The callback procedure must accept two arguments:

  1. A structure containing information about the selection event.

  2. The value passed through the USER_DATA keyword, if provided.

DATE_FORMAT

Set this keyword to a string that specifies the return format for the selected date. The format must use a Valid Date Format.

If not set, the default value is 'y-m-d'. If ENABLE_TIME is set the default is 'Y-m-d\\TH:i:S' .

DIALOG_PARENT

Set this keyword to the widget ID of a widget to be used as the parent of this dialog.

DISABLE_DATES

Set this keyword to a scalar string, array of strings, or list specifying which dates to disable from selection in the calendar.

Each entry can be one of:

  • A single date string, in the format 'YYYY-MM-DD'.

  • The special string 'today', which will be converted to the current system date.

  • A range of dates delimited by '...' in the format 'YYYY-MM-DD...YYYY-MM-DD'. All dates in the range will be disabled.

ENABLE_DATES and DISABLE_DATES cannot be used together.

DISABLE_SUNDAY

Set this keyword to disable all Sundays.

DISABLE_MONDAY

Set this keyword to disable all Mondays.

DISABLE_TUESDAY

Set this keyword to disable all Tuesdays.

DISABLE_WEDNESDAY

Set this keyword to disable all Wednesdays.

DISABLE_THURSDAY

Set this keyword to disable all Thursdays.

DISABLE_FRIDAY

Set this keyword to disable all Fridays.

DISABLE_SATURDAY

Set this keyword to disable all Saturdays.

ENABLE_TIME

Set this keyword to enable time input in the calendar. This modifies the default DATE_FORMAT to include time unless DATE_FORMAT is explicitly set.

ENABLE_DATES

Set this keyword to a scalar string, array of strings, or list specifying which dates to enable for selection in the calendar.

Each entry can be one of:

  • A single date string, in the format 'YYYY-MM-DD'.

  • The special string 'today', which will be converted to the current system date.

  • A range of dates delimited by '...' in the format 'YYYY-MM-DD...YYYY-MM-DD'. All dates in the range will be enabled.

If ENABLE_DATES is not set, all dates are considered enabled by default (subject to MIN_DATE and MAX_DATE constraints).

If ENABLE_DATES is set, all dates not listed in ENABLE_DATES will be disabled.

ENABLE_DATES and DISABLE_DATES cannot be used together.

INITIAL_VALUE

Set this keyword to a string giving the initial date/time shown in the dialog. This must be in the format defined by DATE_FORMAT

If this keyword is set to a date that is disabled then the calendar will default to today's date.

LOCALE

Set this keyword to a string giving the locale code to be used for the calendar. For example:

Locale Name

Locale Code

English

 en
Chinese zh
French

fr

German

de

Japanese

ja

Russian ru
Spanish es

The default locale is determined by the browser’s language settings. If a corresponding locale is not loaded, it will fall back to English. For a full list of locale strings please check here.

MAX_DATE

Set this keyword to a string to define the latest selectable date. All dates after MAX_DATE are disabled.

The string must be in the format 'YYYY-MM-DD'.

MIN_DATE

Set this keyword to a string to define the earliest selectable date. All dates before MIN_DATE are disabled.

The string must be in the format 'YYYY-MM-DD'.

MODAL

Set this keyword to make the dialog modal with DIALOG_PARENT as its parent. This keyword is ignored if DIALOG_PARENT is not set.

MODE

Set this keyword to a 0, 1 or 2 to switch the selection mode for the calendar:

  • Mode 0 allows the selection of a single date

  • Mode 1 allows the selection of multiple distinct dates

  • Mode 2 allows for the selection of a date range

The default behavior for this keyword is 0.

NO_BLOCK

Set this keyword to block until the dialog is closed. If this is set then DIALOG_CALENDAR will return the widget base for the user to resolve on their own. The default behavior is to block.

If /NO_BLOCK is set, the recommended method for retrieving user input is with CALLBACK.

SCALE

Set this keyword to a real number to scale the size of the DIALOG_CALENDAR. The default value for this keyword is 1.

SELECTION_BUTTONS

Set this keyword to 0 to disable the "OK" and "Cancel" buttons in the calendar widget. When this keyword is set to 0, the calendar's values can only be retrieved through the CALLBACK routine.

If this keyword is not specified or set to 1, the widget includes both "OK" and "Cancel" buttons.

TITLE

Set this keyword to a string to be used for the dialog title. The default title is "Select Date."

USER_DATA

Set this keyword to a variable that will be passed as the second argument to the procedure specified by the CALLBACK keyword.

IDL passes variables by reference, meaning that all invocations of the callback can change the value of the USER_DATA variable. See the callback example below.

WEEK_NUMBERS

Set this keyword to display ISO week numbers alongside the calendar view.

XOFFSET

Set this keyword to a number to specify the X offset of the widget in pixels, relative to the screen. If DIALOG_PARENT is set, the offset will be relative to the position of the calling widget.

YOFFSET

Set this keyword to a number to specify the Y offset of the widget in pixels, relative to the screen. If DIALOG_PARENT is set, the offset will be relative to the position of the calling widget.

Output Date Formats

Output date format strings follow the formatting conventions used by Flatpickr. These strings are case-sensitive and composed of tokens representing various date and time components. For example, "Y-m-d" corresponds to a format like 2025-05-29.

Token

Output Example

Description

d

01 to 31

Day of month (2 digits)

D

Mon to Sun

Short weekday name

l (L)

Monday to Sunday

Full weekday name

j

1 to 31

Day of month (no leading 0)

J

 1st, 2nd, 3rd Day with ordinal suffix

w

 0 (Sun) to 6 (Sat) Day of week (number)
F January to December Full month name
m 01 to 12 Month (2 digits)
n 1 to 12 Month (no leading 0)
M Jan to Dec Short month name
U 1451335745 Unix timestamp (in seconds)

Y

 2025 Full year (4 digits)
y 25 Two-digit year
H 00 to 23 Hour (24-hour, 2 digits)
h 01 to 12 Hour (12-hour, 2 digits)
G 0 to 23 Hour (24-hour, no leading 0)
g 1 to 12 Hour (12-hour, no leading 0)
i 00 to 59 Minutes (2 digits)
a am or pm Lowercase AM/PM
K AM or PM

Uppercase AM/PM

Some examples:

Format String

Example Output

"Y-m-d"

 2025-05-29
"l, F j, Y"

Thursday, May 29, 2025

"m/d/Y"

05/29/2025

"Y-m-dTH:i:S"

2025-05-29 14:30:00

Additional Examples

 

; Enables time input and customizes display format.
pro ex1_time_and_format
  date = Dialog_Calendar(/ENABLE_TIME, DATE_FORMAT = 'l, F j, Y H:i')
  print, 'Selected date and time: ', date
end
 
; Opens calendar to a specific date with a custom title.
pro ex2_initial_value_and_title
  date = Dialog_Calendar(INITIAL_VALUE = '2000-01-04', TITLE = 'Please choose a Date')
  print, 'Selected date: ', date
end
 
; Defines and uses a callback to respond to date selection.
pro ex3_callback, event, userdata
  print, 'Callback fired.'
  help, event
  help, userdata
  userdata = userdata + ': Modified by callback!'
end
 
pro ex3_callback_usage
  varIn = 'ExampleData'
  date = Dialog_Calendar(CALLBACK='ex4_callback', USER_DATA=varIn)
  print, 'Final selected date: ', date
  print, varIn
end
 
; Disable some dates.
pro ex4_disable_dates
  disabled = ['2025-05-10', '2025-05-15', '2025-05-20 ... 2025-05-25']
  date = Dialog_Calendar(INITIAL_VALUE = '2025-05-19', DISABLE_DATES = disabled)
  print, 'Selected date: ', date
end
 
; Enforces min/max range and disables weekends.
pro ex5_constraints_and_weekends
  date = Dialog_Calendar(INITIAL_VALUE = '2025-05-01', MIN_DATE = '2025-05-01', MAX_DATE = '2025-05-31', $
  /DISABLE_SATURDAY, /DISABLE_SUNDAY)
  print, 'Selected weekday date: ', date
end
 
; Uses ALT_INPUT formatting and enables multi-date selection.
pro ex6_alt_input_and_mode
  date = Dialog_Calendar(ALT_INPUT='l, F j, Y', MODE=2)
  print, 'Selected date(s): ', date
end
 
; Demonstrates calendar scaling and position adjustment.
pro ex7_scaled_offset
  date = Dialog_Calendar(SCALE = 1.5, XOFFSET = 300, YOFFSET = 200)
  print, 'Selected date: ', date
end
 
; Making use of a Parent Widget
pro ex8_Parent_Widget
compile_opt idl2
  wParent = Widget_Base(/COLUMN, YOFFSET = 100)
  dice = CW_DICE(wParent)
  Widget_Control, wParent, /REALIZE
  Xmanager, 'Dice!', wParent, /NO_BLOCK
  ; notice that YOFFSET is "centered" on the parent object.
  result = Dialog_Calendar(YOFFSET = 100, DIALOG_PARENT = wParent, /MODAL)
  print, result
end
 
pro ex9_Enable_dates
compile_opt idl2
  enable_dates = ['2025-05-10', '2025-05-12', '2025-05-15', '2025-05-20...2025-05-25']
  result = Dialog_Calendar(ENABLE_DATES = enable_dates, INITIAL_VALUE = '2025-05-10')
  print, 'Selected date: ', result
end

Version History

9.2

Introduced

See Also

DIALOG_COLORPICKER