./btns-d1-no-optionals.png.note=================================================

This demo mostly captures the new Note feature in 2.3.  Up first
is a viewer page in a desktop browser, with both Note and Full
buttons disabled.  (Look carefully: this and other pages in 
this demo have a toolbar, but so do the images they display.)

Note is disabled if no .note file is present for any image, 
or the useImageNotes config file/argument setting is False. 
Full is disabled if the showFullscreenButton setting is False. 
By default, Note and Full configs are both True, and adding
a single .note file suffices to show Note.  

Note is shown on all pages in a gallery if enabled for any
image (note-less images have a line-through).  Note, Full,
and Auto are also omitted if JavaScript is disabled; see the
"nojavascript" captures ahead.

./btns-d2-note-only.png.note====================================================

With Note enabled, but not Full.  Full is a limited
JavaScript fullscreen, which lasts for just one page.

./btns-d3-full-only.png.note====================================================

With Full enabled, but not Note.  This is identical to
the 2.2 default layout.  This is also the 2.3 default, 
when no .note files are present for any image.

./btns-d4-all-on.png.note=======================================================

With both Note and Full enabled.  This is the 2.3 default, 
when at least one .note file is present for any image.

./btns-m1-no-optionals.png.note=================================================

The next four shots show the same as the preceding set,
but on a mobile-device browser (via a desktop browser emulation).

./note-d1-large.png.note========================================================

A typical image-note popup, on a desktop browser.  Open
by tapping the Note button on any browser, or up-swiping
on the image itself on touch displays.  Close by tapping
OK, or anywhere outside the popup (except on iOS).

./note-d2-thin.png.note=========================================================

The next two shots show how the note resizes along with the
window and its image.  The popup expands and shrinks both
horizontally and vertically, and its text is adjusted to match.  
For large notes or small displays, the text scrolls vertically.

./note-d4-info-on-top.png.note==================================================

For comparison, here is the image-info popup at the top 
of the page (it's unchanged in 2.3, apart from a rounded 
border); tap the filename or down-swipe on the image 
to open it.  
This popup's text is fixed, and it has a fixed size that 
doesn't change with the window, but its text still 
scrolls as needed.

./note-m1-portrait.png.note=====================================================

The next two shots show the same note popup on a small
mobile, courtesy of browser emulation.  Especially for 
mobile, notes should be relatively small, to minimize
vertical scrolling.

./note-x1-none.png.note=========================================================

The Note button renders with a line-through if there is no
.note file for the image, so users know to skip.  If Note 
is tapped anyhow (or up-swipe is used), an empty "(No note)"
popup is opened—as in the following image.  Up-swipe equates
to raw views as in 2.2 only if Notes are disabled altogether 
(e.g., if no .note files are present).

./note-x3-short.png.note========================================================

A short note: left justified in the popup's space.  The
popup itself is centered in the display, spanning 70% of
it by default.  This span size can be adjusted with config
file/argument setting noteBoxVSpace, which gives the size 
of both left and right padding; wider may be better for 
mobile-only galleries, though subpar for desktop (and media 
queries seem overkill).

./note-x4-long-unicode.png.note=================================================

A larger note, with a blank line (two adjacent line breaks)
for a paragraph break, and Unicode symbols and emojis.  Any 
Unicode characters work in .note files, and the file is decoded
using the Unicode encoding given in config file/argument 
noteEncoding (default UTF-8).

Also shown here: HTML special characters are escaped and displayed
verbatim.  Thus, <A> link text won't render as a link, and HTML or
CSS formatting won't work; notes are plain text only, for simplicity.

See also z-escaped-note-text.png in this gallery for fuller escaping tests.

./tooltips1.png.note============================================================

The next five shots capture viewer-page tooltips, on desktop 
Firefox.  Tooltips don't work in mobile browsers today, even 
with a stylus.  

In 2.3, tips were added for Prev, Next, and Index buttons for
consistency, and tooltips are enabled by default because the 
toolbar is more complex with the addition of Note; disable 
with config file/argument setting useToolTips if desired.
Not shown here, tooltips also popup over thumbnails on the index page.

./x-nojavascript1-2.3.png.note==================================================

The next two pages show the new no-JavaScript display in 2.3,
and its former rendering in 2.2.  2.3 now officially requires 
JavaScript for viewer pages, so this is largely a moot point.

In more detail, though, 2.3 removed the former HREF fallbacks 
on Prev, Next, and Index toolbar buttons, because they invoked 
URL popups that are now redundant with tooltips, and are arguably
more intrusive.  This makes these buttons unusable unless 
JavaScript is enabled, but viewer pages were already mostly 
unusable without JS in 2.2 anyhow (as is most of the web).

