.. _buildesgui_intro:

Buildes GUI
===========

The buildes graphical user interface (gui) is an integrated design environment (IDE) program that can be used to create the :ref:`session_file`, process them and view the produced building information and knowledge. The following lists the parts of the gui.

- a query command-line area: use during the design session to obtain additional information from the building model
- a tree area: shows the relationship between building components.
- a text editor: use to describe parts of the building. Provides buildes and limited python syntax highlighting.
- a model view tab: shows an interactive 3D view of the building component shapes.
- a report view tab: displays reports for advanced queries or "what...if" scenarios (TODO).
- a message area: shows information on selected objects or output during processing of the session file.

Viewer Mode
-----------

In this mode the user can access the tree area, the model view, the message area and the report view. In this mode the user can visualize, browse and analyze the design. It is the default mode when the gui is started.

.. _buildesui_viewer_diagram:
.. figure:: ills/buildesui1.*
   :align: center
   :width: 600

   The gui as a viewer

IDE Mode
--------

In this mode the text area is made visible so that the user can work on the session file. Everything that is possible in the viewer is available in this mode including the ability to create building knowledge. The image shows the ability to highlight an object in the model view when selected in the tree view.

.. _buildesui_ide_diagram:
.. figure:: ills/buildesui2.*
   :align: center
   :width: 600

   The gui as an IDE

Query Line
----------

This is an entry line in the user interface in which the user can query the design. When a query is entered, the query result is provided both in the modelView and in the message area. The possible query options are:

     - **Length**: Measure the distance or length between any two points.
     - **Angle**: Measure the angle between two lines.

.. figure:: ills/queryLine.*
   :align: center
   :width: 569

   The gui query line and Message area view

To obtain information such as `length` or `distance` between two points or to get angular measurements, the GUI provides a command-line interface for entering queries. The following documents the available queries and their syntax::

   length(NAME1_SNAP, NAME2_SNAP)    # Length in mm and angle in degrees is
   		      		     #   calculated.
   distance(NAME1_SNAP, NAME2_SNAP)  # Does the same as length()
   angle(NAME1_SNAP, NAME2_SNAP, NAME3_SNAP)  # The angle between a line from
   		     		 	      #   NAME3_SNAP to NAME1_SNAP and
					      #   another line from NAME3_SNAP to
					      #   NAME2_SNAP is calculated.

.. _session_file:

Session File
============

The plain text file which buildes interprets to create building knowledge is called a *session* file. This section describes the structure of the session file and some fundamental issues concerning using it. Some additional information is also provided in the :ref:`tutorial` section. To see a full description of available commands to use in a session file, visit the :ref:`buildes_reference` section.

When talking about the session file we will refer to the two parts of buildes. The first part is called *buildes* which is the python library that is used to compile or process the session file to produce building information. The second part is the *gui* which is the graphical interface that is used to browse and inspect the complete building knowledge produced using the buildes library.

The user should make a directory for each project. A session file should be created in this directory with a name similar to `session_name.py`. The session file is a python module. A python module is a single computer file that has a name that typically ends with a `.py` extension. The name can be any valid file name for your OS however it is advisable not to include spaces in file names. In this section we will assume that your session file is called `session_name.py`. We shall also assume that the instructions in the :ref:`buildes_install` section were followed exactly.

The first line in the session file should be::

    from buildes import *

This directive makes it possible to use all the available commands in buildes. The next important directive is the identification of the designer. It is possible to go ahead to describe building parts without providing designer information but it is not possible to process the session file and capture any information for browsing in the GUI or exporting to another file format. To provide designer information the following directive must be provided::

     designer(name, phone, email=None, role=None, office=None)
     		    # The name and phone for the designer is required.

Finally the processed building information must be captured with the following directive. ::

	saveSession()  # captures the building knowledge and renders the shapes of all objects

This instructs buildes to save the compiled building information and knowledge to a file with the same name and location as the session file but with a `.bdkl` extension. So from the example above, issuing this command creates a file called `session_name.bdkl`. This is a binary file which can then be inspected using the gui. This directive should be the last line at the end of the session file. If this is not the case, the result of processing any descriptions after this command will not be included as part of the captured information

 This compile process begins when the session file is passed to the python program. One of the ways to do this is to use the menus in the gui but it is also possible to enter the following command at the command line:

.. code-block:: bash

   python session_name.py

If all goes well, and you provided the `saveSession()` directive, the buildes knowledge file is saved in a `session_name.bdkl` file in the same directory as your session file.