1 files changed, 173 insertions, 0 deletions
diff --git a/sources/pyside6/doc/tutorials/basictutorial/qrcfiles.rst b/sources/pyside6/doc/tutorials/basictutorial/qrcfiles.rst
new file mode 100644
index 000000000..858293beb
--- /dev/null
+++ b/sources/pyside6/doc/tutorials/basictutorial/qrcfiles.rst
@@ -0,0 +1,173 @@
+.. _using_qrc_files:
+
+Using ``.qrc`` Files (``pyside6-rcc``)
+**************************************
+
+The `Qt Resource System`_ is a mechanism for storing binary files
+in an application.
+
+The files will be embedded into the application and be acessible for the
+``QFile`` class and the constructors of the ``QIcon`` and ``QPixmap``
+classes taking a file name by using a special file name starting with ``:/``.
+
+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, you can download and use them.
+
+:download:`Download icons <icons.zip>`
+
+.. 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.
+
+
+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``
+
+::
+
+    <!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 ``pyside6-rcc`` tool to generate
+a Python class containing the binary information about the resources
+
+To do this, we need to run::
+
+    pyside6-rcc icons.qrc -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 PySide6.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 PySide6.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