Welcome to [i]Frigcal[/i]: calendars made simple, portable, and private.

This screen is an in-app quick start.  The [i]Docs[/i] link below opens user guides with HTML styling and expanded content.  Here, you'll find usage essentials.

This app's usage is centered around:

• A main [i]menu[/i] of actions opened with a button tap or right swipe

• Touch-screen [i]gestures[/i] that are also available for touchpads and mice

• Calendar [i]files[/i] that you manage with normal file tools and operations

The following sections cover each of these topics in turn, followed by tips for settings, colors, and installs.



[H1]Menu[/H1]

This app's main menu, also called a navigation drawer, is the primary navigation tool of Frigcal.  It is opened and closed by tapping the three-bar [i]hamburger[/i] button at the top right of each screen.  You can also open the menu by swiping rightwards from the display's left edge and can close it by tapping anywhere outside it.  

The menu indicates the currently displayed screen with gray shading.  It allows you to switch to month, search, and settings screens; change the colors theme; open go-to and new-calendar dialogs; save changed calendars; and navigate without gestures.

Most menu actions are self-explanatory.  Of note: if you have no prior calendars to use on first run, you'll use the menu's [i]New Calendar[/i] to create a new calendar and its [i]Save Calendars[/i] to write the new calendar's file to your calendar folder.

Some main-menu items open temporary popups and may redirect you to the next screen.  For example, the [i]Go To[/i] item opens a date-input popup, which in turn opens a selected date's [b]Month[/b] screen.  Navigation items in the menu also open the [b]Month[/b] screen per the corresponding gestures of the next section.



[H1]Gestures[/H1]

Use the following gestures to view and manage your calendars.  The direction of swipes may depend on your device settings, and the way you invoke gestures varies per input device.  On touch screens, use the gestures as described.  On touch pads and mice, swipes might use press-hold-and-move, two-finger gestures, or scroll wheels.


[H2]Date Navigation[/H2]

The [b]Month[/b] screen displays days in weeks that for simplicity always begin with [i]Sunday[/i].  On this screen:

— [u]Swipe left and right[/u] to move to the next and prior [i]month[/i], respectively.  Use either short swipes above the days grid or long swipes anywhere without events (e.g., in the bottom week row).

— [u]Swipe up and down[/u] to move to the next and prior [i]year[/i], respectively.  Use the same lengths and locations as left and right swipes.

— [u]Double-tap anywhere[/u] to go to [i]today[/i]'s month and day.

— [u]Tap [i]Go To[/i][/u] in the main menu to pick and jump to a [i]specific[/i] date.


[H2]Days and Events[/H2]

The [b]Month[/b] screen display days, which in turn display events.  On days and events:

— [u]Swipe up, down, left, and right[/u] to [i]scroll[/i] the events on a day.  Use short swipes on the events.

— [u]Single-tap an event[/u] on a day to [i]open[/i] it in the event dialog (see ahead).  Once open, you may view, edit, delete, or copy the event.  Tap [i]Update[/i] to save changes.

— [u]Single-tap a day's number[/u] to [i]add[/i] or [i]list[/i] events for that day:

....Days [i]without[/i] events open an empty event dialog for [i]adding[/i] a new event.  Tap [i]Create[/i] to save the new event.

....Days [i]with[/i] events open a larger and scrollable [i]list[/i] of all events on that day.  Tap an event in the list to [i]open[/i] it in the event dialog, or tap the list's [i]Add[/i] to open an empty event dialog for [i]adding[/i] a new event.

— [u]Long-press a day's number[/u] to [i]paste[/i] onto that day the event most recently copied in the event dialog.  The pasted event appears in a prefilled event dialog.  Tap [i]Update[/i] to save the event.


[H2]Main Menu[/H2]

The main menu, described earlier, is available on every screen in this app.  On all screens:

— [u]Single-tap[/u] the hamburger button or [u]swipe rightwards[/u] from the app's left edge to [i]open[/i] the main menu.

— [u]Singe-tap[/u] anywhere outside the main menu or [u]swipe leftwards[/u] anywhere to [i]close[/i] the main menu.

— [u]Swipe up and down[/u] to [i]scroll[/i] the main menu and reveal additional options.


[H2]Back and Exit[/H2]

This app's close gestures vary by device category:

— On Android, the system [u]back button[/u] or gesture returns to the [b]Month[/b] screen from other screens or prompts to confirm app exit on the [b]Month[/b] screen.

