Stability | experimental |
---|---|
Maintainer | dwc@cs.yale.edu |
Safe Haskell | None |
A simple Graphical User Interface based on FRP. It uses the SOE graphics library, and draws custom widgets on the screen.
SOE graphics uses OpenGL as the primitive drawing routine, and GLFW library to provide window and input support.
The monadic UI concept is borrowed from Phooey by Conal Elliott.
- label :: String -> UISF a a
- displayStr :: UISF String ()
- display :: Show a => UISF a ()
- withDisplay :: Show b => UISF a b -> UISF a b
- textbox :: UISF String String
- textboxE :: String -> UISF (SEvent String) String
- title :: String -> UISF a b -> UISF a b
- button :: String -> UISF () Bool
- stickyButton :: String -> UISF () Bool
- checkbox :: String -> Bool -> UISF () Bool
- checkGroup :: [(String, a)] -> UISF () [a]
- radio :: [String] -> Int -> UISF () Int
- listbox :: (Eq a, Show a) => UISF ([a], Int) Int
- hSlider :: RealFrac a => (a, a) -> a -> UISF () a
- vSlider :: RealFrac a => (a, a) -> a -> UISF () a
- hiSlider :: Integral a => a -> (a, a) -> a -> UISF () a
- viSlider :: Integral a => a -> (a, a) -> a -> UISF () a
- realtimeGraph :: RealFrac a => Layout -> Time -> Color -> UISF [(a, Time)] ()
- histogram :: RealFrac a => Layout -> UISF (SEvent [a]) ()
- mkWidget :: s -> Layout -> (a -> s -> Rect -> UIEvent -> (b, s, DirtyBit)) -> (Rect -> Bool -> s -> Graphic) -> UISF a b
- mkBasicWidget :: Layout -> (Rect -> Graphic) -> UISF a a
- toggle :: Eq s => s -> Layout -> (Rect -> Bool -> s -> Graphic) -> UISF s Bool
- mkSlider :: Eq a => Bool -> (a -> Int -> Int) -> (Int -> Int -> a) -> (Int -> Int -> a -> a) -> a -> UISF () a
- canvas :: Dimension -> UISF (SEvent Graphic) ()
- canvas' :: Layout -> (a -> Dimension -> Graphic) -> UISF (SEvent a) ()
- focusable :: UISF a b -> UISF a b
- isInFocus :: UISF () Bool
Widgets
displayStr :: UISF String ()Source
DisplayStr is an output widget showing the instantaneous value of a signal of strings.
display :: Show a => UISF a ()Source
display is a widget that takes any show-able value and displays it.
withDisplay :: Show b => UISF a b -> UISF a bSource
withDisplay is a widget modifier that modifies the given widget so that it also displays its output value.
textbox :: UISF String StringSource
Textbox is a widget showing the instantaneous value of a signal of strings.
The textbox widget will often be used with ArrowLoop (the rec keyword).
However, it uses delay
internally, so there should be no fear of a blackhole.
The textbox widget supports mouse clicks and typing as well as the left, right, end, home, delete, and backspace special keys.
textboxE :: String -> UISF (SEvent String) StringSource
This variant of the textbox takes a static argument that is the initial value in the textbox. Then, it takes a stream of 'SEvent String' and only externally updates the contents of the textbox when an event occurs.
title :: String -> UISF a b -> UISF a bSource
Title frames a UI by borders, and displays a static title text.
button :: String -> UISF () BoolSource
A button is a focusable input widget with a state of being on or off. It can be activated with either a button press or the enter key. (Currently, there is no support for the space key due to non-special keys not having Release events.) Buttons also show a static label.
The regular button is down as long as the mouse button or key press is down and then returns to up.
stickyButton :: String -> UISF () BoolSource
The sticky button, on the other hand, once pressed, remains depressed until is is clicked again to be released. Thus, it looks like a button, but it behaves more like a checkbox.
checkbox :: String -> Bool -> UISF () BoolSource
Checkbox allows selection or deselection of an item. It has a static label as well as an initial state.
checkGroup :: [(String, a)] -> UISF () [a]Source
The checkGroup widget creates a group of checkbox
es that all send
their outputs to the same output stream. It takes a static list of
labels for the check boxes and assumes they all start unchecked.
The output stream is a list of each a value that was paired with a String value for which the check box is checked.
radio :: [String] -> Int -> UISF () IntSource
Radio button presents a list of choices and only one of them can be selected at a time. It takes a static list of choices (as Strings) and the index of the initially selected one, and the widget itself returns the continuous stream representing the index of the selected choice.
listbox :: (Eq a, Show a) => UISF ([a], Int) IntSource
The listbox widget creates a box with selectable entries. The input stream is the list of entries as well as which entry is currently selected, and the output stream is the index of the newly selected entry. Note that the index can be greater than the length of the list (simply indicating no choice selected).
Sliders
Sliders are input widgets that allow the user to choose a value within a given range. They come in both continous and discrete flavors as well as in both vertical and horizontal layouts.
Sliders take a boundary argument giving the minimum and maximum possible values for the output as well as an initial value. In addition, discrete (or integral) sliders take a step size as their first argument.
Graphs
realtimeGraph :: RealFrac a => Layout -> Time -> Color -> UISF [(a, Time)] ()Source
The realtimeGraph widget creates a graph of the data with trailing values.
It takes a dimension parameter, the length of the history of the graph
measured in time, and a color for the graphed line.
The signal function then takes an input stream of time as well as
(value,time) event pairs, but since there can be zero or more points
at once, we use [] rather than SEvent
for the type.
The values in the (value,time) event pairs should be between -1 and 1.
histogram :: RealFrac a => Layout -> UISF (SEvent [a]) ()Source
The histogram widget creates a histogram of the input map. It assumes that the elements are to be displayed linearly and evenly spaced.
Widget Builders
:: s | initial state |
-> Layout | layout |
-> (a -> s -> Rect -> UIEvent -> (b, s, DirtyBit)) | computation |
-> (Rect -> Bool -> s -> Graphic) | drawing routine |
-> UISF a b |
mkWidget is a helper function to make stateful widgets easier to write. In essence, it breaks down the idea of a widget into 4 constituent components: state, layout, computation, and drawing.
As mkWidget
allows for making stateful widgets, the first parameter is
simply the initial state.
The layout is the static layout that this widget will use. It
cannot be dependent on any streaming arguments, but a layout can have
"stretchy" sides so that it can expand/shrink to fit an area. Learn
more about making layouts in UIMonad
s UI Layout section -- specifically,
check out the makeLayout
function and the LayoutType
data type.
The computation is where the logic of the widget is held. This
function takes as input the streaming argument a, the widget's state,
a Rect of coordinates indicating the area that has been allotted for
this widget, and the UIEvent
that is triggering this widget's activation
(see the definition of UIEvent
in SOE). The output consists of the
streaming output, the new state, and the dirty bit, which represents
whether the widget needs to be redrawn.
Lastly, the drawing routine takes the same Rect as the computation, a Bool that is true when this widget is in focus and false otherwise, and the current state of the widget (technically, this state is the one freshly returned from the computation). Its output is the Graphic that this widget should display.
Occasionally, one may want to display a non-interactive graphic in
the UI. mkBasicWidget
facilitates this. It takes a layout and a
simple drawing routine and produces a non-interacting widget.
:: Eq s | |
=> s | Initial state value |
-> Layout | The layout for the toggle |
-> (Rect -> Bool -> s -> Graphic) | The drawing routine |
-> UISF s Bool |
The toggle is useful in the creation of both checkbox
es and radio
buttons. It displays on/off according to its input, and when the mouse
is clicked on it, it will output True (otherwise it outputs False).
The UISF returned from a call to toggle accepts the state stream and returns whether the toggle is being clicked.
:: Eq a | |
=> Bool | True for horizontal, False for vertical |
-> (a -> Int -> Int) | A function for converting a value to a position |
-> (Int -> Int -> a) | A function for converting a position to a value |
-> (Int -> Int -> a -> a) | A function for determining how much to jump when a click is on the slider but not the target |
-> a | The initial value for the slider |
-> UISF () a |
The mkSlider widget builder is useful in the creation of all sliders.
canvas :: Dimension -> UISF (SEvent Graphic) ()Source
Canvas displays any graphics. The input is a signal of graphics events because we only want to redraw the screen when the input is there.
canvas' :: Layout -> (a -> Dimension -> Graphic) -> UISF (SEvent a) ()Source
canvas' uses a layout and a graphic generator. This allows it to
behave similarly to canvas
, but it can adjust in cases with stretchy layouts.
Focus
Any widget that wants to accept mouse button clicks or keystrokes must be focusable. The focusable function below achieves this.