Spec:GUI

This document describes the technical requirements for a GridLAB-D Graphical User Interface.

= GUI HTML Encoding =

The simplest GUI can be encoded directly in HTML and loaded by the GridLAB-D model using the following syntax:

gui { source file.html; }

The HTML file may contain any HTML code desired. In addition, it may use Javascript script code load from the support file rt/gridlabd.js to perform API calls to the core.

Wait operations
A GUI block may halt the load process by including a wait entity, as follows:

gui { source file.html; wait action; }

When a wait entity is encountered, the GUI load stops to the GLM load process and turns over control to the GUI. When the GUI action specified is sent by the GUI, such as after a button is pressed, the loader continues loading the GLM file.

= GUI Generation Principles =

A GridLAB-D GUI is generated automatically by GridLAB-D when a GUI block is present in the GLM file. GUIs are collections of GUI entities that link the user to various parts of the GridLAB-D system. The entities include
 * Text entities that can be either constant or linked to GridLAB-D objects, variables, or properties;
 * Input entities that are linked to GridLAB-D object properties or variables;
 * Action entities that control the state of GridLAB-D; and
 * Graphical entities derived from GridLAB-D outputs.

Layout Rules
GUI objects are places on the screen in columns and rows. Normally, each entity is placed the column that corresponds to its position relative to the left side of the current block. Thus the second item in the second row will be placed below the second item in the first row. The exception to this rule is the  group, which suppressed this behavior for its members.

Entity Linkage
Each entity, if suitable, may be linked to an appropriate property, variable or output in GridLAB-D. In general the association rules are as follows:

1 Custom entities are property specific (e.g., calendar, clock, slider, 2D input). 2 Includes the auxiliary [...] button 3 Only CSV output files from recorders, collectors, and histograms can be graphed. 4 Includes automatic unit conversion for both read and write operations.

= GUI Definition Syntax =

The layout of the GUI presentment and linkage of the GUI entities to the GridLAB-D model objects is defined in the GLM file (see GUI_FR).

The syntactical structure of the GLM GUI block shall be

gui_block : "gui" { gui_list } gui_list : entity_block gui_list gui_list : parameter_value gui_list gui_list : entity_block : entity { gui_list } parameter_value : parameter value ; entity : "tab" entity : "group" entity : "table" entity : "span" entity : "text" entity : "input" entity : "checkbox" entity : "radio" entity : "select" entity : "datetime" entity : "graph" entity : "start" entity : "stop" entity : "pause" entity : "reset" entity : "quit" entity : "open" entity : "save" entity : "saveas" entity : "export" parameter : "link" parameter : "value" parameter : "lines" parameter : "password" parameter : "disabled" parameter : "multiple" parameter : "default" parameter : "member" parameter : "choices" parameter : "x" parameter : "y" parameter : "width" parameter : "height" parameter : "color" parameter : "size" parameter : "font" parameter : "style" parameter : "unit" value : object_name "." property_name value : global_varname value : module_name ":" varname value : environment_varname value : set value : enumeration value : real value : integer value : boolean value : string

Common attributes
All entities recognize the following attributes:
 * x - specifies the horizontal position in pixels (for integers) or fraction of the block (for values between 0 and 1) as measured from the left of the block.
 * y - specifies the vertical position in pixels (for integers) or fraction of the block (for values between 0 and 1) as measured from the top of the block.
 * width - specifies the width in pixels (for integers) or fraction of the block (for values between 0 and 1).
 * height - specifies the height in pixels (for integers) or fraction of the block (for values between 0 and 1).
 * color - specifies the color of the entity text as a color name or a hexadecimal rgb code.
 * size - specifies the size of the entity text as a size name or a pixel height.
 * font - specifies the font of the entity text as a font family name.
 * style - specifies the font style of the entity as a style set (e.g., bold, italic, underline)

Common entities

 * tab : A tab block is used to create a tabbed grouping of entities. Recognized parameters are:
 * value - specifies the text to be displayed on the tab


 * group : A group block is used to create a visible grouping of entities using a box. Recognized parameters are:
 * value - specifies the text to be displayed in the upper left corner of the box.


 * table : A table is created to display data in a file. Recognized parameters are:
 * link - specifies the source of the data.
 * columns - specifies the number of columns of data to display.
 * rows - specifies the number of rows of data to display.

