File: pygadgets-products/unzipped/README.txt

PyGadgets - GUI Toys, Just for the Hack of It

Versions:
    Sep 28, 2017: Initial Release
    Oct 05, 2017: PyClock optimization + hand redraws fix
    Nov 01, 2017: PyPhoto update for single-file thumbnails cache

Author:
    Copyright M. Lutz (http://learning-python.com), 1996-2017

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:
    For updates, see learning-python.com/post-release-updates.html.
    To install a new version of PyGadgets in the future, save and 
    restore any customizations you've made in PyGadgets_configs.py.

Other:
    See top-level folder "screenshots" for GUI samples.  Open its 
    file "index.html" to view thumbnail links in any webbrowser.

--------------------------------------------------------------------------------

Release Notes

Sep 28, 2017: Initial Release

Oct 5, 2017: PyClock optimization + hand redraws fix (all packages)

    Fixed a minor defect in PyClock, which delayed redraws of the analog 
    display's minute and hour hands too long in some contexts.  These two 
    hands are normally not redrawn until the second hand reaches 12, as a 
    valid and important optimization.  This delay can be problematic, though,
    if used after any state that precludes analog clock updates - including 
    window minimization, digital-display mode, system suspend, and menu and
    modal-dialog view on some platforms.  In all such cases, the analog time 
    might not be current or correct until the second hand again reaches 12.
    To avoid this lag, PyClock now monitors the last-analog-redraw time to 
    force all hands to be redrawn immediately in all these contexts.

    As a related optimization, PyClock now also avoids updating the analog 
    display's AM/PM label every second, just like the minute and hour hands.
    This seems to have further reduced the memory leakage that occurs while 
    the analog display window is open on Macs: open-window growth is now just
    1M per 20 minutes, which translates to 3M/hour, 72M/day, and 500M/week.  
    This is roughly half what it was formerly - a compelling reason to 
    retain the prior paragraph's optimization - and some popular Mac apps 
    use substantially more memory over time (see your Mac Activity Monitor).
    Oddly, the digital display now leaks memory fastest, but is likely 
    lesser-used; optimizing it remains a low-priority TBD.

    Also changed PyCalc to automatically set the focus on new "cmd" popups'
    entry fields (which also shifts focus to their windows on Windows), and 
    added a Mac All Desktops tip to Mac usage notes below.

Nov 1, 2017: PyPhoto update for single-file thumbnails cache (all packages)

    PyPhoto was upgraded to store a folder's thumbnail images in a single 
    pickle file, instead of individual image files in a subfolder.  This
    new design requires no more space or time, but avoids extra files (15k 
    images formerly meant 15k thumbnail files); multiple file loads and saves;
    and nasty modtime-copy issues for backup programs too rare and complex
    to cover here.  See the source code's viewer_thumbs.py for full details.

    This is a mildly backward-incompatible change.  Prior PyGadgets/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. 
    This program is run with no command line arguments, and asks for a folder
    path and delete verifications.  In the Mac app, it's an executable at 
    "PyGadgets.app/Contents/MacOS" (see Show Package Contents); in other 
    packages, it's in your install folder.  PyPhoto will still work if you 
    don't delete the former subfolders, but they will be unused trash.

    Apart from this compatibility fix, the main user-visible artifact of this
    upgrade is a single "_PyPhoto-thumbs.pkl" file per opened folder, instead
    of the former "thumbs" subfolder.  This thumbnail cache is still built on
    first open and auto-updated on changes as before, to make later opens fast.
    Though less prominent, the new PyPhoto also displays images in the same 
    order everywhere; uses a placeholder thumbnail for photos with errors 
    (instead of omitting); and works on unwriteable folders (though slowly). 

    PyPhoto now also supports a new "NoThumbChanges" configuration-file setting 
    and command-line argument, which can be used to prevent rare but spurious 
    thumbnail regenerations for large, static archives, when file modification
    times are skewed between platforms or filesystems.  See PyGadgets_configs.py.    
    This setting's False default need not be changed in typical usage.  For 
    example, PyPhoto photo archives and thumb caches have been seen to work 
    correctly without this change when used on a single platform, burned to  
    BD-R discs, or transferred between Mac OS and Windows on exFAT drives.

    This release also applied a minor change to PyCalc, to allow fractional 
    floating-point numbers to be entered with a leading "." instead of "0.". 
    To halve a number, for instance, "24 * .5" and "24 * 0.5" both now work. 
    Numbers with "E" exponents allow both forms too: ".1E-99" or "0.1E-99". 

--------------------------------------------------------------------------------

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.

--------------------------------------------------------------------------------

MAC OS APP PACKAGE

    The Mac OS (X) app runs only on Mac 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.
        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.

    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 but not by python.org's Mac Python 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.
        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] Books Programs Blog Python Author Training Search Email ©M.Lutz