./xx-desktop-dyn.png.note=======================================================

The next eight screenshots capture the effects of 2.3's new 
horizontal spacing scheme for dynamic index-page layout.
Fixed shots follow their dynamic equivalents.  In dynamic,
columns are now packed tighter when labels are wider
than images.  This allows some galleries to show more
than one column on larger candy-bar mobiles, making dynamic 
a more useful alternative than before.

./xx-desktop-wide-dyn.png.note==================================================

Stretching the window shows more columns in dynamic layout,
but simply expands the table in fixed layout.  Resizes like 
this can happen in desktop browsers in general, but also 
in mobile browsers for both landscape orientation and popup 
or split-screen app windows where supported.

./xx-mobile-dyn.png.note========================================================

Dynamic layout now shows two columns on an emulated Galaxy Note20 Ultra
with the 2.3 layout improvement, and avoids horizontal scrolls in full.  
This still means more vertical scrolling, but not as much as the former
one-column result.  Fixed layout still requires some minor horizontal 
scrolls, but less vertical; the tradeoff seems too close to call.

./xx-mobile-land-dyn.png.note===================================================

Dynamic and fixed layout in landscape orientation: fixed fills
the space better, but full-size images in viewer pages are 
displayed larger in portrait mode in most phones, and portrait
is probably more natural for users.  Until foldables seize 
the future, at least.

./xx-omit-index-labels-dyn.png.note=============================================

The next two shots show the effects of omitting filename 
labels in dynamic and fixed layout, respectively.  This 
mode, new in 2.3, shows just thumbnails, and is enabled
with config omitIndexPageLabels.  In dynamic layout, its
spacing can be tweaked with configs dynamicLayoutPaddingH/V.
This mode may be useful if filenames are superfluous 
and/or image Notes suffice to describe images.

Build command, dynamic:

py3 $C/thumbspage/thumbspage.py . 
           INDEX=\'index-dynamic\' 
           THUMBS=\'_thumbspage-dynamic\' 
           useDynamicIndexLayout=True 
           dynamicLayoutPaddingH=\'16px\' 
           dynamicLayoutPaddingV=\'16px\' 
           inputCleanThumbsFolder=True 
           inputThumbMaxSize=100 inputUseViewerPages=True 
           popupFgColor=\'tan\' 
           popupOpacity=0.45 
           omitIndexPageLabels=True

Build command, fixed:

py3 $C/thumbspage/thumbspage.py .
           INDEX=\'index\'
           useDynamicIndexLayout=False 
           inputCleanThumbsFolder=True inputThumbsPerRow=4 
           inputThumbMaxSize=100 inputUseViewerPages=True 
           popupFgColor=\'tan\' 
           popupOpacity=0.45 
           omitIndexPageLabels=True

./xx-omit-labels-mobile-i.png.note==============================================

The next two shots show the effects of omitting filename 
labels in a gallery viewed on a relatively small (5.8" 
screen) mobile phone.  Viewers get two columns, and, when
combined with dynamic layout, no horizontal scrolls.
As the second capture shows, image notes can suffice in
some use cases.

Build command (dynamic index layout + thumbs-only index):

python3 $C/thumbspage/thumbspage.py . \
    useDynamicIndexLayout=True \
    inputUseViewerPages=True inputThumbMaxSize=128,128 inputCleanThumbsFolder=True \
    popupFgColor=\'#ddd\' \
    omitIndexPageLabels=True \
    dynamicLayoutPaddingH=\'16px\' dynamicLayoutPaddingV=\'16px\'

./y-pcolors-1-prior-wb.png.note=================================================

The image set starting here demos custom color settings for popup dialogs,
added in the April 2022 repackage of version 2.3.  Each image's note gives
the command used to build the demo, as extra examples.

This first image shows the preset default before the April 2022 update: 
full white on full black, and OK is square (unlike the dialog).  In this
version, popups always inherited all colors from the viewer page at large.

Build command: 

py3 thumbspage/thumbspage.py trnpix/

./y-pcolors-2-preset-wb.png.note================================================

The new preset default after the April 2022 update: OK is rounded, 
and dialogs inherit white-on-black bg/fg/bd colors from the page.

If popup colors are not given, as here, they use their preset Nones in the
config file, which means they inherit from the viewer page as before.  
This holds for background, foreground (text), and border colors in popups.

Build command: 

py3 thumbspage/thumbspage.py trnpix/

./y-pcolors-3-ddd-blk.png.note==================================================

A muted white on full black, to minimize text glare.

Build command: 

py3 thumbspage/thumbspage.py trnpix/ popupFgColor=\'#dddddd\'

