#!/usr/bin/env python3
r"""
=====================================================================================
Frigcal: calendars made simple, portable, and private

A standalone and Python-coded Frigcal app for both Android and PC platforms.
Provided as an app for Android and macOS and executables for Windows and Linux.

Version: 4.1.0, February 2026
Copyright © 2026 quixotely.com.  All rights reserved.

License and terms of use:
    Frigcal is provided freely but as is and with no warranties of any kind, 
    and its maker is not liable for any damages caused by running this program.  
    By downloading, installing, or otherwise accessing Frigcal, you are granted 
    a license to run, view, and modify it, but you may not post, sell, or 
    redistribute it.  By using Frigcal, you are agreeing to these terms of use.
    See also file terms-of-use.txt in the app or its source code folder.

Origins and tools: 
    Some code here derives from either the "PC-Phone USB Sync" PPUS app 
    also available at quixotely.com or the legacy Frigcal 3.0 program 
    available at learning-python.com.  Notably new here are:

    • The Android Storage Access Framework (SAF) for calendar-folder selection
          Instead of PPUS's POSIX via All Files Access and Frigcal 3'0 POSIX

    • A navigation drawer with screens and themes, via KivyMD
          Instead of PPUS's top-of-window tabs and Frigcal 3.0's border buttons

    • Swipe gestures for month-screen month/year navigation
          Instead of Frigcal 3.0's navigation buttons and keypresses

    • App dark/light color theme and colorized event-category overscore bars
          Instead of Frigcal 3.0's many configurable colors

    The legacy Frigcal 3.0 uses tkinter for its GUI and runs as source code in 
    the Pydroid 3 app on Android.  To support a standalone Android app, its code
    was radically rewritten to use both the Kivy and KivyMD GUI frameworks, as 
    well as Android's SAF storage framework for calendar files.  For more on 
    tools used by this app, see about-template.txt and the app's About screen.

Code structure:
    This file defines the app itself, the top-level navigation drawer, and 
    app-wide tools.  Files *gui.py implement GUI components, and common.py 
    collects shared names.  main.kv is the nav drawer, allpopups.kv and 
    allscreens.kv are popups and screens, and common.kv is shared UI defs. 
=====================================================================================
"""




#====================================================================================
# Imports and globals (TBD: some may be unused)
#====================================================================================


# moot tries...
#
# set keyboard mode before other Kivy imports?
# from kivy.config import Config
# Config.set('kivy', 'keyboard_mode', 'dock')
#
# set softinput mode before other Kivy imports?
# from kivy.core.window import Window
# Window.softinput_mode = 'below_target'


# app modules - and prestart_pc_tweaks.py run
from common import *   # collector module used in >1 files

# instance in App, for user persistent configs
from settings import AppSettings

# instance in App, for hang-free POSIX IO (TBD: used?)
from hangless import FileSystemLocalNoHang  

# instances in App, for folder-code bifurcation
from storage import CalendarsStorage_PCs, CalendarsStorage_Android

# instance in App, for month-screen widgets and callbacks
from monthgui import MonthGUI      # (avoids circular from with Factory)

# instance in App, for search-screen widgets and callbacks
from searchgui import SearchGUI    # (avoids circular from with Factory)

# instance in App, for settings-screen widgets and callbacks
from settingsgui import SettingsGUI

# icalendar event and calendar object tools
from icsfiletools import *
import icsfiletools  # to set global

# plus prestart_pc_tweaks imported by common.py for timing


# one Eventdata(), global to support cut/copy in one window and paste in another
CopiedEvent = None


# main data structures: parsed and indexed file data, used but not changed here
from storage import CalendarsTable     # {icsfilename: icalendar.Calendar()}
from storage import EventsTable        # {Edate(): {uid: EventData()} ]
from storage import CalendarsDirty     # {icsfilename: Boolean]

# data structure classes in EventsTable
from storage import Edate, EventData


# linux distribution info for About (3rd-party module, shipped with app)
if RunningOnLinux:
    try:
        from distro import distro
    except:
        print('Required and included distro package not present')
        sys.exit(1)


KV = """
    GUI definition: moved to file main.kv and its subfiles
"""




#====================================================================================
# Classes linked to .kv Kivy-lang files
#====================================================================================



# Coding hindsight: instead of coding the MDScreen subclasses below,
# screens might have been coded in the *gui.py files, with both any 
# methods defined below and methods now coded in the *gui.py standalone
# classes.  OTOH, that may cause widget-mod issues at __init__ time, 
# and the current coding was chosen on purpose to minimize reliance 
# on the very subtle and implicit Python/Kivy-lang linkage in Kivy.



class MainWindow(MDBoxLayout):

    """
    -------------------------------------------------------
    Root window

    This is self.root in App, and the first non <> rule in 
    the .kv file.  A boxLayout is required at GUI root for 
    Android 15+ edge-to-edge .padding, and a Py class is 
    needed for screen-wide gestures.  Per nesting in .kv
    file, contains MDScreen + screens + menu button/items.
    -------------------------------------------------------
    """

    pass



class MonthScreen(MDScreen):

    """
    -------------------------------------------------------
    Swipe and double-tap gestures

    Touch callbacks registered in the Month screen only.
    -------------------------------------------------------
    """

    # minimum distance for swipe instead of tap or event short-scroll
    long_swipe_threshold = dp(200)
 
    # minimum distance for swipe on month label at top: no scolls conflict
    short_swipe_threshhold = dp(40)


    def on_touch_down(self, touch):

        """
        Start of touch gesture

        Note that the Month screen must be open in these gestures' 
        callbacks because the events are only active for that screen.
        Reopening it and tweaking the menu is pointess but harmless.

        See also: 
        - KivyMD TouchBehavior for double taps
        - Kivy Carousel or gestures4kivy.CommonGestures for swipes
        Swipes can also be coded with grabs + touch.dx
        
        TBD: apply this to month grid, not whole screen, else
        a True return breaks this screen's hamburger-menu button?
        This was made moot by the following update.

        UPDATE: this now:
        - Uses a longer swipe distance to minimize conflict with scrolls 
          of events on days
        - Handles swipes on the month label at screen top specially with
          a shorter swipe distance because there is no conflict with event
          scrolls in this context and less space to swipe up/down 
        - does not handle debouncing of medium-speed double taps: event
          edit, add, and list dialogs in monthgui.py avoid double opens  
        """
 
        app = MDApp.get_running_app()                   # for app menu-callback handlers
        monthlabel = self.ids.screenlabel               # for short swipes on month name
 
        if self.collide_point(*touch.pos):              # is the touch within this widget?
            if touch.is_double_tap:                     # that means entire Month screen
                trace('Double Tap')
                if app.pending_tap_event:
                    app.pending_tap_event.cancel()      # cancel day or event single tap
                    app.pending_tap_event = None
                app.on_menu_today(app.menuMonthItem)    # two taps, Month screen is open
                return True                             # True=consume and end the touch event
            else:
                monthtap = monthlabel.collide_point(*touch.pos)
                self.swipe_threshold = \
                    self.short_swipe_threshhold if monthtap else \
                    self.long_swipe_threshold
                touch.ud['initial_pos'] = touch.pos
                #return True                            # True here breaks hamburger button
    
        return super().on_touch_down(touch)             # pass unhandled touches to parent 


    def on_touch_up(self, touch):
 
        """
        End of touch gesture
        """

        app = MDApp.get_running_app()

        if 'initial_pos' in touch.ud:
            initial_x, initial_y = touch.ud['initial_pos']
            final_x, final_y = touch.pos

            dx = final_x - initial_x
            dy = final_y - initial_y

            if abs(dx) > self.swipe_threshold and abs(dx) > abs(dy):
                if dx > 0:
                    trace('Swiped Right')
                    app.on_menu_priormonth(app.menuMonthItem)    # to the right
                else:
                    trace('Swiped Left')
                    app.on_menu_nextmonth(app.menuMonthItem)     # to the left
                return True                                      # end up event

            elif abs(dy) > self.swipe_threshold and abs(dy) > abs(dx):
                if dy > 0:
                    trace('Swiped Up')
                    app.on_menu_nextyear(app.menuMonthItem)      # to the top
                else:
                    trace('Swiped Down')
                    app.on_menu_prioryear(app.menuMonthItem)     # to the bottom
                return True                                      # end up event

        return super().on_touch_up(touch)    # propagate to other widgets



# --------------------- 
# Screens in nav drawer
# ---------------------

#class MonthScreen(MDScreen): 
    # plus monthgui.py methods
    # defined above for swipes

class SettingsScreen(MDScreen): 
    # plus settingsgui.py methods
    pass

class SearchScreen(MDScreen): 
    # plus searchgui.py methods
    pass

class HelpScreen(MDScreen):
    # text management coded here
    pass

class AboutScreen(MDScreen): 
    # text management coded here
    pass



class InfoDialog(BoxLayout):

    """
    -------------------------------------------------------
    The info-message dialog.
    Also defined with <> instance rule in .kv.
    self argument implied in .kv file: root=instance.
    Class and its properties _must_ by defined in .py.
    -------------------------------------------------------
    """

    message = StringProperty()         # passed here as args => root properties
    oncancel = ObjectProperty(None)    # refs bound callback in Main, run in .kv



class ConfirmDialog(BoxLayout):

    """
    -------------------------------------------------------
    All in .kv, but must declare here too
    -------------------------------------------------------
    """

    message = StringProperty()
    onyes = ObjectProperty(None)
    onno = ObjectProperty(None)



class BusyDialog(BoxLayout):

    """
    -------------------------------------------------------
    The busy-wait dialog.
    Also defined with <> instance rule in .kv.
    self argument implied in .kv file: root=instance.
    Class and its properties _must_ by defined in .py.
    -------------------------------------------------------
    """

    message = StringProperty()        # passed here as args => root properties
    onokay = ObjectProperty(None)     # when enabled after thread exit



class NewCalendarDialog(BoxLayout):

    """
    -------------------------------------------------------
    All in .kv, but must declare here too
    -------------------------------------------------------
    """

    message = StringProperty()
    onadd = ObjectProperty(None)
    oncancel = ObjectProperty(None)



'''CUT
class GoToDateDialog(BoxLayout):

    """
    -------------------------------------------------------
    All in .kv, but must declare here too
    Now uses a canned KivyMD dialog: see allpopups.kv
    -------------------------------------------------------
    """

    message = StringProperty()
    onfocus = ObjectProperty(None)
    ongoto = ObjectProperty(None)
    oncancel = ObjectProperty(None)
CUT'''



from kivy.base import EventLoop

class MDTextField_FixSelectPasteBubble(MDTextField):

    #
    # Touch control
    #

    """
    [FC] Override this method in the Kivy TextInput superclass 
    to force the SelectAll/Paste bubble opened on longpress to 
    appear near the touch location.  Else, the bubble is opened 
    way too far ahead and off screen for larger text notes.

    This may reflect Kivy layout assumptions, but it's clearly
    a Kivy bug; GUI toolkits shouldn't require such heroics.
    Kivy TextInput is a mix-in superclass of KivyMD MDTextField:

      class TextInput(FocusBehavior, Widget): ...
      class MDTextField(..., TextInput, ...): ...

    Crucial on phones: no other way to paste, sans an on-screen
    keyboard with widget (Samsung) or control keys (Hacker's).
    The Cut/Copy/Paste bubble on text selects seems to work OK,
    but having to add+select dummy text to get a Paste is bogus.
    """

    def long_touch(self, dt):
        self._long_touch_ev = None
        if self._selection_to == self._selection_from:

            # original Kivy code
            """
            pos = self.to_local(*self._touch_down.pos, relative=False)
            self._show_cut_copy_paste(
                pos, EventLoop.window, mode='paste')
            """

            trace('TextInput bubble tweak')
            pos = self._touch_down.pos
            self._show_cut_copy_paste(
                pos, EventLoop.window, mode='paste', pos_in_window=True)



class ColorPickDialog(BoxLayout):

    """
    -------------------------------------------------------
    All in .kv, but must declare here too; TBD: used in FC?
    -------------------------------------------------------
    """
    
    onpick = ObjectProperty(None)
    oncancel = ObjectProperty(None)



class ConfigCheckbox(CheckBox):

    """
    -------------------------------------------------------
    TBD: from PPUS, used in FC?  (uses KivyMD widgets) 

    Ref in .kv, def in .py: need to set color per patform
    [r, g, b, a] for image tinting - too dim on macos only
    Default is [1, 1, 1, 1], which works well elsewhere
    -------------------------------------------------------
    """

    color = [1, 3, 5, 4] if RunningOnMacOS else [1, 1, 1, 1]



class TextInputNoSelect(MDLabel):  ##TextInput, MDTextField
    
    """
    -------------------------------------------------------
    TBD: from PPUS, used in FC?  (mostly uses MD Labels)
    See note at Help in allscreens.kv: no great options.

    Kivy 2.1.0 has a nasty bug which makes selection handles 
    linger on in the GUI on Android - both after popup dismiss,
    and after tab switch.  This is an issue only for _readonly_
    text, as handles go away on either keyboard minimize or 
    tab switch; chooser paths and log text are readonly.

    The final workaround overrides selection methods in the 
    TextInput class here (it didn't work in .kv) to disable 
    selections in full.  This makes the earlier fixes moot, 
    and brings an end to all the troubles.

    FC UPDATE: later versions of Kivy's TextInput, and by 
    inheritance, KivyMD's MDTextField, have "use_handles" and
    "use_bubble" properties, which, if set to False, disable
    selection handles and bubbles without the method overrides
    here.  See allpopups.kv and common.kv for usage in FC. 
    -------------------------------------------------------
    """

    muiltiline = True

    def on_double_tap(self):  pass   # trace('on_double_tap\n')
    def on_triple_tap(self):  pass   # trace('on_triple_tap\n')
    def on_quad_touch(self):  pass   # trace('on_quad_touch\n')
    def long_touch(self, dt): pass   # trace('long_touch\n')



# See also: BorderedDayLayout and other dynamic widgets in monthgui.py




