Using tkinter Programs on Android: Provisional Guide

Version:	June 8, 2019 (last revised Dec-2024)
Author:	© 2019-2024 M. Lutz, learning-python.com
Quick links:	View and fetch this guide's media
	View the related Mergeall doc

This document describes how to run tkinter GUI programs on Android in the Pydroid 3 app's IDE (its edit+run GUI). This app recently added fledgling but astonishing tkinter support, which allows many Python 3.X programs with tkinter GUIs to be run in source-code form on smartphones, with no or minimal changes. The focus here is on using this app to run both the complete application programs at this site as well as the tutorial examples in the book Programming Python, 4th Edition (a.k.a. PP4E), but this coverage should apply to tkinter GUIs on Android devices in general.

Contents:

• Preface
• PP4E Examples
• Mergeall
• Frigcal
• PyEdit
• PyGadgets
• PyMailGUI

Preface

Before jumping into specific programs, here are a few administrative and global notes up front:

Why provisional?

This guide is marked as provisional because debugging on Android in Pydroid 3 is ongoing, and long-range goals include exploring standalone apps that run outside Pydroid 3 for some of the programs here. Please check back for updates.

Prerequisite docs

This document assumes as prerequisite the Android background coverage of the Termux how-to developed earlier for the Mergeall application. See especially the general usage and known glitches notes in the introduction to Pydroid 3 tkinter GUIs of that how-to's Appendix B. For space, much material there is either abbreviated or omitted here.

Versions supported

Update: as of fall 2020, programs here are known to also work on Pydroid 3 4.0, Python 3.8, and Android 10 (formerly Q).

Findings here reflect versions 2.22 and 3.0 of Pydroid 3; 3.6 and 3.7 of Python; 7, 8, and 9 of Android (Nougat, Oreo, and Pie); and 8.6 of the Tk library wrapped by tkinter (in an Android port of unknown origin). Programs described here are currently known to work on all these systems, except where noted ahead. Per the notebox above, be sure to check facts here against these systems' current status if you're reading this in the future.

Defect sources

The defects noted here that hinder tkinter programs are a mix of Pydroid 3, Python, and Android issues. Those in the latter two categories (e.g., web-browser opens and permission constraints) naturally apply to apps other than Pydroid 3.

Code patches

The custom-file replacements used here are required because it's not possible to integrate Pydroid 3 changes into source-code packages directly, for reasons explained here. For each program with changes, copy custom source-code files to the program's source-code package on Android only (they won't work on PCs) and for Pydroid 3 only (they won't work for GUIs in other apps). See this file for Android names to use in optional platform-specific configuration settings.

Usage pointers

For best usage, a stylus or Bluetooth mouse is generally recommended for most tkinter GUIs in Pydroid 3, especially those with multiple windows or small controls. Window resizes, for example, are difficult with touch alone, though spread/pinch zooms and pans may help. Some programs (e.g., PyPhoto) require a keyboard for operation, though there are on-screen alternatives to Bluetooth keyboards described ahead.

On-screen keyboards

Interacting with Pydroid 3 tkinter text-input fields automatically pops up an on-screen keyboard in most contexts—for better or worse. While work has been done to avoid these popups where they're not useful, they may still be unwelcome at times. As usual on Android, your device's back button (and a downswipe where supported) hides a keyboard that's obscuring important content or GUI components.

Viewing modes

Update: there's more on viewing modes, including Pydroid 3's DPI settings, in the new display-fit sidebar ahead.

Suggestions for Pydroid 3 fullscreen and maximized viewing modes vary per program ahead. In general, fullscreen mode saves space but may conflict with Android's status-bar pulldown at display top; maximized mode uses space well but works only for GUIs without persistent popup window and with either explicit exit widgets or no need to process or verify exits (Pydroid 3 double-back exits do not run program exit handlers).

Screen size

GUIs here have been modified to be generally usable on smaller screens (as small as 5.5 inches and perhaps smaller). Still, some GUI components may render better in landscape orientation, user display settings are widely variable, and larger screens are recommended. Where relevant, use program configuration options to tailor sizes and fonts for better fit.

Useful links

To see the entire set of media—screenshots and source-code—referenced in this document, browse this folder. To fetch all the programs' changed source-code files noted in this guide at once, get this zipfile. To view a list of files recently changed as well as upgrade instructions, see this file.

Pydroid 3 advertising

This guide does not explore the drawbacks of the Pydroid 3 app's pay-or-else advertising model—arguably one if its biggest negatives. For more on this topic, see the aforementioned Mergeall coverage. You may or may not opt to pay this app's freemium fee, but at least you've been warned.

PP4E Examples

Most of the tutorial-level tkinter GUI examples in the book Programming Python, 4th Edition work unchanged in Pydroid 3. True to its educational focus, this makes Pydroid 3 viable as a platform for working along with the book's presentation.

GUI Look and Feel

Here's a sample of the book's programs running on Android in Pydroid 3:

• Basics
• Grids
• Composites
• Toplevels
• Layout
• Menus
• Lists
• Text
• Complete
• Etcetera

You can also view these screenshots in slideshow mode starting here.

Orientation and Viewing Modes

Most of these examples yield smaller displays, which need not use tkinter fullscreen or maximized modes in Pydroid 3, but experiment with screen modes and phone orientations for best effect. Note that double-back exits in any viewing mode do not run tkinter exit handlers, and rotating the screen after a GUI is running may not work on some devices per usage notes ahead.

Running the Programs

1. Install the Pydroid 3 app if needed from the Play Store.
2. Download the book's examples package from this location to any writable folder on your phone, and unzip (i.e., extract) it.
3. Run examples by opening their source-code files in the Pydroid 3 app's editor and pressing the editor's big yellow run button. Most GUI examples reside in the unzipped example package's folder:

   PP4E-Examples-1.4/Examples/PP4E/Gui

   But navigate the examples-package tree to find additional tkinter code to run. Naturally, only this last step must be repeated whenever you wish to run an example.

Usage Notes

Also keep the following in mind when using PP4E book examples on Android:

Home-screen shortcuts

For quick two- or three-tap access to any book example, make a home-screen shortcut (a.k.a. link) to either the example's source-code file or the package's Gui folder. Shortcuts look like this or this and can be made by multiple Android file explorers including the app here, but be sure to set the default app or command to Pydroid 3. Tip: uncheck "Parameters" when making shortcuts in Total Commander 3.0 (details).

Rotates may hang or kill

Update: this note's issue has been fixed as of Pydroid 3's 4.X release in 2020. Specifically, screen rotations have been verified to work well and without requiring screen-zoom settings when using Pydroid 3 version 4.01 on Samsung Android versions 7 (Nougat) through 10. Upgrade your Pydroid 3 app as needed.

On some devices, Pydroid 3 either kills the GUI silently or hangs altogether if the screen is rotated between portrait and landscape orientations while a tkinter GUI is running. Per details here, rotations are known to fail on multiple Samsung devices, but the latest of these rotate correctly if they avoid the Small screen-zoom display setting. If your rotates don't work, change your screen zoom to Medium or Large, apply system updates, or don't rotate.

Rotated activities may slide or hang

Update: this note's issue has been fixed as of Pydroid 3's 4.X release in 2020; see the preceding note's update for more details.

In the same department as the preceding note: per here, changing phone orientation during a spawned activity (e.g., a Share or program-help browse) may cause the GUI to slide off screen or similarly hang, even on devices that handle rotations in general. Rotate twice to restore the GUI where supported.