Note that popupFgColor=\'#ddd\' is equivalent (a CSS shorthand).

./y-pcolors-4-ccc-blk.png.note==================================================

A more-muted white on black; this may be too dull on some displays.

Build command: 

py3 thumbspage/thumbspage.py trnpix/ popupFgColor=\'#ccc\'

./y-pcolors-5-ccc-18.png.note===================================================

Muted white on muted black; arguably dingy, but this is common in dark themes,
and results can vary per display.

Build command: 

py3 thumbspage/thumbspage.py trnpix/ popupBgColor=\'#181818\' popupFgColor=\'#cccccc\'

./y-pcolors-6-blk-grey.png.note=================================================

Black on dark grey: very readable, but may be a bit jarring vs black pages,
and may clash with some images, though black and grey are generally neutral.

Build command: 

py3 thumbspage/thumbspage.py trnpix/ popupBgColor=\'darkgrey\' popupFgColor=\'black\'

./y-pcolors-7-tan-blk.png.note==================================================

Tan on black: this one seems the most readable on a MacBook Pro, but colors 
like tan are risky: they can vary across displays (e.g., tan may be too orangey 
elsewhere), and might clash with image content.

Build command: 

py3 thumbspage/thumbspage.py trnpix/ popupFgColor=\'tan\'

./y-pcolors-8-ivory-cyan.png.note===============================================

How to annoy your readers?—black on ivory with a cyan border.
All other popup-color examples inherit border color from the page 
(and popups' OK buttons always inherit bg/fg from the page by design).  
Ivory is harsh if viewer pages use black, but may pass for lighter 
pages.  Cyan is just to demo borders here; don't try this at home.

Build command: 

py3 thumbspage/thumbspage.py trnpix/ popupBgColor=\'ivory\' popupFgColor=\'black\' popupBorderColor=\'cyan\'

./y-pcolors-9-viewer-thm.png.note===============================================

To close out the popup-colors set, the next two captures show viewer pages
from different galleries, whose viewer-page color themes are configured
to be different from the preset white on black (they use white on blue
and black on gray, respectively).  Because no popup colors are given in 
the builds, they default to the viewer-theme's colors as before.

Build command 1: 

py3 thumbspage/thumbspage.py site-mobile-screenshots/ 
    thumbsBgColor=\'#123456\' thumbsFgColor=\'white\' thumbsBorderColor=\'white\'
    viewerBgColor=\'#123456\'

Build command 2: 

py3 thumbspage/thumbspage.py dynamiclayout/$demo
    viewerBgColor=\'darkgrey\'
    viewerFgColor=\'black\'
    viewerBorderColor=\'black\'

(And yes, Firefox shows the gray button inconsistently like that; it's 
nearly a glitch, but button rendering can vary per browser.)

./yy-opacity1-image.png.note====================================================

The next four screenshots capture the effects of 2.3's new 
viewer-page popup-opacity config setting: the image, followed
by opacities 0.1 (bright), 0.45 (mid), and 0.9 (dark).  Bright
may be better if the note refers back to the image, but dark 
may be better to block out image glare and focus on the note.  
Overlaid images have a subtle interplay with both note goals
and note text color, and the effects may vary by display.

Build commands:

py3 thumbspage/thumbspage.py trnpix/ popupFgColor=\'tan\' popupOpacity=0.N

./z-escaped-note-text.png.note==================================================

A stress test for special characters embedded in .note files.
Note text is escaped for both use in a JavaScript '...' string
(quotes and backslashes), and for display as plain text in HTML
(<, &, and the like).  For more gritty details, see 
escapeForJavaScriptandHTML() in thumbspage.py.


1) HTML special characters: displayed literally

.... < & >

.... <u>spam</u>

.... <A HREF="site">link</A>


2) JavaScript quote characters: do not break strings

.... " '

.... page's "text" 'python"s'


3) JavaScript special characters: ignored in the string

.... \ ${2}

.... \" \' \other \x25 \? \\ \\\ \ \


4) And so on: Unicode code points, emojis, curses

.... ☝, ☀, ⇒, 通用, ñ, ä

.... 👍, 🦧, 🍕

.... #!$%^#&@*()~+;


This image captures the .note file; press Note to compare to its displayed
result, and view the end of this page's source code for escaping results.

./z-for-more-demos-note.png.note================================================

For prior-version examples, open thumbspage's examples/2.2-upgrades/.
For a less artificial demo of 2.3 notes in action, copy/paste to visit:

https://learning-python.com/trnpix/

That gallery was the original use case for thumbspage, and was 
updated with .note files for 2.3.  Given the effort this required,
it's unlikely that other preexisting thumbspage examples or clients 
will sprout notes any time soon.  Then again...