Dat.gui
provides a low footprint way of easily tweaking variables and
settings within your elm project. This project is based off of the
elm-ui
library. The main focus of this library is to provide easy and quick access
to parameters within your application. This package api is different from
the original dat.GUI application
because of language differences between JavaScript and Elm. However, the same
clean interface is provided.
The way this package works is to think of the gui as a form element with
different parameters within the form. This means that you have to keep
track of all the parameter updating as you would from other forms in the
update
function.
The gui is structured around passing OnChange
events to the update function
so that you can update your model with new values from the gui. The gui elements
take in a Form
type with each of the variables you are controlling within
your application. Here, I'm using very generic names for the types so don't
think that you need to stick to my naming conventions. In fact, you should
use something more descriptive to your project.
type Form
= Action
| Boolean Bool
| Text String
| Integer Int
| Floating Float
The gui also needs the messages to be able to change values within your project
as well as toggling the open/close state of the gui window. To change the
values of all the elements in the project, we use a single message OnChange
which takes the Form
object that is being changed. This gives the new
value to change your model.
type Msg
= ToggleControls
| OnChange Form
gui : List (Element.Attribute msg) -> { toggleControls : msg, showControls : Basics.Bool, elements : List (Element msg) } -> Element msg
The main view function for the gui. This is the container wrapper for the whole gui. To add this to your application, you are most likely going to need to use the Element.inFront function in order to place this above everything else you are trying to put into your application. This however, is up to you. In the attributes is where you would put any location information for the gui.
focusStyle : Element.Option
This removes the default focus style for elm-ui. In order to remove the normal focus you must initialize the app with the following
Element.layoutWith
{ options = [ Dat.focusStyle ] }
[] -- Attributes
none -- Page Body
Note: All this does is set the three attributes for Element.focusStyle
to
Nothing
. If you are already using the Element.layoutWith
function, just
know that the focus styling will also be propagated into Dat.
These are all the different variable/action types which can be added and changed
from the gui. Each type needs to be added to the main gui view function and
added with a new Form
handler.
action : { text : String, form : form, onPress : form -> msg } -> Element msg
An element that triggers some sort of event. This is used to send an
event to the update
function. In this case it sends the Action
message.
Dat.action
{ text = "Action Button"
, form = Action
, onPress = OnChange
}
boolean : { text : String, form : Basics.Bool -> form, onClick : form -> msg, checked : Basics.Bool } -> Element msg
Input selection for toggling boolean values.
Dat.boolean
{ text = "Boolean Box"
, form = Boolean
, onClick = OnChange
, checked = model.boolean
}
string : { text : String, form : String -> form, onChange : form -> msg, value : String } -> Element msg
Text area selection for relatively short string values. This provides generally a several word length box. This is good for changing titles, names, and the like.
Dat.string
{ text = "Text Value"
, form = Text
, onChange = OnChange
, value = model.text
}
integer : { text : String, form : Basics.Int -> form, onChange : form -> msg, value : Basics.Int, min : Basics.Int, max : Basics.Int, step : Basics.Int } -> Element msg
An input slider for changing integer values. The slider step can be changed to provide more or less precision over the input values between the upper and lower values.
Dat.integer
{ text = "Integer"
, form = Integer
, onChange = OnChange
, value = model.integer
, min = 0
, max = 100
, step = 1
}
float : { text : String, form : Basics.Float -> form, onChange : form -> msg, value : Basics.Float, min : Basics.Float, max : Basics.Float, step : Basics.Float } -> Element msg
Similar to the integer slider for selecting a values within a range. This selection provides a fine granularity over your input range. For this slider, the step value is much more important. You want to make sure that the step value is small enough so that the input slider is smooth. However, if you have some function that updates on every value change, small step precisions could cause lag when selecting new values.
Dat.float
{ text = "Float"
, form = Floating
, onChange = OnChange
, value = model.float
, min = 0
, max = 10
, step = 0.1
}