git.iko.soy/elk
on a428bef help sign in
elk/libraries/Graphics/Input.elm
228 lines 7.6 kB history raw
1module Graphics.Input where
2{-| This module is for creating standard input widgets such as buttons and
3text fields. All functions in this library follow a general pattern in which
4you create an `Input` that many elements can report to:
6```haskell
7clicks : Input ()
8clicks = input ()
10clickableYogi : Element
11clickableYogi = clickable clicks.handle () (image 40 40 "/yogi.jpg")
12```
14Whenever the user clicks on the resulting `clickableYogi` element, it sends an
15update to the `clicks` input. You will see this pattern again and again in
16examples in this library, so just read on to get a better idea of how it works!
18# Creating Inputs
19@docs Input, input
21# Basic Input Elements
22Text fields come later.
23@docs button, customButton, checkbox, dropDown
25# Clicks and Hovers
26@docs clickable, hoverable
28# Text Fields
29@docs field, password, email, noContent, FieldContent, Selection, Direction
30-}
32import Signal (Signal)
33import Graphics.Element (Element)
34import Native.Graphics.Input
36{-| This is the key abstraction of this library. An `Input` is a record
37of two fields:
39 1. `signal` — all values coming to this input from “the world”
40 2. `handle` — a way to refer to this particular input and send it values
42This will make more sense as you see more examples.
43-}
44type Input a = { signal : Signal a, handle : Handle a }
46data Handle a = Handle
48{-| Create a new `Input`. You just give the initial value for the
49input’s `signal`.
51Note for Advanced Users: creating an `Input` is an inherently imperative
52action, so this is one of very few impure functions in Elm. That means
53`(input ())` and `(input ())` are actually two different inputs with different
54signals and handles. By design, Elm’s impure functions can only be useful
55as you build your signal graph at startup, so Elm is still pure at runtime.
56-}
57input : a -> Input a
58input = Native.Graphics.Input.input
60{-| Create a standard button. The following example begins making a basic
61calculator:
63 data Keys = Number Int | Plus | Minus | Clear
65 keys : Input Keys
66 keys = input Clear
68 calculator : Element
69 calculator =
70 flow right [ button keys.handle (Number 1) "1"
71 , button keys.handle (Number 2) "2"
72 , button keys.handle Plus "+"
73 ]
75If the user presses the "+" button, `keys.signal` will update to `Plus`. If the
76users presses "2", `keys.signal` will update to `(Number 2)`.
77-}
78button : Handle a -> a -> String -> Element
79button = Native.Graphics.Input.button
81{-| Same as `button` but lets you customize buttons to look however you want.
83 click : Input ()
84 click = input ()
86 prettyButton : Element
87 prettyButton =
88 customButton click.handle
89 (image 100 40 "/button_up.jpg")
90 (image 100 40 "/button_hover.jpg")
91 (image 100 40 "/button_down.jpg")
92-}
93customButton : Handle a -> a -> Element -> Element -> Element -> Element
94customButton = Native.Graphics.Input.customButton
96{-| Create a checkbox. The following example creates three synced checkboxes:
98 check : Input Bool
99 check = input False
101 boxes : Bool -> Element
102 boxes checked =
103 let box = container 40 40 middle (checkbox check.handle id checked)
104 in flow right [ box, box, box ]
106 main : Signal Element
107 main = boxes <~ check.signal
108-}
109checkbox : Handle a -> (Bool -> a) -> Bool -> Element
110checkbox = Native.Graphics.Input.checkbox
112{-| Create a drop-down menu. The following drop-down lets you choose your
113favorite British sport:
115 data Sport = Football | Cricket | Snooker
117 sport : Input Sport
118 sport = input Nothing
120 sportDropDown : Element
121 sportDropDown =
122 dropDown sport.handle
123 [ ("" , Nothing)
124 , ("Football", Just Football)
125 , ("Cricket" , Just Cricket)
126 , ("Snooker" , Just Snooker)
127 ]
129If the user selects "Football" from the drop down menue, `sport.signal`
130will update to `Just Football`.
131-}
132dropDown : Handle a -> [(String,a)] -> Element
133dropDown = Native.Graphics.Input.dropDown
135{-| Detect mouse hovers over a specific `Element`. In the following example,
136we will create a hoverable picture called `cat`.
138 hover : Input Bool
139 hover = input False
141 cat : Element
142 cat = image 30 30 "/cat.jpg"
143 |> hoverable hover.handle id
145When the mouse hovers above the `cat` element, `hover.signal` will become
146`True`. When the mouse leaves it, `hover.signal` will become `False`.
147-}
148hoverable : Handle a -> (Bool -> a) -> Element -> Element
149hoverable = Native.Graphics.Input.hoverable
151{-| Detect mouse clicks on a specific `Element`. In the following example,
152we will create a clickable picture called `cat`.
154 data Picture = Cat | Hat
156 picture : Input Picture
157 picture = input Cat
159 cat : Element
160 cat = image 30 30 "/cat.jpg"
161 |> clickable picture.handle Cat
163 hat : Element
164 hat = image 30 30 "/hat.jpg"
165 |> clickable picture.handle Hat
167When the user clicks on the `cat` element, `picture.signal` receives
168an update containing the value `Cat`. When the user clicks on the `hat` element,
169`picture.signal` receives an update containing the value `Hat`. This lets you
170distinguish which element was clicked. In a more complex example, they could be
171distinguished with IDs or more complex data structures.
172-}
173clickable : Handle a -> a -> Element -> Element
174clickable = Native.Graphics.Input.clickable
176{-| Represents the current content of a text field. For example:
178 FieldContent "She sells sea shells" (Selection 0 3 Backward)
180This means the user highlighted the substring `"She"` backwards.
181-}
182type FieldContent = { string:String, selection:Selection }
184{-| The selection within a text field. `start` is never greater than `end`:
186 Selection 0 0 Forward -- cursor precedes all characters
188 Selection 5 9 Backward -- highlighting characters starting after
189 -- the 5th and ending after the 9th
190-}
191type Selection = { start:Int, end:Int, direction:Direction }
193{-| The direction of selection.-}
194data Direction = Forward | Backward
196{-| A field with no content:
198 FieldContent "" (Selection 0 0 Forward)
199-}
200noContent : FieldContent
201noContent = FieldContent "" (Selection 0 0 Forward)
203{-| Create a text field. The following example creates a time-varying element
204called `nameField`. As the user types their name, the field will be updated
205to match what they have entered.
207 name : Input FieldContent
208 name = input noContent
210 nameField : Signal Element
211 nameField = field name.handle (\content -> content) "Name" <~ nameContent
212-}
213field : Handle a -> (FieldContent -> a) -> String -> FieldContent -> Element
214field = Native.Graphics.Input.field
216{-| Same as `field` but the UI element blocks out each characters. -}
217password : Handle a -> (FieldContent -> a) -> String -> FieldContent -> Element
218password = Native.Graphics.Input.password
220{-| Same as `field` but it adds an annotation that this field is for email
221addresses. This is helpful for auto-complete and for mobile users who may
222get a custom keyboard with an `@` and `.com` button.
223-}
224email : Handle a -> (FieldContent -> a) -> String -> FieldContent -> Element
225email = Native.Graphics.Input.email
227-- area : Handle a -> (FieldContent -> a) -> Handle b -> ((Int,Int) -> b) -> (Int,Int) -> String -> FieldContent -> Element
228-- area = Native.Graphics.Input.area