Merged 'main' into 'weblate'.

CHANGELOG.txt

@@ -16,6 +16,15 @@ You should have received a copy of the GNU General Public License
 along with this program.  If not, see
 <http://www.gnu.org/licenses/>.
 
+Changes in v2024.9.0:
+  1/ Regions tab image display is zoomable and draggable.
+  2/ Qt package preference can be changed in settings dialog.
+  3/ Selected image thumbnails use system "selected text" colour.
+  4/ Map marker colours can be changed in settings dialog.
+  5/ Better handling of missing WebGL in map tabs.
+  6/ Improved 'photini-post-install' command.
+  7/ Other minor improvements and bug fixes.
+
 Changes in v2024.8.2:
   1/ Fix map tabs localisation problems on Windows.
 

src/doc/manual/address.rst

@@ -1,5 +1,5 @@
 .. This is part of the Photini documentation.
-   Copyright (C)  2019-23  Jim Easterbrook.
+   Copyright (C)  2019-24  Jim Easterbrook.
    See the file ../DOC_LICENSE.txt for copying conditions.
 
 Location addresses
@@ -30,8 +30,8 @@ The address lookup service is provided by OpenCage_, using data from OpenStreetM
 Other map providers don't allow lookup results to be permanently stored.
 
 Photini attempts to use all the data returned in an address lookup.
-This can lead to some duplication, e.g. Château-Gontier appears twice in ``city``.
-Note also the blue underlining indicating text that is too long to store in IPTC-IIM metadata.
+This can lead to some duplication, e.g. a city name appearing twice in ``City``.
+Note also the blue underlining indicating text (in the ``City`` field) that is too long to store in IPTC-IIM metadata.
 
 .. image:: ../images/screenshot_292.png
 
@@ -41,7 +41,7 @@ The reverse geocoding process chooses a "place" (address, business, landmark, et
 
 .. image:: ../images/screenshot_293.png
 
-It is usually necessary to edit the address quite a lot.
+It is usually necessary to edit the address.
 
 .. image:: ../images/screenshot_294.png
 

src/doc/manual/configuration.rst

@@ -5,11 +5,15 @@
 Configuration
 =============
 
+Photini's ``Options`` menu allows you to adjust its operation to suit your personal preferences.
+
+.. image:: ../images/screenshot_080.png
+
 If there are tabs in the Photini GUI that you don't use, you can remove them by deselecting their entry in the ``Options`` menu.
 
-The ``Options`` menu also has a ``Settings`` item which opens the dialog shown below.
+.. image:: ../images/screenshot_081.png
 
-.. image:: ../images/screenshot_36.png
+The ``Options`` menu has a ``Settings`` item which opens the dialog shown above.
 
 The first three items adjust how Photini uses IPTC-IIM "legacy" metadata.
 (Since 2004 the `IPTC standard`_ uses XMP to store metadata.
@@ -34,13 +38,28 @@ Next there are options to adjust file timestamps.
 "Set to when the file is saved" sets files' timestamps to when you save the file with Photini, like most other computer programs do.
 You may find these options useful if you often use a file browser to sort files by date.
 
-If you have installed gpxpy_ then there is a final option to determine if the altitude is included when a GPX file is used to set pictures' GPS data.
+.. image:: ../images/screenshot_082.png
+
+You may need to scroll down to see all the settings available.
+
+If you have installed gpxpy_ then there is an option to determine if the altitude is included when a GPX file is used to set pictures' GPS data.
+
+.. image:: ../images/screenshot_083.png
+
+Clicking on one of the "map icon colours" fields opens a colour chooser dialog that allows you to click on a colour or type in its values in a variety of formats.
+
+.. image:: ../images/screenshot_084.png
+
+Lastly, if you have more than one Qt package installed then you can choose which one to use.
+If you change the Qt package Photini informs you that it needs to be restarted to use the new package.
 
 .. _configuration-spell:
 
 Spell checking
 ^^^^^^^^^^^^^^
 
+.. image:: ../images/screenshot_085.png
+
 The ``Spelling`` menu allows you to enable or disable spell checking on Photini's text fields, and to select the language dictionary to use.
 The available languages depend on what dictionaries you have installed.
 Adding extra languages on Linux is easy -- just use your system's package manager to install the appropriate dictionary (and make sure you have the appropriate enchant "backend" installed).
@@ -65,25 +84,16 @@ If you'd like to store it elsewhere (e.g. on a networked drive so you can share
 PyQt options
 ^^^^^^^^^^^^
 
-The configuration file includes options to select use of PyQt5, PyQt6, PySide2, or PySide6.
-These may be useful if one of these components on your computer is incompatible with Photini.
-There are so many versions of PyQt that it is impossible to test Photini with every one.
-
-The default options in the configuration file are in the ``[pyqt]`` section:
+Some less used Qt options can only be set by editing the configuration file.
+These options are in the ``[pyqt]`` section:
 
 .. code-block:: guess
 
    [pyqt]
-   qt_lib = 'auto'
+   qt_lib = 'PyQt6'
    scale_factor = 1
    native_dialog = True
 
-To force use of a particular Qt library set the value of ``qt_lib`` to ``'PyQt5'``, ``'PyQt6'``, ``'PySide2'``, or ``'PySide6'``.
-(You can also use the ``photini-configure`` command to set this.)
-You can check which versions Photini is currently using by running it in a command window with the ``--version`` option::
-
-   photini --version
-
 If your computer has a high resolution screen, or you have poor eyesight, you may find the Photini user interface's text is too small to read comfortably.
 Setting ``scale_factor`` to a value larger than ``1`` should enlarge Photini.
 Using non-integer values is possible, but might show artefacts from the scaling.
@@ -111,7 +121,8 @@ If you find problems such as date or timezone values (on the "technical metadata
 
 To find out what styles are available on your computer you can use Photini's ``--version`` flag.
 (You need to run Photini from a command window to do this, see the :ref:`installation troubleshooting<installation-troubleshooting>` section.)
-You can then try one of these styles as follows::
+
+::
 
     $ photini --version
     Photini 2022.3.2, build 2084 (3194bd4)
@@ -123,6 +134,10 @@ You can then try one of these styles as follows::
       available styles: Breeze, bb10dark, bb10bright, cleanlooks, gtk2, cde, motif, plastique, Windows, Fusion
       using style: breeze
 
+You can then try one of these styles by specifying it on the command line::
+
+    $ photini --style motif
+
 Note that the style names are not case sensitive.
 If none of the available styles is to your liking you may be able to install extra ones.
 For example, on some Ubuntu Linux systems the package ``qt5-style-plugins`` is available.
@@ -134,8 +149,7 @@ Note that after doing this you can not set a different style on the command line
 .. code-block:: guess
 
    [pyqt]
-   using_qtwebengine = 'auto'
-   qt_lib = 'auto'
+   qt_lib = 'PyQt5'
    scale_factor = 1
    native_dialog = True
    style = cleanlooks

src/doc/manual/extending.rst

@@ -1,13 +1,35 @@
 .. This is part of the Photini documentation.
-   Copyright (C)  2019-21  Jim Easterbrook.
+   Copyright (C)  2019-24  Jim Easterbrook.
    See the file ../DOC_LICENSE.txt for copying conditions.
 
 Extending Photini
 =================
 
 It is possible to add new functionality to Photini by providing a new "tab".
 Because the tabs are loaded dynamically at run-time the new tab does not need to be part of the Photini Python package.
-For example, if the package ``mypackage`` provides a Photini tab in the module ``mypackage.photini``, then adding ``mypackage.photini`` to the tab modules list (see :ref:`configuration-tabs`) will add the tab to Photini.
+For example, if the package ``mypackage`` provides a Photini tab in the module ``mypackage.photini``, then adding ``mypackage.photini`` to the tab modules list (see :ref:`configuration-tabs`) will make the tab available in Photini.
+
+.. code-block:: guess
+
+    [tabs]
+    modules = ['photini.descriptive',
+             'photini.ownership',
+             'photini.technical',
+             'mypackage.photini',
+             'photini.googlemap',
+             'photini.bingmap',
+             'photini.azuremap',
+             'photini.mapboxmap',
+             'photini.address',
+             'photini.regions',
+             'photini.flickr',
+             'photini.ipernity',
+             'photini.pixelfed',
+             'photini.importer',
+             'photini.googlephotos']
+
+You can add your module anywhere in the configuration file's module list.
+The user can then set the tab order by drag and drop.
 
 Every Photini tab has to have the following interface:
 
@@ -18,18 +40,19 @@ Every Photini tab has to have the following interface:
        def tab_name():
            return 'Tab name'
 
-       def __init__(self, image_list, *arg, **kw):
+       def __init__(self, *arg, **kw):
            super(TabWidget, self).__init__(*arg, **kw)
-           # Add child widgets here. Keep a reference to image_list if you need to
-           # interact with the image selector.
+           self.app = QtWidgets.QApplication.instance()
+           # Add child widgets here. self.app has several useful attributes
+           # such as the configuration and image_list objects.
 
        def refresh(self):
            # Called when the user selects the tab. If your tab does something
            # slow, such as contacting a server, then do it here rather than in
            # __init__. You might also want to update your tab to synchronise with
            # changes made in another tab, like the map tabs do. Otherwise, just
            # update the displayed metadata.
-           self.new_selection(self.image_list.get_selected_images())
+           self.new_selection(self.app.image_list.get_selected_images())
 
        def do_not_close(self):
            # Return True if your tab is busy (e.g. uploading photographs) and
@@ -43,6 +66,6 @@ Every Photini tab has to have the following interface:
 The ``tab_name`` method returns the label given to the tab.
 It should be as short as possible.
 
-When the user defines any new metadata you should get the current selection from the ``image_list`` and set the metadata on every image in the selection.
+When the user defines any new metadata you should get the current selection from the ``self.app.image_list`` and set the metadata on every image in the selection.
 
 It's probably easiest to start with a copy of the Photini tab module most like what you want to do, strip out the bits you don't need and then add your own stuff.

src/doc/manual/map.rst

@@ -9,19 +9,19 @@ The map tabs allow you to set the location of where a photograph was taken.
 Photini currently uses four different map providers: Google, Bing, Azure, and Mapbox/OpenStreetMap.
 (Microsoft have announced that Bing Maps will be "retired" in June 2025. Azure Maps is its replacement.)
 All four tabs have similar functionality, but have different styles and levels of detail.
-Each map has a drop down menu to switch between map and aerial / satellite imagery.
+Each map has a button to switch between map and aerial / satellite imagery.
 
 .. image:: ../images/screenshot_130.png
 
 The map initially displays the previously used location.
-You can change the view by zooming in or out, or by panning the map by dragging it with the mouse.
+You can change the view by zooming in or out (with scroll wheel or the maps' buttons), or by panning the map by dragging it with the mouse.
 However, it's usually easier to find a specific location by using the search facility.
 
 .. image:: ../images/screenshot_131.png
 
 Click on the ``<new search>`` edit box and type in a search term such as the name of a town, then press the 'return' key.
 A drop down list of place names should appear, from which you can select one.
-Note that the search box may be disabled for a few seconds after each search to limit the load on the free servers that provide the service.
+Note that the search box may be disabled for a few seconds after each search to limit the load on the map provider's servers.
 
 .. image:: ../images/screenshot_132.png
 
@@ -35,16 +35,26 @@ You may get more useful results by switching to a different map tab.
 
 .. image:: ../images/screenshot_133.png
 
+Selecting one of the search results shows the selected location on the map.
+The map's zoom level will be adjusted to include the entire area of the named place.
+
 .. image:: ../images/screenshot_134.png
 
 Having found the right town, you can then zoom in and pan around to find the exact location where your photograph was taken.
-Using aerial / satellite imagery can help with this.
 
 .. image:: ../images/screenshot_135.png
 
+.. image:: ../images/screenshot_136.png
+
+Using aerial / satellite imagery can help with this.
+
+.. image:: ../images/screenshot_137.png
+
 Now you can drag and drop your photograph onto the map to set its location.
 To set the same location on multiple images, select them all and then drag and drop one of them.
 
+.. image:: ../images/screenshot_138.png
+
 .. |flag| unicode:: U+02690
 
 Note that photographs that have location data are shown with a flag symbol (|flag|) in the image selector area.
@@ -54,39 +64,42 @@ These values are editable, so you can set the location of photographs directly,
 You can also adjust the location by dragging the marker on the map.
 To clear a photograph's location data just delete the coordinates.
 
-In Photini version 2023.5.0 and later the coordinates are separated by a space.
-Older versions used a comma but this causes problems with locales that use a decimal comma instead of a decimal point.
-
-.. image:: ../images/screenshot_136.png
+.. image:: ../images/screenshot_139.png
 
 When several photographs have location metadata Photini will pan the map (and zoom out if required) to ensure all the selected images are shown on the map.
 Selected images are shown with red markers.
 Unselected images are shown with grey markers.
 
-.. image:: ../images/screenshot_137.png
+If you find the marker colours don't contrast well with your preferred map style or aerial photography then you can change their colours in Photini's :doc:`configuration <configuration>`.
 
-The ``Get altitude from map`` button sets the photograph's altitude (in metres) from its latitude and longitude, using data from the map provider.
-Not all map providers have altitude data, and the accuracy varies quite a lot.
-You can edit the value to correct it.
+As shown above, several images can have the same location.
+A red marker is shown if any of the images is selected, but clicking on the marker will select all the images that have that location.
 
-.. image:: ../images/screenshot_138.png
+.. tip::
+    If you have several images at one location, but need to move some of them to a different location, select the images to be moved in the image selector, then drag them onto their new position on the map.
+
+.. image:: ../images/screenshot_140.png
 
 Selecting another map tab will show the same location but with data and imagery from a different provider.
 
-.. image:: ../images/screenshot_139.png
+.. image:: ../images/screenshot_141.png
+
+The ``Get altitude from map`` button sets the photograph's altitude (in metres) from its latitude and longitude, using data from the map provider.
+Not all map providers have altitude data, and the accuracy varies quite a lot.
+You can edit the value to correct it.
 
 Map failures
 ------------
 
-.. image:: ../images/screenshot_140.png
+.. image:: ../images/screenshot_142.png
 
 Some map tabs might fail to load, showing the above error message instead.
 This could be because of problems with WebGL_, a sophisticated graphics system used in HTML 5.
 Some of the map providers use WebGL to draw their maps, so if WebGL, or some feature of it, is missing the map won't load.
 
 Problems with WebGL could be caused by having an incompatible graphics card or driver, or by the system configuration.
 Clicking on the link in the error message might provide some useful diagnostic information.
-You could also try using ``photini-configure`` to switch to a different Qt package.
+You could also try choosing a different Qt package in Photini's :doc:`configuration <configuration>`.
 
 GPX file import
 ---------------
@@ -108,20 +121,27 @@ If the file has a large number of points, closely positioned in space or time, t
 
 Selecting a photograph shows up to four track points in red.
 These are points with time stamps around the time the photograph was taken.
+The blue and red colours used can be changed in Photini's :doc:`configuration <configuration>`.
 
 .. image:: ../images/screenshot_223.png
 
 After zooming in on the red track points the photograph can be dragged to the map as usual.
 
 .. image:: ../images/screenshot_224.png
 
-Alternatively, the ``Set coords from GPX`` button can be used to set the latitude and longitude of all the selected photographs to the nearest (in time) GPX track point.
+Alternatively, the ``Set coords from GPX`` button can be used to set the latitude and longitude of the selected photograph to the nearest (in time) GPX track point.
 Note that this also sets the altitude if your GPX file has altitude data.
 This can be disabled in Photini's :doc:`configuration <configuration>`.
 
+.. image:: ../images/screenshot_225.png
+
+If multiple images are selected the ``Set coords from GPX`` button sets all their locations.
+
 The usefulness of GPX data depends on the accuracy of your GPS tracker, and on your camera's clock accuracy.
 You might want to adjust the timestamps in the :doc:`technical metadata <technical_metadata>` tab first.
 
+.. image:: ../images/screenshot_226.png
+
 When you've finished with the GPX track points they can be removed from the map with the ``Remove GPX data`` button.
 
 Altitude considerations