From 89f5b036809e8c92d1ce5845417b644064953507 Mon Sep 17 00:00:00 2001 From: Cristian Maureira-Fredes Date: Sat, 16 May 2020 02:42:41 +0200 Subject: 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 --- .../pyside2/doc/tutorials/basictutorial/icons.png | Bin 0 -> 3202 bytes .../doc/tutorials/basictutorial/icons/forward.png | Bin 0 -> 1113 bytes .../doc/tutorials/basictutorial/icons/pause.png | Bin 0 -> 1001 bytes .../doc/tutorials/basictutorial/icons/play.png | Bin 0 -> 970 bytes .../doc/tutorials/basictutorial/icons/previous.png | Bin 0 -> 1050 bytes .../doc/tutorials/basictutorial/icons/stop.png | Bin 0 -> 1064 bytes .../doc/tutorials/basictutorial/player-new.png | Bin 0 -> 7818 bytes .../pyside2/doc/tutorials/basictutorial/player.png | Bin 0 -> 5835 bytes .../doc/tutorials/basictutorial/qrcfiles.rst | 169 +++++++++++++++++++++ .../doc/tutorials/basictutorial/uifiles.rst | 4 +- sources/pyside2/doc/tutorials/index.rst | 1 + 11 files changed, 172 insertions(+), 2 deletions(-) create mode 100644 sources/pyside2/doc/tutorials/basictutorial/icons.png create mode 100644 sources/pyside2/doc/tutorials/basictutorial/icons/forward.png create mode 100644 sources/pyside2/doc/tutorials/basictutorial/icons/pause.png create mode 100644 sources/pyside2/doc/tutorials/basictutorial/icons/play.png create mode 100644 sources/pyside2/doc/tutorials/basictutorial/icons/previous.png create mode 100644 sources/pyside2/doc/tutorials/basictutorial/icons/stop.png create mode 100644 sources/pyside2/doc/tutorials/basictutorial/player-new.png create mode 100644 sources/pyside2/doc/tutorials/basictutorial/player.png create mode 100644 sources/pyside2/doc/tutorials/basictutorial/qrcfiles.rst 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 Binary files /dev/null and b/sources/pyside2/doc/tutorials/basictutorial/icons.png differ 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 Binary files /dev/null and b/sources/pyside2/doc/tutorials/basictutorial/icons/forward.png differ 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 Binary files /dev/null and b/sources/pyside2/doc/tutorials/basictutorial/icons/pause.png differ 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 Binary files /dev/null and b/sources/pyside2/doc/tutorials/basictutorial/icons/play.png differ 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 Binary files /dev/null and b/sources/pyside2/doc/tutorials/basictutorial/icons/previous.png differ 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 Binary files /dev/null and b/sources/pyside2/doc/tutorials/basictutorial/icons/stop.png differ 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 Binary files /dev/null and b/sources/pyside2/doc/tutorials/basictutorial/player-new.png differ 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 Binary files /dev/null and b/sources/pyside2/doc/tutorials/basictutorial/player.png differ 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` + +:: + + + + + icons/play.png + icons/pause.png + icons/stop.png + icons/previous.png + icons/forward.png + + + + +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 --------------------------- -- cgit v1.2.3