=========================================================================
FRIGCAL 3.0 MODS, OCT-2024
=========================================================================

This is a plain-text document best viewed with monospace font
and no line wrapping.  It summarizes Frigcal 3.0 enhancements, 
removals, repairs, and platform support/usage.



=========================================================================
1. ENHANCEMENTS
=========================================================================

Emojis work where supported
---------------------------
    Non-BMP Unicode characters, including emojis, are now supported
    for display, input, and copy/paste.  This works as well as the
    underlying Tk 8.6.13 GUI library allows; emojis aren't yet 
    colored on Windows, for instance, but render reasonably well. 
    Emojis don't yet work on Android, but may soon; see PLATFORMS.

Limited dark mode support
-------------------------
    There is some support for dark mode where available, though colors 
    of most UI components are still explicitly configured per your config
    settings in file "frigcal_configs.py".  Today, dark mode is ignored
    on Windows and Android, and applies only to a handful of widgets.

Find calendar-search GUI
------------------------
    A new month-windows Find button and popup dialogs in the main GUI 
    provides simple search for text in calendar fields.  This works
    like the former "searchcals.py" command-line script, but is all 
    GUI, faster, and more convenient.  The script is still included.
    Colors and fonts of Find dialogs use configs of the event dialog.

Copy added to event-edit dialog
-------------------------------
    The event-edit dialog gained a "Copy" button, which copies the event
    being viewed for later right-click pastes, but does not close the 
    dialog.  Together with the dialog's "Delete," this is a convenience
    which duplicates the functionality of the event-rightclick copy/cut 
    dialog (which can be difficult to open on most Android devices). 

Help is now "Help" and online
-----------------------------
    The User Guide is now accessed with a "Help" button (replacing the
    former cryptic "?"), and always opens the online, not local, copy of 
    the guide to support future doc changes.  No local copy is shipped.

Three dialog-color configs
--------------------------
    Dialogs now support three color settings instead of two: background
    color of the entire dialog background; background color of input
    fields nested within the dialog; and foreground color of text in 
    input fields.  See "frigcal_configs.py" notes for more info.

Word-wrapped descriptions
-------------------------
    Text wrapping in the event dialog's multiline description field 
    now uses word wrapping (breaking on words) instead of the former
    naive character wrapping.  This better supports narrower dialogs
    on Android: your text will automatically wrap at word breaks as 
    you type without Enter/Return presses, and will resize itself to
    the event dialog's window size as needed.

Month names abbreviated on Android
----------------------------------
    To conserve display space, month names at the top of month windows
    are now shown as three-letter abbreviations on Android only.  Also
    for smaller Android screens, controls space is reduced in general,
    and the new "buttonNarrowingFactor" conserves more space per ahead.

Android patches integrated
--------------------------
    All the changes required for use on Android have been added to the 
    common and portable source-code package.  This means Android users
    now simply run the source-code package directly, without having to
    fetch any patched files.  See "PLATFORMS" ahead for more info.

Buttons narrowing config
------------------------
    Control buttons may be rendered narrower than defaults with a
    new config, "buttonNarrowingFactor", documented with presets 
    in "frigcal_configs_base.py".  While presets work well on each 
    platform, this can be used to make buttons wider or narrower 
    (e.g., on larger or smaller Android displays).

Terms-of-use doc
----------------
    There is now a formal terms-of-use file which defines license
    and privacy policies of this program.  See "terms-of-use.txt" 
    in your unzipped install package, or at the program's website.



=========================================================================
2. REMOVALS
=========================================================================

Hover footer dropped
--------------------
    The former footer tool - which displayed event description text
    at the bottom of month windows on mouse hover - has been removed.  
    This did not work on Android, worked unevenly on PCs after resizes,
    and was rarely, if ever, used.  Click events to view descriptions.

Month images dropped
--------------------
    The former month images tool - which displayed an image for the 
    viewed month in a popup window - has been removed.  This was arguably
    gimmicky, and was not useful in practice.  The space taken by footer
    and image toggles at top of window was used by the new Find button.



=========================================================================
3. REPAIRS
=========================================================================

Fix for macOS event bug
-----------------------
    This version's code works around a bug in the latest version of 
    the Tkinter GUI library on macOS, which may fire redundant events
    for double clicks on a window that doesn't currently have focus, 
    yielding spurious dialogs.  No user intervention is required.

Fix backslash escapes broken by Python 3.13
-------------------------------------------
    Frigcal and the iCalendar package it embeds use "\<unrecognized>"
    character escapes that worked for over 30 years, but will begin
    generating syntax errors in Python 3.13 (rudely).  These were 
    recoded to avoid errors in the source-code package on 3.13+.

Fix lingering selection after event clicks
------------------------------------------
    On macOS, and perhaps others, part of an event label's text would
    remain selected after the event-edit dialog opened by an event
    double click was closed.  This bogus selection is now cleared.

Fix cursor color in event labels
--------------------------------
    In double-click ("mouse") mode, the input cursor in month-window 
    event labels is now the same color as the event's foreground text.
    This was formerly black, and hard to see in some color schemes.

