dhxpyt.calendar

 17class Calendar:
 18    """A Python wrapper for the DHX Calendar JavaScript widget.
 19
 20    This class provides an interface to create and manipulate a calendar widget,
 21    allowing users to select dates, configure display modes, and handle events.
 22    It integrates with a JavaScript-based calendar via Pyodide.
 23
 24    Args:
 25        config (CalendarConfig): Configuration object for the calendar.
 26        widget_parent (Any, optional): The parent DOM element for the calendar. Defaults to None.
 27
 28    Example:
 29        ```
 30        from calendar_config import CalendarConfig
 31        config = CalendarConfig(date_format="%Y-%m-%d")
 32        cal = Calendar(config)
 33        cal.set_value("2025-08-12")
 34        print(cal.get_value())
 35        '2025-08-12'
 36        ```
 37    """
 38    def __init__(self, config: CalendarConfig, widget_parent: Any = None):
 39        """Initializes the calendar instance."""
 40        self.calendar = js.dhx.Calendar.new(widget_parent, js.JSON.parse(json.dumps(config.to_dict())))
 41
 42    """ Calendar API Functions """
 43
 44    def clear(self) -> None:
 45        """Clears the value set in the calendar.
 46
 47        Resets the selected date(s) to an empty state.
 48        """
 49        self.calendar.clear()
 50
 51    def destructor(self) -> None:
 52        """Removes a calendar instance and releases occupied resources.
 53
 54        Call this method to clean up the calendar widget when it is no longer needed.
 55        """
 56        self.calendar.destructor()
 57
 58    def get_current_mode(self) -> str:
 59        """Returns the current mode of displaying the Calendar.
 60
 61        Returns:
 62            str: The current mode (e.g., 'calendar', 'month', 'year').
 63        """
 64        return self.calendar.getCurrentMode()
 65
 66    def get_value(self, as_date_obj: bool = False) -> Union[str, List[str]]:
 67        """Returns the selected date(s) in the calendar.
 68
 69        Args:
 70            as_date_obj (bool, optional): If True, returns the date(s) as JavaScript Date object(s).
 71                                         If False, returns date(s) as string(s) in the configured format.
 72                                         Defaults to False.
 73
 74        Returns:
 75            Union[str, List[str]]: A single date string or a list of date strings (e.g., '2025-08-12').
 76                                 If `as_date_obj` is True, returns JavaScript Date object(s).
 77
 78        Example:
 79            >>> cal.set_value("2025-08-12")
 80            >>> cal.get_value()
 81            '2025-08-12'
 82            >>> cal.get_value(as_date_obj=True)
 83            <JavaScript Date object>
 84        """
 85        return self.calendar.getValue(as_date_obj)
 86
 87    def link(self, calendar: Any) -> None:
 88        """Links the calendar to another calendar for selecting a date range.
 89
 90        Args:
 91            calendar (Calendar): Another Calendar instance to link with for range selection.
 92        """
 93        self.calendar.link(calendar.calendar)
 94
 95    def paint(self) -> None:
 96        """Repaints the calendar on a page.
 97
 98        Call this method to refresh the calendar's display after changes.
 99        """