Import paths

Some book examples require path settings for PP4E package imports. If needed, this setting can be forced by appending pathname strings to Python's sys.path list at the start of examples' code. Use the unzipped examples folder's path up to and including its Examples folder. For example, after an import sys:

sys.path.append('/sdcard/Download/PP4E-Examples-1.4/Examples')

Install Pillow for images

Some of the book's GUI examples use the Pillow (formerly PIL) 3rd-party image-processing library. To install this for use on Android, either run a pip install Pillow command line in Pydroid 3's Terminal, or use the app's Pip interface. Both can be found in the app's main (top left) menu. Pillow subsumes PIL and generally requires no code changes in book examples.

A mouse, stylus, or zoom may help

Some examples have smaller controls and may warrant window resizes or moves; a stylus or mouse may make these interactions easier, and spread/pinch zooms and pans can aid accessibility.

Font constraints

Update: Pydroid 3's 3.0 release in early April 2019 fixed its font crash by coercing any unknown font-family name to helvetica, but its other font limitations described here are still present.

Because some font types cause tkinter GUIs to crash silently in Pydroid 3, examples that use custom text fonts may require code changes. In general, font families courier, times, and helvetica work (and monaco is courier and arial is helvetica), but most others crash the GUI, and italic and bold styles are ignored for courier.

General caveats

As shipped, some book examples exhibit cosmetic or operational rough edges on Android that stem from Pydroid 3's tkinter implementation (e.g., toolbar images are too small in this), and other examples may require changes to disable features unsupported on Android (e.g., Windows icon files in this). Some examples may also require patches applied to the larger programs described ahead on this page (e.g., sys.executable and webbrowser spawning workarounds described here). On the other hand, changing code is a normal part of the book's learning experience, and a few blemishes seem a reasonable price for running PC-level GUIs on a phone.

Other PP4E-related programs

In addition to the book's examples package, some of the larger programs described later on this page are enhanced and standalone versions of the book's larger examples. The current releases of the book's PyEdit and components of its PyGadgets, for example, can also be run on Android today. The enhanced version of the book's PyMailGUI is still a work in progress on Android, though Mergeall uses some of the book's directory-processing code. Frigcal is not from the book but employs its tkinter techniques.

Mergeall

Mergeall—an incremental-backup and change-propagation system—can be used to sync on-phone content to and from removable media. This program has both a command-line mode usable in apps like Termux, as well as a tkinter GUI usable in Pydroid 3. Pydroid 3 has a Terminal interface too, but it's too limited to recommend for Mergeall's command-line mode. The following summarizes the expanded coverage in this document and augments Mergeall's base user guide. Note that Mergeall changes a destination folder by design; use it with care.

GUI Look and Feel

Mergeall's GUI looks like this when run on Android in Pydroid 3:

Portrait

Start, browse, report, finish, update, finish

Landscape

Start, browse, report, finish, update, finish

Non-maximized/fullscreen

Landscape, portrait, status

You can also view these screenshots in slideshow mode starting here.

Orientation

Mergeall's GUI is usable in either landscape or portrait phone orientation, though portrait mode displays more run messages without scrolls, and landscape is less likely to truncate GUI content. Per usage notes ahead, rotating the screen after the GUI is running may not work on some devices.

Viewing Modes

Because Mergeall's GUI has no persistent popup windows and its exit verification can be skipped, it may render and work best using Pydroid 3's tkinter fullscreen and maximized viewing modes, the latter of which automatically resizes for fit on rotations. Select these modes by turning the first "Tkinter" switch off and the second on in Pydroid 3's Settings ⇨ System dialog before running the GUI, and press your phone's back button twice to exit the GUI. Mergeall's GUI can be run in non-fullscreen and non-maximized viewing modes too (see the captures above), but they hold little usage advantage.

Running the Program

To run Mergeall on your Android device, follow these steps:

1. Install the Pydroid 3 app if needed from the Play Store.
2. Download Mergeall's source-code package from this page to any writable folder on your phone, and unzip (i.e., extract) it.
3. Fetch the two custom files:
   • launch-mergeall-GUI.pyw
   • mergeall_configs.py

   And move them to the top level of your unzipped Mergeall source-code package, replacing their original versions. Download by clicking "save" in the "Raw text" line of these links' pages, and search for "# ANDROID" to see code changes made if desired. Note: some browsers may append a bogus ".txt" to the end of a saved ".pyw" file's name; delete the ".txt" manually by renaming.

4. Run Mergeall by opening its source-code package's file launch-mergeall-GUI.pyw in the Pydroid 3 app's editor and pressing the editor's big yellow run button. Mergeall's GUI should appear and work largely the same as it does on PCs. Naturally, only this last step must be repeated on later runs.

Usage Notes

Also keep the following in mind when using Mergeall on Android:

Home-screen shortcuts

For quick two-tap access to Mergeall, make a home-screen shortcut (a.k.a. link) to its launch-mergeall-GUI.pyw source-code file. Shortcuts look like this or this and can be made by multiple Android file explorers including the app here, but be sure to set the default app or command to Pydroid 3. Tip: uncheck "Parameters" when making shortcuts in Total Commander 3.0 (details).

Oreo+ only for all usage

Mergeall can be used on Android 8 (Oreo) and higher only, due to an Android timestamp bug in earlier versions. Mergeall will compare folders prior to Oreo, but the results are not meaningful because file timestamps are always copy time instead of modification time, and Mergeall updates will always fail due to timestamp-copy errors.

Rotates may hang or kill

Update: this note's issue has been fixed as of Pydroid 3's 4.X release in 2020. Specifically, screen rotations have been verified to work well and without requiring screen-zoom settings when using Pydroid 3 version 4.01 on Samsung Android versions 7 (Nougat) through 10. Upgrade your Pydroid 3 app as needed.

On some devices, Pydroid 3 either kills the GUI silently or hangs altogether if the screen is rotated between portrait and landscape orientations while a tkinter GUI is running. Per details here, rotations are known to fail on multiple Samsung devices, but the latest of these rotate correctly if they avoid the Small screen-zoom display setting. If your rotates don't work, change your screen zoom to Medium or Large, apply system updates, or don't rotate.

Rotated activities may slide or hang

Update: this note's issue has been fixed as of Pydroid 3's 4.X release in 2020; see the preceding note's update for more details.

In the same department as the preceding note: per here, changing phone orientation during a spawned activity (e.g., a Share or program-help browse) may cause the GUI to slide off screen or similarly hang, even on devices that handle rotations in general. Rotate twice to restore the GUI where supported.

Use FAT32 for interoperability

Update: this note's issue has been fixed as of Samsung Android 10 in 2020. Mergeall users of this and later Androids can use exFAT for removable drives and avoid DST issues, though users of older-Android Samsung devices are still advised to use FAT32. See the Mergeall doc for more details, and upgrade your Android if possible and desired.

Removable media used with Mergeall on Android should generally be formatted as FAT32 instead of exFAT, due to an existing Android exFAT timestamp bug which may skew file modification times both read and written (by 16 hours in US Pacific time) and hampers Mergeall file comparisons. To date, this bug has been observed on Samsung Android devices only, though it appears on multiple such devices, and its full scope is unknown. Note that file times on FAT32 drives may need to be adjusted on daylight-savings-time (DST) rollovers to make them compare correctly with times on non-FAT drives that use UTC-based time; for details and instructions, see this note.

Storage constraints

Update: see also this note about possible changes to internal-storage permissions in Android 11.

