Merge pull request #89 from boydm/boyd

A lot of documentation.

Author: boydm

lib/scenic/component.ex

@@ -17,14 +17,39 @@ defmodule Scenic.Component do
 
   At the top of your module definition.
 
+  ## Standard Components
+
+  Scenic includes a small number of standard components that you can simply reuse in your
+  scenes. These were chosen to be in the main library because a) they are used frequently,
+  and b) their use promotes a certain amount of "common" look and feel.
+
+  All of these components are typically added/modified via the helper functions in the
+  [`Scenic.Components`](Scenic.Components.html) module.
+
+  * [`Button`](Scenic.Component.Button.html) a simple button.
+  * [`Checkbox`](Scenic.Component.Input.Checkbox.html) a checkbox input field. 
+  * [`Dropdown`](Scenic.Component.Input.Dropdown.html) a dropdown / select input field.
+  * [`RadioGroup`](Scenic.Component.Input.RadioGroup.html) a group of radio button inputs.
+  * [`Slider`](Scenic.Component.Input.Slider.html) a slider input.
+  * [`TextField`](Scenic.Component.Input.TextField.html) a text / password input field.
+  * [`Toggle`](Scenic.Component.Input.Toggle.html) an on/off toggle input.
+
+  ## Other Components
+
+  For completeness, Scenic also includes the following standard components. They are used
+  by the components above, although you are free to use them as well if they fit your needs.
+
+  * [`Caret`](Scenic.Component.Input.Caret.html) the vertical, blinking, caret line in a text field.
+  * [`RadioButton`](Scenic.Component.Input.RadioButton.html) a single radio button in a radio group.
+
   ## Verifiers
 
   One of the main differences between a Component and a Scene is the two extra callbacks
   that are used to verify incoming data. Since Components are meant to be reused, you
   should do some basic validation that the data being set up is valid, then provide
   feedback if it isn't.
 
-  ## No children
+  ## Optional: No Children
 
   There is an optimization you can use. If you know for certain that your component
   will not attempt to use any components, you can set `has_children` to `false` like this.

lib/scenic/component/button.ex

@@ -1,6 +1,77 @@
 defmodule Scenic.Component.Button do
-  @moduledoc false
+  @moduledoc """
+  Add a button to a graph
 
+  A button is a small scene that is pretty much just some text drawn over a
+  rounded rectangle. The button scene contains logic to detect when the button
+  is pressed, tracks it as the pointer moves around, and when it is released.
+
+  ## Data
+
+  `title`
+
+  * `title` - a bitstring describing the text to show in the button
+
+  ## Messages
+
+  If a button press is successful, it sends an event message to the host scene
+  in the form of:
+
+      {:click, id}
+
+  ## Styles
+
+  Buttons honor the following standard styles
+
+  * `:hidden` - If `false` the component is rendered. If `true`, it is skipped.
+  The default is `false`.
+  * `:theme` - The color set used to draw. See below. The default is `:primary`
+
+  ## Additional Styles
+
+  Buttons honor the following list of additional styles.
+
+  * `:width` - pass in a number to set the width of the button.
+  * `:height` - pass in a number to set the height of the button.
+  * `:radius` - pass in a number to set the radius of the button's rounded
+  rectangle.
+  * `:alignment` - set the alignment of the text inside the button. Can be one
+  of `:left, :right, :center`. The default is `:center`.
+  * `:button_font_size` - the size of the font in the button
+
+  Buttons do not use the inherited `:font_size` style as they should look
+  consistent regardless of what size the surrounding text is.
+
+  ## Theme
+
+  Buttons work well with the following predefined themes:
+  `:primary`, `:secondary`, `:success`, `:danger`, `:warning`, `:info`,
+  `:text`, `:light`, `:dark`
+
+  To pass in a custom theme, supply a map with at least the following entries:
+
+  * `:text` - the color of the text in the button
+  * `:background` - the normal background of the button
+  * `:active` - the background while the button is pressed
+
+  ## Usage
+
+  You should add/modify components via the helper functions in
+  [`Scenic.Components`](Scenic.Components.html#button/3)
+
+  ### Examples
+
+  The following example creates a simple button and positions it on the screen.
+
+      graph
+      |> button("Example", id: :button_id, translate: {20, 20})
+
+  The next example makes the same button as before, but colors it as a warning
+  button. See the options list above for more details.
+
+      graph
+      |> button("Example", id: :button_id, translate: {20, 20}, theme: :warning)
+  """
   use Scenic.Component, has_children: false
 
   alias Scenic.Graph
@@ -20,6 +91,7 @@ defmodule Scenic.Component.Button do
   @default_alignment :center
 
   # --------------------------------------------------------
+  @doc false
   def info(data) do
     """
     #{IO.ANSI.red()}Button data must be a bitstring: initial_text
@@ -29,10 +101,12 @@ defmodule Scenic.Component.Button do
   end
 
   # --------------------------------------------------------
+  @doc false
   def verify(text) when is_bitstring(text), do: {:ok, text}
   def verify(_), do: :invalid_data
 
   # --------------------------------------------------------
+  @doc false
   def init(text, opts) when is_bitstring(text) and is_list(opts) do
     id = opts[:id]
     styles = opts[:styles]
@@ -114,6 +188,7 @@ defmodule Scenic.Component.Button do
   end
 
   # --------------------------------------------------------
+  @doc false
   def handle_input(
         {:cursor_enter, _uid},
         _context,

lib/scenic/component/input/caret.ex

@@ -4,8 +4,28 @@
 #
 
 defmodule Scenic.Component.Input.Caret do
-  @moduledoc false
+  @moduledoc """
+  Add a blinking text-input caret to a graph.
 
