FRP.UISF.Widget.Construction

This module provides functions and utilities that help in the construction of new widgets. They are used by FRP.UISF.Widget, and can be used for any custom widgets as well.

Documentation

padding :: Int

Default padding between border and content.

bg :: Color

The default assumed background color of the GUI window.

(//) :: Graphic -> Graphic -> Graphic

An infix shorthand for overGraphic.

whenG :: Bool -> Graphic -> Graphic

A nice way to make a graphic under only certain conditions.

inside :: Point -> Rect -> Bool

Tests whether a Point is within the bounds of a rectangle.

Widget Builders

mkWidget

Arguments

:: 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 UITypes 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.

mkBasicWidget

Arguments

:: Layout

layout

-> (Rect -> Graphic)

drawing routine

-> UISF a a

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.

toggle

Arguments

:: 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 checkboxes 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.

mkSlider

Arguments

:: 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 (SEvent a) a

The mkSlider widget builder is useful in the creation of all sliders.

cyclebox :: Layout -> [(Rect -> Bool -> Graphic, b)] -> Int -> UISF () b

cyclebox is a clickable widget that cycles through a predefined set set of appearances/output values.

cycleboxS :: Layout -> [(Rect -> Bool -> Graphic, b)] -> Int -> UISF (SEvent Int) b

cycleboxS is a cyclebox that additionally accepts input events that can set it to a particular appearance/output.

Focus

Any widget that wants to accept mouse button clicks or keystrokes must be focusable. The focusable function below achieves this.

focusable :: UISF a b -> UISF a b

Making a widget focusable makes it accessible to tabbing and allows it to see any mouse button clicks and keystrokes when it is actually in focus.

isInFocus :: UISF () Bool

Although mouse button clicks and keystrokes will be available once a widget marks itself as focusable, the widget may also simply want to know whether it is currently in focus to change its appearance. This can be achieved with the following signal function.

Supplemental Drawing Function

shadowBox :: (Color, Color, Color, Color) -> Rect -> Graphic

A convenience function for making a box that appears to have a shadow. This is accomplished by using four colors representing:

(Top outside, Top inside, Bottom inside, Bottom Outside).

This is designed to be used with the below values pushed, popped, and marked.

pushed :: (Color, Color, Color, Color)

A pushed shadowBox appears as if it is pushed inward.

marked :: (Color, Color, Color, Color)

A marked shadowBox appears somewhat between popped and pushed and is designed to indicate that the box is at the ready.

popped :: (Color, Color, Color, Color)

A popped shadowBox appears as if it pops outward.