Mergeall can be used with both Termux command lines and Pydroid 3 GUIs. The full story on its storage constraints for Termux and Pydroid 3 is here and here. In brief, because both Termux and Pydroid 3 can update only their own app-specific folders on removable media, you must either choose which app will update removable-media content and nest it appropriately (see the next note), or locate your content anywhere in internal storage (e.g., /sdcard) where it can be updated by both apps.

GUI storage constraints

Update: see also this note about possible changes to internal-storage permissions in Android 11.

If you choose to use Mergeall in Pydroid 3 only, content that will only be read can be located anywhere. Content that will be updated can be located anywhere in internal storage (e.g., /sdcard), or nested in Pydroid 3's app-specific folder created manually on removable drives and named as follows (where the xs are your drive's Android ID):

/storage/xxxx-xxxx/Android/data/ru.iiec.pydroid3

Merging to removable media looks like this in the GUI.

Caution: nested-content deletions

Content nested in app-specific folders on removable media is automatically deleted when the owning app is uninstalled. This is especially dangerous in Mergeall, as the nested content may be all your on-phone data. Move nested content before uninstalls, or use an unnested folder in internal storage for on-phone content instead of removable media.

Preserve file times on copies

Android file-manager apps may not retain file modification times when these apps copy content. To ensure that times are propagated to your phone, perform your bulk copies either on your PC for removable media; using Mergeall's cpall.py utility from a command-line interface; or by running a sync in Mergeall's GUI to an empty folder. See the Mergeall-on-Android how-to's extended coverage here and here.

Font constraints

Update: Pydroid 3's 3.0 release in early April 2019 fixed its font crash by coercing any unknown font-family name to helvetica, but its other font limitations described here are still present.

Because some font types cause tkinter GUIs to crash silently in Pydroid 3, Mergeall's configuration file mergeall_configs.py was changed to disable text-area font customization by presetting it to None, which applies the system default. Experiment with font settings in this file as desired. In general, font families courier, times, and helvetica work (and monaco is courier and arial is helvetica), but most others crash the GUI, and italic and bold styles are ignored for courier.

Path configs for Android (March 2019)

Just for Android, Mergeall recognizes new settings in the user configurations file that give both path-input prefills and chooser-dialog starting folders for the FROM, TO, and logfile folders. These are designed to simplify—or completely avoid—the Android tkinter chooser dialog which can unfortunately be just as tedious to use as it is on Linux (though the effect is worse on a smartphone). Search for "[Mar0819]" in the configurations file to see the new settings.

You can still use the GUI's Browse buttons to pick arbitrary folders as before (in addition to manual entry and file-explorer copy/paste), but the new starting-folder settings can make the dialog less frustrating, and the new prefills will likely suffice in most common usage (and are the Pydroid 3 GUI equivalent of Termux command-line $plug and $data shell settings). The logfile default folder was also changed to Admin-Mergeall in /sdcard; its former Documents might not exist unless you run MS Office apps.