#====================================================================================
# The App class (a.k.a. "app" in .kv), with this program's non-screen logic in FC
#====================================================================================


class Frigcal(MDApp):

    """
    ----------------------------------------------------------
    Handles app build, startup, and close, along with all
    main-menu actions and common ops.  Screen-specific logic
    is mostly split off to separate *gui.py files, which get
    a link back the App instance for ops and other screens.

    Builds main root widget defined in ./main.kv, in build().
    Loads file by explicit name (alts: class name or string).
    Could build GUI manually, but avoids add_widget(), etc.
    In all cases, 'root' refers to the top-level main widget.

    See common.kv for use of dynamic_font_size and font_size,
    and the related variables for font name.  TL;DR: KivyMD
    overrides them for MD, so they must be reset after creates.
    UPDATE: font-name setting was dropped, rationale elsewhere.

    NB: MDApp is patched trivially to avoid a brief KivyMD icon 
    on startup, only on macOS hosts used for PyInstaller builds.
    ----------------------------------------------------------
    """

    # class globals

    # bound to Widget font_size in .kv: changes update all (non-KivyMD) widgets
    dynamic_font_size = NumericProperty(FONT_SIZE_DEFAULT)    # set before build()

    # NOT bound to Widget font_name in .kv: breaks menu icons and hamburger button
    #dynamic_font_name = StringProperty(FONT_NAME_DEFAULT)    # CUT (see common.kv)

    # till overridden by self attribute on PCs in storage.py
    folderchooser_open = False

    # TBD: a frigcal3 feature that may not work in phones' cramped displays
    mutiple_month_windows = False

    # to cancel single-tap handlers on double-tap in MonthScreen
    pending_tap_event = None

    # for splitting text into multiple Labels
    textboxlabels = {}    # {layout-widget: [label-widgets]}




#====================================================================================
# App: GUI Build
#====================================================================================



    def build(self):

        """
        -------------------------------------------------------------------
        Make GUI, run before App.on_start().
        The return value here becomes self.root for the App instance.
        This method is optional if the .kv file is auto loaded by name.
        -------------------------------------------------------------------
        """

        traces('@' * 80, 'app.build')    # call out in android logcat

        # from settings, set for use by this and other classes
        self.settings = AppSettings(self)                        # do here for theme+bubbles

        self.theme_cls.theme_style = self.settings.colortheme    # now persistent
        self.theme_cls.primary_palette = 'Blue'                  # must be before kv load

        #self.theme_cls.theme_style = 'Dark'                     # or 'Light' (no 'Auto')
        #self.theme_cls.theme_style_switch_animation = True      # broken in kivymd 1.1.1!
        #self.theme_cls.primary_hue = '800'

        # required by .kv before search-screen is built, dialogs are later
        self.editbubbles = self.settings.editbubbles

        # [4.1] not required till edit dialog opened, but init here for proximty
        self.defaultcalendar = self.settings.defaultcalendar

        # build gui from kvlang rules        # name frigcal.kv would be auto, but eibti
        #tree = Builder.load_string(KV)      # if an embedded string here, can do > once

        # kvlang files are relative to '.' set prestart_pc_tweaks: source-code dir, 
        # or, per build's --add-data, macOS .app or temp unzip for PyInstaller exes 

        kvlangfile = 'main.kv'
        tree = Builder.load_file(kvlangfile)    # this plus its includes

        # nav-drawer clickables (sans child-widget scans)
        self.menuAllItems = [
            tree.ids[id] for id in 
                ('month', 'search', 'goto',
                 'save',  'new', 'theme', 'settings',
                 'help', 'about',
                 'today', 'nextmo', 'priormo', 'nextyr', 'prioryr')]

        # screen switches
        self.menuSwitchScreenItems = [
            tree.ids[id] for id in 
                ('month', 'search', 'settings', 'help',  'about')]

        # month-screen openers
        self.menuOpenMonthItems = [
            tree.ids[id] for id in 
                ('goto', 'today', 'nextmo', 'priormo', 'nextyr', 'prioryr')]

        # no screen change
        self.menuNeutralItems = [
            tree.ids[id] for id in 
                ('new', 'save', 'theme')]

        # menu state-transition info
        self.menuMonthItem   = tree.ids.month     # for forced screen switches
        self.menuPriorSelect = tree.ids.month     # for shading and click skips

        # opens with first screen in mgr: Month
        self.menuMonthItem.selected = True
        self.menuMonthItem.selected_color = self.manual_theme_color_sel()

        # proto: force days and month label
        ##self.fill_days_grid(tree)

        trace('end app.build')
        return tree    # becomes App's self.root




