Welcome to [i][CO]Frigcal[/CO][/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 in the top-right corner 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] or the equivalent top-of-screen save button to write the new calendar's file to your calendars 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.

New in 4.1: the main menu's [i]Save Calendars[/i] option is prefixed with a "*" whenever there are unsaved calendar-file changes.  Check this indicator to know if a save is required, rather than running a save or close.

New in 4.3: to avoid menu opens, a [i]save icon button[/i] also appears at the top-left corner of every screen when there are unsaved calendar changes.  Check this to know if a save is required, and tap it to save changed calendar files. Tapping it is the same as tapping the menu's [i]Save Calendars[/i].



[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:

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

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

— [CO]Double-tap anywhere[/CO] to go to [i][b]today[/b][/i]'s month and day.  Today's month is displayed and its day number is highlighted.

— [CO]Tap [i]Go To[/i][/CO] in the main menu to pick and jump to a [i][b]specific[/b][/i] date.  The chosen day's month is displayed and its day number is highlighted.


[H2]Days and Events[/H2]

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

— [CO]Swipe up, down, left, and right[/CO] to [i][b]scroll[/b][/i] the events on a day.  Use short swipes on the events.  Day scrolls are reset on navigations and loads.

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

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

—— Days [CO]without[/CO] prior events open an empty event dialog for [i][b]adding[/b][/i] a new event.  Tap [i]Save[/i] to save the new event.

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

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

New in 4.3: as a convenience, [i]Paste[/i] in event lists works the same as long-press pastes for days with prior events.


[H2]Main Menu[/H2]

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

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

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

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


[H2]Event Dialog[/H2]

The event dialog, opened by gestures above, allows you to view, edit, copy, and delete 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.

Edit event-dialog fields by tapping them, and tap [CO]Save[/CO] to save changes or new events.  To repeat or move events, tap [CO]Copy[/CO] or [CO]Cut[/CO], respectively, followed by long-press pastes in the [b]Month[/b] screen on the target day's number.  Repeats and moves enable calendar-field changes in the pasted event, and [CO]Del[/CO] deletes without copying.  Close the event dialog with [CO]Exit[/CO] or [CO]Cancel[/CO], which are verified if there are unsaved event changes.

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

New in 4.1: the event dialog's [i]Category[/i] field is colorized per its color name, and the dialog's [i]Calendar[/i] field is prefilled with a sole or user-chosen default calendar for new adds to save a step.  For the latter, choose a default calendar in the [b]Settings[/b] screen, and see more info in 4.1 Recent News at [i]Website[/i] below.

New in 4.2: the event dialog's new [CO]Cut[/CO] is the same as [CO]Copy[/CO] plus [CO]Del[/CO] but saves a step for event moves, and empty fields are filled with defaults.  Find more info in 4.2 Recent News at [i]Website[/i] below.

New in 4.3: a new [i]one-tap Copy/Cut mode[/i], enabled by default, closes the event dialog immediately on [CO]Copy[/CO] and [CO]Cut[/CO] taps to save a step for event repeats and moves.  Disable this mode in [b]Settings[/b] if you prefer to verify cuts and leave the dialog open after copies.  See 4.3 Recent News at [i]Website[/i] below for more info.


[H2]Back and Exit[/H2]

This app's close gestures vary by device category:
 
— On Android, the system [CO]Back[/CO] button or gesture either returns to the [b]Month[/b] screen from other screens or puts the app in Android [i]paused[/i] mode, where it remains in memory and can be resumed quickly in Android Recents.  Closing the app in Recents (e.g., by swipe) closes it in full and reclaims its memory for other apps to use, subject to the caution below.

— On PCs, the [CO]escape[/CO] key returns to the [b]Month[/b] screen from other screens, and both the [CO]escape[/CO] key on [b]Month[/b] and window [CO]close[/CO] button ("x") either prompt to confirm app exit if there are unsaved calendar changes or close the app.  PC forced closes (e.g., via Windows Task Manager) also close the app, subject to the caution below.

— On all platforms, the [CO]Quit App[/CO] action in the main menu also closes the app but first confirms app exit if there are unsaved calendar changes.  This is the same as the window [CO]close[/CO] button on PCs, but on Android may be faster than some Recents closes and more safely checks for calendar changes.  

On PCs, you must also navigate out of open popup dialogs to close the app with an [CO]escape[/CO] or [CO]close[/CO].  This avoids losing changes on closes.  Android [CO]Back[/CO] simply pauses the app if a dialog is open: the dialog resumes when the app resumes.  Menu [CO]Quit App[/CO] cannot be selected when dialogs are open.

[EM]Caution[/EM]: both Recents closes on Android and forced closes on PCs kill the app immediately and discard any unsaved calendar changes.  Use these carefully if there are unsaved changes as indicated by both the top-of-screen save button and "*" before [i]Save Calendars[/i] in the main menu, or use [CO]Quit App[/CO] for changes warnings on all platforms.

New in 4.2: Android [CO]Back[/CO] now pauses instead of closing, because it's more in line with Android norms, parallels Android Home and Recents taps, and avoids having to reload calendars to resume the app.  Close fully in Recents.

New in 4.3: menu [CO]Quit App[/CO] provides an alternative, platform-neutral, and safe app exit.



[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 or its equivalent top-of-screen save button.  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 Calendars[/i] or top-of-screen save button, and [b]Settings[/b] folder change, and it uses the system chooser on Android and a custom chooser on PCs.  You can choose any accessible folder on your device and may change your chosen folder at any time in the [b]Settings[/b] screen.

Once chosen, the calendars 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]Displays[/i] the combination of all events among all calendar files in the calendars folder

— [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] and top-of-screen save button

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

Additional calendar essentials:

[CO]Sharing[/CO]

....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.

[CO]Backups[/CO]

....Also in the calendars folder, this app saves backup copies of the ICS calendar files it changes.  These backups are made each time an ICS file is resaved and retain the file's prior contents.  They show up in the calendars 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].

[CO]Clouds[/CO]

....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.

New in 4.1: the main menu's [i]Save Calendars[/i] option is prefixed with a "*" to indicate unsaved calendar-file changes; the calendars load and save confirmation dialogs display a scrollable number-events report as a cross-check; and a tools script can combine calendars (see Source Code at [i]Website[/i] below).

New in 4.3: as noted in Menu, for convenience, a top-of-screen [i]save button[/i] also appears to indicate unsaved calendar changes and works the same as main-menu [i]Save Calendars[/i] when pressed.



[H1]Settings[/H1]

The [b]Settings[/b] screen lets you manage color theme, font size, backups, calendars 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 [CO]Windows[/CO] and [CO]Linux[/CO], it's in this app's install folder, where you unzipped the download and where the executable resides.  

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

— On [CO]Android[/CO], it's in this app's private storage and is 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: among [b]Settings[/b] fields, [i]Color theme[/i] always reflects main-menu [i]Theme[/i] toggles; [i]Font size[/i] is an alternative to font or zoom settings on the underlying host device; [i]Default calendar[/i] is used to prefill calendar in the event dialog for new adds unless a sole calendar file is used; and [i]One-tap Copy/Cut[/i] mode is described in Event Dialog above.



[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.

New in 4.1: as noted in Event Dialog, the event dialog's [i]Category[/i] field is also colorized per its value, to reflect and preview overscore bars.



[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 [CO]Android[/CO], 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 [CO]Windows[/CO], 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 [CO]macOS[/CO], 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 [CO]Linux[/CO], 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 [CO]source-code package[/CO], 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.
