# `taurus.qt.qtgui.taurusgui`

This package provides TaurusGui, a generic framework for creating GUIs without actual coding (just configuration files).

See the examples provided in the conf subdirectory directory as well as the documentation of the `TaurusGui` class.

## The “new GUI wizard” and XML configuration files

Note that the configuration files can either be written by hand or by launching the “new GUI” wizard with taurus newgui, which will create a new directory containing configuration, resource and launcher files.

The new GUI wizard stores all the options in xml format in a file called config.xml and creates a simple config.py file containing the following line:

    XML_CONFIG = 'config.xml'

This line indicates that config.xml should also be used as a source of configuration options (in case of conflict, the options set in config.py prevail).

Classes

class AppSettingsWizard(parent=None, jdrawCommand='jdraw', configFilePrefix='config')

  This Wizard provide functionality for creating from scratch a configuration directory for a TaurusGUI based application.

  The files in the configuration dir determine the default, permanent, pre-defined contents of the GUI. While the user may add/remove more elements at run time and those customizations will also be stored, this file defines what a user will find when launching the GUI for the first time.

  (more info)

class DockWidgetPanel(parent, widget, name, mainwindow)

  This is an extended QDockWidget which provides some methods for being used as a “panel” of a TaurusGui application. Widgets of TaurusGui are inserted in the application by adding them to a DockWidgetPanel.

  (more info)

class ExternalAppEditor(parent=None)

  A dialog for configuring an external appaction for a TaurusMainWindow.

  (more info)

class PanelDescriptionWizard(parent=None, designMode=False, gui=None, extraWidgets=None)

  A wizard-style dialog for configuring a new TaurusGui panel. Use `getDialog()` for launching it

  (more info)

class TaurusGui(parent=None, confname=None, configRecursionDepth=None, settingsname=None)

  This is main class for constructing the dynamic GUIs. TaurusGui is a specialised TaurusMainWindow which is able to handle “panels” and load configuration files. There are several ways of using TaurusGui. In the following we will give 3 examples on how to create a simple GUI called “MyGui” which contains one panel called “Foo” and consisting of a QWidget:

  Example 1: use declarative configuration files.

  You can create a purely declarative configuration file to be interpreted by the standard taurusgui script:

      from taurus.qt.qtgui.taurusgui.utils import PanelDescription

      GUI_NAME = 'MyGui'
      panel = PanelDescription('Foo',
                               classname='taurus.external.qt.Qt.QWidget')

  Note that this just a very simple example. For a much richer one, see the `taurus.qt.qtgui.taurusgui.conf.tgconf_example01`

  Example 2: do everything programmatically.

  A stand-alone python script that launches the gui when executed. No configuration file is used here. Panels and other components are added programatically:

      if __name__ == '__main__':
          from taurus.qt.qtgui.application import TaurusApplication
          from taurus.qt.qtgui.taurusgui import TaurusGui
          from taurus.external.qt import Qt
          app = TaurusApplication(cmd_line_parser=None, app_name='MyGui')
          gui = TaurusGui()
          panel = Qt.QWidget()
          gui.createPanel(panel, 'Foo')
          gui.show()
          app.exec_()

  Example 3: mixing declarative and programmatic ways

  It is also possible to create a stand-alone python script which loads itself as a configuration file. In this way you can add things programmatically and at the same time use the declarative way:

      GUI_NAME = 'MyGui' # <-- declarative!
      if __name__ == '__main__':
          from taurus.qt.qtgui.application import TaurusApplication
          from taurus.qt.qtgui.taurusgui import TaurusGui
          from taurus.external.qt import Qt
          app = TaurusApplication(cmd_line_parser=None)
          gui = TaurusGui(confname=__file__)
          panel = Qt.QWidget()
          gui.createPanel(panel, 'Foo')  # <-- programmatic!
          gui.show()
          app.exec_()

  (more info)