Tip: if you opt to use the Browse file-chooser dialogs instead of the new prefill settings (or must use the dialogs for a run's unique requirements), spread/pinch zooms can make these dialogs much more usable, especially on smaller displays. See the general tkinter usage notes here for more.

Read-only text for Android (March 2019)

Also just for Android, the message-text display area at the bottom of Mergeall's GUI is set to read-only mode after a run finishes, so that slower swipes to scroll will not trigger an annoying on-screen keyboard popup which overlays and obscures the very text being scrolled. The only downside of this read-only setting is that copy/paste no longer works on the GUI's message-text display area itself, but this area was never meant to be more than progress indicator and final-result viewer—a constraint that's especially relevant on smartphones with limited screen space. Open the saved logfile separately in your favorite text editor to process a run's messages more generally.

Label trims and font configs for smaller phones (March 2019)

The original text labels in Mergeall's PC GUI were shortened for fit on phone displays twice—once to fit larger phones and again later to accommodate smaller devices. As shipped, the labels have been verified to fit screens as small as 5.5 inches (see the original, shorter, and final versions on this phone size). Still, smaller devices were not tested, and Android tkinter naively clips other nearby widgets when labels are too wide to fit, rather than truncating label text.

If labels are still too wide for a smaller phone you use, either interact with the GUI in landscape mode for more space (and rotate to portrait to see more messages where supported); edit the code to shorten labels further (search for "# ANDROID - shorter" in launch-mergeall-GUI.pyw to find labels' text); or simply change the new LABELFONT setting in the configurations file to a smaller custom font. For symmetry, a new HEADERFONT in the same file supports custom section-header fonts too, but its default is small enough on all devices tested and usually leaves room for messages.

Formerly disabled widgets: help and logfiles (April 2019)

The "Help" and "Popup logfile?" (f.k.a. "Show logfile popup?") buttons in Mergeall's GUI were originally disabled on Android, due to problems involving the Python webbrowser module they employ. This required users to open Mergeall's user guide and logfiles outside the GUI (the user guide is available both at the top level of the source-code package and online, and logfiles appear after a run in the folder chosen in the GUI).

This program worked around the webbrowser issues in April 2019, using techniques described here and here. Hence, Mergeall's user guide and logfiles now open from within the GUI on Android just as they do on PCs, though viewer options may be limited, and Android always displays the online version of help to include recent changes; open files manually if they are subpar in the GUI. Mergeall's "Help" button is also uncolored on Android, due to an unrelated tkinter issue. Caution: changing phone orientation during spawned activities can misplace or hang the GUI; see the earlier rotations note.

Frigcal

Frigcal—a personal calendar program that uses portable iCalendar ICS files for event storage—can be used on Android to view and edit calendars which can also be used on other platforms, including Windows, Mac OS, and Linux PCs. Frigcal's animated launcher is not currently supported, but its main script can be run directly. This program runs only as a GUI. The following augments Frigcal's base user guide.

GUI Look and Feel

Frigcal's GUI looks like this when run on Android in Pydroid 3:

• Month window
• Event view/edit
• Images
• Portrait
• Rightclicks
• Event list
• Zoomed
• Multiwindow
• Save on exit

You can also view these screenshots in slideshow mode starting here.

Orientation

Due to its size, Frigcal's GUI may work best in landscape (horizontal) phone orientation to maximize event label size. Per usage notes ahead, rotating the screen after the GUI is running may not work on some devices; where needed, rotate your phone to landscape orientation before running the program, and view more events by clicking a day's number or rotating to portrait where supported (more on event views ahead).

Viewing Modes

Pydroid 3's maximized viewing mode cannot be used for Frigcal if you wish to either save calendar changes or view Frigcal's persistent popup windows like month clones and images. Most importantly, saves do not work in this mode because they happen in Frigcal only on exit requests; maximized mode hides the window-border exit button; Frigcal has no exit button of its own; and Pydroid 3 double-back exits do not run GUIs' exit handers. Persistent popups can't be viewed because the main window overlays and thus hides them.

Technically, Pydroid 3's double-back exits can be used in either maximized or non-maximized modes, but they are the only Frigcal exit option in the former. Hence, maximized mode makes sense for Frigcal only when viewing but not changing calendars, and you should always use the window-border's upper-right "X" exit button instead of double-back exits in non-maximized mode unless you have no calendar changes to save.

Select or disable maximized mode before running the GUI with "Tkinter: maximize first window" in Pydroid 3's Settings ⇨ System dialog, and use a stylus or mouse for best window move/resize results in non-maximized mode; when used, maximized mode automatically sizes for fit.

Running the Program

(Much of the following no longer applies as of Frigcal 3.0: see the note above)

To run Frigcal on your Android device, follow these steps:

1. Install the Pydroid 3 app if needed from the Play Store.
2. Download Frigcal's source-code package from this page to any writable folder on your phone, and unzip (i.e., extract) it.
3. Fetch the three custom files:
   • frigcal.py
   • frigcal_configs.py
   • scrolledlist.py

   And move them to the top level of your unzipped Frigcal source-code package, replacing their original versions. Download by clicking "save" in the "Raw text" line of these links' pages, and search for "# ANDROID" to see code changes made if desired.

4. Optional: the code folder also includes patches to file frigcal-launcher.pyw, but this is not currently required, as it applies only to the unusable launcher (see Usage Notes ahead). To experiment with its code, fetch and move this file to the top level of the unzipped package. Note: some browsers may append a bogus ".txt" to the end of a saved ".pyw" file's name; delete the ".txt" manually by renaming.
5. Run Frigcal by opening its source-code package's file frigcal.py in the Pydroid 3 app's editor and pressing the editor's big yellow run button. Frigcal's GUI should appear and work largely the same as it does on PCs. Naturally, only this last step must be repeated on later runs.

Usage Notes

Also keep the following in mind when using Frigcal on Android:

Home-screen shortcuts

For quick two-tap access to Frigcal, make a home-screen shortcut (a.k.a. link) to its frigcal.py source-code file. Shortcuts look like this or this and can be made by multiple Android file explorers including the app here, but be sure to set the default app or command to Pydroid 3. Tip: uncheck "Parameters" when making shortcuts in Total Commander 3.0 (details).

Rotates may hang or kill

Update: this note's issue has been fixed as of Pydroid 3's 4.X release in 2020. Specifically, screen rotations have been verified to work well and without requiring screen-zoom settings when using Pydroid 3 version 4.01 on Samsung Android versions 7 (Nougat) through 10. Upgrade your Pydroid 3 app as needed.

On some devices, Pydroid 3 either kills the GUI silently or hangs altogether if the screen is rotated between portrait and landscape orientations while a tkinter GUI is running. Per details here, rotations are known to fail on multiple Samsung devices, but the latest of these rotate correctly if they avoid the Small screen-zoom display setting. If your rotates don't work, change your screen zoom to Medium or Large, apply system updates, or don't rotate.

Rotated activities may slide or hang

Update: this note's issue has been fixed as of Pydroid 3's 4.X release in 2020; see the preceding note's update for more details.

In the same department as the preceding note: per here, changing phone orientation during a spawned activity (e.g., a Share or program-help browse) may cause the GUI to slide off screen or similarly hang, even on devices that handle rotations in general. Rotate twice to restore the GUI where supported.

Oreo+ only for updates

Frigcal can be used for updates on Android 8 (Oreo) and higher only, due to an Android timestamp bug in earlier versions that breaks calendar backups on saves. Prior to Oreo, calendars in Frigcal can be viewed but cannot be changed and saved.

Maximize for view-only (only)

Pydroid 3's maximized mode is recommended when using Frigcal to view but not change calendars on your phone, because this mode provides the most screen space (especially if your navigation bar is hidden), and it automatically resizes the window to refit the new aspect ratio after rotations. As noted earlier, this mode doesn't support calendar saves; use non-maximized mode to save, and manually resize to refit on rotations (shrinking before rotating may help with resizing).

Title dates for Android

Just for Android, calendar month and year was added to month-window titles, so they are displayed in non-maximized mode for windows that are too small to retain their normal date+year labels. Month name is almost always obscured in portrait orientation: use landscape mode instead, or run in non-maximized mode to see the new month-window title.

Truncated widgets and ignored hovers

Some Frigcal widgets are obscured and unusable in portrait phone orientation; use landscape mode instead, and hide your phone's navigation bar for more GUI room (where possible). Conversely, option lists (e.g., color-scheme choices) too long for the display are truncated in landscape mode; rotate to portrait mode where supported to see more options.

Also note that month name may not be visible in some usage modes (per the prior note), and the Footer feature is limited by screen size but not generally useful on Android anyhow without a mouse—stylus hovers (e.g., on Samsung Note devices) are recognized by Android but not dispatched by Pydroid 3's tkinter; Bluetooth mouse hovers are always dispatched; and fingers don't hover.

Launcher not supported

Frigcal's animated launcher, file frigcal-launcher.pyw, displays its GUI but does not open the calendar, because it is not possible to view the windows of a GUI program started by another GUI program in Pydroid 3. Run Frigcal's main script frigcal.py directly instead per above.

Start-ups and navigations are fast

Frigcal loads calendars quickly on start-up. In testing, a set of calendars with events spanning 15 years loads in 3 seconds on a Mac OS PC and 4 to 5 seconds on a recent Android smartphone. The screen will be blank during loads due to the prior note's launcher issue, but the wait is short. Once calendars are loaded, cross-month navigation is nearly instantaneous on all Android devices tested.

How to rightclick

Rightclicks are required to copy/paste events. In Pydroid 3, Frigcal rightclicks on events, days, or event-selection list items are triggered by either a subtle swipe (left or right) with touch or stylus; a swipe with the mouse cursor while holding its left button; or a keyboard control + mouse click combo. Long presses and mouse rightclicks are not recognized. This may take some practice to perfect; zoom in if needed with two-finger spread/pinch zoom and three-finger pan gestures.

Viewing more events

Due to phone size constraints, the number of events that a day can display is limited, especially in landscape orientation. To view more events, double-tap a day's number to open its event-selection-list display. Like the GUI at large, this display supports both single clicks to open view/edit dialogs, as well as rightclicks (per the prior note) to open copy/cut dialogs. You can also view more events by rotating your device to portrait mode, but this fails on some phones while the GUI is running and truncates event text.

Newlines may need help

The return key on some recent Samsung on-screen keyboards does not send a newline character to Frigcal in Pydroid 3. This matters for multiline descriptions in the event-edit dialog but appears to be limited in scope (version 3.2 of the keyboard is the only known offender). If the return key does not move the cursor to the next line on your device, either use a physical Bluetooth keyboard; use Samsung's handwriting-recognition input, whose return key works correctly; or install and use an alternative keyboard whose return key works properly.

For the latter option, both Google Gboard and Hacker's Keyboard on-screen keyboards correctly send newlines to Frigcal on return-key presses. The second of these also provides access to PyEdit menu shortcuts and can be opened on demand for PyPhoto commands.

Copy/paste may need help

Android-style copy and paste via longpresses is not available in tkinter GUIs run in Pydroid 3. To cut and paste text in Frigcal's text-input fields, highlight with touch, then use the PC-like key combinations Ctrl+c to copy and Ctrl-v to paste in keyboards that support these. You'll find support for these keys in both Bluetooth keyboards and alternative on-screen keyboards like Hacker's Keyboard.

Storage constraints

Update: see also this note about possible changes to internal-storage permissions in Android 11.

Due to Android and Pydroid 3 permission constraints, view-only calendars can be stored anywhere on your device, but updatable calendars must be in a folder that either is located anywhere in internal storage (e.g., /sdcard) or is nested in Pydroid 3's app-specific folder on removable-media. To nest on removable media, locate your calendars folder in the following manually created folder on your drive (the xs are your drive's Android ID):

/storage/xxxx-xxxx/Android/data/ru.iiec.pydroid3

Updates to any other removable-storage folders will fail, like the sequence here, here, and here. Note that uninstalling an app deletes its app-specific folders, including any user content there.

Calendar transfers

To transfer calendars between your phone and PCs, simply copy your Frigcal calendar folder to or from your phone. Files in this folder work in a variety of calendar programs, including Frigcal on PCs. Be sure to set your calendar-folder path—icspath in the Frigcal configurations file frigcal_configs.py—to the folder you'll use on the phone for calendars shared with PCs.

Optional Android-changes calendar

You may find it useful to dedicate a calendar file to events edited on your Android device, and select this file in the GUI whenever creating new events on your phone. This way, Android changes can be easily transferred to your PCs and won't interfere with calendar edits made elsewhere.

To make a new calendar file for Android use, run the Frigcal source-code package's makenewcalendar.py on either your PC or phone. On your phone, run this script by opening it in Pydroid 3's IDE like this and pressing the yellow run button as usual, and enter a calendar name like this. Once created, choose the new calendar in the GUI like this You can also run the maker script in the app's Terminal interface, but it's a lot of typing in a primitive shell.

For more on Frigcal calendar files in general, see its user guide's coverage. You can also sync shared calendar files back and forth between PCs and phones, but a dedicated Android calendar supports changes more freely (though you should take care to avoid overwriting your Android calendar by to-phone content syncs).

Optional Pillow install

Frigcal's month-images option requires the Pillow third-party library to be installed in Pydroid 3 for some image types, though not for the shipped default images and not for PNGs and GIFs in general. Install Pillow if needed by running the command line pip install Pillow in Pydroid 3's Terminal window opened from its main menu, or 's Pip interface. More details here.

Font constraints

Update: Pydroid 3's 3.0 release in early April 2019 fixed its font crash by coercing any unknown font-family name to helvetica, but its other font limitations described here are still present.

Because some font types cause tkinter GUIs to crash silently in Pydroid 3, Frigcal's configuration file frigcal_configs.py was changed to disable most user font customizations by presetting them to None, which applies system defaults. Experiment with Frigcal font settings in this file as desired. In general, font families courier, times, and helvetica work (and monaco is courier and arial is helvetica), but most others crash the GUI, and italic and bold styles are ignored for courier.

Other configurations

Also in frigcal_configs.py: the font of Frigcal's event edit/view dialog was preset for readability (system defaults are small); the initial size of this dialog was preset for use on a phone (though it's resizable in the GUI); and click mode was changed from double-click mouse to single-click touch to minimize keyboard popups at the expense of inline summary edits (see the user guide for more on the difference). Tailor any of these for your usage, and see frigcal_configs_base.py in your source-code package for the full set of user-configurable options. See also the smaller-phones fit note ahead for related notes.

