What fun is a model without being able to see and play with it in real time? The Gui classes allow you to easily do this and works on top of the Java Swing gui system (except the Vis2DOpenGL and Vis3DOpenGL, which are built on lwjgl).

7.1 Types of Gui and Method Descriptions

Here we list the different guis that are provided by HAL and provide a summary of their functions

7.1.1 GridWindow

The simplest built-in Gui, it is nothing more than a UIGrid imbedded in a UIWindow. Recommended for first-time users. All functions described below after Close() are also shared with the UIGrid class

GridWindow(title,xDim,yDim,scaleFactor,main?,active?):
sets up a GridWindow, the pixel dimensions of the created window will be: Width = xDim * scaleFactor and Height = yDim * scaleFactor the main boolean specifies whether the program should exit when the window is closed. the active boolean allows easily toggling the objects on and off.
TickPause(milliseconds):
call this once per step of your model, and the function will ensure that your model runs at the rate provided in milliseconds. the function will take the amount time between calls into account to ensure a consistent tick rate.
IsKeyDown(char):
returns whether the given key is currently pressed
AddKeyResponse(OnKeyDown,OnKeyUp):
takes 2 key response functions that will be called whenever a key is pressed or released
Close():
disposes of the GridWindow.
Clear(color):
sets all pixels to a single color.
SetPix(x,y,color),SetPix(i,color):
sets an individual pixel on the GridWindow. in the visualization the pixel will take up scaleFactor*scaleFactor screen pixels.
SetPix(x,y,ColorIntGenerator),SetPix(i,ColorIntGenerator):
same functionality as SetPix with a color argument, but instead takes a ColorIntGenerator function (a function that takes no arguments and returns an int). The reason to use this method is that when the gui is inactivated the ColorIntGenerator function will not be called, which saves the computation time of generating the color.
SetString(string,xLeft,yTop,color,bkColor):
draws a string to the GridWindow. The characters in the string have length 3 pixels, and height 5 pixels, with one pixel width between characters. All characters will be drawn to the same line.
GetPix(x,y),GetPix(i):
returns the pixel color at that location as a colorInt
PlotSegment(x1,y1,x2,y2,color,scaleX,scaleY):
Plots a line segment, connecting all pixels between the points defined by (x1,y1) and (x2,y2) with the provided color. If you are using this function on a per-timestep basis, I recommend setting individual pixels with SetPix, as it is more performant. The scaling variables adjust the spatial scale of the points.
PlotLine(double[]xs,double[]ys,color,startPoint,endPoint,scaleX,scaleY):
plots a line by drawing segments between consecutive points. point i is defined by (xs[i],ys[i]). Points are drawn starting at index startPoint, and ending at index endPoint. The scaling variables adjust the spatial scale of the points.
PlotLine(double[]xys,color,startPoint,endPoint,scaleX,scaleY):
plots a line by drawing segments between consecutive points. Points are expected in the coords format (x1,y1,x2,y2,x3,y3...). Point i is defined by (xys[i*2],xys[i*2+1]). Points are drawn starting at index startPoint, and ending at index endPoint. The scaling variables adjust the spatial scale of the points.
DrawStringSingleLine(string,xLeft,yTop,color,bkColor):
draws a string onto the GuiWindow.
AddAlphaGrid(overlay):
adds another UIGrid as an overlay to compose with the main UIGrid. Alpha blending will be used to combine them.

7.1.2 UIWindow

A container for Gui Components, which will be detailed below. The most supported of the gui types.

UIWindow(title,main?,CloseAction,active?):
the title string is displayed in the top bar, the main boolean specifies whether the program should exit when the window is closed. The active boolean allows easily toggling the objects on and off.
AddCol(column,component):
components are added to the gui from top to bottom in columns. When the window is displayed, the rows and columns expand to fit the largest element in each.
RunGui():
once all components have been added, the RunGui function runs the gui and displays it to the screen.
GetBool(label):
attempts to pull a boolean from the Param with the cooresponding label, works with the UIBoolInput
GetInt(label):
attempts to pull an integer from the Param with the cooresponding label, works with the UIIntInput and UIComboBoxInput (returns the index of the chosen option)
GetDouble(label):
attempts to pull a double from the Param with the cooresponding label, works with the UIIntInput and UIDoubleInput
GetString(label):
attempts to pull a string from the Param with the cooresponding label, works with all Param types
Dispose():
disposes of the GridWindow.
TickPause(millis):
call this once per step of your model, and the function will ensure that your model runs at the rate provided in millis. The function will take the amount time between calls into account to ensure a consistent tick rate.
IsKeyDown(char):
returns whether the given key is currently pressed
AddKeyResponse(OnKeyDown,OnKeyUp):
takes 2 key response functions that will be called whenever a key is pressed or released

7.1.3 OpenGL2DWindow

A window for visualizing 2D models, especially off lattice ones. I usually recommend using a UIGrid instead for 2D models.