Fix GUI blurriness on Windows
-----------------------------
    Frigcal now automatically removes the former blurriness its GUI 
    shared on Windows with all Tkinter programs (and some others). 
    You no longer need to navigate through DPI settings in the 
    program file's Properties to work around this manually.



=========================================================================
4. PLATFORMS
=========================================================================

This program runs on macOS, Windows, Linux, and Android.  Its version
3.0 is available in portable source-code form that runs on all supported
platforms, as well as a standalone app for macOS and a standalone 
executable for Windows.  As a brief platform install/usage guide:

macOS
-----
    Download and unzip the macOS app, and move it to your 
    Applications folder for easy access.  Run to the app itself
    (file "Frigcal.app") to start the program as usual.  

    To access supplemental tools (e.g., "makenewcalendar") use 
    Finder's "Show Package Contents" on the app itself and run 
    executables in its "Contents/Resources" subfolder using  
    command lines in Terminal.  The app's "Contents/Resources" 
    subfolder also hosts the configs file ("frigcal_configs.py")
    as well as the default calendars folder ("Calendars").
    Tools executables have a noticeable pause when first run.

    The macOS app is a universal2 binary, which runs natively 
    on both Intel and Apple M chips, and should work on macOS 
    Catalina and newer.  As a fallback, the source-code package 
    also works on macOS the same as it does on Linux (ahead).

Windows
-------
    Download and unzip the Windows executable.  This creates
    a folder which contains a "Frigcal.exe" which you run as 
    usual to start the program (e.g., by clicks in Explorer).

    Also in the unzipped folder are supplemental tools (e.g.,
    "makenewcalendar.exe"), which are generally run by clicks
    in File Explorer or command lines in a console such as
    Command Prompt.  The unzipped folder also hosts the configs
    file ("frigcal_configs.py") as well as the default calendars
    folder ("Calendars").

    The Windows executable should run on both Windows 11 and
    10 64-bit machines.  If it doesn't run on your device, try 
    running with the source-code package, as on Linux (next).

Linux 
-----
    There is no Linux executable in this version due to Linux 
    library skew/  To run, please fetch and unzip the portable
    source-code package, and run "frigcal-main.py" in the unzip
    with normal Python techniques to start the program (e.g., a 
    "python3 frigcal-main.py" command in Terminal).  

    The unzipped folder also hosts the "frigcal_configs.py" 
    configs file, the "Calendars" default calendars folder, 
    and supplemental tools (e.g., "makenewcalendar.py").
   
    All this also applies to WSL2 Linux on Windows, though 
    this program has not yet been vetted there.

Android
-------
    All prior Android patches were integrated into the common
    source-code package, so extra patches are no longer required.
    To run, simply fetch and unzip the portable source-code 
    package, and open and run its "frigcal-main.py" in the 
    Pydroid 3 app to start the program. 

    The unzipped folder also hosts the "frigcal_configs.py" 
    configs file, the "Calendars" default calendars folder, 
    and supplemental tools (e.g., "makenewcalendar.py").

    Storage note: in October 2024, the Pydroid 3 app's version
    7.4 has finally gained Android's All Files Access permission, 
    which means you may download and unzip this program anywhere
    in shared/internal storage on your phone or drives.  Likewise,
    your calendars folder may be kept anywhere in shared storage.
    This is a recent development; for background info, see:
    => "learning-python.com/pydroid3-loses-storage-access.html".

    Usage note: some features, including Clone and Find, assume a
    multiple-window UI that isn't fully supported in Pydroid 3,
    but can be simulated by disabling fullscreen in app settings.
    See Tkinter fullscreen toggles in the app's Settings=>System, plus:
    => "learning-python.com/using-tkinter-programs-on-android.html#moreonfit"

    Emojis note: support for these is dependent on the version of
    Tk provided by the Pydroid 3 app, which tends to lag behind PC
    Pythons.  As of this app's 7.4, its Python 3.11 uses Tk 8.6.10
    which does not support emojis (they are retained in calendar
    files, but display as a "?" in the GUI), but this is prone to 
    change in a future Pydroid 3.  See also "minimumTkForEmojis" 
    in file "frigcal_configs_base.py" for a new, related config.

    Explorers tip: you can open+run Frigcal's script "frigcal-main.py"
    in Pydroid 3 itself (post All Files Access grant).  File-explorer 
    apps (e.g., CX, Solid) can also open+run this script in Pydroid 3, 
    and even allow you to make a homescreen shortcut that does the same,
    but this needs some help today.  All explorers tested open such 
    files with the Storage Access Framework, which doesn't give access 
    to other required code and files in the script's folder.  To work 
    around this, add the following Python code (without its enclosing
    " quotes) at the start of the script (before its first "import" line)
    to change to the script's directory and fix both opens and shortcuts 
    (this can't be automated because your unzip folder may vary): 
    => "import os; os.chdir('/sdcard/Download/Frigcal--source')"

[end]