Formerly disabled widgets: help (April 2019)

The "?" help button in Frigcal's GUI was originally disabled on Android, due to problems involving the Python webbrowser module it employs. This required users to open Frigcal's user guide outside the GUI (the user guide is available both at the top level of the source-code package and online).

This program worked around the webbrowser issues in April 2019, using techniques described here and here. Hence, Frigcal's user guide now opens from within the GUI on Android just as it does on PCs, though viewer options may be limited, and Android always displays the online version of help to include recent changes; open the guide manually if it is subpar in the GUI. Caution: changing phone orientation during spawned activities can misplace or hang the GUI; see the earlier rotations note.

Improved fit on smaller phones (April 2019)

Frigcal's GUI was recently modified to better fit smaller Android devices: button fonts were shrunk, the "mm/yy/dddd" date input field now has a fixed font and size, and the month label's preset font was reduced. The net effect keeps the month name visible and makes Frigcal's GUI usable in landscape mode, on displays as small as 5.5 inches and perhaps smaller. That said, Frigcal is a rich and large GUI; rotate or open event lists as needed, and see frigcal_configs.py. to further tailor fonts for fit as desired. Fine point: this file's new button-font preset is noticeably smaller than the default on smaller devices but may be no different on yours; tweak as you wish.

Despite the recent work, some Frigcal preset configurations may still render better in landscape orientation and/or larger screens. The event edit/view dialog's 80-character width, for example, works well in landscape orientation on screens as small as 5.5 inches and handles larger event descriptions (including those you might create on PCs), but it will span off screen in portrait orientation on many devices. Like much on smartphones, this is an intractable tradeoff. To make this better fit portrait mode at the expense of larger-note content, change the eventdialogtextwidth setting in frigcal_configs.py.

PyEdit

PyEdit—a general-purpose text editor and Python code launcher—can be used on Android to both edit arbitrary text files and run Python code being edited in the GUI. This program runs only as a GUI. The following augments PyEdit's base user guide.

GUI Look and Feel

PyEdit's GUI looks like this when run on Android in Pydroid 3:

• Main and popup
• File dialog
• Menu options
• Portrait max
• Info dialog
• Grep search
• Run code
• Save on exit
• Help dialog

You can also view these screenshots in slideshow mode starting here.

Orientation

Due to phone size constraints, PyEdit's GUI may work best in landscape (horizontal) phone orientation, to avoid horizontal slides and toolbar truncation. Per usage notes ahead, rotating the screen after the GUI is running may not work on some devices; where needed and desired, rotate your phone to landscape orientation before running the program.

Viewing Modes

Because it opens many persistent popup windows and must verify program closes, PyEdit's GUI is better used without Pydroid 3's tkinter maximized viewing mode. This mode automatically resizes for fit, but it overlays persistent popups, and its lack of a window-border exit button encourages silent double-click exits that may discard changes. Maximized mode may be best used in PyEdit only to view, but not change, a single document. Select or disable this mode before running the GUI with "Tkinter: maximize first window" in Pydroid 3's Settings ⇨ System dialog, and use a stylus or mouse for best window move/resize results in non-maximized mode.

Whether you use maximized mode or not, do not exit the GUI with a Pydroid 3 double-back click or unsaved changes may be lost. Instead, be sure to exit the GUI only by using its Quit toolbar button or File ⇨ Quit menu option available in all modes, or by pressing its window-border's "X" exit button available in non-maximized mode. All three techniques offer you a chance to save edits before the GUI closes.

Running the Program

(Much of the following no longer applies as of PyEdit 4.0: see the note above)

To run PyEdit on your Android device, follow these steps:

1. Install the Pydroid 3 app if needed from the Play Store.
2. Download PyEdit's source-code package from this page to any writable folder on your phone, and unzip (i.e., extract) it.
3. Fetch the two custom files:
   • textEditor.py
   • textConfig.py

   And move them to the top level of your unzipped PyEdit source-code package, replacing their original versions. Download by clicking "save" in the "Raw text" line of these links' pages, and search for "# ANDROID" to see code changes made if desired.

4. Run PyEdit by opening its source-code package's file textEditor.py in the Pydroid 3 app's editor and pressing the editor's big yellow run button. PyEdit's GUI should appear and work largely the same as it does on PCs. Naturally, only this last step must be repeated on later runs.

Usage Notes

Also keep the following in mind when using PyEdit on Android:

Home-screen shortcuts

For quick two-tap access to PyEdit, make a home-screen shortcut (a.k.a. link) to its textEditor.py source-code file. Shortcuts look like this or this and can be made by multiple Android file explorers including the app here, but be sure to set the default app or command to Pydroid 3. Tip: uncheck "Parameters" when making shortcuts in Total Commander 3.0 (details).

Rotates may hang or kill