— On PCs, the [u]escape key[/u] returns to the [b]Month[/b] screen from other screens, and both the [u]escape key[/u] and window [u]close button[/u] prompt to confirm app exit if there are unsaved calendar changes.


[H2]Event Dialog[/H2]

The event dialog, opened by gestures above, allows you to view, edit, delete, and copy an event.  It includes a one-line [i]Title[/i], a multiple-line [i]Note[/i] with automatic word wrapping, and [i]Calendar[/i] and [i]Category[/i] choices, the latter of which is used to colorize an event's overscore bar (see Colors ahead).  The entire dialog scrolls to reveal more [i]Note[/i] text.

To ease edits, text fields display handles and a Cut/Copy/Paste bubble on text selection and a Select All/Paste bubble on long-presses.  Text fields also support keyboard combinations where available: with key [i]control[/i] (or [i]command[/i] on macOS), type [i]C[/i], [i]X[/i], [i]V[/i], [i]A[/i], [i]Z[/i], and [i]R[/i] for copy, cut, paste, select all, undo, and redo, respectively.  Handles and bubbles may be disabled in [b]Settings[/b] for keyboard-only use.

In the event dialog itself, tap [i]Update[/i] or [i]Create[/i] to save changes, and use its [i]Copy[/i] or [i]Copy[/i] plus [i]Delete[/i] to copy or cut for long-press pasting in the [b]Month[/b] screen (e.g., to repeat or move events).  The latter also enables calendar-field changes in the pasted event.



[H1]Calendars[/H1]

In this app, calendars are simply files in a folder, which you can manage with normal file operations.  Calendar changes made in this app are applied in memory and written to files only when you choose [i]Save Calendars[/i] in the main menu.  Here's more info about this model.

This app [i]asks[/i] you to select a folder for storing your calendar files whenever it requires access to one.  This can occur on the first run, startup load, main-menu [i]Save Calendar[/i], and [b]Settings[/b] folder change, and uses the system chooser on Android and a custom chooser on PCs.  You can use any accessible folder on your device and may change your chosen folder at any time in the [b]Settings[/b] screen.

Once chosen, the calendar folder stores one [i]ICS file[/i] for every calendar you make or use in this app.  ICS files follow the iCalendar standard, which makes them portable to other devices and programs.  They are named with a [i].ics[/i] extension and use the broad Unicode UTF-8 text encoding.  To manage ICS files, this app:

— [i]Loads[/i] all the calendar files in the calendars folder on both startup of the app and folder changes in [b]Settings[/b]

— [i]Saves[/i] changed calendars to their files in the calendars folder on main-menu [i]Save Calendars[/i]

— [i]Prompts[/i] you to save if you try to close this app or change folders when there are unsaved calendar changes

Additional calendar essentials:

[i]Sharing[/i]