#====================================================================================
# App: main menu and its actions
#====================================================================================



    def toggle_menu(self):

        """
        -------------------------------------------------------------------
        Show or hide the navigation drawer and its nested menu.
        -------------------------------------------------------------------
        """

        trace('toggle_menu')
        self.root.ids['nav_drawer'].set_state('toggle')



    def switch_to_screen(self, switchto, root=None, label=None):

        """
        -------------------------------------------------------------------
        Change main window's screen to the one named switchto in .kv.
        Noth that the first sreen in manager (month) is opened first.
        -------------------------------------------------------------------
        """

        trace('switch_to_screen')
        self.root.ids.navscreenmgr.current = switchto



    def changed_calendars_indicator(self, instance, state):

        """
        -------------------------------------------------------------------
        [4.1] Add a "* " prefix to main menu's "Save Calendars" label to 
        show that there are unsaved calendar changes, so users don't have
        to save or close to trigger and dismiss messages to find out.  

        Called on menu.state changes to mod label when menu is displayed, 
        not on every CalendarsDirty change.  This includes hamburger menu, 
        pullovers, and forced opens, if any.  It makes the "* " add and
        remove noticeable, but usefully.  Kivy on_open no longer works.

        Was initially coded as a '[sup]mods[/sup]' superscript suffix,
        but its small size was hard to read, and this was eventually 
        abandoned because it could be truncated for larger font sizes.
        -------------------------------------------------------------------
        """

        trace(f'menu.state: {state}')
        if state != 'open':
           return
        
        indicatorshow = any(CalendarsDirty[icsfilename] for icsfilename in CalendarsTable)
        indicatortext = '* '
        menusavelabel = self.root.ids.save

        if indicatorshow and not menusavelabel.text.startswith(indicatortext):
            menusavelabel.text = indicatortext + menusavelabel.text

        elif not indicatorshow and menusavelabel.text.startswith(indicatortext):
            menusavelabel.text = menusavelabel.text[len(indicatortext):]



    #-------------------------------------------------------------------
    # Shared manual theme colors, for kivymd colors fail in nav menu.
    # KivyMD 1.1.1 also botched colors on theme switches after screen 
    # switches: KivyMD 1.2.0 handles ok but requires Kivy 2.3.1 (gulp).
    # Also used in the .kv by a class that initializes colors @startup.
    # See also themeForPopup() for manual popup dialogs theme tweaks.
    #-------------------------------------------------------------------

    def manual_theme_color_fg(self):
        return 'white' if self.theme_cls.theme_style == 'Dark' else 'black'

    def manual_theme_color_bg(self):
        return '#212121' if self.theme_cls.theme_style == 'Dark' else 'white'

    def manual_theme_color_sel(self):
        return 'gray'

 

    def manage_menu_post_click(self, clicked, toggle=True):
      
        """
        -------------------------------------------------------------------
        Go manual on colors and selections for navigation-drawer items.
        Else, multiple menu items are selected and wrongly colored after
        switching themes - so badly that icons/text are invisible (argh!). 

        The only workaround that sufficed for all cases is a full colors 
        reset for all menu items after each menu selection, along with: 

        - Graying clicked navSwitchScreenItems that imply a screen switch
        - Graying Month for clicked navOpenMonthItems that imply a Month open
        - Graying navPriorSelect's for clicks on navNeutralItems to restore

        Graying is used to indicate the current screen.  This doesn't fully
        disable items because changing item.disabled triggers another Kivy 
        or KivyMD bug that changes the color of unrelated widgets, including 
        screen text and the hamburger icon, making them invisible (argh!).

        The graying steps could be done in each item's callback instead of 
        using item lists, but centralized here.  This originally used a 
        gross child-widget walk before adopting item lists made in build():
        '''
        menuitems = self.root.ids['nav_drawer_menu'].children[0].children
        for child in menuitems:
            if hasattr(child, 'text') and hasattr(child, 'icon'):
                child.selected = False
        '''

        Skip menu close for nav items to keep menu open for mutiple clicks,
        skip clicks on items whose screen is already open, and postpone 
        menu-item color changes with Clock till menu state is complete.

        Subtle: swipes invoke nav menu ops, which don't toggle the menu
        (for multiple taps) but work for swipes too (no menu, Month open).
        Also: KivyMD 1.1.1's theme_style_switch_animation broken (argh!!!).
        -------------------------------------------------------------------
        """

        # close nav drawer menu, except for nav items

        if toggle:
            self.toggle_menu()

        def reset_menu_items(clicked):

            # reset menu-item colors/selection

            for item in self.menuAllItems:
                #item.disabled = False
                item.text_color     = self.manual_theme_color_fg()
                item.selected_color = self.manual_theme_color_fg()
                item.icon_color     = self.manual_theme_color_fg()  
                item.bg_color       = self.manual_theme_color_bg()

            # set or restore menu-item selection

            if clicked in self.menuSwitchScreenItems:
                #clicked.disabled = True                      # kivymd 1.1.1 code bug
                clicked.selected = True
                clicked.selected_color = self.manual_theme_color_sel()
                self.menuPriorSelect = clicked
        
            elif clicked in self.menuOpenMonthItems:
                self.menuMonthItem.selected = True
                self.menuMonthItem.selected_color = self.manual_theme_color_sel()
                self.menuPriorSelect = self.menuMonthItem

            elif clicked in self.menuNeutralItems:
                trace('prior select')
                self.menuPriorSelect.selected = True
                self.menuPriorSelect.selected_color = self.manual_theme_color_sel()

        # do-later required, else state flux botches some colors
        Clock.schedule_once(lambda dt: reset_menu_items(clicked))



    # ==============
    # MENU CALLBACKS
    # ==============



    # ----
    # MAIN
    # ----

    
    """ 
    # now done in storage.py after calendars ask + load thread 
    def fill_days_grid(self, tree=None): 
        # prototype; must go deeper for ids in screens
        ...trimmed...
    """



    def on_menu_month(self, instance):                  
        if instance == self.menuPriorSelect:
            # ignore if already open
            trace('skip')
        else:
            # screen switch
            self.switch_to_screen('month')
        self.manage_menu_post_click(instance)



    def on_menu_search(self, instance):
        if instance == self.menuPriorSelect:
            # ignore if already open
            trace('skip')
        else:
            # screen switch
            self.switch_to_screen('search')
        self.manage_menu_post_click(instance)



    def on_goto_date(self, instance, value, date_range):
        
        # Used for both Ok in Go To popup and item pick in 
        # Search screen; value is the target date as a py 
        # datetime.date object, other arguments are unused
        # date-picker artifacts, date picker is auto-closed;

        # mod month-screen content
        date = value.strftime('%m/%d/%Y')              # MM/DD/YYYY
        self.monthgui.viewdate.setdate(date)
        self.refill_month_widgets()                    # [4.1] unscrolls days
            
        # mod screen+menu after Ok, not Cancel; instance != goto
        self.switch_to_screen('month')
        self.manage_menu_post_click(self.root.ids.goto, toggle=False)



    def on_menu_goto(self, instance):
        # popup + switch to Month screen

        # FC 3.0-'s goto was a persistent widget at top of month.  
        # FC 4.0 uses a modal popup dialog opened in main menu instead.
        # Now uses a canned KivyMD 1.2.0 picker dialog instead of custom.

        trace('menu goto')
        viewdate = self.monthgui.viewdate
        config = dict(
                    month=viewdate.month(),     # open on view date, else today and +navs
                    day=viewdate.day(),
                    year=viewdate.year(),
                    firstweekday=6)             # start weeks Sunday, else 0=Monday != Month

        # toggle now for date popup, but can't set menu to Month until Ok;
        # pass nav-neutral 'new' to reset prior shade lost on toggle (hack!)

        #self.manage_menu_post_click(instance)
        self.manage_menu_post_click(self.root.ids.new, toggle=True)

        # open kivymd date picker dialog
        datedialog = MDDatePicker(**config)           # in 1.2.0, always a popup, input=dd/mm/yyyy 
        datedialog.helper_text = ''                   # else always shows "Wrong date," weirdly
        datedialog.bind(on_save=self.on_goto_date)    # bind required (for properties?)
        datedialog.open()

        # prior custom-dialog code cut here: see allpopups.kv



    # -----
    # TOOLS
    # -----


    def on_menu_save(self, instance):
        # no popup or screen switch, but may show folder-ask and busy-wait popups

        # There is a gray boundary use case if the calendar folder 
        # has become inaccessible and we must ask for a new one now,
        # but the best we can do is to save changes to a new folder 
        # here because loading new calendar files would wipe out the 
        # very changes that the user is trying to save.  
        #
        # After saving in this case, the GUI won't quite reflect the 
        # new folder, but this is so rare as to be likely impossible.
        # The user would have to delete or rename the calendar folder 
        # or remove the app's permission to it... while the app is 
        # running and after calendars have been loaded.
        #
        # So, this can plausibly be marked up to a user procedural error,
        # and the user can sort out the aftereffects.  Still, for safety,
        # run_with_* now augments an info_message to alert the user if this 
        # bizarre use case is detected.  For more info, see storage.py's 
        # ask_calendars_folder_info().
        #
        # [4.1] The menu's save label now displays a changes indicator,
        # so users need not run a save to check if there are any changes.

        trace('save')
        if not any(CalendarsDirty[icsfilename] for icsfilename in CalendarsTable):
            # skip popups, but tell user too else silence
            self.info_message('No changed calendars to save', usetoast=True)
        else:
            Clock.schedule_once(
                lambda dt:
                    self.storage.run_with_calendars_folder(
                        self.storage.backup_and_save_all_changed_ics_files)    # see Subtle there
            ) 
        self.manage_menu_post_click(instance)



    def on_menu_new(self, instance):
        # popup only, no screen switch

        # FC 3.0-'s new was a cmdline script that wrote canned text to 
        # a .ics file and expected it to be loaded on the next GUI launch.  
        # FC 4.0's New instead adds an in-memory calendar only and relies 
        # on user Save to write it to .ics file.  4.0 also avoids a bogus 
        # sole event by adding it only on Save iff required, and avoids a 
        # default calendar by expecting New for initially empty folders
        # and requiring at least one calendar (e.g. by New) before events
        # can be added.

        trace('new')
        message = (
            '[b]Enter new calendar name[/b]'
            '\n\n'
            'Below, please enter the name of the new calendar you wish to add, with '
            'or without the ".ics" extension of its filename.'
            '\n\n'
            'Add events to your new calendar normally by selecting it in the '
            'event dialog, and use the main menu\'s Save to create the new '
            'calendar\'s ".ics" file.')

        def add_calendar(prompter):                                # prompter: root from .kv
             self.dismiss_popup(prompter)                          # also in enclosing scope

             icsfilename = prompter.ids.newcalname.text
             if not icsfilename: 
                 # add with no filename
                 self.info_message(
                     'Calendar name empty: skipped', usetoast=True)
                 return

             if not icsfilename.endswith('.ics'): 
                 icsfilename += '.ics' 

             if icsfilename in CalendarsTable:
                 # else backup/save may overwrite original!
                 self.info_message(
                     'Calendar already exists: skipped', usetoast=True)
                 return
                          
             CalendarsTable[icsfilename] = new_vcalendar()         # make empty in-memory calendar
             CalendarsDirty[icsfilename] = True                    # force first write on Save
             self.info_message(
                 'Calendar added: Save for file', usetoast=True)
   
        prompter = NewCalendarDialog(
                       message=message,
                       onadd=add_calendar,
                       oncancel=self.dismiss_popup)

        popup = Popup(
                    title='New Calendar',
                    content=prompter, 
                    auto_dismiss=False,          # ignore taps outside
                    size_hint=(0.9, 0.8),        # phones wide, e-2-e short
                    **self.themeForPopup())      # fg/bg colors if 'light'

        self.popupStack.push(popup)
        self.popupStack.open()                   # show top Popup with Dialog
        self.manage_menu_post_click(instance)



    def on_theme(self, instance, toggle=True):

        # no popup or screen switch
        # toggle is False for Settings screen Theme

        trace('theme')
        if self.theme_cls.theme_style == 'Dark':
            self.theme_cls.theme_style = 'Light'
        else: 
            self.theme_cls.theme_style = 'Dark'

        self.monthgui.shade_current_day()    # re-colorize current day
        self.set_system_bars_fg_color()      # toggle bars' color on Android
        self.set_system_bars_bg_color()      # no-op for transparent bars

        # ad-hoc theme fixes: some already-built widgets do not auto-adjust;
        # themes seem awfully buggy in kivymd 1.2.0; have they improved yet?

        self.searchgui.fix_widgets_for_theme()
        self.settingsgui.fix_widgets_for_theme()

        # also update theme name in the Settings screen
        # moot for Settings mods but not for main-menu Theme
        # .settings table is not updated till Save to file

        newtheme = self.theme_cls.theme_style
        self.settingsgui.screen.ids.colortheme.text = newtheme

        self.manage_menu_post_click(instance, toggle) 



    def on_menu_settings(self, instance):
        if instance == self.menuPriorSelect:
            # ignore if already open
            trace('skip')
        else:
            # screen switch
            self.switch_to_screen('settings')
        self.manage_menu_post_click(instance)



    # ----
    # INFO
    # ----


    """CUT
    def split_label_text_halves(self, text):

        # NO LONGER USED: generalized into set_split_label_text().
        # Split text into halves for two labels to avoid blank text.
        # A gross workaround for Label size limits: see Help in 
        # allscreens.kv, and notes at on_pause()/on_resume ahead.  
        # Also unknown if must stage text for Label like TextInput.

        lines = text.split('\n')
        half  = len(lines) // 2
        lines1, lines2 = lines[:half], lines[half:]
        return '\n'.join(lines1), '\n'.join(lines2)

        # was used like this:
        helpscreen  = self.root.ids.navscreenmgr.get_screen('help')
        helpwidget1 = helpscreen.ids.helptext_half1
        helpwidget2 = helpscreen.ids.helptext_half2
        helpwidget1.text, helpwidget2.text = \
            self.split_label_text(self.stage_help_message)
    CUT"""



    def set_split_label_text(self, text, labelbox, reuse=True):

        # Display large text in multiple Labels for size limits.
        # Avoids blank text initially (but not after pause/resume).
        # - labelbox: a layout in a ScrollView for the text Labels
        # - reuse: set text of existing Labels for speed, else rebuilds
        # Splits on lines b/c words/chars imply complex partial lines.
        # Originally used halves, generalized for more+smaller labels.

        maxlinesperlabel = 20    # FC lines (labels): Help=94 (5), About+TOU=75 (4)

        if labelbox not in self.textboxlabels:
            # first build
            reuse = False
            labelslist = self.textboxlabels[labelbox] = []    # grow shared mutable
        elif reuse:
            # retain priors
            labelslist = self.textboxlabels[labelbox]         # mod text in-place
        else:
            # rebuild labels
            priorlabels = self.textboxlabels[labelbox]        # clear and regrow
            for priorlabel in priorlabels:
                labelbox.remove_widget(priorlabel)            # or priorlabel.parent
            labelslist = self.textboxlabels[labelbox] = []     
        
        lines = text.split('\n')
        numlabels = math.ceil(len(lines) / maxlinesperlabel)

        nlabel = 0
        verify = []
        while lines:
            chunklist, lines = lines[:maxlinesperlabel], lines[maxlinesperlabel:]
            chunktext = '\n'.join(chunklist) or ' '
            verify.append(chunktext)

            nlabel += 1
            if reuse:                                           # prior labels present
                labelslist[nlabel - 1].text = chunktext         # reset label's text
            else:                                               # make/fill new label
                nextlabel = Factory.LabelTextDisplay(           # class def in .kv file
                    text=chunktext,                             # empty str makes too tall
                    padding=((dp(10), dp(10), dp(10), 0)        if nlabel == 1 else
                             (dp(10), 0,      dp(10), 0)        if nlabel < numlabels else
                             (dp(10), 0,      dp(10), dp(10))   # left, top, right, bottom
                ))

                labelbox.add_widget(nextlabel)
                labelslist.append(nextlabel)

                # bind font size+name _after_ creation else kivmd overrides per MD
                nextlabel.font_size = self.dynamic_font_size
               #nextlabel.font_name = self.dynamic_font_name    # CUT

        trace(f'text split across {nlabel} Labels')

        # this will only fail at dev/testing time: app info is not dynamic
        # ('\n'.join(verify) == text) false if last label is for empty line 
       
        assert (len(text) ==  
                sum(len(line) for line in verify)          # label chunks text 
                    + (nlabel - 1)                         # '\n' between labels
                    - int(verify and verify[-1] == ' ')    # last is ' ' if empty
        ), 'text-split sanity test failed'



    def set_help_text(self, dt, reuse=True):

        # run by on_menu_help (tap) and on_resume (scroll glitch) 
        # replaces [H] headers now, so retained for later changes

        self.help_text_set = True

        helpscreen = self.root.ids.navscreenmgr.get_screen('help')
        helptext   = self.headerize_text_markup(self.stage_help_message)    # mod [H]s
        helpbox    = helpscreen.ids.helptextbox

        self.set_split_label_text(helptext, helpbox, reuse)



    def set_about_text(self, dt, reuse=True):
 
        # run by on_menu_about (tap) and on_resume (scroll glitch)
        # replaces [H] headers now, so retained for later changes

        self.about_text_set = True

        aboutscreen = self.root.ids.navscreenmgr.get_screen('about')
        abouttext   = self.headerize_text_markup(self.stage_about_message)   # mod [H]s
        aboutbox    = aboutscreen.ids.abouttextbox

        self.set_split_label_text(abouttext, aboutbox, reuse)



    def on_menu_help(self, instance):
        if instance == self.menuPriorSelect:
            # ignore if already open
            trace('skip help switch')
        else:
            # screen switch, skip fill if already set
            # TBD: still need to stage text for fill lag?

            if not getattr(self, 'help_text_set', False):
                Clock.schedule_once(self.set_help_text)
 
            self.switch_to_screen('help')
        self.manage_menu_post_click(instance)



    def on_menu_about(self, instance):
        if instance == self.menuPriorSelect:
            # ignore if already open
            trace('skip about sitch')
        else:
            # screen switch, skip fill if already set
            # TBD: still need to stage text for fill lag?

            if not getattr(self, 'about_text_set', False):
                Clock.schedule_once(self.set_about_text)

            self.switch_to_screen('about')
        self.manage_menu_post_click(instance)



    # ---
    # NAV
    # ---


    def refill_month_widgets(self):
 
        # [4.1] run reset_daycell_scrolls() here for all navs 
        # and loads; but not for event-dialog update/delete/add,
        # which call only fill_events() directly instead of this
        # and should not undo an existing daycell events scroll;

        self.monthgui.reset_daycell_scrolls()    # [4.1] unscroll days
        self.monthgui.fill_days()                # clears prior daynums
        self.monthgui.fill_events()              # clears prior events



    def on_menu_today(self, instance):
        # switch to Month screen
        trace('today')

        self.monthgui.viewdate.settoday()
        self.refill_month_widgets()                   # [4.1] unscrolls days

        self.switch_to_screen('month')                         # moot if run by gesture
        self.manage_menu_post_click(instance, toggle=False)    # keep menu open if open



    def on_menu_nextmonth(self, instance):
        # switch to Month screen
        trace('nextmonth')

        if not self.mutiple_month_windows:            # tbd
            self.monthgui.viewdate.setnextmonth()     # move just this window
            self.refill_month_widgets()               # [4.1] unscrolls days
        else:
            for window in OpenMonthWindows:           # else all open windows move
                window.viewdate.setnextmonth()        # move this window
                window.refill_month_widgets()

        self.switch_to_screen('month')
        self.manage_menu_post_click(instance, toggle=False)



    def on_menu_priormonth(self, instance):
        # switch to Month screen
        trace('priormonth')

        if not self.mutiple_month_windows:
            self.monthgui.viewdate.setprevmonth()
            self.refill_month_widgets()               # [4.1] unscrolls days
        else:
            for window in OpenMonthWindows:           # tbd
                window.viewdate.setprevmonth()
                window.refill_month_widgets()

        self.switch_to_screen('month')
        self.manage_menu_post_click(instance, toggle=False)



    def on_menu_nextyear(self, instance):
        # switch to Month screen
        trace('nextyear')

        if not self.mutiple_month_windows:
            self.monthgui.viewdate.setnextyear()
            self.refill_month_widgets()               # [4.1] unscrolls days
        else:
            for window in OpenMonthWindows:           # tbd
                window.viewdate.setnextyear()
                window.refill_month_widgets()

        self.switch_to_screen('month')
        self.manage_menu_post_click(instance, toggle=False)



    def on_menu_prioryear(self, instance):
        # switch to Month screen
        trace('prioryear')

        if not self.mutiple_month_windows: 
            self.monthgui.viewdate.setprevyear()
            self.refill_month_widgets()               # [4.1] unscrolls days
        else:
            for window in OpenMonthWindows:           # tbd
                window.viewdate.setprevyear()
                window.refill_month_widgets()

        self.switch_to_screen('month')
        self.manage_menu_post_click(instance, toggle=False)




#====================================================================================
# App: startup code, run after App.build() GUI construction
#====================================================================================



    def on_start(self):

        """
        -------------------------------------------------------------------
        Run by Kivy App.run() after initialization - after build() 
        has built the GUI, but before the app has started running.
        self.root is a preset link to the GUI's top-level instance,
        which is returned by App.build() (or made auto if no build())
        [not used much in FC because most code in is in App, not GUI].
        -------------------------------------------------------------------
        """

        super().on_start()
        traces('~' * 80, 'app.on_start')    # call out in android logcat
        root = self.root



        # -------
        # PRELIMS
        # -------

        # allow Popups to nest
        self.popupStack = PopupStack()
 
        # from hangless, set in kivy chooser on its create (TBD: used?)
        self.fileSystemLocalNoHang = FileSystemLocalNoHang(self)

        # now done earlier in build() for theme
        # self.settings = AppSettings(self)

        # propagate non-user-changeable cross-file global (yuck)
        icsfiletools.retainLiteralBackslashes = self.settings.retainLiteralBackslashes

        # create month-screen widgets+callbacks once on startup 
        self.monthgui = MonthGUI(self)

        # init calendar days for 'today' in case user taps "x" in folder ask
        self.monthgui.fill_days()

        # search-screen methods, factored to file
        searchscreen = self.root.ids.navscreenmgr.get_screen('search')
        self.searchgui = SearchGUI(self, searchscreen)

        # settings-screen methods, factored to file
        settingsscreen = self.root.ids.navscreenmgr.get_screen('settings')
        self.settingsgui = SettingsGUI(self, settingsscreen)

        # init Settings fields from self.settings: explicit access, not properties
        self.settingsgui.fill_widgets_from_settings()

        # tweak gui+configs for platforms, etc. (after settings loaded)
        self.startup_gui_and_config_tweaks()

        # [4.1] register menu state-change callback to mod saves indicator
        self.root.ids.nav_drawer.bind(state=self.changed_calendars_indicator)



        # ---------
        # CALENDARS
        # ---------

        # make platform-specific interface to calendars folder

        maxbackups = self.settings.maxbackups
        self.storage = (
                 CalendarsStorage_Android(self, maxbackups) if RunningOnAndroid else 
                 CalendarsStorage_PCs(self, maxbackups)
        )

        # make suggested default calendars folder if needed on PCs - only.

        # POSIX/pathname is ok for PCs, but not for Android, which does not 
        # allow shared-storage or Documents/ access sans user permission and
        # has no other good options.  See storage.default_calendar_folder_path().
        
        if not RunningOnAndroid:
            homepath = self.storage.default_calendar_folder_path()
            self.defcalspath = osjoin(homepath, CALENDARS_FOLDER_DEFAULT_NAME)
            try:
                if not os.path.exists(self.defcalspath):
                    os.makedirs(self.defcalspath)
            except:
                trace('Cannot make suggested calendars folder:', self.defcalspath)

        # plan calendar load, which will trigger a folder ask when runnum == 1 or no access
        # but don't ask/load unless on_start successful and not until TOU screen dismissed
        # load_all_ics_files also fills days/events for month: must do on load thread exit

        def after_terms_of_use():
            Clock.schedule_once(
                lambda dt:
                    self.storage.run_with_calendars_folder(
                        self.storage.load_all_ics_files          # refills gui on tread exit
                ))



        # ------
        # SPLASH
        # ------

        # close splash screen for Windows and Linux frozen executables now: 
        # the app window has been opened; must do this _before_ missing-files
        # error popup (and others) ahead, else splash screen covers it;

        if hasattr(sys, 'frozen') and (RunningOnWindows or RunningOnLinux):
            prestart_pc_tweaks.close_pc_exe_splash_screen()



        # ------
        # WINDOW
        # ------

        # on android, pan iff needed so input target is above onscreen keyboard;
        # '' (no pan: default), 'pan' (cpver bottom half), 'resize' (doesn't work
        # with SDL2 on Android), or 'below_target' (scroll window so target text 
        # field isjust above keyboard); the latter is generally best, but doesn't
        # handle multiline text field that grows on input: see allpopups.kv;

        Window.softinput_mode = 'below_target'

        # catch Back button: ask user to save if any calendars changed;
        # also ignore Back/Escape if any dialog open: Back too easy on android

        Window.bind(on_keyboard=self.catch_back_button)

        # warn user if tries to close app when any calendars have changed;
        # tbd: called on 'back' when app foreground?, but NOT on recents swipe?
 
        Window.bind(on_request_close=self.on_request_close)

        # this is not called for SDL2 on Android - bind to keyboard height changes
        # Window.bind(keyboard_height=lambda *pargs: trace('kb height:', pargs))
        #
        # LATER RETRY: unusable for fixed Note size for autosroll on cursor:
        # there is no keyboard_height callback for onscreen-keyboard show/hide, 
        # only Android insets callbacks that ignore os-keyboard's size as coded
        # [only nav/status bar heights are pulled by the e-2-e insets callback,
        # though kb height is available in callback as the .bottom of Type.ime()
        # and might be used to set a fixed size for Note = (root - buttons - ime=0),
        # but could not find a way to make Note size fixed in the .kv code (TBD)]
        """
        def on_keyboard_height(instance, height):
            trace('on_keyboard_height:', height)
        Window.bind(keyboard_height=on_keyboard_height)
        """



        # --------
        # PC ICONS
        # --------

        # pcs seem to need help on these beyond pyinstaller build
        # the .ico doesn't work on Windows with Kivy (cause unknown)
        # *SEE ALSO* prestart_pc_tweaks.py's macOS Dock-icon workaround

        if not RunningOnAndroid:
            self.title = APPNAME                                        # TBD: unused?
            pciconname = ('Frigcal1024.png' if RunningOnWindows else    # not .ico
                          'frigcal.icns'    if RunningOnMacOS   else
                          'frigcal.gif')
            pciconpath  = osjoin('icons', pciconname)
            self.icon   = pciconpath    # rounded-corners version
            Window.icon = pciconpath    # else kivy icon displayed



        # ------------
        # EDGE-TO-EDGE
        # ------------

        # Adapted from PPUS 1.4.0.  Run before any window makers on Android 
        # to register an insets callback handler that pads the main window
        # as needed for e-2-e display mode mandated when targeting Android 15+.
        
        # Handles status bar, navigation bar (3-button and gesture), and hidden
        # camera cutouts.  Must also work around padding issues for a KivyMD 
        # hamburger button and navigation drawer in small-screen landscape
        # (caution: button reposition here uses constants also in main.kv).  

        # Other requirements:
        # - Make MainWindow root a BoxLayout or similar, for .padding property
        # - Make system-bar insets initially black in strings.xml (via 
        #   buildozer.spec's apptheme) to match the Kivy splashscreen
        # - Change system-bar bg colors to transparent where possible, so 
        #   the window's bg color set by KivyMD extends below them and 
        #   auto-updates on app-theme toggles
        # - Change system-bar fg colors per KivyMD app theme both here and 
        #   on Theme toggles, ignoring device theme
        # - Some API calls are absent on older Androids: punt on e-2-e and
        #   transparent and force system bar colors per app theme on 10,
        #   and let system bars go black despite app theme on 9-.

        # This gnarly code is still needed in Kivy 2.3.1 (and KivyMD 1.2.0).
        # When built with this Kivy and KivyMD for target=Android 16 (api 36) 
        # and run on Android 15+, insets are _not_ automatically padded, and 
        # status and nav bars cover top/bottom of app's screen (really, the
        # app stretches into them).  It was not just Kivy 2.1.0 used by PPUS.

        # To handle e-2-e, must either redesign GUI, apply this code and its
        # other requirements, or build for Android 14 and sideloading only and
        # skip both e-2-e and Play drama (though an Android 16 build posted on
        # Play today gets 2/3 years updates/availability; Android 14 gets 0/1).
        # A temp optout is available if target Android 15 but goes away on 16.

        # This uses setDecorFitsSystemWindows(False) to enable e-2-e portably;
        # setNavigationBarContrastEnforced(False) to avoid a scrim on the 
        # 3-button navbar, so it's fully transparent; and both XML code in 
        # styles.xml and Java API calls to set status- and nav-bars colors.  
        # Some tools are unavailable on older Androids, hence the cutoff here.
        # See set_system_bars_bg_color() for the version-specific bar coloring.
 
        # With this, all MDScreens work, all Popups are ok, folderchooser is 
        # moot (SAF), and all Androids 8..16 are reasonable.  Has same unrelated 
        # Samsung rightways-rotate and tap-in-splitscreen glitches as PPUS,
        # and Android 16 also required predictive-back optout manifest setting.

        # Android suggests WindowCompat.enableEdgeToEdge(window) in androidx.core 
        # 1.17, but this made no difference here for b/w compat and still leaves
        # the navbar translucent and uses device (not app) theme for bar colors:
        # - developer.android.com/develop/ui/views/layout/edge-to-edge
        # - developer.android.com/develop/ui/views/layout/edge-to-edge-manually 

        # Currently unused: the height of the onscreen keyoard is also available 
        # in callback as the .bottom of Type.ime() value (for Note fixed size?).
        # Naturally, this is useful only on Android (Windows touchscreens differ).


        if RunningOnAndroid and self.get_android_version() == 10:           # minimize nesting

            # Skip e-2-e and force stat/nav bar colors per app theme
            # Avoids b/w compat issues, including missing api calls 

            trace('skipping edge-to-edge')                                  # really just 10 now
            self.set_system_bars_bg_color()                                 # black=>app theme on 10-
            self.set_system_bars_fg_color()                                 # !app theme on all
          
 
        if RunningOnAndroid and self.get_android_version() >= 11:           # skip on older androids

            # Enable e-2-e on next frame and catch insets callback
            # In callback, pad window for insets, fix btn+navdrawer

            trace('applying edge-to-edge')
            self.using_edge_to_edge = True                                  # (moot?) for chooser height

            @run_on_ui_thread
            def go_edge_to_edge(dt):                                        # nested ops must be ui thread
                trace('going edge-to-edge')
         
                # Get top view of kivy activity
                activity = self.get_android_activity()                      # $=static nested class
                AndrRId  = autoclass('android.R$id')
                rootview = activity.getWindow().getDecorView().findViewById(AndrRId.content)

                # Enable e-2-e mode for b/w compat with older androids
                WindowCompat = autoclass('androidx.core.view.WindowCompat')
                window = activity.getWindow()
                WindowCompat.setDecorFitsSystemWindows(window, False)           # must be in main ui thread?
                #WindowCompat.enableEdgeToEdge(window)                          # same effect in this context
   
                # Make navbar truly transparent, no scrim
                window.setNavigationBarContrastEnforced(False)                  # must be in main ui thread

                # Set initial system-bar colors for app theme, with e-2-e
                self.set_system_bars_bg_color()                                 # black=>transparent on andr11+                                 
                self.set_system_bars_fg_color()                                 # also run on main-menu Theme toggles

                # Define insets callback function
                def onApplyWindowInsets(view, insets):

                    # Get overlay regions sizes
                    Type    = autoclass('androidx.core.view.WindowInsetsCompat$Type')   # not android.view.WindowInsets    
                    avoid   = Type.systemBars() | Type.displayCutout()
                    select  = insets.getInsets(avoid)

                    # Pad kivy main window for insets
                    padding = (select.left, select.top, select.right, select.bottom)    # kivy order, four possible sides
                    self.root.padding = padding                                         # pad kivy main window for insets
          
                    # Fix hbbutton and navdrawer in small-screen landscape
                    if select.left or select.right:
                        def fix_hbbutton_after_main_resized(dt):

                            # reposition hamburger button for navbar in small-screen landscape
                            # else offsceeen (left navbar) or on navbar (right navbar) as coded in .kv

                            hbbutton = self.root.ids.hbbutton
                            startpos = self.root.width - (hbbutton.width + dp(8))    # as in .kv (caution)
                            hbbutton.x = (startpos - select.left) - select.right     # one select is 0

                            # manually close navdrawer (tried do_layout() disable/reenable, toggle_menu()*2)
                            # else part of navdrawer exposed on left navbar in small-screen landscape
 
                            if select.left:
                                self.root.ids.nav_drawer.set_state('closed')
 
                        # wait until main-window insets padding applied
                        Clock.schedule_once(fix_hbbutton_after_main_resized, 0.25)                     

                    trace('window insets callback:', padding)
                    return insets                                                 # or WindowInsets.CONSUMED (moot)

                # Register callback to android java api
                self.saveinsetslistener = onApplyWindowInsets                     # required: save reference in py
                rootview.setOnApplyWindowInsetsListener(onApplyWindowInsets)

                # Force insets update @startup (java: rootview.post(Runnable))
                rootview.requestApplyInsets()                                     # must be in main ui thread
 
            # Run all in main UI thread after other on_start() ui ops
            Clock.schedule_once(go_edge_to_edge)



        # ------
        # VITALS
        # ------ 

        # warn the user if supporting runtime files are absent in CWD: 
        # user likely moved exe out of unzip folder (in docs, but...);
        # subtle: also works if run as source from another dir, not as
        # exe in folder, thanks to os.chdir() in prestart_pc_tweaks.py;     
        # POSIX/filepaths OK on Android: files in app-install folder

        # UPDATE: this is likely moot in FC.  Unlike PPUS, FC's PyInstaller
        # exes on Windows and Linux ship just an exe plus user-only tools; 
        # their runtime items are all in the temp sys_MEIPASS unzip folder 
        # to which the app chdir()s on startup for relative access, so they 
        # won't be moved by users.  FC's macOS app's vitals are nested in the
        # .app bundle but the exe also there is unlikely to be moved; users 
        # also seem unlikely to move main.py out of the source-code package;
        # and the Android app's bits are fully off-limits.  Still...

        vitals = (HELP_FILE, ABOUT_FILE, TERMS_OF_USE_FILE)
        #vitals+= (FRIGCAL_PATH, 'frigcal-anim.gif')                # not .png    # TBD
        #vitals+= ('frigcal-pc',) if not RunningOnAndroid else ()

        if any(not osexists(v) for v in vitals):
            self.info_message(
                  '[b]Fatal error: missing app files[/b]'
                  '\n\n'
                  'This app cannot run, because it cannot find one '
                  'or more of its supporting files.  Did you move the '
                  'executable without its folder?  That doesn\'t work.'
                  '\n\n'
                  'The app will close itself to avoid exceptions.  Please ' 
                  'ensure that the app install folder is complete, and see '
                  'the User Guide\'s App-Packages coverage for more info.',
                                     usetoast=False, 
                                     nextop=self.shutdown_app)
            return   # show message and die on Okay



        # -----------
        # RUN COUNTER
        # -----------

        # get+incr run counter, ensure vitals
        # POSIX/filepaths OK on Android too: file in app-private folder
        # not used for trial version in FC, but may be other (dialog tweaks?)

        try:
            self.runnum = self.get_and_inc_run_counter()
        except:
            self.info_message(
                  '[b]Fatal error: cannot write admin files[/b]'
                  '\n\n'
                  'This app cannot run because it does not have permission '
                  'to write its admin files.  On Windows, this is often caused '
                  'by unzipping the package in C:\\Program Files; please use '
                  'any other location.  In other cases, please ensure that the '
                  'app\'s data folder is available and allows reads and writes.' 
                  '\n\n'
                  'The app will close itself to avoid exceptions.  Please ' 
                  'see the User Guide\'s App-Packages coverage for more info.',
                                     usetoast=False, 
                                     nextop=self.shutdown_app)
            return   # show message and die on Okay



        # ----------
        # HELP+ABOUT
        # ----------

        # queue text for help and about screen, but don't set in widgets 
        # till later and defer with Clock then, else lag in its display;
        # TBD: is this still required for FC labels vs PPUS's textinputs?
        # POSIX/filepaths OK on Android: files in app-install folder
        # CAUTION: tou_text2 is also used ahead for welcome screen, and
        # text markup here is also in Help/About .txt and a storage info.
        # UPDATE: this redundancy was reduced by headerize_text_markup().

        # load terms-of-use file, for About and popup
        tou_file = open(TERMS_OF_USE_FILE, 'r', encoding='utf8')
        tou_text = tou_file.read()
        tou_file.close()

        # text displayed on request, headerized later on fill
        with open(HELP_FILE, 'r', encoding='utf8') as help_file: 
            self.stage_help_message = help_file.read()

        with open(ABOUT_FILE, 'r', encoding='utf8') as about_file:
            platname  = ('Android' if RunningOnAndroid else
                         'Windows' if RunningOnWindows else    # no cigwin: a windows exe
                         'macOS'   if RunningOnMacOS   else
                         'Linux'   if RunningOnLinux   else '(Unknown)') 

            try:
                if RunningOnAndroid:
                    platname += f' {int(self.get_android_version())}'               # 16
                elif RunningOnWindows:
                    platname += f' {platform.win32_ver()[0]}'                       # 11
                elif RunningOnMacOS:
                    platname += f' {platform.mac_ver()[0]}'                         # 15.6.1
                elif RunningOnLinux:
                    platname += f' ({distro.name()} {distro.version_parts()[0]})'   # (Ubuntu 24)
            except:
                pass  # punt - not worth reporting

            # (ppus) add underlines to uppers    
            # tou_text2 = ''.join([line + '\n' if not line.isupper() else
            #                      line + '\n' + '=' * len(line) + '\n'
            #                         for line in tou_text.splitlines()])
 
            # change all-upper lines to underscores with uppers per simplistic titlecase 
            def titlecase(string):
                lowers = ['of', 'and', 'or', 'to']    # partial 
                return ' '.join(word.lower() if word.lower() in lowers else 
                                word.capitalize() 
                                for word in string.split(' '))
                
            # kivy text markup for headers must match about-template.txt
            tou_text2 = ''.join(
                [(line if not line.isupper() else 
                  f'[H2]{titlecase(line)}[/H2]')
                 + '\n'
                 for line in tou_text.splitlines()]
            )

            about_message = (about_file.read() % 
                     dict(VERSION    = VERSION, 
                          PUBDATE    = PUBDATE,
                          PLATFORM   = platname,
                          COPYYEAR   = PUBDATE.split()[1],
                          TERMSOFUSE = tou_text2))

            # headerized later on fill
            self.stage_about_message = about_message



        # ------------
        # TERMS OF USE
        # ------------

        # popup terms-of-use blurb on first run (also added to About tab above);
        # on all platforms; onerous, but makers need to protect themselves too;
        # popup ~last so appears on top (and above the calendars-folder popup);
        # use nextop to run calendars asks/load after this screen is dismissed;

        if self.runnum > 1:
            after_terms_of_use()
        else:
            self.info_message(f'[i]Welcome to {APPNAME}[/i]'
                               '\n\n'
                               'Before you get started, please take a moment to '
                               'read and agree to the following.'
                               '\n\n\n\n'
                              f'{tou_text2}'
                               '\n\n\n'
                               'For reference, you can find a copy of all these '
                               'statements in About of the app\'s main menu.',
                                       usetoast=False,
                                       nextop=after_terms_of_use)

        # now it's the user's turn
        traces('end app.on_start', '~' * 80)