OpenGL2DWindow(xPix,yPix,xDim,yDim,title,active?):
creates a Vis2DOpenGL window. The dimensions on screen are xPix by yPix. the xDim and yDim dimensions should match the model being drawn. The title string is displayed on the top of the window, the active boolean allows easily disabling the Vis2DOpenGL
Update():
renders all draw commands to the window
IsClosed():
returns true if the close button has been clicked in the Gui
Close():
closes the Vis2DOpenGL. Happens automatically when the main function finishes.
Clear(clearColor):
usually called first, sets the screen to a color.
Circle(x,y,z,radius,color):
Draws a circle. Currently this is the only builtin draw functionality along with the FanShape function from which it is derived.
Line(x1,y1,x2,y2,color):
Draws a line between 2 points
LineStrip(double[]xs,double[]ys,color):
draws a set of connected line segments, xs and ys are expected to be the same length.
LineStrip(double[]coords,color):
draws a set of connected line segments, coords is expected to consist of [x1,y1,x2,y2...] pairs of point coordinates.
TickPause(millis):
call this once per step of your model, and the function will ensure that your model runs at the rate provided in millis. The function will take the amount time between calls into account to ensure a consistent tick rate.

7.1.4 OpenGL3DWindow

A window for visualizing 3D models.

Vis3DOpenGL(xPix,yPix,xDim,yDim,title,active?):
creates a Vis3DOpenGL window. The dimensions on screen are xPix by yPix. The xDim, yDim, and zDim dimensions should match the model being drawn. The title string is displayed on the top of the window, the active boolean allows easily disabling the Vis3DOpenGL
CONTROLS:
to move around inside an active Vis3DOpenGL window, click on the window, after which the following controls apply:
  • Esc Key: Get the mouse back
  • Mouse Move: Change look direction
  • W Key: Move forward
  • S Key: Move backward
  • D Key: Move right
  • A Key: Move left
  • Shift Key: Move up
  • Space Key: Move down
  • Q Key: Temporarily increase move speed
  • E Key: Temporarily decrease move speed

Update():
renders all draw commands to the window
Clear(color):
usually called before anything else: clears the gui
CheckClosed():
returns true if the close button has been clicked in the Gui
Close():
closes the Vis3DOpenGL. Happens automatically when the main function finishes.
Circle(x,y,z,radius,color):
Draws a circle. Currently this is the only builtin draw functionality along with the FanShape function from which it is derived.
CelSphere(x,y,z,radius,color):
Draws a cool looking cel-shaded sphere, which is really several Circle function calls in a row internally. Less performant than calling the Circle function.
TickPause(millis):
call this once per step of your model, and the function will ensure that your model runs at the rate provided in millis. The function will take the amount time between calls into account to ensure a consistent tick rate.
Line(x1,y1,z1,x2,y2,z2,color):
Draws a line between 2 points
LineStrip(double[]xs,double[]ys,double[]zs,color):
draws a set of connected line segments, xs and ys are expected to be the same length.
LineStrip(double[]coords,color):
draws a set of connected line segments, coords is expected to consist of [x1,y1,z1,x2,y2,z2...] triplets of point coordinates.

7.2 Types of GuiComponent and Method Descriptions

7.2.1 UIGrid

A grid of pixels that are each set individually. Very fast and useful for displaying the contents of grids

UIGrid(gridW,gridH,scaleFactor,active?):
sets up a UIGrid, the pixel dimensions of the created area will be: Width = xDim * scaleFactor and Height = yDim * scaleFactor. The active boolean allows easily toggling the objects on and off. The functions that the UIGrid can execute are included above. see the GridWindow for the list of UIGrid functions

7.2.2 UILabel

A label that displays text on the Gui and can be continuously updated. The UILabel’s on-screen size will remain fixed at whatever size is needed to render the string first passed to it.

7.2.3 UIButton

A button that when clicked triggers an interrupting function

7.2.4 UIBoolInput

A button that can be set and unset, must be labeled. Use the UIWindow Param functions to interact.

7.2.5 UIIntInput

An input line that expects an integer, must be labeled. Use the UIWindow Param functions to interact.

7.2.6 UIDoubleInput

An input line that expects a double, must be labeled. Use the UIWindow Param functions to interact.

7.2.7 UIStringInput

An input line that takes any string, must be labeled. Use the UIWindow Param functions to interact.

7.2.8 UIComboBoxInput

A dropdown menu of text options, must be labeled. Use the UIWindow Param functions to interact.

7.2.9 UIFileChooserInput

A button that when clicked triggers a gui that facilitates choosing an existing file or creating one, must be labeled. Use the UIWindow Param functions to interact.

7.3 GifMaker

The GifMaker object is used in combination with a UIGrid or GridWindow to make GIF videos of model runs.

GifMaker(outputPath,timeBetweenFramesMS,loopContinuously?):
creates a GifMaker object. the outputPath argument specifies the name of the file that will be output. timeBettweenFramesMS specifies how many milliseconds the GIF should pause between frames. loopContinuously specifies whether the GIF should automatically restart when it finishes.
AddFrame(UIGrid):
adds the current UIGrid state to the GIF as a single frame
Close():
Close this GifMaker object