PyGadgets - GUI Toys, Just for the Hack of It Versions: Jan 31, 2019 (n/a): New guide - limited Android support (see below) Sep 28, 2018 (4.3): PyPhoto image auto-rotation + Pillow workarounds Nov 01, 2017 (4.2): PyPhoto update for single-file thumbnails cache Oct 05, 2017 (4.1): PyClock optimization + hand redraws fix Sep 28, 2017 (4.0): Initial standalone release Earlier versions appeared in the book Programming Python Author: Copyright M. Lutz (http://learning-python.com), 1996-2018 License: Provided freely, but with no warranties of any kind. This program is open source and is yours to use and copy as you like for personal use. For quality and attribution purposes, any bulk redistributions must include in full and unaltered form this file, and folder "screenshots" from the top level of this package. This license applies both to the PyGadgets program, as well as each of the gadget programs it launches. Platforms: PyGadgets is a desktop GUI that runs on Mac OS, Windows, and Linux. It provides a stand-alone format for each, and source code for all. All formats run PyGadgets' calculator, clock, photo viewer, and game. Fetch: From "http://learning-python.com/pygadgets.html" download and unzip: - PyGadgets.app.zip (Mac app) - PyGadgets-64bit.zip or PyGadgets-32bit.zip (Windows executable) - PyGadgets.zip (Linux executable) - PyGadgets-source.zip (source code) See Package Usage Basics below for more install details. Start: To launch the program, run the unzipped folder or its file: - PyGadgets.app (Mac app) - PyGadgets.exe (Windows executable) - PyGadgets (Linux executable) - PyGadgets.py or PyGadgets_bar.pyw (source code) Users of source code and Windows and Linux executables may also run gadgets individually with command-line configurations. See Package Usage Basics below for more run details. Docs: Press '?' on your keyboard in PyGadgets and each gadget it runs to view in-program documentation. Some gadgets also open help on 'Help' or '?' widget clicks or menu entries. On Mac OS, each gadget's help is also available in the top-of-screen menu. Configs: Edit file PyGadgets_configs.py to customize the appearance and behavior of both PyGadgets itself and all the gadgets it spawns. That file documents all the settings available. Tools: PyGadgets is coded in Python, and uses tkinter/Tk for its GUI. Mac frozen apps are built with py2app; others use PyInstaller. Upgrades: To install a new version of PyGadgets in the future, save and restore any customizations you've made in PyGadgets_configs.py. Updates: Watch http://learning-python.com/post-release-updates.html for new-release announcements and additional usage pointers. Other: See top-level folder "screenshots" for GUI samples. Open its file "index.html" to view thumbnail links in any web browser. -------------------------------------------------------------------------------- RELEASE NOTES See the [code] and [web] links in the following for more details. Jan 31, 2019 (n/a): New guide - limited Android support For details on running some PyGadgets on Android devices, see this page: https://www.learning-python.com/using-tkinter-programs-on-android.html Sep 28, 2018 (4.3): PyPhoto image auto-rotation and Pillow workarounds PyPhoto now automatically rotates tilted images with "Orientation" Exif tags to display right-side up - both the thumbnail when stored, and the image when viewed. It also works around a Pillow library bug which could trigger too-many-open-files errors in rare contexts, and an obscure issue in older Pillows that botched image formats on saves. Users of the prior version should delete their "_PyPhoto-thumbs.pkl" cache files in image folders to enable the auto-rotation enhancement. Else images will rotate when viewed, but thumbnails will remain askew. [code] _PyPhoto/PIL/pyphoto.py, _PyPhoto/PIL/viewer_thumbs.py (2.2) [web] learning-python.com/post-release-updates.html#pygadgetssep2018 Nov 01, 2017 (4.2): PyPhoto update for single-file thumbnails cache PyPhoto now stores a folder's thumbnail images in a single pickle file, instead of individual image files in a subfolder. This requires no more space or time, but avoids extra files (15k images formerly meant 15k thumbnail files); multiple file loads and saves; and rare modtime-copy issues for thumbnails in backup programs. PyCalc also now allows fractional numbers to be entered with a leading "." instead of "0.". The PyPhoto change is mildly backward incompatible. Prior PyPhoto version users: when upgrading to a newer release, run the included "delete-pyphoto2.0-thumbs-folders.py" script (or its frozen executable) from a command line to delete all former PyPhoto thumbnail subfolders. [code] _PyPhoto/PIL/pyphoto.py, _PyPhoto/PIL/viewer_thumbs.py (2.1) [web] learning-python.com/post-release-updates.html#pygadgetsnov1 Oct 05, 2017 (4.1): PyClock optimization + hand redraws fix PyClock now avoids updating the analog display's AM/PM label every second (just like the minute and hour hands) to optimize Mac memory use, and fixes a minor defect in PyClock which delayed redraws of the analog display's minute and hour hands too long in some contexts. [code] _PyClock/Clock/clock.py (3.0.1) [web] https://www.learning-python.com/post-release-updates.html#pygadgetsoct4 Sep 28, 2017 (4.0): Initial standalone release Radically upgraded and enhanced versions of both PyGadgets itself, as well as all the gadget programs it spawns. See each gadget's code file(s) for more details; their subfolders are prefixed with a "_". See also learning-python.com/programs.html for PyEdit and PyMailGUI. Earlier versions 1..3 appeared in editions 2..4 of Programming Python. -------------------------------------------------------------------------------- PACKAGE USAGE BASICS PyGadgets is available as full source code, a Mac app, and executables for Windows and Linux. Source code is the ultimate in portability, but apps and executables integrate better with your computer's GUI, do not require any additional install steps, and are immune to future changes in the Python programming language they use. In all packages, and on all platforms, the PyGadgets launcher toolbar GUI allows you to start any of the four gadget GUIs on demand: - the PyCalc calculator - the PyClock analog/digital clock - the PyPhoto photo viewer - the PyToe AI-based game The source-code and Windows and Linux executable packages also allow you to run gadgets individually, by starting their main scripts or programs via click, command line, or other technique. This mode does not use PyGadgets' config-file settings, but accepts configurations as command-line arguments as described ahead. The Mac app provides the PyGadgets toolbar for launching configured gadgets easily. The following sections give the fundamentals of each format's usage: - Mac OS App Package - Windows Executable Package - Linux Executable Package - Source-Code Package Each section is self-contained, so read the section for your format(s). -------------------------------------------------------------------------------- MAC OS APP PACKAGE The Mac OS (X) app runs only on Mac OS systems, but requires no Python install and better supports the Mac user experience. To Install: Fetch file "PyGadgets.app.zip", unzip it by a double-click (or other), and drag the resulting PyGadgets.app to your /Applications folder in Finder to access it from Launchpad. You can also move PyGadgets.app and create aliases to it anywhere else on your computer. No other software must be installed to run the app. To Run: Click "PyGadgets.app" to start the program (or run the app any other way). Running PyGadgets.app automatically launches PyGadgets' GUI toolbar, the same as running the source-code package's PyGadgets.py. Clicking PyGadgets' app icon or Dock entry while the program is running automatically deiconifies (unhides) its main window, and always lifts it above other windows on screen (handy to locate it in a busy session). Double-click the app and single-click the Dock to make this work. Tip: to access a gadget on every Mac desktop, right-click its Dock app icon, select Options, and choose the Assign To section's All Desktops. This both displays an open gadget on every desktop, and reopens a minimized gadget directly on the current desktop. For more details: http://learning-python.com/post-release-updates.html#macalldesktops. Files: Your PyGadgets_configs.py configurations file is located inside the unzipped app's folder, at path: PyGadgets.app/Contents/Resources Navigate to this nested folder in Finder by a right-click on PyGadgets.app and Show Package Contents (or use "ls" in Terminal). There is no separate user guide in this program, as each gadget GUI provides in-program help; press "?" or use widgets in the toolbar or any gadget to access its help. Versions: The Mac OS app was built on Mac OS version 10.11 El Capitan, as a Mac universal binary. It has been verified to run on this as well as Mac OS 10.12 Sierra, and is expected to work on later Mac OS versions. Support for earlier versions of Mac OS (a.k.a. Mac OS X and macOS) remains to be verified. Known Issues and Workarounds: 1) Mac Dock zombies: use App Exposé Due to a flaw in the underlying Tk 8.5 toolkit, closed windows may leave zombie items in Dock menus that can be safely ignored. Tk 8.6 fixes this bug, but has other problems on Macs that cloud its adoption; see http://learning-python.com/post-release-updates.html#homebrewdoa and https://learning-python.com/post-release-updates.html#macpythontk86. As a workaround: use App Exposé to access open windows (e.g., 3-finger downswipes on a window, app, or Dock icon), per the updates note here: http://learning-python.com/post-release-updates.html#appexpose. 2) Mac PyClock disallows PNGs: use GIF or JPEG On Mac OS only, due to a flaw in both Tk 8.5 and 8.6, PyClock may leak memory badly on El Capitan, and worse on Sierra, if a PNG image is used for the clockface in the user configurations file. Use a GIF or JPEG image instead, as described in PyGadgets_configs.py. On Macs, PyClock uses a GIF image as its default; if a PNG is configured, it issues a warning and falls back on its default GIF to avoid issues. 3) Minimize PyClock to reduce memory growth on Macs Also on Mac OS, despite the PNG fix, PyClock's memory usage may still grow modestly over time. To avoid memory growth, minimize PyClock to the Dock when it's not in use; PyClock skips display updates on Mac OS and Windows in this state, to minimize both memory and CPU use. No memory growth occurs while PyClock is minimized. You can also lessen the impact of memory growth by restarting PyClock every few days, though neither running without an image nor digital display mode has a significant impact on CPU or memory use on Macs. PyClock memory growth has been seen only on Mac OS; it does not occur on Windows or Linux, and may be less (but is still present) in Tk 8.6. See also the Oct 5, 2017 release notes above; Mac now leaks less memory. 4) Minimize PyClock to reduce CPU usage on most platforms PyClock updates its display once per second. This is normally a trivial overhead. To reduce CPU usage over time, though, PyClock skips display updates on Mac OS and Windows when minimized (a.k.a. iconified). On Macs, this both lessens CPU and energy draw, and avoids memory growth per the prior note. -------------------------------------------------------------------------------- WINDOWS EXECUTABLE PACKAGE The Windows executables run only on Windows systems, but require no Python install and better support the Windows user interface. To Install: Fetch file "PyGadgets-64bit.zip" or "PyGadgets-32bit.zip" and unzip it on your computer (see Versions below for the difference). Copy the unzipped folder to your desktop or elsewhere to save it. Make Desktop shortcuts to the unzipped folder's executable (per the next section) for quick access as desired. No other software must be installed to run the executable. To Run: Click on the unzipped folder's "PyGadgets.exe" file to run. This automatically starts PyGadgets' GUI toolbar, the same as running the source-code package's script PyGadgets.py. You may also run individual gadgets directly, by running their executables located in the unzipped install folder. Use command-line arguments to configure in this mode (e.g., the file's "Setting = Value" becomes argument "-Setting Value"). Files: Your PyGadgets_configs.py configurations file is located at the top level of the same folder as the ".exe" executable (the folder created by unzipping the download). There is no separate user guide in this program, as each gadget GUI provides in-program help; press "?" or use widgets in the toolbar or any gadget to access its help. Versions: The Windows executable comes in both 64- and 32-bit forms, as denoted by its zipfile names. The former works only on 64-bit systems; the latter works more broadly but may run slower on 64-bit systems. The 64-bit executable was built on Windows 7, and the 32-bit version on Windows 8, but both have been verified to run on Windows 7, 8, and 10. Known Issues and Workarounds: 1) Startup delays: use source if needed Startups may be briefly delayed due to PyInstaller folder extracts. Use the source-code package if this is problematic on slower machines. 2) Minimize PyClock to reduce CPU usage on most platforms PyClock updates its display once per second. This is normally a trivial overhead. To reduce CPU usage over time, though, PyClock skips display updates on Mac OS and Windows when minimized (a.k.a. iconified). On Windows, this may lessen CPU and energy draw. -------------------------------------------------------------------------------- LINUX EXECUTABLE PACKAGE The Linux executable runs only on Linux systems, but requires no Python install and may better support the Linux user interface. To Install: Fetch file "PyGadgets.zip" and unzip it on your computer. Copy the unzipped folder to your home, desktop, or other folder to make it easy to access, and make desktop shortcuts to the executable as desired. No other software must be installed to run the executable. To Run: Click on the unzipped folder's "PyGadgets" file to run. This automatically starts PyGadgets' GUI toolbar, the same as running the source-code package's script PyGadgets.py. You may also run individual gadgets directly, by running their executables located in the unzipped install folder. Use command-line arguments to configure in this mode (e.g., the file's "Setting = Value" becomes argument "-Setting Value"). Files: Your PyGadgets_configs.py configurations file is located at the top level of the same folder as the executable (the folder created by unzipping the download). There is no separate user guide in this program, as each gadget GUI provides in-program help; press "?" or use widgets in the toolbar or any gadget to access its help. Versions: The sole Linux executable was built on Ubuntu Linux 16.04, on a 64-bit system. It is known to work on this and other versions of Ubuntu and is expected to work on some other distributions of Linux, but this is to be verified. If it fails on your system, use the source-code PyGadgets package. Known Issues and Workarounds: 1) Startup delays: use source if needed Startups may be briefly delayed due to PyInstaller folder extracts. Use the source-code package if this is problematic on slower machines. 2) Minimize PyClock to reduce CPU usage on most platforms PyClock updates its display once per second. This is normally a trivial overhead. To reduce CPU usage over time, though, PyClock skips display updates on Mac OS and Windows when minimized (a.k.a. iconified). Due to a Tk bug, this optimization doesn't apply on Linux, though PyClock reports 0% CPU usage and no memory growth when both open and minimized on that platform. 3) PyClock does not set its app-bar icon on Linux For reasons to be determined but likely related to the Tk 8.6 GUI library used, PyClock does not set its app-bar icon for its windows on Linux. All other gadgets do set their icon on Linux using the same image file and identical code, so this is an isolated case. Moreover, it occurs whether PyClock uses Pillow or not, and PyClock correctly sets its window-border icons on Windows. Developers can find more details in windowicons.py; this seems a bug in Linux Tk 8.6. -------------------------------------------------------------------------------- SOURCE-CODE PACKAGE The source-code version of PyGadgets runs on all flavors of Mac, Windows, and Linux, but requires a separately installed Python. To Install: Fetch file "PyGadgets-source.zip" and unzip it on your computer. Also fetch and install a usable Python 3.X if one is not already present. On Mac and Linux, also install the tkinter/Tk toolkit if needed, per notes at www.python.org/downloads/ and, for Mac, https://www.python.org/download/mac/tcltk/. On all platforms, also install the Pillow package if you will be using PyPhoto or PyClock, as described in "Dependencies" below. To Run: Run the main script "PyGadgets.py" in the unzipped folder to launch the toolbar, using any Python program-launching technique on your platform: Windows icon clicks, IDLE, command lines, Mac Python Launcher, etc. Running file "PyGadgets_bar.pyw" has the same effect, but will not produce a console on Windows. You can also run these files in PyEdit (see learning-python.com/pyedit). You may also run individual gadgets directly, by running their main scripts located in the unzipped install folder. See file PyGadgets.py for the table "mytools" giving the name and folder location of each gadget's script. Use command-line arguments to configure in this mode (e.g., the file's "Setting = Value" becomes argument "-Setting Value"). Mac Tip: to access a gadget on every Mac desktop, right-click its Dock app icon, select Options, and choose the Assign To section's All Desktops. This both displays an open gadget on every desktop, and reopens a minimized gadget on the current desktop. More details: http://learning-python.com/post-release-updates.html#macalldesktops. Files: Your PyGadgets_configs.py configurations file is located in the same folder as the main scripts' source-code file (the folder created by unzipping the download). There is no separate user guide in this program, as each gadget GUI provides in-program help; press "?" or use widgets in the toolbar or any gadget to access its help. Programmers note: this package's code was kept as close to its original PP4E version as possible, but substantial changes were made for general functionality upgrades, as well as launch, configuration, and Mac OS port extensions (e.g., Mac menus, reopens, and focus). Search code on "[SA]" for changes. Versions: Source code is platform-neutral and is not dependent on the version of your operating system. This package runs on all versions of Mac OS (X), Windows, and Linux in common use today. The source-code package does, however, require and assume a separately installed Python on your computer: download one for your platform from www.python.org/downloads if Python is not already installed. PyGadgets' source code has been verified to run on all Python 3.X through 3.6. Later Python versions are expected to work too, but 3.6 is the latest verified. Dependencies: Besides Python and Tk, the only third-party install requirement is in gadget PyPhoto, which requires Pillow (PIL) available from https://pypi.python.org/pypi/Pillow. Install a Pillow package for your platform and Python version. App, exe, and executable packages include Pillow automatically, along with Python and Tk. The PyClock gadget uses Pillow if present for clockface images to support nearly all image types. If Pillow is not installed, PyClock supports GIF images with all Pythons, plus PNG images with Pythons that use Tk 8.6+ (including the standard Windows python.org install). Because app, exe, and executable PyClocks include PIL automatically, they always support most image types. For more on image types supported by tkinter, see this folder's file GUI/gifs/README.txt. For recent Pillow install tips, see the note at https://www.learning-python.com/tagpix/README-macapp.html. Known Issues and Workarounds: 1) Mac Dock zombies: use App Exposé On Mac OS, closed windows may leave zombie items in Dock menus due to a flaw in the underlying Tk 8.5 toolkit. Tk 8.6 -- supported by Homebrew Python and python.org's Mac Python 3.6.5+ today -- fixes this Dock bug, but has other issues on Macs that cloud its adoption. See http://learning-python.com/post-release-updates.html#homebrewdoa and https://learning-python.com/post-release-updates.html#macpythontk86. As a workaround: use App Exposé to access open windows (e.g., 3-finger downswipes on a window, app, or Dock icon), per the updates note here: http://learning-python.com/post-release-updates.html#appexpose. 2) Mac PyClock disallows PNGs: use GIF or JPEG On Mac OS only, due to a flaw in both Tk 8.5 and 8.6, PyClock may leak memory badly on El Capitan, and worse on Sierra, if a PNG image is used for the clockface in the user configurations file. Use a GIF or JPEG image instead, as described in PyGadgets_configs.py. On Macs, PyClock uses a GIF image as its default; if a PNG is configured, it issues a warning and falls back on its default GIF to avoid issues. 3) Minimize PyClock to reduce memory growth on Macs Also on Mac OS, despite the PNG fix, PyClock's memory usage may still grow modestly over time. To avoid memory growth, minimize PyClock to the Dock when it's not in use; PyClock skips display updates on Mac OS and Windows in this state, to minimize both memory and CPU use. No memory growth occurs while PyClock is minimized. You can also lessen the impact of memory growth by restarting PyClock every few days, though neither running without an image nor digital display mode has a significant impact on CPU or memory use on Macs. PyClock memory growth has been seen only on Mac OS; it does not occur on Windows or Linux, and may be less (but is still present) in Tk 8.6. See also the Oct 5, 2017 release notes above; Mac now leaks less memory. 4) Minimize PyClock to reduce CPU usage on most platforms PyClock updates its display once per second. This is normally a trivial overhead. To reduce CPU usage over time, though, PyClock skips display updates on Mac OS and Windows when it is minimized (a.k.a. iconified). On Macs and Windows, this may lessen CPU and energy draw. On Macs, it also avoids memory growth, per the prior note. Due to a Tk bug, this optimization doesn't apply on Linux, though PyClock reports 0% CPU usage and no memory growth when both open and minimized on that platform. 5) PyClock does not set its app-bar icon on Linux For reasons to be determined but likely related to the Tk 8.6 GUI library used, PyClock does not set its app-bar icon for its windows on Linux. All other gadgets do set their icon on Linux using the same image file and identical code, so this is an isolated case. Moreover, it occurs whether PyClock uses Pillow or not, and PyClock correctly sets its window-border icons on Windows. Developers can find more details in windowicons.py; this seems a bug in Linux Tk 8.6. -------------------------------------------------------------------------------- [end]