File: pygadgets-products/unzipped/README.txt

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]



[Home page] Books Code Blog Python Author Train Find ©M.Lutz