Update: this note's issue has been fixed as of Pydroid 3's 4.X release in 2020. Specifically, screen rotations have been verified to work well and without requiring screen-zoom settings when using Pydroid 3 version 4.01 on Samsung Android versions 7 (Nougat) through 10. Upgrade your Pydroid 3 app as needed.

On some devices, Pydroid 3 either kills the GUI silently or hangs altogether if the screen is rotated between portrait and landscape orientations while a tkinter GUI is running. Per details here, rotations are known to fail on multiple Samsung devices, but the latest of these rotate correctly if they avoid the Small screen-zoom display setting. If your rotates don't work, change your screen zoom to Medium or Large, apply system updates, or don't rotate.

Rotated activities may slide or hang

Update: this note's issue has been fixed as of Pydroid 3's 4.X release in 2020; see the preceding note's update for more details.

In the same department as the preceding note: per here, changing phone orientation during a spawned activity (e.g., a Share or program-help browse) may cause the GUI to slide off screen or similarly hang, even on devices that handle rotations in general. Rotate twice to restore the GUI where supported.

Truncated widgets

Some PyEdit toolbar widgets are obscured and unusable in portrait phone orientation. Use landscape mode instead (where helpful); rotate as needed to see more widgets (where supported); and hide your phone's navigation bar for more GUI room (where possible).

Toolbar symbols

PyEdit was changed to use the same toolbar symbols as the Mac OS PC because those used for Linux rendered too small to be usable on Android. Even so, a stylus or mouse helps, and menus may be more accessible on Android in general.

Cosmetic caveats

Pydroid 3 always botches the Unicode main/popup character of PyEdit window titles in non-maximized mode and occasionally munges Unicode characters in PyEdit's toolbar in all viewing modes. This shot captures both glitches; the failing characters are basic Unicode symbols normally supported by tkinter. There is no workaround, short of dropping the characters, and the visual cues they're designed to provide, altogether; for now, please mind the gaps.

Keyboard shortcuts

PyEdit's menu options and their keyboard shortcuts are always available regardless of screen size and orientation. Use menu pulldowns or access menu shortcuts with a Bluetooth keyboard or an alternative on-screen keyboard with control keys (see the next item) if toolbar buttons are not accessible due to truncation. Caveat: Pydroid 3's tkinter does not seem to recognize the Alt key for menu shortcuts, in keyboards that support this key; use pulldown-menu or toolbar-button equivalents instead.

Newlines may need help

The return key on some recent Samsung on-screen keyboards does not send a newline character to PyEdit in Pydroid 3. This is crucial to editing multiline text in PyEdit but appears to be limited in scope (version 3.2 of the keyboard is the only known offender). If the return key does not move the cursor to the next line on your device, either use a physical Bluetooth keyboard; use Samsung's handwriting-recognition input, whose return key works correctly; or install and use an alternative keyboard whose return key works properly.

For the latter option, both Google Gboard and Hacker's Keyboard on-screen keyboards correctly send newlines to PyEdit on return-key presses. The second of these also has a full set of control and function keys useful for PyEdit menu shortcuts and an on-demand-open feature useful for PyGadgets' PyPhoto operation (see ahead).

Copy/paste may need help

Android-style copy and paste via longpresses is not available in tkinter GUIs run in Pydroid 3. To cut and paste text in PyEdit's edit windows and other text-input fields, highlight with touch, then either use Edit menu options in edit windows to copy and paste, or use the PC-like key combinations Ctrl+c to copy and Ctrl-v to paste in keyboards that support these. You'll find support for these keys in both Bluetooth keyboards and alternative on-screen keyboards like Hacker's Keyboard.

Weird cursor rectangles (or not)

In limited contexts, Pydroid 3's tkinter may draw a large rectangle around the cursor in PyEdit's text input fields. It's not clear if this is intended visibility feature or anomaly and has been observed only when using a Bluetooth keyboard on Samsung Galaxy Note9 devices running Android Oreo. It does not appear for earlier Androids or on-screen keyboards, and later Androids were not tested.

If the rectangle appears on your device, turning it on and off is easy: to disable, click your phone's back button once and tap the text anywhere on the screen before reusing your keyboard; to enable, click your phone's back button once and start reusing your keyboard without a screen tap. Strange (and undocumented, as far as a web search can tell) but true.

Storage constraints

Update: see also this note about possible changes to internal-storage permissions in Android 11.

In Pydroid 3, PyEdit can both save (and auto-save) files anywhere in internal storage (e.g., /sdcard). On a removable drive, it can save (and auto-save) files only in the Pydroid 3 app-specific folder, which is the drive's manually created folder named as follows (the xs mean your drive's Android ID):

/storage/xxxx-xxxx/Android/data/ru.iiec.pydroid3

Files can be viewed anywhere on your device, but saves are limited this way by Android and Pydroid 3 permission constraints. Note that uninstalling an app deletes its app-specific folders, including any user content there.

Grep must use threads

PyEdit's configuration file textConfig.py was changed to use threads instead of the multiprocessing module for parallel greps because the latter fails on Android due to that platform's lack of required semaphore support. Threads work well in testing so far, though they cannot leverage multiple CPU cores (a factor perhaps more important on PCs than phones).

Font constraints

Update: Pydroid 3's 3.0 release in early April 2019 fixed its font crash by coercing any unknown font-family name to helvetica, but its other font limitations described here are still present.

Because some font types cause tkinter GUIs to crash silently in Pydroid 3, PyEdit's configuration file textConfig.py was also changed to disable most user font customizations by adding triple quotes above and below custom settings. The default fonts pick list was also changed to remove crashing fonts, and a text-font preset was coded for readability (the system default is likely too small for some readers to use).

Experiment with PyEdit font settings in the configuration file as desired. In general, font families courier, times, and helvetica work (and monaco is courier and arial is helvetica), but most others crash the GUI, and italic and bold styles are ignored for courier.

New config: file-choosers start folder (March 2019)

Just for Android, PyEdit recognizes a new filechooserstart user setting in the textConfig.py configuration file. When set to a valid folder (or None, to use the internal-storage root default), the Open and Save file-chooser dialogs initially start at the folder specified, instead of the Pydroid 3 app's app-private $HOME folder nested in /data/data. Later navigations pick up from the last folder selected as before, but the new setting allows you to avoid a tedious initial navigation up and down to your content folder. For examples and more details, see the configuration file.

Formerly disabled widgets: user-guide help (April 2019)

The help dialog opened by both the "Help" button and menu options in PyEdit's GUI generally works well, but the dialog's "User Guide" button was originally disabled on Android, due to problems involving the Python webbrowser module it employs. This required users to open PyEdit's user guide outside the GUI (the user guide is available both at the top level of the source-code package and online).

This program worked around the webbrowser issues in April 2019, using techniques described here and here. Hence, PyEdit's user guide now opens from within the GUI on Android just as it does on PCs, though viewer options may be limited, and Android always displays the online version of help to include recent changes; open the guide manually if it is subpar in the GUI. Caution: changing phone orientation during spawned activities can misplace or hang the GUI; see the earlier rotations note.

Run-Code "Click" per default apps on Android (April 2019)

On a related note, the "Click" mode in PyEdit's Run-Code tool was modified to do something marginally useful on Android (its former Linux handler didn't work at all). On Android, this mode now works similarly to help's user-guide display: it relies on Android's default-apps model to select a handler to open the edited file; a back tap in the handler routes focus back to PyEdit automatically; and rotating the handler may harm PyEdit's GUI (per the preceding note).