#====================================================================================
# App: utility methods
#====================================================================================



    def get_android_activity(self, docast=True):

        """
        -------------------------------------------------------------------
        Common preamble for pyjnius java-api code: the main activity (screen)
        -------------------------------------------------------------------
        """

        pythonact = autoclass(ACTIVITY_CLASS_NAME)
        mActivity = pythonact.mActivity

        # cast may be unwanted: see storage.py's ask_calendars_folder
        if docast:
            # normal
            activity  = cast('android.app.Activity', mActivity)
            return activity
        else:
            # rare
            return mActivity


            
    def get_android_context(self, activity=None):

        """ 
        -------------------------------------------------------------------
        Common preamble for pyjnius java-api code: the app's context (info)
        -------------------------------------------------------------------
        """

        if activity == None:
            activity = self.get_android_activity()
        context = cast('android.content.Context', activity.getApplicationContext())
        return context



    def get_android_version(self):

        """
        -------------------------------------------------------------------
        Get version of Android on device running the app.
        Cached for speed, though likely relatively trivial.

        This is android.os.Build.VERSION.RELEASE in Java;
        SDK_INT may be botched if rooted and nonstandard (?).
        Subtly, VERSION is a nested class, not a Build field:
        developer.android.com/reference/android/os/Build
        developer.android.com/reference/android/os/Build.VERSION

        NB: Python's sys.getandroidapilevel() is the API at _build_ 
        time, not _run_ time, and won't suffice for checking the 
        host device's version.  E.g., Termux is always 24 (Android 7)
        today, on Android 10 and 13 phones.  This seems useless for 
        most apps' use cases, but host #s require pyjnius code below.

        UPDATE: Python now has platform.android_ver() which returns
        both the host's release (e.g., 13) and the build's API 
        (e.g., 24, redundantly), but it requires Python 3.13+.
        -------------------------------------------------------------------
        """

        if hasattr(self, 'cache_android_version'):
            return self.cache_android_version
        else:
            VERSION = autoclass('android.os.Build$VERSION')
            apiversion = VERSION.SDK_INT    # api/sdk version number, e.g., 35
            andversion = VERSION.RELEASE    # android version number, e.g., 15
            trace('Host Android:', apiversion, andversion)

            # str may be x, x.y, x.y.z, or ? - drop all but x or x.y
            while andversion.count('.') > 1:
                andversion = andversion[:andversion.rfind('.')]
            numandversion = float(andversion)

            self.cache_android_version = numandversion
            return numandversion



    def dismiss_popup(self, popupcontent):

        """
        -------------------------------------------------------------------
        Close the topmost popup on the popups stack.

        Used for all modal popups; this coding avoids setting
        popup content's close handler after the popup is made
        (popup needs content, but content close needs popup...).
        popupcontent often passed from .kv, where it's dialog root.

        Now just a convenience interface to the popups stack.
        Kivy Popups also have an auto_dismiss, which runs dismiss()
        on taps outside the dialog and is enabled by default. 

        UPDATE: pass Popup's content to avoid closing an overlaid
        dialog on double taps (see popups stack for more info).
        Also set Kivy auto_dismiss=False to prevent taps and closes
        outside scope of popups stack (they're also ambiguous+twitchy).
        -------------------------------------------------------------------
        """

        self.popupStack.dismiss(popupcontent)    # topmost: no longer assumes only 1 modal


  
    @mainthread
    def info_message(self, pmsg, usetoast=False, longtime=False, nextop=None):

        """
        --------------------------------------------------------------------
        Show an info message as an Android Toast, or in-GUI overlay Popup.
        pmsg is the text to show+scroll in the popup: a Python string in toast.
        If usetoast, uses an Android Toast display on Android: 2-lines max.
        longtime is passed on to show_toast, for its popup duration.
        nextop is any zero-argument callable run after info-popup close.

        @mainthread is required to run graphics updates in main/GUI thread only.
        @run_on_ui_thread is apparently just for Android things like Toast.
        It's unclear why we're not in the main/GUI thread here, but...

        (DETAILS: @mainthread simply calls Clock.schedule_once(..., 0) to ensure
        that calls to the function are run on the next UI event-loop iteration
        ("frame").   This only matters in code run by another thread that must 
        update the GUI.  @run_on_ui_thread acheives a similar effect by running
        calls to the wrapped function on the Java Python activity's UI thread.)

        Pass nextop to chain one next dialog after the info popup: any callable.
        Caution: this doesn't support >1 overlapping modal dialogs as is (was).
        LATER: yes it does - Popups are now stacked for overlaps, and also allow
        for double taps without silently closing covered popups (see PopupStack).
        Double taps seems a scourge in Kivy, but may stem from touch scaffolding?

        Also now uses a shorter popup if usetoast and not on Android - no reason
        to take up most of the window for 1 cryptic line.  This might also use 
        macOS slide-down popups, but Kivy doesn't support them? (KivyMD?; tbd).
        UPDATE: the text is now scrollable in .kv, so go a bit smaller everywhere.

        LATER: delay the setting of the popup's text content until the next 
        "frame," to avoid glitchy lag on slower phones.  Else, the text displays
        as a scrunched single column initially, before being drawn in full.  This
        was glaring on only one older/slower test phone (2018 Note 9), but may be 
        an issue on lower-end phones in general.  The delayed set has no noticeable 
        impact on faster phones, and is the same solution used for larger texts in 
        the Help and About tabs: see on_start() and on_tab_switch(). 

        LATER: scale the popup per message size.  Especially for narrow phones, 
        90% wide (link confirmation+chooser) where warranted will help.

        [4.0] Use "markup: True" in all screens and popups (including this)
        to allow Kivy text markup - code [] for bold, italic, underscore, 
        colors, etc.  But not if usetoast, per next method.
        --------------------------------------------------------------------
        """

        trace('info_message', nextop)

        if usetoast and RunningOnAndroid and len(pmsg.splitlines()) <= 2:
            # the arguably silly Android popup
            self.show_toast(pmsg, longtime)

        else:
            # toast is limited: make me an in-GUI modal popup
            if not nextop:
                canceller = self.dismiss_popup    # close Info: modal, basically
            else:
                canceller = (lambda popupcontent: 
                                (self.dismiss_popup(popupcontent), nextop()) )

            # shorter for one-liners
            # and wider for phones if 'big' (most are tall or wide)
            # sizer = (0.8, 0.5) if usetoast else (0.8, 0.8) 

            tallmsg = pmsg.count('\n') > 3 
            widemsg = any(len(line) > 30 for line in pmsg.splitlines())
            swidth  = 0.9 if widemsg else 0.8 
            sheight = 0.8 if tallmsg else 0.5
            sizer   = (swidth, sheight)

            content = InfoDialog(oncancel=canceller)    # delay message=pmsg

            popup = Popup(
                        title='Info', 
                        content=content,
                        auto_dismiss=False,        # ignore taps outside
                        size_hint=sizer,           # sized per message, (x, y)  
                        **self.themeForPopup())    # fg/bg colors if 'light'

            self.popupStack.push(popup)
            self.popupStack.open()                 # show top Popup with Dialog

            def set_info_text(dt): 
                hmsg = self.headerize_text_markup(pmsg)    # replace any [H]s now
                content.message = hmsg                     # closure: enclosing scope
            Clock.schedule_once(set_info_text)             # delay to avoid lag



    @run_on_ui_thread
    def show_toast(self, pmsg, longtime=False):

        """
        -------------------------------------------------------------------
        Show an info message as an Android Toast.
        Highly limited popup for short messages only.
        These can overlap poorly if longtime=True.
        Call this directly, or info_message(usetoast=True).
        See also: from kivymd.toast import toast

        [4.0] Kivy text markup will be displayed literally in
        Android toast - don't use [] markup in shorter messages.
        -------------------------------------------------------------------
        """

        # 2-line max (and should be narrow)
        pmsg = pmsg.strip().split('\n')
        pmsg = '\n'.join([pmsg[0], pmsg[-1] if len(pmsg) > 1 else ''])

        # Android API bit
        context  = self.get_android_context()
        String   = autoclass('java.lang.String')
        jmsg     = cast('java.lang.CharSequence', String(pmsg))
        Toast    = autoclass('android.widget.Toast')
        duration = Toast.LENGTH_LONG if longtime else Toast.LENGTH_SHORT
        Toast.makeText(context, jmsg, duration).show()



    def postBusyPopup(self, kindtext='loading'):

        """
        -------------------------------------------------------------------
        Post a blocking modal dialog while a calendar load or save is 
        being run in a thread.  kindtext is 'loading' or 'saving'.

        Popup changed but not auto-closed by the app on thread completion,
        to both avoid a flash for fast actions and provide exit feedback:
        - [This] Starts with busy note, image animated, Okay disabled
        - [Next] After op, caller changes note, stops animation, enables Okay
        calendarsfolder has been ensured by ask before this is called.
        If alendarsfolder is empty, a user alert posts above this dialog.
        -------------------------------------------------------------------
        """

        message = (
            '[b]Please Wait...[/b]'
            '\n\n'
           f'Frigcal is busy {kindtext} your ICS calendar files in:'
            '\n\n'
           f'....{self.storage.pprintFolder(self.settings.calendarsfolder)}'
            '\n\n'
            'This popup will update when this operation finishes.')

        blocker = BusyDialog(
                      message=message, 
                      onokay=self.dismiss_popup)     # when enabled after thread

        popup = Popup(
                    title='Busy Wait',
                    content=blocker,
                    auto_dismiss=False,           # ignore taps outside
                    size_hint=(0.9, 0.8),         # phones wide, e-2-e short
                    **self.themeForPopup())       # fg/bg colors if 'light'

        self.popupStack.push(popup)
        self.popupStack.open()                    # show top Popup with Dialog
        self._kindtext = kindtext
        return blocker



    def finalizeBusyPopup(self, blocker, animtest=False):

        """
        -------------------------------------------------------------------
        Update the busy-wait modal popup to reflect operation exit,
        per the preceding method's docs.  calendarsfolder has been 
        ensured (verified or set) by ask before this is called.
        -------------------------------------------------------------------
        """

        # [4.1] stats for loaded events

        numevents_allcals = sum(len(EventsTable[date]) for date in EventsTable)

        numevents_percal = (
            (icsfilename, sum(+1 
                 for date in EventsTable 
                     for uid in EventsTable[date] 
                         if EventsTable[date][uid].calendar == icsfilename))
             for icsfilename in CalendarsTable)


        # [4.1] format stats report

        eventplurality = '' if numevents_allcals == 1 else 's'

        filessegue = (
             'in no ICS files.' if len(CalendarsTable) == 0 else
             'in 1 ICS file:'   if len(CalendarsTable) == 1 else
            f'among {len(CalendarsTable):,} ICS files:') 

        reports_percal = '\n'.join(f'....{name}: {total:,}' 
                                       for (name, total) in sorted(numevents_percal))

        # f'{\n}' fails in earlier python used by buildozer
        # f'{f"\n\n{reports_percal}" if CalendarsTable else ""}

        maybe_reports_percal = ('\n\n' + reports_percal) if CalendarsTable else ''


        # change dialog message

        blocker.message = self.headerize_text_markup(
            f'Frigcal has finished {self._kindtext} your ICS files in:'
            '\n\n'
           f'....{self.storage.pprintFolder(self.settings.calendarsfolder)}'
            '\n\n'
            'Please press Okay to continue.'
            '\n\n\n'

           # [4.1] stats for loaded events
           f'[H2]Calendar-Folder Stats[/H2]\n\n'
           f'{numevents_allcals:,} total event{eventplurality} {filessegue}'
           f'{maybe_reports_percal}')

        blocker.ids.busyokay.disabled = False         # enable Okay for user close
        if not animtest:
            blocker.ids.busyimage.anim_delay = -1     # stop animated gif
            blocker.ids.busyimage.reload()            # reset gif: clear flips



    def themeForPopup(self):

        """
        -------------------------------------------------------------------
        Manually color a popup dialog about to be posted per the current
        theme settings in the app.  

        KivyMD auto-theming requires all-KivyMD widgets.  Theme colors work
        for most widgets from KivyMD like MDDialog, but not for core Kivy
        widgets like Popup and FloatLayout - popups' MDLabels had black text 
        on dark grey in light mode.  Hence, force colors.  Recoding to use
        KivyMD only is work and may not be as nice for larger messages.

        Popup dialogs are all modal: theme won't change while they're open.
        MDLabels embedded in popup for text message auto-themed by KivyMD.
        -------------------------------------------------------------------
        """

        if self.theme_cls.theme_style == 'Dark':                   # per app's theme
            return dict()                                          # do the Kivy default
 
        elif self.theme_cls.theme_style == 'Light':
            return dict(title_color='black',                       # match MDLabel text
                        background='',                             # remove default base
                        background_color=[1.0, 1.0, 1.0, 1])       # 'white', not transparent
                       #background_color=[0.9, 0.9, 0.9, 1])       # off 'white', not transparent



    def open_web_page(self, url):

        """
        -------------------------------------------------------------------
        The Android Intent is automated by android package:
        https://github.com/kivy/python-for-android/blob/develop/
            pythonforandroid/recipes/android/src/android/_android.pyx

        What webbrowser invokes on Android:
        Intent = autoclass('android.content.Intent')
        Uri    = autoclass('android.net.Uri')
        intent = Intent()
        intent.setAction(Intent.ACTION_VIEW)
        intent.setData(Uri.parse(url))
        activity = self.get_android_activity()
        activity.startActivity(browserIntent)
        -------------------------------------------------------------------
        """

        webbrowser.open(url)    # yes, that's it (for Android and PCs)



    def launch_file_explorer(self, folder=None):
      
        r"""
        -------------------------------------------------------------------
        Used for Calendar Files button in Help screen.
        folder is a URI on Android and a pathname on PCs.

        On Android: requires a file-explorer app; can this be lifted?
        On Linux: assume xdg-open installed, and background it via &
        else it blocks and may hang GUI on Windows WSL2 Linux (only).

        ABOUT WINDOWS/WSL2 PATH CONVERSIONS FOR EXPLORERS:

        This performs Windows <=> WSL2 pathname conversions because 
        Windows may be using a pathname chosen on WSL2 and vice-versa:
        - On Windows: /home/me/temp => \\wsl.localhost\Ubuntu\home\me\temp
        - On WSL2:    C:\users\me\temp => /mnt/c/users/me/temp
        Else, explorers crash with an exc on Windows and fail on WSL2.

        This differs from direct file opens.  Windows can open calendars 
        with a WSL2 folder path, but WSL2 cannot open calendars with a 
        Windows path, and we do not do these conversions for calendar 
        access.  Hence, this buys us WSL2 path explores on Windows and 
        Windows path explores on WSL2, but WSL2 is crippled for Windows 
        paths (and why Windows can use a WSL2 path at all remains a mystery).

        But this is really only an issue for the source-code package, 
        where a settings file may be shared by Windows and WSL2.  In 
        more-common executable installs, Windows and Linux will have 
        separate settings files with platform-specific pathnames, and
        shared source-code folders seem highly unlikely to impossible.
        See also PC opens in run_with_calendars_folder() of storage.py.

        ABOUT ANDROID SAF PICKER CODE:

        See ahead; as coded, the picker may open on a Recents, weakly. 
        -------------------------------------------------------------------
        """

        folder = folder or self.settings.calendarsfolder   # path or URI
        if not folder: return                              # too soon?
 
        # windows <=> wsl pathname conversion (tests are partial)
        if (RunningOnWindows and 
           (folder.startswith('/') and '\\' not in folder)):
            folder = \
                os.popen(f'wsl wslpath -w "{folder}"').read().rstrip() or folder

        elif (RunningOnWSL2 and 
             (re.match(r'^[a-zA-Z]:', folder) or '\\' in folder)):
            folder = \
                os.popen(fr'wslpath "{folder}"').read().rstrip() or folder

        # pcs are easy
        if not RunningOnAndroid:
            # pcs are easy...
            try:
                if RunningOnWindows:
                    os.startfile(folder)
                elif RunningOnMacOS:
                    os.system('open "%s"' % folder)         # allow spaces in pathname
                elif RunningOnLinux:
                    os.system('xdg-open "%s" &' % folder)   # ditto, xdg assumed on host
            except:
                # e.g., os.startfile can't access folder for wsl2 path
                trace(folder, sys.exc_info(), sep='...\n')
                self.info_message(f'Cannot explore {folder}', usetoast=True)

        else:
            # android is not...

            # use SAF/AOSP/builtin/DocumentsUI explorer because could not get
            # the explorer-app code from PPUS below to work with content URIs;
            # this code abuses the SAF picker (choice is ignored) but suffices
            # for a simple files list and does not require an explorer app;

            # regrettably, this UI lists only Recent files (either due to an 
            # undocumented coding error or in an attempt to be "user friendly"),
            # but Android Intents in this role are about as wonky as it gets,
            # and this app action is not useful enough to agonize over more;

            Intent = autoclass('android.content.Intent')
            DocumentsContract = autoclass('android.provider.DocumentsContract')

            folderUri = folder                              # str, not Uri.parse(folder) here
            intent = Intent(Intent.ACTION_GET_CONTENT)      # _VIEW, _GET_CONTENT, _OPEN_DOCUMENT?
            intent.addCategory(Intent.CATEGORY_OPENABLE)    # a real file, essentially
            intent.setType('text/calendar')
            intent.putExtra(DocumentsContract.EXTRA_INITIAL_URI, folderUri)    # andr 8+ only
 
            activity = self.get_android_activity()
            activity.startActivity(intent)                  # and a lame Recents UI opens


            # this failed to add a title to DocumentsUI
            # String = autoclass('java.lang.String')
            # intent = Intent.createChooser(intent, String(folderUri))

            # these failed in later androids: no-ops
            # intent.putExtra("android.content.extra.SHOW_ADVANCED", True)
            # intent.putExtra("android.content.extra.FANCY", True)
            # intent.putExtra("android.content.extra.SHOW_FILESIZE", True)

            # this fails too: DoumentsUI is not for browsing as of Android 12?
            # ComponentName = autoclass('android.content.ComponentName')
            # intent = Intent(Intent.ACTION_VIEW)
            # intent.setComponent(ComponentName('com.android.documentsui', 'com.android.documentsui.files.FilesActivity'))

            """FAIL
            # alternative tried to open the content URI in a file-explorer 
            # app (like PPUS does with a pathname via All Files Access), 
            # but failed for reasons TBD and not worth chasing further;
            # opens file explorer apps, but all report errors for the URI;
            # downside: unlike SAF, it requires an explorer-app install;

            activity = self.get_android_activity()
            #folder = self.storage.pprintFolder(folder)     # no: drop any %xx URI escapes?
 
            Uri = autoclass('android.net.Uri')
            uri = Uri.parse(folder)                         # required for content URI

            Intent = autoclass('android.content.Intent')
            intent = Intent(Intent.ACTION_VIEW) 
            intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)    # need on android 7+
            intent.setDataAndType(uri, 'resource/folder')

            # check if a handler app exits, else fails with exc
            if not intent.resolveActivity(activity.getPackageManager()):
                self.info_message('Please install a file-explorer app', usetoast=True)
            else:
                try:
                    activity.startActivity(intent)
                except Exception as E:
                    # unclear if any errors ever come here
                    trace(folder, uri, sys.exc_info(), sep='...\n')
                    self.info_message(f'Cannot explore {folder}', usetoast=True)
            FAIL"""



    def get_and_inc_run_counter(self):

        r"""
        --------------------------------------------------------------------
        Fetch + update the run-counter file.  Used on all platforms 
        to show terms of use on first run.  POSIX/filepaths are OK 
        here on Android because accessing app's own private folder.

        The write() here can easily fail if users unzip the Windows 
        package in C:\Program Files.  Catch this at call and issue a
        popup with tips, and close.  User should unzip anywhere else;
        permission mods (once) and run-as-admin (always) are harder.
        --------------------------------------------------------------------
        """

        # get run counter on all plaforms
        apppriv = self.storage_path_app_private() or ''
        countpath = osjoin(apppriv, RUNCOUNT_FILE)
        if not osexists(countpath):
            countruns = 1
        else:
            countfile = open(countpath, 'r')         # in app-private, not install
            countruns = int(countfile.read()) + 1
            countfile.close()

        # save new run counter on all platforms (POSIX + filepaths for all)
        countfile = open(countpath, 'w')
        countfile.write(str(countruns))
        countfile.close()

        trace('#Runs:', countruns)
        return countruns    # for terms of use, possibly others later 



    def storage_path_app_private(self):

        """
        --------------------------------------------------------------------
        Borrowed from PPUS: app's own, private, storage folder.
        Used to store public and persistent reources, which in 
        FC 4.0 means config-settings and run-counts files only.
        Nit: not in storage.py because not for _calendars_ storage.

        POSIX+pathnames OK for result path on all platforms: it's accessible 
        to the app.  User may access the result path on PCs but not on Android,
        which backs up these items to users' accounts if logged in/enabled.
        macOS maps this to ~/Library because translocation of unsigned apps
        may make the app's own install folder unusable for persistent data.
        Windows and Linux simply use the executable's install/unzip folder.

        Android details:

        The result here is /data app-private "internal" storage, which is 
        unusable for most user content.  It's fully app-private (sans file 
        provider+SAF), auto-uploaded to Google account for reinstalls (sans 
        user disable), and nuked on uninstall (sans hasFragileUserData toggle).

        This is not app-specific storage at /sdcard/Android/data nor general
        shared storage at /sdcard.  App-specific is no longer accessible to 
        file-explorer apps in 2025 (except Files==AOSP), and shared requires 
        user permissions via All Files Access or the SAF chooser just for 
        admin items.  HENCE: there is no user access to these items on Android
        (though there is no obvious reason why user access would be required).
        See also storage.default_calendar_folder_path()'s similar dilemma.

        API: this is Context.getFilesDir() in Java => the files/ subfolder 
        of app private.  The app install is in its (hidden) app/ subfolder.
        It has at least 2 names on Samsung phones, /data/data + /data/user/0,
        and Python tools don't map the two to a common canonical form (yet?).
        There is also Context.getDataDir(); and Environment.getDataDirectory()
        for a home folder, which seems to just be the parent folder of 
        Context.getFilesDir(), and shouldn't be used (supposedly...).
        --------------------------------------------------------------------
        """

        if RunningOnAndroid:
            # ask Android where the app-private folder is, per above
            # /data/data/com.quixotely.frigcal/files, a.k.a. /data/user/0/com...
            # not really 'public' on Android, but perstent and auto-backedup

            path = android.storage.app_storage_path()
            trace('app-priv:', path)
            return path

        elif RunningOnMacOS:
            # don't use install unzip on macos, becuase its security-based
            # translocation may disallow app's own folder: use ~/Library
            # see https://learning-python.com/pyedit.html#autosave2025

            if not hasattr(sys, 'frozen'):
                return '.'                                             # source, dev
            else:
                applib = osjoin(os.path.expanduser('~'), 'Library', APPNAME)
                if not osexists(applib):
                    os.makedirs(applib)    # make Library too if needed, vs mkdir
                return applib

        else:
            # Windows, Linux: cwd, which is app install/unzip folder
            # app requires write access to this: don't install in C:\Program Files
            # frozen exes use install unzip, not sys.MEIPASS run unzip: a temp dir

            if not hasattr(sys, 'frozen'):
                return '.'                                             # source, dev
            else:
                exepath = sys.executable
                exedir  = os.path.dirname(os.path.abspath(exepath))    # install/unzip folder
                return exedir                                          # use '.' for all extras



    def set_font_size(self, fontsize):

        """
        --------------------------------------------------------------------
        On defocus for font size in Settings: setting the App instance's 
        dynamic_font_size here automatically changes font size for 
        EVERY wdget in GUI, because Widget font_size is bound to it
        in the .kv file.  Powerful (and arguably scary).  Alternatively,
        GUIs can bind font_size to this property in selected widgets.

        This size is in absolute pixels as coded, but could append size
        string with 'dp' or 'sp' to use density and user+density scaling:
        see kivy.org/doc/stable/api-kivy.metrics.html#kivy.metrics.sp.
        This seems arbitrary (a relative # is a relative #), but the 
        preset defalt may need to be scaled per device on startup. 
        Kivy's default is '15sp' which maps to '39' pixels on a Note20.

        LATER: use 'sp' pixels to avoid the scaling issues of preset...
        Downside: this provides less granularity then absolute pixels
        (1 sp pixel is about 2.56absolute pixels on screens like the 
        Note20's), and could probably specialize preset by platform.
        
        LATER: use the fontsize from the GUI as a string and allow 
        input per float filter, instead of assuming an int().  This 
        allows fraction sp pixels to compensate for the granularity.
     
        LATER: for better granularity, use absolute int pixels in GUI, 
        but set default/start to '15sp' equivalent per kivy.metrics (39
        on Note20).  This scales per device and user settings on first
        run, though it won't auto-update for user settings till rerun.
 
        LATER: this is now also run on startup and restore defaults
        to set fontsize; else user must click Apply each run/restore.

        NB: don't need to mod self.width to force widgets' minimum_width 
        to recalc for scrolling - happens automatically when font changed;

        NB: see common.kv for use of dynamic_font_size and font_size.
        KivyMD's overrides require it to be reset after some creates.
        --------------------------------------------------------------------
        """

        # there be much magic here...

        if fontsize != 0:                        # zero=keep default
            self.dynamic_font_size = fontsize    # abs, not + 'sp'

        # force Help/About refills that rescale headers for new fontsize
        # app is in startup or on Settings screen: no need to refill now

        self.help_text_set  = False
        self.about_text_set = False



    '''CUT
    def set_font_name(self, fontname):

        """
        --------------------------------------------------------------------
        Like font_size but for font_name, added in FC 4.0, marginally useful.

        UNUSED: Per common.kv, setting font_name globally in Widget would 
        break KivyMD menu icons and hamburger button, so it's not done.  
        Unlike font size, this makes font name apply only to new text, 
        not text already displayed, and font name in general applies only 
        to a subset of text widgets, not all.  PUNT on font-name setting. 
        --------------------------------------------------------------------
        """

        if fontname != '':                       # empty=keep default
            self.dynamic_font_name = fontname    # one of kivy's builtins
    CUT'''



    def headerize_text_markup(self, text):

        """
        --------------------------------------------------------------------
        Dynamically scale the fontsize of headers in marked-up text per 
        the user-changeable global fontsize setting.  Done for Help and
        About screen text, info_massage() notes, and other popup dialogs.
        There's no way to do this with Kivy markup sans text replacement.

        Must be redone for Help and About on fontsize mods in Settings: 
        already-loaded flags are removed to force refills in screens when 
        next viewed, and [H] are retained in text to defer replacements.
        This is open-ended styling, but use Kivy []s where they suffice.

        Underlines iffy because they look like links, but OK in headers.
        Size here is unscaled pixels because dynamic_font_size is too:
        use a proportional add-on instead of screen-dependent constants.
        The multipliers mean: 1.25 = +1/4, 1.125 = +1/8, 1.0625 = +1/16. 
        For abs @: @32 => 40, 36, 34; @25 => 31, 28, 26; @40 => 50, 45, 42.

        Example: 
            [H1]Gestures[/H1] => 
            [b][color=#2299ff][size=32]Gestures[/size][/color][/b] 
        --------------------------------------------------------------------
        """

        hdrcolor = '#2299ff'   # works in dark and light themes

        replaces = {
            '[H1]':  f'[u][b][color={hdrcolor}][size={int(self.dynamic_font_size * 1.25)}]',
            '[/H1]':  '[/size][/color][/b][/u]',

            '[H2]':  f'[b][color={hdrcolor}][size={int(self.dynamic_font_size * 1.125)}]',
            '[/H2]':  '[/size][/color][/b]',

            '[H3]':  f'[color={hdrcolor}][size={int(self.dynamic_font_size + 1.0625)}]',
            '[/H3]':  '[/size][/color]',
        }

        for tag in replaces:
            text = text.replace(tag, replaces[tag])
        return text



    def set_system_bars_fg_color(self):

        """
        --------------------------------------------------------------------
        On all Androids, set the foreground color of system's status and
        3-button navigation bars to jive with the app color theme.

        Called on menu Theme toggles (see on_theme) and initially when
        either setting up edge-to-edge display with transparent bars or
        forcing bar bg colors on older androids (see on_start, which 
        uses the same sort of wacky Java-api code). 

        This is independent of and ignores device theme on purpose:
        app has own Theme (Kivy has no direct device-theme access).
        The navbar color also applies only to the 3-button navbar;  
        the gestures navbar is always transparent with a neutral
        grey fg bar (and also works well with insets padding).

        WindowInsetsController not found on Android 8 and 9 but
        is on 10+ (it was added in 11, and androidx is used): punt.
        --------------------------------------------------------------------
        """

        if (not RunningOnAndroid) or (self.get_android_version() <= 9):
            return

        trace('setting bars fg')
        activity = self.get_android_activity()
        AndrRId  = autoclass('android.R$id')
        window   = activity.getWindow()
        rootview = window.getDecorView().findViewById(AndrRId.content)

        @run_on_ui_thread    # @mainthread fails
        def setter():
            WindowCompat = autoclass('androidx.core.view.WindowCompat')
            insetsController = WindowCompat.getInsetsController(window, rootview)
            if not insetsController:
                trace('set_bar_fg: no controller')
            else:
                applight = self.theme_cls.theme_style == 'Light'
                insetsController.setAppearanceLightNavigationBars(applight)
                insetsController.setAppearanceLightStatusBars(applight)

        # avoid android 10- java exception: 
        # "Only the original thread that created a view hierarchy can touch its views"
        setter()



    def set_system_bars_bg_color(self, initial=False):

        """
        --------------------------------------------------------------------
        On all Androids, set the status and 3-button navigation bars' 
        background color per app theme and support of host Android.  
 
        Bg always starts as black in styles.xml, to jive with the
        always-black Kivy splashscreen.  Else, during splashscreen, 
        Androids 14- show a dark-on-grey nav bar and a white-on-white 
        status bar (with a dark artifact on some).  

        After the splashscreen is closed, override the styles.xml
        initial black in on_start(), and invert it if needed for
        for main-menu Theme taps in on_theme(), by these rules:
        
        - On Androids 15+, set only nav bar bg to transparent.  Status
          bar is always transparent by Android policy.  Edge-to-edge is 
          both enabled by the app and enforced by Android, so the KivyMD  
          app-theme bg color shows under bars via edge-to-edge padding.

        - On Androids 11..14, set both status and nav bar bgs to 
          transparent.  Edge-to-edge is enabled by app, so the KivyMD 
          app-theme bg color shows under the bars as padding.

        - On Android 10, set both bars to the color of the KivyMD
          app-theme bg color.  Edge-to-edge is not enabled by the app
          due to missing API call getInsets() (despite using androidx), 
          so the app-theme bg won't appear under transparent bars.  
 
        - On Androids 8..9, bars don't respect app theme and e-2-e is 
          not usable.  WindowInsetsController, required to set bar fg 
          per app theme, is unavailable on 9- (despite using androidx), 
          so system bars are always black in dark and light app themes.

        - Android 7- are unsupported because some phones lack the
          timestamps support required for calendar-file backups.
 
        All of which reflects as-vetted parameters and is about as
        convoluted as it can be, but such is life in Android dev.
 
        rgb()s below are KivyMD 'Dark'/'Light' app-theme bg colors. 
        In Android 15+, the status bar bg is Color.TRANSPARENT by
        policy and ignores both color calls and XML settings, but 
        the nav bar default is auto-color + 80% translucent/opaque.

        This code, like the styles.xml colors code it overrides, 
        uses deprecated tools, but there are no known alternatives 
        today.  Apps are now probably expected to accept policy 
        defaults for bar colors based on device theme, but this 
        doesn't work with in-app themes like those in KivyMD.

        Nit: the @run_on_ui_thread defers this call, which makes 
        bars dark grey on Android 10 (only) until initial popups 
        closed, and there seems no way to prioritize this.  Meh.
        --------------------------------------------------------------------
        """

        if (not RunningOnAndroid) or (self.get_android_version() <= 9):
            return

        trace('setting bars bg')
        Color = autoclass('android.graphics.Color')
        transparent = Color.TRANSPARENT                # also #00000000, @android:color/transparent
        solidblack  = Color.rgb(18, 18, 18)            # app-theme backgrounds
        solidwhite  = Color.rgb(250, 250, 250)

        @run_on_ui_thread    # @mainthread fails
        def setter():
            activity = self.get_android_activity()
            window   = activity.getWindow()
            andrvers = self.get_android_version()
            try:
                if andrvers >= 15:
                    window.setNavigationBarColor(transparent)

                elif andrvers >= 11:
                    window.setStatusBarColor(transparent)
                    window.setNavigationBarColor(transparent)

                elif andrvers == 10:
                    appthemebg = (
                        solidblack if self.theme_cls.theme_style == 'Dark' else 
                        solidwhite)
                    window.setStatusBarColor(appthemebg)
                    window.setNavigationBarColor(appthemebg)
            except:
                trace('except in set bars bg color')       # in case exc if calls removed
                trace(sys.exc_info())

        # avoid android 10- java exception?: 
        # "Only the original thread that created a view hierarchy can touch its views"
        setter()