100        self.calendar.paint()
101
102    def set_value(self, value: Union[str, List[str]]) -> bool:
103        """Selects a date or dates in the calendar.
104
105        Args:
106            value (Union[str, List[str]]): A single date string (e.g., '2025-08-12') or a list of date strings.
107
108        Returns:
109            bool: True if the value was set successfully, False otherwise.
110
111        Example:
112            >>> cal.set_value(["2025-08-12", "2025-08-15"])
113            True
114        """
115        return self.calendar.setValue(value)
116
117    def show_date(self, date: Union[str, None] = None, mode: str = "calendar") -> None:
118        """Shows a specified date and/or opens the calendar in one of the available modes.
119
120        Args:
121            date (Union[str, None], optional): The date to show (e.g., '2025-08-12'). If None, shows the current date.
122            mode (str, optional): The display mode ('calendar', 'month', or 'year'). Defaults to 'calendar'.
123        """
124        self.calendar.showDate(date, mode)
125
126    """ Calendar Events """
127
128    def add_event_handler(self, event_name: str, handler: Callable) -> None:
129        """Helper method to dynamically add event handlers.
130
131        Args:
132            event_name (str): The name of the event (e.g., 'beforeChange', 'change').
133            handler (Callable): The callback function to handle the event.
134        """
135        event_proxy = create_proxy(handler)
136        self.calendar.events[event_name] = event_proxy
137
138    def before_change(self, handler: Callable[[str, str, bool], Union[bool, None]]) -> None:
139        """Fires before the change of date selection.
140
141        Args:
142            handler (Callable[[str, str, bool], Union[bool, None]]): A callback function that receives:
143                - old_date (str): The previously selected date.
144                - new_date (str): The newly selected date.
145                - click (bool): Whether the change was triggered by a user click.
146                The handler can return False to cancel the change, or None to allow it.
147
148        Example:
149            >>> def on_before_change(old_date, new_date, click):
150            ...     print(f"Changing from {old_date} to {new_date}")
151            ...     return True
152            >>> cal.before_change(on_before_change)
153        """
154        self.add_event_handler('beforeChange', handler)
155
156    def cancel_click(self, handler: Callable[[], None]) -> None:
157        """Fires when the user clicks on the 'Cancel' control.
158
159        Args:
160            handler (Callable[[], None]): A callback function to handle the cancel click event.
161        """
162        self.add_event_handler('cancelClick', handler)
163
164    def change(self, handler: Callable[[str, str, bool], None]) -> None:
165        """Fires on change of date selection.
166
167        Args:
168            handler (Callable[[str, str, bool], None]): A callback function that receives:
169                - old_date (str): The previously selected date.
170                - new_date (str): The newly selected date.
171                - click (bool): Whether the change was triggered by a user click.
172
173        Example:
174            >>> def on_change(old_date, new_date, click):
175            ...     print(f"Date changed to {new_date}")
176            >>> cal.change(on_change)
177        """
178        self.add_event_handler('change', handler)
179
180    def date_mouse_over(self, handler: Callable[[str, str], None]) -> None:
181        """Fires when the mouse pointer is over a date.
182
183        Args:
184            handler (Callable[[str, str], None]): A callback function that receives:
185                - date (str): The date under the mouse pointer.
186                - formatted_date (str): The formatted date string.
187        """
188        self.add_event_handler('dateMouseOver', handler)
189
190    def mode_change(self, handler: Callable[[str], None]) -> None:
191        """Fires on change of the calendar mode.
192
193        Args:
194            handler (Callable[[str], None]): A callback function that receives:
195                - mode (str): The new mode ('calendar', 'month', or 'year').
196        """
197        self.add_event_handler('modeChange', handler)
198
199    def month_selected(self, handler: Callable[[int], None]) -> None:
200        """Fires after a month was selected in the calendar.
201
202        Args:
203            handler (Callable[[int], None]): A callback function that receives:
204                - month (int): The selected month (0-11).
205        """
206        self.add_event_handler('monthSelected', handler)
207
208    def year_selected(self, handler: Callable[[int], None]) -> None:
209        """Fires after a year was selected in the calendar.
210
211        Args:
212            handler (Callable[[int], None]): A callback function that receives:
213                - year (int): The selected year.
214        """
215        self.add_event_handler('yearSelected', handler)
216
217    """ Calendar Properties """
218
219    @property
220    def css(self) -> str:
221        """Adds style classes to the calendar.
222
223        Returns:
224            str: The CSS class(es) applied to the calendar.
225        """
226        return self.calendar.css
227
228    @css.setter
229    def css(self, value: str) -> None:
230        self.calendar.css = value
231
232    @property
233    def date(self) -> str:
234        """Defines the date that will be opened when the calendar is created.
235
236        Returns:
237            str: The initial date string (e.g., '2025-08-12').
238        """
239        return self.calendar.date
240
241    @date.setter
242    def date(self, value: str) -> None:
243        self.calendar.date = value
244
245    @property
246    def date_format(self) -> str:
247        """Defines the format of dates in the calendar.
248
249        The format string follows the DHX Calendar specification (e.g., '%Y-%m-%d' for 'YYYY-MM-DD').
250
251        Returns:
252            str: The current date format string.
253        """
254        return self.calendar.dateFormat
255
256    @date_format.setter
257    def date_format(self, value: str) -> None:
258        self.calendar.dateFormat = value
259
260    @property
261    def disabled_dates(self) -> Callable[[str], bool]:
262        """Allows disabling some date intervals.
263
264        Returns:
265            Callable[[str], bool]: A function that takes a date string and returns True if the date should be disabled.
266        """
267        return self.calendar.disabledDates
268
269    @disabled_dates.setter
270    def disabled_dates(self, value: Callable[[str], bool]) -> None:
271        self.calendar.disabledDates = value
272
273    @property
274    def mark(self) -> Callable[[str], str]:
275        """Adds a CSS class to specific days.
276
277        Returns:
278            Callable[[str], str]: A function that takes a date string and returns a CSS class to apply.
279        """
280        return self.calendar.mark
281
282    @mark.setter
283    def mark(self, value: Callable[[str], str]) -> None:
284        self.calendar.mark = value
285
286    @property
287    def mode(self) -> str:
288        """The mode of Calendar initialization.
289
290        Returns:
291            str: The current mode ('calendar', 'month', or 'year').
292        """
293        return self.calendar.mode
294
295    @mode.setter
296    def mode(self, value: str) -> None:
297        self.calendar.mode = value
298
299    @property
300    def range(self) -> bool:
301        """Enables/disables the possibility to select a range of dates.
302
303        Returns:
304            bool: True if range selection is enabled, False otherwise.
305        """
306        return self.calendar.range
307
308    @range.setter
309    def range(self, value: bool) -> None:
310        self.calendar.range = value
311
312    @property
313    def this_month_only(self) -> bool:
314        """Hides dates of the previous/next months relative to the currently displayed one.
315
316        Returns:
317            bool: True if only the current month's dates are shown, False otherwise.
318        """
319        return self.calendar.thisMonthOnly
320
321    @this_month_only.setter
322    def this_month_only(self, value: bool) -> None:
323        self.calendar.thisMonthOnly = value
324
325    @property
326    def time_format(self) -> int:
327        """Defines the time format for the timepicker in the calendar.
328
329        Returns:
330            int: The time format (e.g., 12 for 12-hour, 24 for 24-hour).
331        """
332        return self.calendar.timeFormat
333
334    @time_format.setter
335    def time_format(self, value: int) -> None:
336        self.calendar.timeFormat = value
337
338    @property
339    def time_picker(self) -> bool:
340        """Adds a timepicker into the calendar.
341
342        Returns:
343            bool: True if the timepicker is enabled, False otherwise.
344        """
345        return self.calendar.timePicker
346
347    @time_picker.setter
348    def time_picker(self, value: bool) -> None:
349        self.calendar.timePicker = value
350
351    @property
352    def value(self) -> Union[str, List[str]]:
353        """Selects the day(s) (adds a round blue marker).
354
355        Returns:
356            Union[str, List[str]]: The selected date(s) as a string or list of strings.
357        """
358        return self.calendar.value
359
360    @value.setter
361    def value(self, value: Union[str, List[str]]) -> None:
362        self.calendar.value = value
363
364    @property
365    def week_numbers(self) -> bool:
366        """Defines whether to show the numbers of weeks.
367
368        Returns:
369            bool: True if week numbers are shown, False otherwise.
370        """
371        return self.calendar.weekNumbers
372
373    @week_numbers.setter
374    def week_numbers(self, value: bool) -> None:
375        self.calendar.weekNumbers = value
376
377    @property
378    def week_start(self) -> str:
379        """Sets the starting day of the week.
380
381        Returns:
382            str: The starting day (e.g., 'sunday', 'monday').
383        """
384        return self.calendar.weekStart
385
386    @week_start.setter
387    def week_start(self, value: str) -> None:
388        self.calendar.weekStart = value
389
390    @property
391    def width(self) -> Union[str, int]:
392        """Sets the width of the calendar.
393
394        Returns:
395            Union[str, int]: The width of the calendar (e.g., '300px' or 300).
396        """
397        return self.calendar.width
398
399    @width.setter
400    def width(self, value: Union[str, int]) -> None:
401        self.calendar.width = value

 8class CalendarConfig(ControlConfig):
 9    """Configuration class for Calendar."""
10    def __init__(self,
11                 date: Union[str, Any] = None,
12                 date_format: str = "%d/%m/%y",
13                 disabled_dates: Callable[[Any], bool] = None,
14                 mark: Callable[[Any], str] = None,
15                 mode: str = "calendar",
16                 range: bool = False,
17                 this_month_only: bool = False,
18                 time_format: int = 24,
19                 time_picker: bool = False,
20                 value: Union[str, Any, List[Union[str, Any]]] = None,
21                 week_numbers: bool = False,
22                 week_start: str = "sunday",
23                 css: str = None,
24                 width: Union[int, str] = "250px"):
25        self.date = date
26        self.date_format = date_format
27        self.disabled_dates = disabled_dates
28        self.mark = mark
29        self.mode = mode
30        self.range = range
31        self.this_month_only = this_month_only
32        self.time_format = time_format
33        self.time_picker = time_picker
34        self.value = value
35        self.week_numbers = week_numbers
36        self.week_start = week_start
37        self.css = css
38        self.width = width