doc: add tutorial for using qrc files

We currently have only a tutorial for .ui files,
and the .qrc case was missing.

Task-number: PYSIDE-841
Change-Id: Ic12e8e77cb1ee042bc118fab74c97b3f6ba54ff4
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>

11 files changed, 172 insertions, 2 deletions

diff --git a/sources/pyside2/doc/tutorials/basictutorial/icons.png b/sources/pyside2/doc/tutorials/basictutorial/icons.png
new file mode 100644
index 000000000..0bcfd7d77
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/basictutorial/icons.png
diff --git a/sources/pyside2/doc/tutorials/basictutorial/icons/forward.png b/sources/pyside2/doc/tutorials/basictutorial/icons/forward.png
new file mode 100644
index 000000000..c7a532dfe
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/basictutorial/icons/forward.png
diff --git a/sources/pyside2/doc/tutorials/basictutorial/icons/pause.png b/sources/pyside2/doc/tutorials/basictutorial/icons/pause.png
new file mode 100644
index 000000000..d0beadb43
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/basictutorial/icons/pause.png
diff --git a/sources/pyside2/doc/tutorials/basictutorial/icons/play.png b/sources/pyside2/doc/tutorials/basictutorial/icons/play.png
new file mode 100644
index 000000000..345685337
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/basictutorial/icons/play.png
diff --git a/sources/pyside2/doc/tutorials/basictutorial/icons/previous.png b/sources/pyside2/doc/tutorials/basictutorial/icons/previous.png
new file mode 100644
index 000000000..979f18565
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/basictutorial/icons/previous.png
diff --git a/sources/pyside2/doc/tutorials/basictutorial/icons/stop.png b/sources/pyside2/doc/tutorials/basictutorial/icons/stop.png
new file mode 100644
index 000000000..1e88ded3a
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/basictutorial/icons/stop.png
diff --git a/sources/pyside2/doc/tutorials/basictutorial/player-new.png b/sources/pyside2/doc/tutorials/basictutorial/player-new.png
new file mode 100644
index 000000000..e1f660e5f
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/basictutorial/player-new.png
diff --git a/sources/pyside2/doc/tutorials/basictutorial/player.png b/sources/pyside2/doc/tutorials/basictutorial/player.png
new file mode 100644
index 000000000..3060a990d
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/basictutorial/player.png
diff --git a/sources/pyside2/doc/tutorials/basictutorial/qrcfiles.rst b/sources/pyside2/doc/tutorials/basictutorial/qrcfiles.rst
new file mode 100644
index 000000000..2f986875c
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/basictutorial/qrcfiles.rst
@@ -0,0 +1,169 @@
+Using `.qrc` Files (`pyside2-rcc`)
+**********************************
+
+The `Qt Resource System`_ is a mechanism for storing binary files
+in an application.
+
+The most common uses are for custom images, icons, fonts, among others.
+
+In this tutorial you will learn how to load custom images as button icons.
+
+For inspiration, we will try to adapt the multimedia player example
+from Qt.
+
+As you can see on the following image, the `QPushButton` that are used
+for the media actions (play, pause, stop, and so on) are using the
+default icons meant for such actions.
+
+.. image:: player.png
+   :alt: Multimedia Player Qt Example
+
+You could make the application more attractive by designing the icons,
+but in case you don't want to design them, `download the following set`_
+and use them.
+
+.. image:: icons.png
+   :alt: New Multimedia icons
+
+You can find more information about the `rcc` command, and `.qrc` file
+format, and the resource system in general in the `Qt Resource System`_
+site.
+
+.. _`download the following set`: icons/
+
+
+The `.qrc` file
+================
+
+Before running any command, add information about the resources to a `.qrc`
+file.
+In the following example, notice how the resources are listed in `icons.qrc`
+
+::
+
+    </ui>
+    <!DOCTYPE RCC><RCC version="1.0">
+    <qresource>
+        <file>icons/play.png</file>
+        <file>icons/pause.png</file>
+        <file>icons/stop.png</file>
+        <file>icons/previous.png</file>
+        <file>icons/forward.png</file>
+    </qresource>
+    </RCC>
+
+
+Generating a Python file
+=========================
+
+Now that the `icons.qrc` file is ready, use the `pyside2-rcc` tool to generate
+a Python class containing the binary information about the resources
+
+To do this, we need to run::
+
+    pyside2-rcc icons.rc -o rc_icons.py
+
+The `-o` option lets you specify the output filename,
+which is `rc_icons.py` in this case.
+
+To use the generated file, add the following import at the top of your main Python file::
+
+    import rc_icons
+
+
+Changes in the code
+===================
+
+As you are modifying an existing example, you need to modify the following
+lines:
+
+.. code-block:: python
+
+    from PySide2.QtGui import QIcon, QKeySequence
+    playIcon = self.style().standardIcon(QStyle.SP_MediaPlay)
+    previousIcon = self.style().standardIcon(QStyle.SP_MediaSkipBackward)
+    pauseIcon = self.style().standardIcon(QStyle.SP_MediaPause)
+    nextIcon = self.style().standardIcon(QStyle.SP_MediaSkipForward)
+    stopIcon = self.style().standardIcon(QStyle.SP_MediaStop)
+
+and replace them with the following:
+
+.. code-block:: python
+
+    from PySide2.QtGui import QIcon, QKeySequence, QPixmap
+    playIcon = QIcon(QPixmap(":/icons/play.png"))
+    previousIcon = QIcon(QPixmap(":/icons/previous.png"))
+    pauseIcon = QIcon(QPixmap(":/icons/pause.png"))
+    nextIcon = QIcon(QPixmap(":/icons/forward.png"))
+    stopIcon = QIcon(QPixmap(":/icons/stop.png"))
+
+This ensures that the new icons are used instead of the default ones provided
+by the application theme.
+Notice that the lines are not consecutive, but are in different parts
+of the file.
+
+After all your imports, add the following
+
+.. code-block:: python
+
+    import rc_icons
+
+Now, the constructor of your class should look like this:
+
+.. code-block:: python
+
+    def __init__(self):
+        super(MainWindow, self).__init__()
+
+        self.playlist = QMediaPlaylist()
+        self.player = QMediaPlayer()
+
+        toolBar = QToolBar()
+        self.addToolBar(toolBar)
+
+        fileMenu = self.menuBar().addMenu("&File")
+        openAction = QAction(QIcon.fromTheme("document-open"),
+                             "&Open...", self, shortcut=QKeySequence.Open,
+                             triggered=self.open)
+        fileMenu.addAction(openAction)
+        exitAction = QAction(QIcon.fromTheme("application-exit"), "E&xit",
+                             self, shortcut="Ctrl+Q", triggered=self.close)
+        fileMenu.addAction(exitAction)
+
+        playMenu = self.menuBar().addMenu("&Play")
+        playIcon = QIcon(QPixmap(":/icons/play.png"))
+        self.playAction = toolBar.addAction(playIcon, "Play")
+        self.playAction.triggered.connect(self.player.play)
+        playMenu.addAction(self.playAction)
+
+        previousIcon = QIcon(QPixmap(":/icons/previous.png"))
+        self.previousAction = toolBar.addAction(previousIcon, "Previous")
+        self.previousAction.triggered.connect(self.previousClicked)
+        playMenu.addAction(self.previousAction)
+
+        pauseIcon = QIcon(QPixmap(":/icons/pause.png"))
+        self.pauseAction = toolBar.addAction(pauseIcon, "Pause")
+        self.pauseAction.triggered.connect(self.player.pause)
+        playMenu.addAction(self.pauseAction)
+
+        nextIcon = QIcon(QPixmap(":/icons/forward.png"))
+        self.nextAction = toolBar.addAction(nextIcon, "Next")
+        self.nextAction.triggered.connect(self.playlist.next)
+        playMenu.addAction(self.nextAction)
+
+        stopIcon = QIcon(QPixmap(":/icons/stop.png"))
+        self.stopAction = toolBar.addAction(stopIcon, "Stop")
+        self.stopAction.triggered.connect(self.player.stop)
+        playMenu.addAction(self.stopAction)
+
+        # many lines were omitted
+
+Executing the example
+=====================
+
+Run the application by calling `python main.py` to checkout the new icon-set:
+
+.. image:: player-new.png
+   :alt: New Multimedia Player Qt Example
+
+.. _`Qt Resource System`: https://doc.qt.io/qt-5/resources.html
diff --git a/sources/pyside2/doc/tutorials/basictutorial/uifiles.rst b/sources/pyside2/doc/tutorials/basictutorial/uifiles.rst
index 2c0178e2e..2a0d65e46 100644
--- a/sources/pyside2/doc/tutorials/basictutorial/uifiles.rst
+++ b/sources/pyside2/doc/tutorials/basictutorial/uifiles.rst
@@ -1,5 +1,5 @@
-Using UI Files
-***************
+Using `.ui` Files (`QUiLoader` and `pyside2-uic`)
+*************************************************
 
 This page describes the use of Qt Creator to create graphical
 interfaces for your Qt for Python project.
diff --git a/sources/pyside2/doc/tutorials/index.rst b/sources/pyside2/doc/tutorials/index.rst
index 73e6b6b26..598b42ca1 100644
--- a/sources/pyside2/doc/tutorials/index.rst
+++ b/sources/pyside2/doc/tutorials/index.rst
@@ -18,6 +18,7 @@ Basic tutorials
     basictutorial/clickablebutton.rst
     basictutorial/dialog.rst
     basictutorial/uifiles.rst
+    basictutorial/qrcfiles.rst
 
 Real use-cases applications
 ---------------------------