Commit 41db0d8e authored by David Boddie's avatar David Boddie 💬
Browse files

Start documenting the pictures example

parent 000ed2ac
......@@ -19,3 +19,6 @@
[submodule "Apps/Examples/General/Treasure/app"]
path = Apps/Examples/General/Treasure/app
url = https://source.puri.sm/librem5-examples/treasure.git
[submodule "Apps/Examples/Files/Pictures/app"]
path = Apps/Examples/Files/Pictures/app
url = https://source.puri.sm/Librem5/example-apps/pictures.git
.. |executable| replace:: ``pictures``
.. |desktop-entry-ref| replace:: desktop entry file
.. include:: /Apps/Examples/common/Building_the_App.txt
.. |project| replace:: https://source.puri.sm/Librem5/example-apps
.. |repo| replace:: pictures.git
.. |project-repo| replace:: ``https://source.puri.sm/Librem5/example-apps/pictures.git``
.. include:: /Apps/Examples/common/Getting_the_App.txt
.. |manifest| replace:: ``com.example.pictures.json``
.. |manifest-path| replace:: app/com.example.pictures.json
.. |app-id| replace:: com.example.pictures
.. include:: ../../common/Packaging_the_App.txt
.. _Files_Pictures_example_src:
Source Files
============
.. contents::
:local:
The main source code for the application can be found in the ``main.py`` file within the ``src`` directory. The purpose of the other files is explained in other tutorials, such as the :ref:`First_Application` tutorial.
The Program
-----------
Most the code for the application is included in a single ``main.py`` file which contains a single ``Application`` class to manage the running of the application and a ``main`` function to start it.
Much of the is very similar to other examples and tutorials. We will focus on the parts that are specific to this example.
Relevant Modules
~~~~~~~~~~~~~~~~
Besides standard Python modules such as ``os`` and ``sys``, the ``Handy`` module helps us to create adaptive user interfaces. This module is imported in the same way as the ``Gtk`` module:
.. literalinclude:: app/src/main.py
:language: python3
:start-at: import os
:end-at: Pages
The ``widgets`` module contains a helper class that we won't cover in any detail.
Application Class
~~~~~~~~~~~~~~~~~
The ``Application`` class provides the usual methods to set up the application
and perform tasks when it is run.
In the ``do_startup`` method we define two parameters for the thumbnail dimensions:
.. literalinclude:: app/src/main.py
:language: python3
:start-at: do_startup
:end-at: thumbnail_height
These are hard-coded in this example, but more complex applications would load these values from the application's settings.
In the ``do_activate`` method we set up the user interface, using a helper class to set up an adaptive user interface consisting of two leaflets: one in the window's header bar; the other in the main area of the window:
.. literalinclude:: app/src/main.py
:language: python3
:start-at: do_activate
:end-at: show_all
The leaflet in the main area holds two pages: one with a list of thumbnails; the other with a simple image viewer. The ``do_activate`` method also calls the ``load_thumbnails`` method to load thumbnails for the images. This is described later.
Summary
-------
You can access files in specific directories in the user's home directory by calling the ``GLib.get_user_special_dir`` function to obtain the file paths you require. The directory you want to access is specified using a value from the ``GLib.UserDirectory`` enum.
In this case we use ``DIRECTORY_PICTURES`` to access the user's pictures directory and load images using the ``GdkPixbuf.Pixbuf`` class.
.. include:: /links.txt
.. _examples_Files_Pictures:
Pictures
========
This example shows how to read image files from one of the user's directories and display their contents. When run, the application shows thumbnails of the images in a scrolling list. When a thumbnail is selected, a larger version of the images is displayed.
.. image:: images/screenshot.png
:scale: 50%
:align: center
:alt: A screenshot of the application running in the phone environment
We will focus on the parts of the application that are related to reading the image files and displaying their contents.
.. toctree::
:maxdepth: 1
Getting_the_App
Source_Code
Building_the_App
Packaging_the_App
.. include:: /links.txt
......@@ -19,7 +19,8 @@ development tools and libraries.
.. toctree::
:maxdepth: 1
General/Treasure/index
Networking/NetworkState/index
Files/Pictures/index
General/Treasure/index
.. include:: /links.txt
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment