Skip to content

Developer information

Jump to bottom
Wouter Wijsman edited this page Sep 5, 2021 · 25 revisions

Table of contents

Tools

Minigalaxy has been created using the following tools:

Setting up a development environment

Setting up a development environment can simply be done by first installing the following software:

  • python3
  • python3-gi
  • python3-requests
  • webkit2gtk
  • glade
  • git

After having done so, the git repo can be cloned and the application started with:

git clone https://github.com/sharkwouter/minigalaxy.git
cd minigalaxy
scripts/compile-translations.sh
bin/minigalaxy

It is also possible to use a VENV with the following set of commands:

git clone https://github.com/sharkwouter/minigalaxy.git
cd minigalaxy
scripts/compile-translations.sh
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
bin/minigalaxy

Project structure

  • bin: contains the minigalaxy launch script
  • data: contains the ui files and other non-python files like translations, images and configuration files
    • mo: contains compiled translation
    • po: contains translation files
    • ui: contains the Glade files which contain the interface of Minigalaxy
  • debian: contains the Debian/Ubuntu packaging specific files. Here is some good documentation on what each file does.
  • minigalaxy: contains the source code, the python files in this directory contain code which doesn't draw GTK items like windows and buttons
    • ui: contains the source code for all GTK items like windows and buttons
  • tests: contains unit tests for the project
  • scripts: contains some scripts for managing translations and creating screenshots for the README

Glade usage

Glade is used to create GTK interfaces for Minigalaxy whenever possible. The Glade files all have the following in common:

  • The top level GTK item, usually the window, has the composite option enabled. This makes us able to use them as the base for a class.
  • The top level GTK item is named with CamelCase.
  • All text is in English.
  • All strings set within Glade are translatable.
  • Signals for buttons and other widgets are added from within Glade.

Glade files are loaded as the base for a class with the following line before the class definition:

@Gtk.Template.from_file(os.path.join(UI_DIR, "file.ui"))

Within the class the __gtype_name__ has to match the name of the top level GTK item. Other items are imported using widget_name_in_glade = Gtk.Template.Child().

Making strings translatable

Minigalaxy supports translations to multiple different languages. The default language is English. To allow for translations to work, strings will need to be set in a particular way depending on where they are located.

Glade

Strings in Glade are translatable by default. Please do set a comment for translators to give them a little bit of context as to where the string is used and what it is used for.

Python

In python for a string to be translatable, first makes sure the following import can be found in the file you're working in:

from minigalaxy.translation import _

Then you can simply make your strings translatable by changing your string definition from the following format "your string" to _("your string").

When using format on translatable strings, do so like _("your string {}").format(variable). Using format within the brackets makes the translation unable to load.

Adding your strings to the translation files

After you've defined translatable strings, you'll still need to add them to the translation file. This can simply be done by running the scripts/update-translation-files.sh script.

Adding an option to the settings menu

Adding an additional option to the settings menu is relatively simple, but requires changes to multiple files. Here is a list of actions which need to be performed and where to add one.

  1. First you come up with a name for the setting and add it to the default configuration. This can be done by adding it to the DEFAULT_CONFIGURATION dictionary in minigalaxy/constants.py. Settings in the default configuration which aren't in the user's configuration yet are added automatically.
  2. Add a widget which is used to set the setting to the preferences menu. For this open the data/ui/preferences.ui files with Glade. Make sure to add a label and to give the widget for changing the setting (for instance an entry, switch or combobox) an ID.
  3. Add the widget to the minigalaxy/ui/preferences.py under the Preferences class. For this you need to have the ID of your widget. It can be added like the other widgets already there: widget_id = Gtk.Template.Child(). Replace widget_id with the ID.
  4. Set the state of the widget when the preferences menu is opened. This can be done in the minigalaxy/ui/preferences.py file in the __init__ method. If your option is a boolean (True or False), you can simply add something like this: self.widget_id.set_active(Config.get("your_setting_name")). Do replace your_setting_name and widget_id with the correct values.
  5. Save the setting when pressing save in the preferences menu. This can be done in the save_pressed method in minigalaxy/ui/preferences.py. If your setting is a boolean, you can simply add something like this: Config.set("your_setting_name", self.widget_id.get_active()). Do replace your_setting_name and widget_id with the correct values.
  6. Make your setting do something. The value a setting is set to can be loaded in any python code in Minigalaxy in which the Config object has been imported. The following code will return the value of the setting: Config.get("your_setting_name"). Make sure to replace your_setting_name here and save what is returned to a variable.

Good luck! If you need any help, just hop on Discord and ask.

Problems with the code

Generally the Minigalaxy code is pretty clean, but there are some problem areas which will likely require fixing in the future. If you find any issues with the code please let us know by reporting an issue on this repo.

Clone this wiki locally