# GenerateDS GUI Notes

Author: | Dave Kuhlman
Contact: | dkuhlman (at) davekuhlman (dot) org
Address: |
    http://www.davekuhlman.org

revision: | 2.35.20

date: | April 21, 2020

copyright: | Copyright (c) 2016 Dave Kuhlman. This documentation and the software it describes is covered by The MIT License: http://www.opensource.org/licenses/mit-license.php.
abstract: | This document describes generateds_ui.py, the graphical front end to generateDS.py.

Contents

# 1 Introduction

`generateds_gui.py` provides a graphical front end for `generateDS.py`. Some may find it easier to configure and to select and set options for `generateDS.py` using this graphical application.

# 2 Requirements

You will need Gtk support for Python in order to run `generateds_gui.py`.

You must run `generateds_gui.py` under Python 3. Python 2 is not supported.

Note that you can use the "--session" command line flag supported by `generateDS.py` on a machine that does not have Python Gtk support installed.

# 3 Usage notes

## 3.1 What it does

Here are some of the different ways that you can use `generateds_gui.py`:

1. You can generate modules from within `generateds_gui.py` using the "Generate" item in the "Tools" menu.
2. You can produce and view a command line that reflects your configuration using the "Generate CL" item in the "Tools" menu, and then you can copy and paste the resulting command line into a `bash` script (for Linux) or a `.bat` file (for MS Windows), which you can then run from the command line.
3. You can run the session file that you've saved with the "--session" command line flag supported by `generateDS.py`.
4. You can load a previously saved session file into `generateds_gui.py` using the "--session" command line option, and then modify that session and/or use it to generate modules, or to generate a command line.

## 3.2 How to use it

You can get some help by running the following:

    $ ./generateds_gui.py --help

Command line options and arguments:

    Usage:
    python generateds_gui.py [options] --session=<some_session_file.session>
    example:
            python generateds_gui.py --session=generator01.session
    Options:
      -h, --help            show this help message and exit
      --exec-path=EXEC_PATH
                                                    path to executable generated in command line.
                                                    Example: "python /path/to/generateDS.py".  Default:
                                                    "./generateDS.py".  Use Tools/Generate CL (Ctrl-T) to
                                                    see it.
      --impl-gui=IMPL_GUI   name of glade file that defines the GUI if not
                                                    embedded.
      -s SESSION, --session=SESSION
                                                    name of a session file to be loaded.

exec-path
  If your copy of `generateDS.py` is in a special location, you can specify that location using this option. The version of `generateDS.py` at that location will be run when you select the "Generate" item from the "Tools" menu.
impl-gui
  The file `generateds_gui.glade` specifies and describes the user interface. This file has been embedded into `generateds_gui.py`. If you modify `generateds_gui.glade` and want to use that modified version, specify it with this option.
s, session
  If you have created and saved a session file using `generateds_gui.py` and want to load that file the next time you run `generateds_gui.py`, use this option. Alternatively, once `generateds_gui.py` has been started, you can use the "Load session" item under the "File" menu.

# 4 Internationalization

Note: This work on internationalization for generateds_gui is experimental and does not yet work.

## 4.1 Preparation

Here is what I've done:

    $ cd generateds/gui/
    $ mkdir po
    # Create the template file.
    $ xgettext -k_ -kN_ -o po/generateds_gui.pot generateds_gui.glade
    # Create a file for the translator.  This one is for the Russian language.
    $ msginit --locale=ru --input=generateds_gui.pot

And, after someone has added their translations (for example, to `ru.po`), we translate it to binary with the following command:

    $ msgfmt -o generateds_gui.mo ru.po

Finally, move the binary file to the appropriate directory under the directory containing the executable (`generateds_gui.py`). See Installation and setup.

## 4.2 Installation and setup

Now we have to move the `.mo` file where it will be used when we run `generateds_gui.py`. We place it in a sub-directory under the location of `generateds_gui.py` itself.

    $ cd /directory/containing/generateds_gui.py
    $ mkdir locale
    $ mkdir locale/ru
    $ mkdir locale/ru/LC_MESSAGES
    $ mv generateds_gui.mo locale/ru/LC_MESSAGES/

## 4.3 Additional information

Here are some helpful references:

- https://en.wikipedia.org/wiki/Gettext
- http://faq.pygtk.org/index.py?req=show&file=faq22.002.htp
- http://www.servin.com/linux/GladeInternationalization.html
- http://www.learningpython.com/2006/12/03/translating-your-pythonpygtk-application/