# QStarDict documentation

QStarDict is a dictionary application. It allows the user to install Kiwix and StarDict dictionaries and look up words from these dictionaries.

This guide is aimed to assist you in using QStarDict.

## Contents

- Starting QStarDict
- Running in background
- Starting with system
- Installing Kiwix dictionaries
- Installing StarDict dictionaries
- Looking up words
- Popup window

## Starting QStarDict

It is possible to start QStarDict either through the menu of the desktop environment in the "Education" section or using the command line by typing the command

`qstardict`

## Running in background

When QStarDict is started, it can be either in normal mode, when the main window is shown as here: or it can be started in background mode.

When QStarDict runs in background mode, it is displayed in the notification area:

The purpose of the background mode is to make it possible for QStarDict to scan selection in other applications and to show the popup window with dictionary articles. See the section on popup window for more details.

In order to make QStarDict able to run in background, the corresponding setting should be set on: By default it is on.

QStarDict remembers whether it was in normal or background mode on exit, and on a subsequent start it restores the state of being in background.

If you want QStarDict to be started in background, use the `--background` command line option by starting QStarDict as

`qstardict --background`

## Starting with system

It is possible to set up starting of QStarDict with system in common desktop environments. In order to enable starting of QStarDict with system, use the corresponding setting:

By default starting with system is off.

## Installing Kiwix dictionaries

Kiwix is a project which goal is to create offline versions of websites. The most prominent of these websites for using with QStarDict is Wiktionary.

In order to download offline versions of Wiktionary for languages you are interested in, visit Kiwix ZIM download page and select the "nopic" version of Wiktionary for the language you are interested in.

Note that the language specified in the filename is the target language, not a source language. Each language contains articles for words in all source languages, in the target language. For instance, if you want to look up words in Russian translated to English, you need to use the file with "en_all" language code.

Examples of filenames:

- "wiktionary_en_all_nopic_2023-07.zim" is a dictionary in English for all languages
- "wiktionary_ru_all_nopic_2023-09.zim" is a dictionary in Russian for all languages

Let us suppose that you have downloaded a file "wiktionary_en_all_nopic_2023-07.zim" to "~/Downloads" directory.

It can be installed from the "Dictionaries" tab of the Settings Dialog, which can be opened using "Settings" → "Configure QStarDict" menu in the main window:

In order to install a dictionary, press the "Add Dictionary" button, which is marked on the screenshot.

Doing it would result in opening a file dialog:

In the file dialog, select "Kiwix ZIM files" filter (marked on the screenshot) and then pick the ZIM file you want to add.

When the file is selected, an add dictionary dialog would appear:

It would prompt you to move the dictionary file to a QStarDict's directory.

It is also possible to not move, but create a symbolink link to the dictionary file. In order to do it, select "Symlink" in the combobox in the add dialog.

After importing the dictionary, it would appear at the top of the list of dictionaries in the settings dialog:

After pressing OK the added dictionary will be enabled and it will be possible to look up words from it.

## Installing StarDict dictionaries

QStarDict supports StarDict 2.x and StarDict 3.x dictionaries.

A StarDict dictionary consists of three files:

- ".ifo", a file containing metadata about the dictionary
- ".idx", an index file of the dictionary
- ".dict.dz", a file containing dictionary articles

It is possible to install a StarDict dictionary to QStarDict by opening the "Dictionaries" tab in the Settings Dialog, which can be opened using "Settings" → "Configure QStarDict" menu in the main window: In order to install a dictionary file to QStarDict, press the "Add Dictionary" button, which is marked on the screenshot.

Doing it would result in opening a file dialog:

In the file dialog, select "StarDict IFO files" filter (marked on the screenshot) and then pick the ".ifo" file of the dictionary you want to add.

Note that the `.idx` and `.dict.dz` files must be in the same directory as the `.ifo` file in order to allow the dictionary to be successfully imported.

After importing the dictionary, it would appear at the top of the list of dictionaries in the settings dialog:

After pressing OK the added dictionary will be enabled and it will be possible to look up words from it.

## Looking up words

It is possible to look up words in the main window of QStarDict. The words to be looked up can be typed into the text input. By default, the words are searched as soon as they are typed, but this behaviour can be turned off in the General tab of the settings dialog.

## Popup window

A popup window is a window that can be shown near words selected by mouse. Its behaviour can be configured in the "Popup window" tab of the settings dialog.