#====================================================================================
# App: GUI startup tweaks
#====================================================================================



    def startup_gui_and_config_tweaks(self):

        """
        Assorted mods to gui and configs for platform diffs/etc, post load
        of persisted setings.  Called explicitly from App.on_start(), only
        after load_settings has initialized or loaded settings.

        FC: this is now mostly unused code from PPUS.  Some that does 
        not require an App 'self' was moved to prestart_pc_tweaks.py.
        """



        # ---------
        # FONT SIZE
        # ---------

        # uses globalfontsize, already loaded by the settings system;
        # apply settings's font size now, else user must tap it each 
        # run, even though settings has been set to the last size saved;
        # see also restore-defaults, which similarly auto-applies value;
        # update: this, and every other context, now does same for name;
        # update: font-name setting was dropped - see rationale elsewhere;

        self.set_font_size(self.settings.globalfontsize)

       #self.set_font_name(self.settings.globalfontname)    # CUT



        # -------
        # SCROLLS
        # -------

        if not RunningOnAndroid:    # all PCs

            # default scrolling is too slow on PCs (only)  [TBD - gui]
           
            # TBD: +allpopups +others?
            scrollviews = (
                 self.root.ids.navscreenmgr.get_screen('help').ids.helptextscroll,
                 self.root.ids.navscreenmgr.get_screen('about').ids.abouttextscroll)

            for scroll in scrollviews:
                if RunningOnWindows or RunningOnLinux:
                    scroll.scroll_wheel_distance = 20
                    scroll.smooth_scroll_end = 20
                else:
                    scroll.scroll_wheel_distance = 10      # macos is special
                    scroll.smooth_scroll_end = 60



        # -------
        # PC DOTS
        # ------- 

        # moved to the new prestart_pc_tweaks.py



        # -----------
        # WINDOW SIZE
        # -----------

        """UNUSED
        if (RunningOnWindows or RunningOnLinux):    # not Android or macOS
            
            # FC - UNUSED: disable this temp workaround because Windows and Linux 
            # defaults now work well.  This code was required for PPUS's Kivy 2.1.0.
            # With newer Kivy 2.3.1 used in FC, this code is no longer needed on 
            # Linux, and on Windows it makes the window so large that it's partly 
            # off screen even with the position code below: drop it.

            initial_center = Window.center    # save for position recenter next

            lx = 150 if RunningOnLinux else 0                                   # was 100
            Window.size = (kivy.metrics.dp(748+lx), kivy.metrics.dp(612+lx))    # (w, h)

            #Window.size = (748, 612)    # different: too small on low-res dell
            #Window.size = (1120, 920)   # original:  too small on high-res yoga
        UNUSED"""
 


        # ---------------
        # WINDOW POSITION
        # ---------------

        """UNUSED
        if (RunningOnWindows):    # not Linux, macOS, or Android

            # FC - UNUSED: disable this temp workaround because Windows default 
            # now works well.  This code was required for PPUS's Kivy 2.1.0.  
            # With newer Kivy 2.3.1 used in FC, the window appears partly off 
            # screen because it's too big... which means the preceding size code
            # breaks it.  With the size code disabled it now has no effect: punt.    

            # recenter instead of pinning to abs location
            new_center = Window.center                      # center after resize above

            diffx = new_center[0] - initial_center[0]       # how much did center change?
            diffy = new_center[1] - initial_center[1] 

            Window.left = max(5,  Window.left - diffx)      # adjust top-left for change
            Window.top  = max(25, Window.top  - diffy)      # but not past top-left corner

            trace('Repos:', initial_center, new_center)     # @2k: (400.0, 300.0) (561.0, 459.0)
        UNUSED"""



        # -----------
        # TEXT ALIGNS
        # -----------

        """UNUSED
        # FC - UNUSED: FC uses KivyMD labels and text, not Kivy TextInput.

        # Force left-align text in Main tab's path fields (else pseudo-random)
        # weirdly hard, but halign and scroll_x in .kv had no effect, for reasons tbd
        # scheduling separately helps, but still fails on 1 of 6 test devs (andr9)
        # UPDATE: this is related to font size: moving below that setting here 
        # fixed andr9 too; clock scheduling is still required, but just once...

        def leftalign(field):
            self.ids[field].cursor = (0, 0)
 
        Clock.schedule_once(lambda dt: (leftalign('frompath'), leftalign('topath')))

        #Clock.schedule_once(lambda dt: leftalign('frompath'))
        #Clock.schedule_once(lambda dt: leftalign('topath'))
        UNUSED"""




