billstclair / elm-svg-button / Svg.Button

The Svg.Button module makes it easy to create SVG buttons.

Currently, the buttons are rectangular, with a two-pixel wide black border, containing either text or Svg you provide for their body. They support single clicks or repeated clicks, and work on both regular computer browsers, with a mouse, or portable browsers, with a touch screen.

Types


type Button state msg

An Svg Button.

Create one with simpleButton or repeatingButton.


type Content msg
    = TextContent String
    | SvgContent (Svg msg)
    | NoContent

Three ways to draw the button content.

TextContent encapsulates a String, which is sized to half the button height and centered.

SvgContent allows you to render any Svg you wish.

NoContent renders nothing.


type alias Location =
( Basics.Float, Basics.Float )

A two-dimensional location: (x, y)


type alias Size =
( Basics.Float, Basics.Float )

A two-dimensional size: (width, height)


type Msg

Opaque internal message.

You wrap these with the (Msg -> msg) you pass to render, and pass them to update.


type RepeatTime
    = NoRepeat
    | RepeatTime Basics.Float
    | RepeatTimeWithInitialDelay Basics.Float Basics.Float

First arg to repeatingButton.

The two Float args to RepeatTimeWithInitialDelay are the initial delay and the subsequent repeat period, in milliseconds.


type alias Colors =
{ background : String
, outline : String
, text : String 
}

The Colors for a button.

Constructors

simpleButton : Size -> state -> Button state msg

Create a simple, rectanglar button.

It sends a msg when clicked or tapped.

The view function draws a two-pixel wide, black border around it. Your drawing function should leave room for that, or it will be overlaid.

repeatingButton : RepeatTime -> Size -> state -> Button state msg

Like simpleButton, but repeats the click or tap periodically, as long as the mouse or finger is held down.

Events

update : (Msg -> msg) -> Msg -> Button state msg -> ( Basics.Bool, Button state msg, Platform.Cmd.Cmd msg )

Call this to process a Button message from inside your wrapper.

The Bool in the return value is true if this message should be interpreted as a click on the button. Simple buttons never change the button or return a command you need to care about, but you'll need to call getState on the button to figure out what to do (unless your application has only a single button).

checkSubscription : Msg -> Button state msg -> Maybe ( Basics.Float, Msg )

Subscriptions are one type of message you can get inside your wrapper.

In order to check if a message is a subscription, call checkSubscription. If it returns a time delay and Button message, you need to use that to create a time subscription for your application.

Simple buttons don't need subscriptions. Only repeating buttons use them.

Triangular Buttons


type TriangularButtonDirection
    = UpButton
    | DownButton
    | RightButton
    | LeftButton

The direction a triangular button points.

setTriangularButtonRenderers : TriangularButtonDirection -> Button state msg -> Button state msg

Change the button to render as a triangle, instead of a rectangle.

Button state accessors

getState : Button state msg -> state

Read a button's state.

setState : state -> Button state msg -> Button state msg

Set a button's state.

isTouchAware : Button state msg -> Basics.Bool

Return True if a Button is touch aware.

setTouchAware : Basics.Bool -> Button state msg -> Button state msg

Set whether a button is touch aware.

update notices when it gets a touch event, and sets the touchAware state, but since you usually don't save updated simple buttons, the next event won't notice. Mobile browsers have a delay in generating a simulated click event. Knowing that the button is touch aware eliminates that delay, since the click is then generated by the TouchEnd event instead of the MouseUp event.

getSize : Button state msg -> Size

Read a button's size.

setSize : Size -> Button state msg -> Button state msg

Set a button's size.

getColors : Button state msg -> Colors

Get the colors of a button.

setColors : Colors -> Button state msg -> Button state msg

Change the colors of a button.

getRenderBorder : Button state msg -> Button state msg -> Svg msg

Get a button's border renderer.

setRenderBorder : (Button state msg -> Svg msg) -> Button state msg -> Button state msg

Replace a button's default renderButton function with your own.

getRenderContent : Button state msg -> Content msg -> Button state msg -> Svg msg

Get a button's content renderer.

setRenderContent : (Content msg -> Button state msg -> Svg msg) -> Button state msg -> Button state msg

Replace a button's default renderContent function with your own.

getRenderOverlay : Button state msg -> (Msg -> msg) -> Button state msg -> Svg msg

Get a button's content renderer.

setRenderOverlay : ((Msg -> msg) -> Button state msg -> Svg msg) -> Button state msg -> Button state msg

Replace a button's default renderOverlay function with your own.

Constants

normalRepeatTime : RepeatTime

This is the usual value used for the repeat time of a repeating button.

It has an initial delay of 1/2 second and a repeat period of 1/10 second.

defaultColors : Colors

The defaut colors.

Rendering

render : Location -> Content msg -> (Msg -> msg) -> Button state msg -> Svg msg

Render a button's outline, your content, and the mouse-sensitive overlay.

Does this by sizing an SVG g element at the Location you pass and the size of the Button, and calling renderBorder, renderContent, and renderOverlay inside it.

renderBorder : Button state msg -> Svg msg

Draw a button's border.

This is the default border renderer for a button.

You won't usually use this, letting render call it for you.

You should call this BEFORE drawing your button, so that its opaque body does not cover your beautiful drawing.

renderContent : Content msg -> Button state msg -> Svg msg

Render the visible, non-border part of a button.

This is the default content renderer for a button.

You won't usually use this, letting render call it for you.

But you could use it for a non-button, if you just want some text centered in a rectangle.

renderOverlay : (Msg -> msg) -> Button state msg -> Svg msg

Draw a button's transparent, mouse/touch-sensitive overlay.

This is the default overlay renderer for a button.

You won't usually use this, letting render call it for you.

You should call this AFTER drawing your button, so that the overlay is the last thing drawn. Otherwise, it may not get all the mouse/touch events.

renderTriangularBorder : TriangularButtonDirection -> Button state msg -> Svg msg

Draw a triangular button's border.

You'll usually use this via setTriangularButtonRenderers.

You should call this BEFORE drawing your button, so that its opaque body does not cover your beautiful drawing.

renderTriangularOverlay : TriangularButtonDirection -> (Msg -> msg) -> Button state msg -> Svg msg

Draw a triangular button's overlay.

You'll usually use this via setTriangularButtonRenderers.

You should call this AFTER drawing your button, so that the overlay is the last thing drawn. Otherwise, it may not get all the mouse/touch events.

Triangular Button Corners

triangularButtonCorners : TriangularButtonDirection -> Button state msg -> ( Location, Location, Location )

Return the three corners of a triangular button.

triangularButtonPathString : TriangularButtonDirection -> Button state msg -> String

Return a path string to draw a triangular button. Suitable as the arg to Svg.Attribute.d.