The following entities may be used in any block.


 * text : Creates a text entity on the screen. Text entities recognized the following attributes:
 * lines - specifies how many lines of text are displayed.


 * input : Creates a text input entity on the screen. The input entity must be linked to a string or number property.  If the linked property is a number property, the input shall be constrained to match the property.  Supported property shall include integers (8,16,32,64 bit), doubles and complex numbers.  When the property has units associated with it, the property shall be displayed in those units by default, or use the units provided by the unit attribute.  If the user enters a unit, the input shall be converted accordingly, if possible. Loadshapes and enduses shall be considered strings.  Input entities recognized the following attributes:
 * lines - specifies how many lines of text are displayed.
 * password - specifies that the text should be obfuscated.
 * disabled - specifies that the text should be read only.
 * unit - specifies the units in which to display numbers.


 * select : Creates a selection input. The select must be linked to a property that is a set, an enumeration, or an object reference so that the choices can be automatically presented.  The select entity recognizes the following attributes:
 * lines - specifies the number of select items to show.
 * drop - specifies whether a drop list is used


 * check : Creates a checkbox input. If member is omitted, the link must refer to a boolean property.  If member is included, it must match a member of the set property that link refers to.  The attribute value provides the text label to be placed adjacent to the checkbox.  Check entities support the following attributes:
 * member - specifies which member of the set the check box is linked to.


 * radio : Creates a radio button input. The link must refer to an enumeration property. The value of member must match a member of the enumeration that the link refers to.  The value provides the text label to be placed adjacent to the radio button. Radio entities support the following attributes
 * member - specifies which member of the enumeration the radio is linked to.


 * datetime : Create a date entry field. The link must refer to a TIMESTAMP property.


 * graph : Creates a graph entity. The link must refer to a CSV data file, most often one generated by GridLAB-D during the run.  Graph entities support the following attributes:
 * package - specifies the plotting package to use (e.g., gnuplot)
 * command - specifies the plotting command string to send to the package.
 * refresh - specifies the plotting refresh delay in seconds (default is to wait until done).


 * file : Create a filename entity. The link must refer to a string.  A "..." button will placed adjacent to the field, which when clicked open the standard file dialog.

Action entities
The following entities create action buttons.


 * start : Creates a button which when clicked starts the simulation. This entity shall be disabled when the simulation is already running.


 * pause : Creates a button which when clicked pauses the simulation. This entity shall be disabled when the simulation isn't running.


 * stop : Creates a button which when clicked stops the simulation. This entity shall be disabled when the simulation isn't running.  A stop action shall require confirmation.


 * reset : Creates a button which when clicked reset the simulation. This entity shall be disabled when the simulation hasn't started.  A reset action shall require confirmation.


 * quit : Creates a button which when clicked exit the GUI. This action shall require confirmation when the current session is not saved.


 * open : Creates a button which when clicked open a file dialog and loads the selected GLM, XML, or GLD file. This action shall require confirmation when the current session is not saved.


 * save : Creates a button which when clicked saves the current session as a GLD file.


 * saveas : Creates a button which when clicked open a file dialog and saves the current session to the specified GLD file.


 * export : Creates a button which when clicked opens a file dialog and saves the current session to the specified GLM or XML file.

= Implementation approach =

The GUI API is an integral part of the core. The following coding elements are required

load.c
A new top level loader block is added to support parsing gui block. This includes all the subordinate GUI blocks.

gui.h
The gui entity structure is defined. It allows GUI entities to be organized in a hierarchy (parent-child) or linked lists that mirrors the representation in the GLM file.

gui.c
The GUI module itself contains GUI entity creation, management and generation code.

server.c
The server code is extended to allow linkage commands from the GUI module. The linkages include
 * reading a variable or property;
 * writing a variable or property; and
 * initiating an action.

graph.c
The current version of GridLAB-D (2.1) supports graphing using only gnuplot. However, for web-based GUIs, jpgraph will be supported as well.

= Examples =

. The following GLM file generates the page shown in Figure 1.

gui { title link :modelname; group { title link House1:name; row { // first row text value "Floor area:"; input { link House1:floorarea; unit "sf"; }		}		row { // second row text value "Floor area:"; check link House1:system_type; }		row { // third row text value "System mode: "; check link House1:system_mode; }		row { // fourth row text value "Construction quality"; select link "House1:thermal_integrity_level"; }		row { text value "File name:"; span { input link :modelname; action save; action load; }		}	}	row { span { action restart; action run; action pause; action stop; }	}	status link :stream; }

object house { name "House1"; floorarea 1200 sf; }

= Todo =


 * 1) Special entities for datetime, schedules, loadshapes, and enduses neeed to be defined.