+
+  ## Data
+
+  `{height, color}`
+
+  * `height` - integer greater than zero
+  * `color` - any [valid color](Scenic.Primitive.Style.Paint.Color.html).
+
+  ## Usage
+
+  The caret component is used by the TextField component and usually isn't accessed directly,
+  although you are free to do so if it fits your needs. There is no short-cut helper
+  function so you will need to add it to the graph manually.
+
+  The following example adds a caret to a graph.
+
+      graph
+      |> Caret.add_to_graph({height, theme.text}, id: :caret)
+  """
   use Scenic.Component, has_children: false
 
   import Scenic.Primitives,
@@ -28,6 +48,7 @@ defmodule Scenic.Component.Input.Caret do
   # setup
 
   # --------------------------------------------------------
+  @doc false
   def info(data) do
     """
     #{IO.ANSI.red()}Caret data must be: {height, color}
@@ -37,6 +58,7 @@ defmodule Scenic.Component.Input.Caret do
   end
 
   # --------------------------------------------------------
+  @doc false
   @spec verify(any()) :: :invalid_data | {:ok, {number(), any()}}
   def verify({height, color} = data)
       when is_number(height) and height > 0 do
@@ -49,6 +71,7 @@ defmodule Scenic.Component.Input.Caret do
   def verify(_), do: :invalid_data
 
   # --------------------------------------------------------
+  @doc false
   def init({height, color}, _opts) do
     # build the graph, initially not showing
     graph =
@@ -72,6 +95,7 @@ defmodule Scenic.Component.Input.Caret do
   end
 
   # --------------------------------------------------------
+  @doc false
   def handle_cast(:start_caret, %{graph: graph, timer: nil} = state) do
     # turn on the caret
     graph =
@@ -127,6 +151,7 @@ defmodule Scenic.Component.Input.Caret do
   def handle_cast(_, state), do: {:noreply, state}
 
   # --------------------------------------------------------
+  @doc false
   def handle_info(:blink, %{graph: graph, hidden: hidden} = state) do
     # invert the hidden flag
     hidden = !hidden

lib/scenic/component/input/checkbox.ex

@@ -1,5 +1,53 @@
 defmodule Scenic.Component.Input.Checkbox do
-  @moduledoc false
+  @moduledoc """
+  Add a checkbox to a graph
+
+  ## Data
+
+  `{text, checked?}`
+
+  * `text` - must be a bitstring
+  * `checked?` - must be a boolean and indicates if the checkbox is set.
+
+  ## Messages
+
+  When the state of the checkbox, it sends an event message to the host scene
+  in the form of:
+
+  `{:value_changed, id, checked?}`
+
+  ## Styles
+
+  Buttons honor the following standard styles
+
+  * `:hidden` - If `false` the component is rendered. If `true`, it is skipped.
+  The default is `false`.
+  * `:theme` - The color set used to draw. See below. The default is `:dark`
+
+  ## Theme
+
+  Checkboxes work well with the following predefined themes: `:light`, `:dark`
+
+  To pass in a custom theme, supply a map with at least the following entries:
+
+  * `:text` - the color of the text in the button
+  * `:background` - the background of the box
+  * `:border` - the border of the box
+  * `:active` - the border of the box while the button is pressed
+  * `:thumb` - the color of the check mark itself
+
+  ## Usage
+
+  You should add/modify components via the helper functions in
+  [`Scenic.Components`](Scenic.Components.html#checkbox/3)
+
+  ### Examples
+
+  The following example creates a checkbox and positions it on the screen.
+
+      graph
+      |> checkbox({"Example", true}, id: :checkbox_id, translate: {20, 20})
+  """
 
   use Scenic.Component, has_children: false
 
@@ -18,7 +66,8 @@ defmodule Scenic.Component.Input.Checkbox do
   # @default_height    16
   # @default_radius    3
 
-  #  #--------------------------------------------------------
+  # --------------------------------------------------------
+  @doc false
   def info(data) do
     """
     #{IO.ANSI.red()}Checkbox data must be: {text, checked?}
@@ -28,13 +77,15 @@ defmodule Scenic.Component.Input.Checkbox do
   end
 
   # --------------------------------------------------------
+  @doc false
   def verify({text, checked} = data) when is_bitstring(text) and is_boolean(checked) do
     {:ok, data}
   end
 
   def verify(_), do: :invalid_data
 
   # --------------------------------------------------------
+  @doc false
   def init({text, checked?}, opts) do
     id = opts[:id]
     styles = opts[:styles]
@@ -101,6 +152,7 @@ defmodule Scenic.Component.Input.Checkbox do
   end
 
   # --------------------------------------------------------
+  @doc false
   def handle_input({:cursor_enter, _uid}, _, %{pressed: true} = state) do
     state = Map.put(state, :contained, true)
     graph = update_graph(state)