#====================================================================================
# App: app closes
#====================================================================================



    def shutdown_app(self, popupcontent=None):
        
        """
        --------------------------------------------------------------------
        The quest for a hang-free app close on Android: forcibly close 
        app to avoid state-related hangs.  Not ideal, but other 
        options were prone to hang.

	Now used in all app-exit contexts: Back, close, fatal errors.  
        NOT run for Recents upswipes on Andoid (saves here won't help). 
        popupcontent is optional and ignored: may be called from a 
        popup or not, but this is shutdown, right?

        History: kivy closes were seen to hang sporadically in initial PPUS
        Android app dev, with no useful info in the log ("Leaving application 
        in progress..." was displayed, but the GUI didn't close).  
 
        As a workaround, force the close with either self.stop(), sys.exit(), 
        or os._exit().  These may dork up kivy state (and sys.exit may be 
        caught/disabled by kivy), but the app run is over anyhow.  The 
        atexit module's handlers are not run for os._exit - a last resort.
        --------------------------------------------------------------------
        """

        traces('os._exit: bye', '-' * 80)    # TBD: auto-save calendars if settings?
        os._exit(0)                          # nuclear option: this feels wrong, but it works...



    def warn_before_exit(self, changedCalendars):

        """
        --------------------------------------------------------------------
        Confirm app close request with user.  Used in three contexts:

        - On all platforms, suggest a Save when user tries to close app 
          with Back or Escape and there ARE unsaved calendar changes.

        - On PCs, suggest a Save when user tries to close app with a
          window "X" or other and there ARE usaved calendar changes.

        - On Android, verify intent when user taps Back to close and there
          are NOT unsaved calendar changes: Back is easy to tap inadvertenly.

        - On PCs, close silently if there are NOT unsaved calendar changes.

        This explcit model replaces a two-step save?+close? dialog model 
        in FCs 3.0-.  Never run on Recents-swipe closes, sadly (see ahead).
        --------------------------------------------------------------------
        """

        message_changed = (
            '[b]Unsaved calendar changes[/b]'
            '\n\n'
            '[u][i]Caution[/i][/u]: '
            'some of your calendars have unsaved changes.'
            '\n\n'
            'To save these changes, tap Cancel and then Save Calendars '
            'in the main menu.  '
            'To discard changes and close the app now, tap Confirm.')

        message_unchanged = (
            '[b]No unsaved calendar changes[/b]'
            '\n\n'
            'None of your calendars have unsaved changes and no Save '
            'is required.  Tap Confirm to close the app now or Cancel to '
            'keep using it.')
       
        message = message_changed if changedCalendars else message_unchanged

        confirmer = ConfirmDialog(
                        message=message,
                        onyes=self.shutdown_app,
                        onno=self.dismiss_popup)

        popup = Popup(
                    title='Confirm App Close',
                    content=confirmer,
                    auto_dismiss=False,        # ignore taps outside
                    size_hint=(0.9, 0.8),      # phones wide, e-2-e short
                    **self.themeForPopup())    # fg/bg colors if 'light'

        self.popupStack.push(popup)
        self.popupStack.open()                 # show top Popup with Dialog


 
    def catch_back_button(self, window, key, scancode, codepoint, modifiers):

        """
        --------------------------------------------------------------------
        On keypress 27 -- which is Escape on keyoards and also means Back
        button tap or gesture on Android -- apply one of these in turn:

        - Go up one level if PC-only folderchooser open
        - Ignore if any modal dialogs open
        - Return to the Month screen if another screen is open
        - Warn and confirm if any unsaved calendar mods
        - Confirm on Android always: too easy to tap inadvertently
        - Else close app: we don't stack screen history, so Back sans
          chooser, dialogs, subscreen, or mods can only mean exit.

        NOTE: the mapping from Back to the filechooser's .back() is
        moot on Android because that platform uses the SAF picker, 
        not the KivyMD chooser (and Back is caugth+handled by SAF).

        NOTE: some web examples check for key=1001 too, but this was 
        presumably for an older version of Kivy.  27=Escape suffices
        today for both Android Back button and keyboard Escape key.

        TBD: _should_ a Back tap sans calendar changes close the app,
        or should it simply enter pause state?  There seems no real 
        norm for this, but a full close requires calendar reloads.
        There is this for Java Activity, but it's supposed to be the 
        default on Android 12+ so Kivy may prevent pause on Back:

            public void onBackPressed()
               // Move task containing this activity to back of stack
               moveTaskToBack(true);

        FUTURISMS: Back becomes _predictive_ when apps target and run on 
	Android 16+: requires a callback model, and the API Kivy uses to
	get here no longer works (per docs, "onBackPressed is not called
	and KeyEvent.KEYCODE_BACK is not dispatched anymore").  Apps can
        opt out via build files, but the opt out goes away if target 17+.
        To postpone changes, FC 4.0 selects the opt-out option on this.
	The keycode may have changed in Kivy, but is still 27 in 2.3.1. 
        Kivy also changed window centering on Windows; use auto scheme. 

        UPDATE: on Android 16 without an opt-out for predictive-back, 
        Back is never caught here, and Android always puts the app in 
        pause state (it's moved to Recents after an on_pause()) but does 
        not kill it, regardless of whether calendars have changed or not.  
        This seems atypical, but is it as good as prompt+close?  Sans
        Back, there's no indiction of unsaved calendar changes (TBD). 
        --------------------------------------------------------------------
        """

        # return: True=end key processing, False=continue processing key

        if key != 27:       # Escape key and Android Back
            return False    # False=continue processing key

        else:
            trace('back button press')

            if self.folderchooser_open:          # never true on Android
                # go up if chooser open
                self.folderchooser.back()        # using KivyMD chooser
                return True                      # True=stop processng key
            
            elif not self.popupStack.empty():
                # ignore if any modal dialog open
                return True

            elif self.root.ids.navscreenmgr.current != 'month':
                # change to Month screen if not already there - like hbmenu Month tap
                self.switch_to_screen('month')
                self.manage_menu_post_click(self.root.ids.month, toggle=False)
                return True

            elif any(CalendarsDirty.values()): 
                # ask before close everywhere if mods
                self.warn_before_exit(changedCalendars=True)
                return True

            elif RunningOnAndroid:
                # ask before close on android if no mods
                self.warn_before_exit(changedCalendars=False)
                return True
          
            else:
                # close now - sans hanging!      # tbd: or simply pause on Android?
                self.shutdown_app()              # never returns



    def on_request_close(self, *args, **kargs):

        """
        --------------------------------------------------------------------
        Window exit: warn user and cancel if unsaved calendar mods, 
        else close app.  

        Not called for the Back button: intercepted by catch_back_button().
        Called in various context on PCs and Android.  On PCs, always 
        called for window "X" and perhaps other app closes.  

        On Android, may vary per version and vendor (as usual).  Per
        recent tracing, this is NOT called on an upswipe on the app in
        Recents: we get on_pause() on Recents open but then nothing more,
        so there's no way to prevent loss of calendar changes :-(.
 
        Also on Android, not called for a close in splitscreen mode but 
        IS called for a close in popup mode in a Samsung device (oddly).  
        Since there is nothing the app can do to avoid the close in popup
        mode (returning True doesn't stop close and dialog can't be shown),
        this simply returns False, and calendar changes are again lost :-(. 

        Caveat: older notes per PPUS which seem to contradict the above,
        but may hold true for apps with a running foreground service?...  
        "Curiously, this is still invoked on Android for Recents-swipe closes,
        which trigger on_pause, on_resume, this, and on_stop when a service 
        is running (and the first three of these with no service - sometimes), 
        but cannot be disabled by a True return here in any event (so bail)."

        [4.1] Don't keep stacking warning dialogs if the user keeps pressing
        window close after that warn_before_exit has been issued.  Formerly 
        occurred only on PCs and only if there were unsaved changed; and may
        be a user error, but make it moot.  Done by ignoring window close if
        _any_ modal dialog is open; it may also be a event dialog's changes
        warning on dialog close too.  TBD: is this safer or too extreme?
        --------------------------------------------------------------------
        """

        # return: True=don't exit, False=do exit

        trace('app request close')

        if RunningOnAndroid:               # not run for Back, Recents swipe, split close
            return False                   # can't stop|dialog if run for popup close...

        elif not self.popupStack.empty():
            # [4.1] ignore if any modal dialog open - including warn_before_exit
            return True

        elif any(CalendarsDirty.values()): 
            # ask before close
            self.warn_before_exit(changedCalendars=True)
            return True

        else:
            # close now - sans hanging!
            self.shutdown_app()            # never returns



    def on_pause(self):

        """
        --------------------------------------------------------------------
        Android only: on user leaving the running app by picking another 
        in Recents or Android taskbar.  Also run when SAF picker opened.

        Not triggered when up-swipe to kill app in Recents (probably: 
        see note above).  Returning True leaves app in paused state 
        instead of killing it now and restarting it fully on resume 
        (True is the default, but the docs seemed askew on latest read).

        ====
        Scroll workaround: per a known Kivy defect, pausing an app during
        scroll animation sometimes makes scrolled Labels' text empty on 
        resume.  This affects Help and About screens only but is glaring.
        Their text may reappear immediately at other positions, reappear 
        after a delay (up to ~20 seconds), or never reappear at all.  App 
        pause while scrolling is required to trigger this glitch, so it's 
        rare, but these screens' web links and calendar-files explore 
        raise the odds of app switches.  Workarounds pursued:

        1) FAIL: use Kivy's effect_cls.halt or .cancel here to end the 
           animation, on the theory that queued motions botch the widget
           on resume.  This was abandoned because neither seemed to have 
           any effect, and using either prevents on_resume() from being 
           called later for reasons tbd.  Kivy's Animation.stop_all(scroll)
           was also explored, but this seems to be both ineffectual and 
           unused by scroll effects per a brief code tour (docs are thin).

        2) PASS: per Kivy docs, blank widgets may reflect the fact that 
           OpenGL context might not be preserved across pause/resume, 
           because Android may destroy it to free up resources.  Android's
           API has a setPreserveEGLContextOnPause() to avoid destroying 
           OpenGL contexts on pauses, but it's a no-op on some devices, 
           is perilous to use, and should not be required.  Per the web, 
           using this may terminate or destabalize apps in some contexts,
           and Kivy already has mechanisms to restore lost OpenGL contexts
           on resume (that's why pause works at all).  Kivy's mechanism 
           smimply seems to be failing for in-progress scrolls. 

        3) PASS: disable pause mode by returning False here.  This would 
           require restarting the app in full on resumes, losing any user 
           context and unsaved calendar changes in the process.

        4) PASS: switch from multiple Labels to RSTDocument.  Kivy docs 
           warn that this is experimental and unstable, it seems too much 
           for the simple Help/About screens, and it was unvetted for bugs.

        5) USED: reset or reload the scroll's labels' text in on_resume 
           below, on the theory that the OpenGL context might have been 
           damaged or freed and requires an explicit reload or re-render 
           of the scrolled text content to force creation of new textures.
           Passing reuse as True or False to the splitter seems the same,
           though False yields a minor twitch (see set_split_label_text()).
 
        6) USED: reduce the size of the Labels used for scrolled text, 
           on the theory that this may simplify OpenGL context restores.
           They were formally halves (2 Labels per screen) to avoid blank
           text on older devices with small texture limits, but this was 
           generalized to support larger text and more and smaller labels.
           Using a minimal 1 line per label did not differ from 20 or 50.

        RESULTS: a combination of #5 and #6 did _not_ fix blank text on 
        scrolls, and no other workarounds are known (and RecycleView is 
        right out).  While blank text still occurs occasionally, the 
        generalization for #6 is now usable in other apps (e.g., PPUS).  
        But like other Kivy glitches (see PPUS's vanishing tabs bar, empty
        splitscreen text, and rightways rotation navbar overlays), this
        one is rare but unfixable: PUNT.

        All of which seems a lot to ask of app devs just for displaying
        text in a GUI, but Toga--the only alternative to Kivy for Python 
        on Android--today lacks both gestures and nav drawers.  Improve me.
        --------------------------------------------------------------------
        """

        trace('App.on_pause')

        # stop scroll animation iff it's the current screen
        # no: this prevents on_resume() from being called for Help+About

        """PUNT
        if self.root.ids.navscreenmgr.current == 'help':
            trace('pause help scroll')
            screen = self.root.ids.navscreenmgr.get_screen('help')
            scroll = screen.ids.helptextscroll
            scroll.effect_cls.cancel()
            #scroll.effect_cls.halt()
            #Animation.stop_all(scroll)

        elif self.root.ids.navscreenmgr.current == 'about':
            trace('pause about scroll')
            screen = self.root.ids.navscreenmgr.get_screen('about')
            scroll = screen.ids.abouttextscroll
            scroll.effect_cls.cancel()
            #scroll.effect_cls.halt()
            #Animation.stop_all(scroll)
        PUNT"""
        
        return True    # True=pause, don't stop now, run on _resume() later



    def on_resume(self):

        """
        --------------------------------------------------------------------
        Android only: on user returning to the paused app by picking it in 
        Recents or Android taskbar.  Also run when SAF picker closed, and
        when getting focus by initial tap in split-screen mode (kivy bug?).

        Not triggered if repick app in either Recents or Apps after killing
        it with a Back button or a Recents upswipe: on_start() comes after 
        both, with unpacking logcat msgs for a fresh run.  Return is moot.

        See on_pause() above for text-reset rationale.  TBD: as coded, 
        skips reset unless scrolled text is on the current screen; if it's
        required to reset always, use [if hasattr(self, 'help_text_set')].
        The lambdas are superfluous+harmless if reuse=True, its default. 
        NB: halting the animation in on_pause() prevents on_resume() calls.
        --------------------------------------------------------------------
        """

        trace('App.on_resume')    # placeholder for future expansion

        # reset scrolled text iff it's the current screen

        currentscreen = self.root.ids.navscreenmgr.current
        trace(f'{currentscreen=}')

        if currentscreen == 'help':
            trace('reset help text')
            Clock.schedule_once(                                   # reset label text
                lambda dt: self.set_help_text(dt, reuse=True))     # just s_h_t if r=True

        elif currentscreen == 'about':                             # else avoid overhead
            trace('reset about text')
            Clock.schedule_once(
                lambda dt: self.set_about_text(dt, reuse=True))



    def on_stop(self):

        """
        --------------------------------------------------------------------
        Android only: NOT called on Recents upswipes and NOT called if 
        the app is paused (post on_pause()) and the OS kills the app for 
        memory constraints or any other.  Hence, not very useful: save
        any saves in on_pause too or only.  

        Exception: IS called for popup-mode close after an on_pause() and 
        on_resume(), though spltscreen close only on_pause() and NOT this
        (well, on Samsung).  Recents sipes call none, but on_pause() is 
        run when the user selects the Recents screen.
        --------------------------------------------------------------------
        """

        trace('App.on_stop')      # placeholder for future expansion




#========================================================================================
# Run that app 
#====================================================================================


Frigcal().run()    # build(), on_start(), and watch for user events