....To share calendars with other programs or devices, either copy calendar ICS files to or from the calendars folder (e.g., in a file-explorer app), or choose a calendars folder in this app that is part of regularly synced content (e.g., in a folder tree managed by quixotely.com's [i]PC-Phone USB Sync[/i] app).  Unlike some calendar apps, Frigcal does not require imports and exports to use ICS files.

[i]Backups[/i]

....Also in the calendars folder, this app saves backup copies of the ICS calendar files it changes.  These backups are made before every write to an ICS file, and show up in the calendar folder's [i]_Backups[/i] subfolder, named with backup date and time plus the original ICS file's name.  To restore your calendar files from these backups, rename them to discard their date and time, and move them one level up to your calendars folder.  The [i]_Backups[/i] subfolder is self-cleaning, per a [i]Max backups[/i] number-files-per-calendar limit in [b]Settings[/b].

[i]Clouds[/i]

....On Android, the calendars-folder chooser allows you to pick a folder on any available content medium, including internal storage and clouds.  If you choose to host your calendars folder remotely, please be aware that your files will be transmitted from and to your provider on loads and saves and are only as private and secure as your provider's interfaces.  Local storage is generally recommended.



[H1]Settings[/H1]

The [b]Settings[/b] screen lets you manage color theme, font size, backups, calendar folder, and more.  The choices you make in it are saved in a file (in JSON format) so they can be restored on each run.  Use this screen's [i]Save[/i] to save its settings to the file, and use its [i]Restore[/i] to reset options to their original values (followed by [i]Save[/i] if desired).

The settings file is not generally useful to users but can be copied on PCs to sync settings.  Its location is platform specific:

— On [u]Windows and Linux[/u], it's in this app's install folder, where you unzipped the download and where the executable resides.  

— On [u]macOS[/u], it's in the ~/Libraries/Frigcal subfolder of your home folder.

— On [u]Android[/u], it's in this app's private storage and automatically synced to and from your Google ID account when this is enabled.

No changes to items in [b]Settings[/b] are saved permanently to this file unless you tap its [i]Save[/i], except for [i]Calendars folder[/i], which is auto-saved after all folder asks for convenience, and is not reset to empty or a prior path on [i]Restore[/i].  Whether saved or not, changes made in [b]Settings[/b] are applied in the running App.

Tips: [i]Color theme[/i] always reflects main-menu [i]Theme[/i] toggles, and [i]Font size[/i] is an alternative to font or zoom settings on the underlying host device.



[H1]Colors[/H1]

Color theme in both the main menu and [b]Settings[/b] selects an overall app motif.  Colors may also be applied to event overscore bars in the [b]Month[/b] screen and event-list dialog, per event category names.  Choose a color for an event by selecting from preset colors in that event's [i]Category[/i] field in the event dialog.

For simplicity, event category is a predefined color name, and calendars are not colorized.  This ensures that event colors work the same on all devices without settings syncs.  For users of legacy Frigcal, a script converts former calendar and category colors to the new category color names: see [i]convert_legacy_colors.zip[/i] either in the [i]tools[/i] folder of app PC installs or online at the [i]Website[/i] link below.

Tips: to use the default yellow accent color, pick the [i](none)[/i] category, which is the same as no category and unknown category.  To show no color at all, pick the [i]black[/i] or [i]white[/i] categories, which match the background color of the [b]Month[/b] screen and event-list dialog in Dark and Light themes, respectively.



[H1]Installs[/H1]

For Android, install this app from the Google Play store.  For Windows, macOS, and Linux PCs, install this app from quixotely.com using the [i]Downloads[/i] link on this app's [b]About[/b] screen.  Each PC platform's version of this app is provided as a zipfile, which you'll download and unzip on your devices.  Platform tips:

— On [u]Android[/u], install this app from Google Play, using the [i]Play Store[/i] link on this app's About screen.  Launch this app by tapping its icon in the apps screen and uninstall with your device's usual procedure.  The Android app is also available on quixotely.com as a sideloadable APK file; see the [b]About[/b] screen's [i]Downloads[/i] link.

— On [u]Windows[/u], the unzip makes a folder that contains the [i]Frigcal.exe[/i] executable, which you can run with a click in File Explorer.  Please unzip in a writeable folder, not in [i]C:\Program Files[/i].  To uninstall, delete this app's unzipped folder.  Windows may ask you to approve this app on first run by clicking [i]More info[/i] and then [i]Run anyway[/i].

— On [u]macOS[/u], the unzip makes a [i]Frigcal.app[/i] package folder, which you can run with a click in Finder and move to Applications for convenience.  To uninstall, delete the package folder.  Optional: to avoid first-run approval steps on macOS, remove this app's quarantine flag with Terminal command [i]xattr -c /path.../Frigcal.app[/i].

— On [u]Linux[/u], the unzip makes a folder that contains the [i]Frigcal[/i] executable, which you can run with a click in a file explorer.  To uninstall, delete this app's unzipped folder.  This is an Ubuntu 24 executable, which will not run on all Linux hosts.  If executable runs fail, please instead use the source-code package described next.

The apps and executables above provide seamless user experiences and are recommended for most users.  As an alternative, the app's open-source code is provided in its [u]source-code package[/u], both for vetting the app and as a fallback option if the apps or executables will not run due to library or host skew.  

To view or run the source-code package, fetch it using either the [i]Website[/i] link below or [i]Downloads[/i] in [b]About[/b] and unzip.  Source-code runs (only) are started by launching the package's [i[main.py[/i] script and require installs of Python 3.8 or later, Kivy 2.3.1, KivyMD 1.2.0, and Pillow 10.4 or later.  Launch with any script technique, such as explorer icon clicks or command lines [i]py -3 main.py[/i] on Windows and [i]python3 main.py[/i] elsewhere.  Install Python on the host and install the others within Python using [i]pip[/i].



[H1]For More Info[/H1]

For the online user guide, tap [i]Docs[/i] below.  For your calendars folder or files, tap [i]Files[/i] below.  For logistics info, app benefits, terms of use, and privacy policy, open this app's [b]About[/b] screen in the main menu.