As noted here, this is similar in sprit to running open and start command lines on Mac OS and Windows, respectively, but Android's default-apps model is not nearly as general, and the set of apps available for opening some files may be limited or unusable (e.g., HTML options may be constrained to text editors). If "Click" isn't useful for your files, open them in a file-manager app instead. Also note that "Capture" mode for running Python code is fully operational on Android; "Click" is only a minor convenience for other text.

Custom help-text dialogs and smaller phones (April 2019)

Also in April, fonts in PyEdit's help dialog were reduced for better fit on phones, and its "About" and "Version" popups were converted to use phone-sized custom dialogs, with "OK" buttons for ease of use and word-wrapped scrolled text to avoid the text truncation of common dialogs in Pydroid 3's tkinter (Linux's standard lightbulb icon was the only casualty of translation). The starting size of these popups also better fits smaller displays.

PyGadgets

PyGadgets—a GUI utility "toy box"—is partly operational on Android. Although the program's launcher itself does not run, the programs launched, including a calculator, clock, photo viewer, and simple game, can be run directly on this platform in Pydroid 3. These programs run only as GUIs. The following augments PyGadgets' base release notes.

GUI Look and Feel

On Android, the directly runnable utilities of PyGadgets look like this in Pydroid 3:

• PyCalc
• PyCalc windows
• PyClock
• PyClock max
• PyToe
• PyToe landscape
• PyPhoto
• PyPhoto portrait
• PyPhoto keys

You can also view these screenshots in slideshow mode starting here.

Orientation

All these GUIs work in either portrait or landscape orientation; experiment to find the best rotation for each, but note that rotating the screen after a GUI is running may not work on some devices per usage notes ahead.

Viewing Modes

PyToe tends to render and work best in Pydroid 3's tkinter maximized viewing mode for automatic fill and resizing; select this mode before running the GUI with "Tkinter: maximize first window" in Pydroid 3's Settings ⇨ System dialog, and press your phone's back button twice to exit the GUI in this mode. PyCalc and PyPhoto both open persistent popup windows that can be easily hidden in maximized mode; clear maximized mode for these GUIs, and exit by clicking the GUI's or window's exit button. PyClock works in any viewing mode.

Running the Programs

To run PyGadgets utilities on your Android device, follow these steps:

1. Install the Pydroid 3 app if needed from the Play Store.
2. Download PyGadgets' source-code package from this page to any writable folder on your phone, and unzip (i.e., extract) it.
3. Fetch the three custom files:
   • calculator.py
   • tictactoe.py
   • tictactoe_lists.py

   And move the first of these files to the _PyCalc/Calculator subfolder located at the top level of your unzipped PyGadgets source-code package, replacing this file's original version. Similarly move the other two files to the _PyToe/TicTacToe subfolder at the same location, replacing their originals too. Download by clicking "save" in the "Raw text" line of these links' pages, and search for "# ANDROID" to see code changes made if desired.

4. To both upgrade the look and feel of the gadgets' help dialogs on Android, and avoid their font-related crashes in older Pydroid 3s, also fetch custom file:
   • helpmessage.py

   And copy it to all four gadget-script subfolders listed in step 6 below. Download by clicking "save" in the "Raw text" line of this link's page.

5. Optional: the code folder also includes patches to files PyGadgets.py and PyGadgets_configs.py, but these are not currently required, as they apply only to the unusable launcher (see Usage Notes ahead). To experiment with their code, fetch and move these files to the top level of the unzipped package. If it ever becomes operational, PyGadgets.py's folder will also require a copy of helpmessage.py for appearance and font-crash avoidance.
6. Run PyGadgets utilities by opening any of the following source-code package's files in the Pydroid 3 app's editor:

   _PyCalc/Calculator/calculator.py
   _PyClock/Clock/clock.py
   _PyPhoto/PIL/pyphoto.py
   _PyToe/TicTacToe/tictactoe.py
   

   Once a file is open, press the editor's big yellow run button to run the program, which will work largely the same as it does on PCs. Naturally, only this last step must be repeated on later gadget runs.

Usage Notes

Also keep the following in mind when using PyGadgets utilities on Android:

Home-screen shortcuts

For quick two-tap access to any PyGadgets utility, make a home-screen shortcut (a.k.a. link) to its source-code file (e.g., to calculator.py in folder _PyClock/Clock for PyCalc). Shortcuts look like this or this and can be made by multiple Android file explorers including the app here, but be sure to set the default app or command to Pydroid 3. Tip: uncheck "Parameters" when making shortcuts in Total Commander 3.0 (details).

Rotates may hang or kill

Update: this note's issue has been fixed as of Pydroid 3's 4.X release in 2020. Specifically, screen rotations have been verified to work well and without requiring screen-zoom settings when using Pydroid 3 version 4.01 on Samsung Android versions 7 (Nougat) through 10. Upgrade your Pydroid 3 app as needed.

On some devices, Pydroid 3 either kills the GUI silently or hangs altogether if the screen is rotated between portrait and landscape orientations while a tkinter GUI is running. Per details here, rotations are known to fail on multiple Samsung devices, but the latest of these rotate correctly if they avoid the Small screen-zoom display setting. If your rotates don't work, change your screen zoom to Medium or Large, apply system updates, or don't rotate.

Rotated activities may slide or hang

Update: this note's issue has been fixed as of Pydroid 3's 4.X release in 2020; see the preceding note's update for more details.

In the same department as the preceding note: per here, changing phone orientation during a spawned activity (e.g., a Share or program-help browse) may cause the GUI to slide off screen or similarly hang, even on devices that handle rotations in general. Rotate twice to restore the GUI where supported.

Launcher not supported

PyGadgets' utility launcher, file PyGadgets.py, displays its GUI but its gadget buttons do not work, because GUI programs spawned by GUI programs run but do not display their windows in Pydroid 3. Run gadgets directly instead per above. Note that the launcher requires the new helpmessage.py to display its help text properly.

PyPhoto: install Pillow

PyPhoto requires the Pillow third-party library to be installed in Pydroid 3: install it by running the command line pip install Pillow in Pydroid 3's Terminal window opened from its main menu, or using the app's Pip interface.

PyPhoto: keypresses need help

PyPhoto's operation relies heavily on keyboard keypresses that are not normally available in touch. The on-screen keyboard doesn't appear in PyPhoto because its GUI has no input field to tap, and most preinstalled keyboards (including Samsung's) won't open any other way. Luckily, there are three workarounds for this issue.

To perform keypresses in PyPhoto, either use a physical Bluetooth keyboard; click the GUI's Help button and press the text content of its help dialog to force the on-screen keyboard to appear (a trick to be sure, but it works); or install the Hacker's Keyboard app on your phone and enable its permanent-notification option, which allows you to pop up its on-screen keyboard on demand by clicking the app's entry in Android's notifications pulldown. Once opened, the keyboard looks like this. Bonus: Hacker's Keyboard also provides arrow keys which scroll PyPhoto indexes and images; enables newlines and menu shortcuts in PyEdit; and supports Ctrl-c/v copy/paste globally.

PyPhoto: thumbnail storage

Update: see also this note about possible changes to internal-storage permissions in Android 11.

PyPhoto must be able to store thumbnail cache files when they are updated. These files are written in the opened images folder and in Pydroid 3 can be saved either anywhere in internal storage (e.g., /sdcard), or on removable drives only in the following manually created Pydroid 3 app-specific folder (in which xs stand for your drive's Android ID):

/storage/xxxx-xxxx/Android/data/ru.iiec.pydroid3

Cache files can be viewed anywhere on your device, but saves are limited by Android and Pydroid 3 permission constraints. Note that uninstalling an app deletes its app-specific folders, including any user content there.

PyPhoto: FAT32 updates

Update: Mergeall no longer requires FAT32 for removable drives, as of Samsung Android 10 in 2020; use exFAT to avoid DST issues, per the earlier note.

PyPhoto may update its per-folder cache files unexpectedly, if you are using a FAT32 SD card for on-phone storage, and daylight savings time or time zone differs from that used when thumbnails were saved. This is a one-time update. Content managed by Mergeall on removable drives should generally be stored using FAT32 for interoperability (see Mergeall usage notes).

PyPhoto: no TIFFs

PyPhoto does not support TIFF images in Pydroid 3, because the Pillow library it uses for image processing does not either. These photos work on PC platforms but have rendering issues on some Mac OS versions; in PyPhoto, they appear as "?" items in thumbnail indexes and do not open when clicked.

Font constraints

Update: Pydroid 3's 3.0 release in early April 2019 fixed its font crash by coercing any unknown font-family name to helvetica, but its other font limitations described here are still present.

Because some font types cause tkinter GUIs to crash silently in Pydroid 3, PyGadgets' configuration file PyGadgets_configs.py was changed to disable user font customizations by adding triple quotes above and below custom settings. At present, this file is unused because it applies only to gadgets when they are launched from the currently unusable launcher. Fonts in gadgets run directly are taken from command-line arguments or else hardcoded defaults.

If the launcher ever comes online, or you wish to specify fonts for gadgets run directly, be careful to use only supported font names. In general, font families courier, times, and helvetica work (and monaco is courier and arial is helvetica), but most others crash the GUI, and italic and bold styles are ignored for courier. Similar font fixes were applied to helpmessage.py; see the note ahead.

PyClock and PyToe: suggested exercises

The PyCalc and PyPhoto gadgets might see some use on your phone, but PyClock and PyToe are difficult to cast as more than novelties or educational examples—especially given that Pydroid 3 can run just one tkinter GUI at a time. Because of this, neither of the latter two has been polished in this release, and both remain candidates for your changes. PyClock, for example, would benefit from different GUI sizes on Android (e.g., larger clock-face items and smaller timer-expired font), and PyToe may play better with a larger board (e.g., a degree of 4). On the other hand, they work; experiment with their code as desired.

PyCalc: new "back" button (March 2019)

Just for Android, PyCalc has a new "back" button which erases the rightmost character displayed, and the last entered, in the calculator's main display. This works just like a keyboard's backspace key but can be used on touchscreens when no physical keyboard is present and on-screen keyboards are not available. Note that the new "back" button works for the main display only; use your keyboard's backspace key for text in "cmd" command-line popups.

PyCalc: fix for stuck-on buttons (March 2019)

Also for Android, a fix was applied to work around a Pydroid 3 tkinter bug which formerly made the calculator's main buttons appear to retain their pressed state until the next GUI event. This was actually caused by tkinter temporarily dropping a pressed button's background colors (a GUI update call had no effect, but a tap anywhere restored colors).

The workaround involved changing the code to use labels instead of buttons as formerly done for Mac OS, at a very minor cost in cosmetics. Labels don't give press feedback (short of adding manual and error-prone after timer code), but buttons in Pydroid 3, like those in PyCalc's lower rows, don't give feedback for quicker taps either. As an added bonus, labels also take up slightly less space on cramped phone displays. For more details, and a related but rarer button-state issue, read the backstory here.

PyCalc: using on-screen keyboards (April 2019)

PyCalc's "cmd" popup fully supports keyboard input of arbitrary expressions; tap or click its input field to open an on-screen keyboard if needed. On Android alone, however, PyCalc's main display does not recognize operator keys entered with a shift key (e.g., + and *, typically), on either physical or on-screen keyboards. The main display supports keyboard input of other keys—including numbers, backspace, and enter/return to "eval"—but shifted operators must be input by tapping or mouse-clicking the GUI's buttons instead.

Keyboard backspace and enter/return keys were enabled by patches in April 2019 that work around an issue in Pydroid 3's tkinter, but shifted operator keys remain unusable on Android due to a bug in this tkinter, described further here. This is, however, a minor limitation for a redundant and less-functional usage mode: the "cmd" popup supports all key presses, including backspace and enter/return; using an on-screen keyboard for the main display requires tapping a "cmd" input field or opening an on-demand keyboard like Hacker's Keyboard (see its PyPhoto note above); and the GUI's calculator buttons are usually easier to use than a keyboard in any event.

helpmessage.py: fonts and fit (April 2019)

Update: Pydroid 3's 3.0 release in early April 2019 fixed its font crash by coercing any unknown font-family name to helvetica, but help-dialog patches noted here also improve look and feel.

The help dialogs of all PyGadgets' utility programs crash without the helpmessage.py patches noted by the install instructions earlier because this file's original code tries to set font type to system, which fails (see the font-constraints note above for more details).

Other help-dialog upgrades: As of April 2019, the help dialogs created by the helpmessage.py module also include a new "OK" button for ease of use on Android, where the window-border's exit button is frustratingly small. In addition, these dialogs now open smaller initially and use a fixed font for better fit on smaller screens (and PyCalc's history display copies the idea).

PyToe patched for Python 3.8 in Pydroid 3 4.X (fall 2020)

Update: as part of the fall 2020 revision, PyToe source file tictactoe_lists.py was patched to use library call time.perf_counter wherever time.clock is unavailable because Python rudely removed the latter in 3.8 after supporting it for some 30 years. This impacts every Python program that uses time.clock and isn't unique to Android or Pydroid 3, but Pydroid 3 4.X's automatic bleeding-edge inclusion of Python 3.8 escalates the issue to immediate necessity for Android tkinter programs. For more background—and to read the full diatribe—tap here.

PyMailGUI

PyMailGUI—a full-featured POP/SMTP email client GUI documented here—has not yet been ported to Android, because its account launcher is rendered unusable by an innate limitation in Pydroid 3's tkinter support.

In short, GUI programs spawned by other GUI programs in the Pydroid 3 app run but do not display their windows. This same limitation cripples launchers in Frigcal and PyGadgets above, but their launched programs can still be run directly with a minor loss in functionality. In PyMailGUI, though, this issue is fatal because it is impossible to open email accounts as freestanding programs without the launcher.

Though its exact causes are unknown, this constraint may be a limitation inherent in the Pydroid 3 approach: a spawned Linux program may have no notion of running in that app's IDE, and this may be the sole source of tkinter support. A specific import-statement format, for example, is required to enable GUIs at all, and tkinter GUIs fail if run in Pydroid 3's own Terminal instead of its IDE. See this note for another look at this limitation.

On the upside, PyMailGUI's core functionality—including email loads, sends, and views, and parallel usage of all these with threads—works well on Android after patching its nested PyEdit code per above, and looks like the following when opening the single book-example account by directly running file PyMailGui.py in folder PyMailGui-PP4E/ (view in slideshow mode here):

• Mail loads
• Mail fetches
• Mail views

Running the program's main Launch_PyMailGUI.py multiple-account launcher, however, does not work. Barring a workaround for the GUI-spawn issue, PyMailGUI awaits either a major rewrite to open accounts as in-process tkinter Toplevel windows or an alternative method for opening email accounts' windows without a launcher. Watch for progress here, but this is complex enough to be filed as very-long-term task.

Top

Code

Media

Mergeall

News

Blog

Apps

Input

©M.Lutz