Merge pull request #282 from boydm/v0.11

V0.11

Author: boydm

guides/getting_started.md

@@ -3,10 +3,9 @@
 This guide will walk you through installing the new project generator, then
 building your first Scenic application.
 
-Some initial setup is required for windows.  You'll need 
-windows services for linux (WSL) and VcXsrv,
-[Jeffrey Borchert's article details these steps.](https://medium.com/@jeffborch/running-the-scenic-elixir-gui-framework-on-windows-10-using-wsl-f9c01fd276f6)
-You'll come back here to finish.
+## Install Dependencies
+
+See [Install Dependencies](install_dependencies.html)
 
 ## Install `scenic.new`
 

guides/install_dependencies.md

@@ -4,8 +4,9 @@ The design of Scenic goes to great lengths to minimize its dependencies to just
 the minimum. Namely, it needs Erlang/Elixir and OpenGL.
 
 Rendering your application into a window on your local computer (MacOS, Ubuntu
-and others) is done by the `scenic_driver_glfw` driver. It uses the GLFW and
-GLEW libraries to connect to OpenGL.
+and others) is done by the
+[`scenic_driver_local`](https://github.com/ScenicFramework/scenic_driver_local)
+driver. It uses the GLFW and GLEW libraries to connect to OpenGL.
 
 The instructions below assume you have already installed Elixir/Erlang. If you
 need to install Elixir/Erlang there are instructions on the [elixir-lang
@@ -22,7 +23,13 @@ brew install glfw3 glew pkg-config
 ```
 
 Once these components have been installed, you should be able to build the
-`scenic_driver_glfw` driver.
+`scenic_driver_local` driver.
+
+## On Windows
+
+Some initial setup is required for windows. You'll need windows services for
+linux (WSL) and VcXsrv, [Jeffrey Borchert's article details these
+steps.](https://medium.com/@jeffborch/running-the-scenic-elixir-gui-framework-on-windows-10-using-wsl-f9c01fd276f6)
 
 ## On Ubuntu 16
 

guides/upgrading_to_v0.11.md

@@ -208,7 +208,7 @@ defmodule MyDevice.Scene.Example do
 
   # display any received events
   def handle_event(event, _, %{assigns: %{graph: graph}} = scene) do
-    graph = Graph.modify( graph, :text, &text(&1, inspect(event))
+    graph = Graph.modify( graph, :text, &text(&1, inspect(event)))
 
     scene =
       scene

lib/scenic/color.ex

@@ -156,6 +156,13 @@ defmodule Scenic.Color do
     yellow_green: {0x9A, 0xCD, 0x32}
   }
 
+  @g :color_g
+  @ga :color_ga
+  @rgb :color_rgb
+  @rgba :color_rgba
+  @hsv :color_hsv
+  @hsl :color_hsl
+
   @moduledoc """
   APIs to create and work with colors.
 
@@ -180,15 +187,15 @@ defmodule Scenic.Color do
   For HSL and HSV, h is a float between 0 and 360, while the s, v and l values
   are floats between 0 and 100.
 
-  | Format          | Implicit | Explicit  |
-  |---------------|------------------------|-----------|
-  | Named Color | *na* | See the Named Color Table |
-  | Grayscale | `g` | `{:g, g}` |
-  | Gray, Alpha | `{g, a}` | `{:g, {g, a}}` |
-  | Red, Green, Blue | `{r, g, b}` | `{:rgb, {r, g, b}}` |
-  | Red, Green, Blue, Alpha | `{r, g, b, a}` | `{:rgba, {r, g, b, a}}` |
-  | Hue, Saturation, Value | *na* | `{:hsv, {h, s, v}}` |
-  | Hue, Saturation, Lightness | *na* | `{:hsl, {h, s, l}}` |
+  | Format                     | Implicit       | Explicit                    |
+  |----------------------------|----------------|-----------------------------|
+  | Named Color                | *na*           | See the Named Color Table   |
+  | Grayscale                  | `g`            | `{:#{@g}, g}`               |
+  | Gray, Alpha                | `{g, a}`       | `{:#{@ga}, {g, a}}`         |
+  | Red, Green, Blue           | `{r, g, b}`    | `{:#{@rgb}, {r, g, b}}`     |
+  | Red, Green, Blue, Alpha    | `{r, g, b, a}` | `{:#{@rgba}, {r, g, b, a}}` |
+  | Hue, Saturation, Value     | *na*           | `{:#{@hsv}, {h, s, v}}`     |
+  | Hue, Saturation, Lightness | *na*           | `{:#{@hsl}, {h, s, l}}`     |
 
 
   ## Named Colors
@@ -204,26 +211,29 @@ defmodule Scenic.Color do
 
   ## Additional Named Colors
 
-    | Name          | Value                  |
-  |---------------|------------------------|
-  | `:clear` | `{0x80, 0x80, 0x80, 0x00}` |
+  | Name          | Value                       |
+  |---------------|-----------------------------|
+  | `:clear` | `{0x80, 0x80, 0x80, 0x00}`       |
   | `:transparent` | `{0x80, 0x80, 0x80, 0x00}` |
 
   ## Converting Between Color Formats
 
-  By using the functions `to_g`, `to_ga`, `to_rgb`, `to_rgb`, `to_hsl`, and `to_hsv`
-  you can convert between any implicit or explicit color type to any explicit color type.
+  By using the functions `to_g/1`, `to_ga/1`, `to_rgb/1`, `to_rgb/1`,
+  `to_hsl/1`, and `to_hsv/1` you can convert between any implicit or explicit
+  color type to any explicit color type.
   """
 
-  # import IEx
-
   @g :color_g
   @ga :color_ga
   @rgb :color_rgb
   @rgba :color_rgba
   @hsv :color_hsv
   @hsl :color_hsl
 
+  # Epsilon value from JS
+  # https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/EPSILON
+  @epsilon 2.22044e-16
+
   @type implicit ::
           atom
           | {name :: atom, a :: integer}
@@ -534,9 +544,9 @@ defmodule Scenic.Color do
     l = (max + min) / 2
 
     s =
-      case delta do
-        0 -> 0
-        d -> d / (1 - abs(2 * l - 1))
+      cond do
+        delta < @epsilon -> 0.0
+        true -> delta / (1 - abs(2 * l - 1))
       end
 
     {h, s * 100, l * 100}

lib/scenic/component.ex

@@ -210,12 +210,8 @@ defmodule Scenic.Component do
       # --------------------------------------------------------
       defoverridable add_to_graph: 3
     end
-
-    # quote
   end
 
-  # defmacro
-
   @filter_out [
     :cap,
     :fill,
@@ -240,7 +236,6 @@ defmodule Scenic.Component do
   # prepare the list of opts to send to a component as it is being started up
   # the main task is to remove styles that have already been consumed or don't make
   # sense, while leaving any opts/styles that are intended for the component itself.
-  # also, add the viewport as an option.
   @doc false
   @spec filter_opts(opts :: Keyword.t()) :: Keyword.t()
   def filter_opts(opts) when is_list(opts) do

lib/scenic/driver.ex

@@ -887,7 +887,11 @@ defmodule Scenic.Driver do
     name: [type: :atom]
   ]
 
-  @doc false
+  @doc """
+  Validate driver configuration
+
+  Used primarily for dynamic view port creation
+  """
   def validate([]), do: {:ok, []}
 
   def validate(drivers) do

lib/scenic/graph.ex

@@ -68,8 +68,9 @@ defmodule Scenic.Graph do
   that new primitives added to it are inserted into the new group instead of the
   root of the graph.
 
-  Finally, when the group is finished, a translation matrix and a `:text_align` style
-  are added to it. These properties are _inherited_ by the primitives in the group.
+  Finally, when the group is finished, a translation matrix and a `:text_align`
+  style (see `Scenic.Primitive.Style.TextAlign`) are added to it. These
+  properties are _inherited_ by the primitives in the group.
 
   ## Inheritance
 
@@ -575,15 +576,13 @@ defmodule Scenic.Graph do
 
   Pass in a function that accepts a primitive and returns a boolean.
 
-  Returns a list of tuples containing the matching id at the primitive.
-
-  `[{id, primitive}]`
+  Returns a list of primitives.
 
   __Warning:__ This function crawls the entire graph and is thus slower than
   accessing items via a fully-specified id.
   """
 
-  @spec find(graph :: t(), (any -> as_boolean(term()))) :: list({any, Primitive.t()})
+  @spec find(graph :: t(), (any -> as_boolean(term()))) :: list(Primitive.t())
   def find(graph, finder)
 
   # pass in an atom based id, and it will transform all mapped uids

lib/scenic/primitive.ex

@@ -20,15 +20,15 @@ defmodule Scenic.Primitive do
   ## How to use primitives
 
   By far, the easiest way to use primitives is to import the helper functions in
-  [`Scenic.Primitives`](Scenic.Primitives.html). These helpers can both add primitives to
+  `Scenic.Primitives`. These helpers can both add primitives to
   a scene you are building and modify later as you react to events.
 
   ```elixir
   import Scenic.Primitives
 
   @graph Scenic.Graph.build()
-    |> rect( {100, 50}, stroke: {1, :yellow} )
-    |> rectangle( {100, 50}, stroke: {1, :yellow} )
+         |> rect({100, 50}, stroke: {1, :yellow})
+         |> rectangle({100, 50}, stroke: {1, :yellow})
   ```
 
   Once you get a primitive out of a graph via functions such as `Graph.modify`, or `Graph.get`,
@@ -44,21 +44,20 @@ defmodule Scenic.Primitive do
 
   | Helper | Primitive Module | Description |
   |---|---|---|
-  | [`arc/3`](Scenic.Primitives.html#arc/3) | `Scenic.Primitive.Arc` | Draw an arc around a circle |
-  | [`circle/3`](Scenic.Components.html#circle/3) | `Scenic.Primitive.Circle` | Draw a full circle |
-  | [`component/3`](Scenic.Primitives.html#component/3) | `Scenic.Primitive.Component` | Start a child component |
-  | [`ellipse/3`](Scenic.Primitives.html#ellipse/3) | `Scenic.Primitive.Ellipse` | Draw an ellipse |
-  | [`group/3`](Scenic.Primitives.html#group/3) | `Scenic.Primitive.Group` | Create a group |
-  | [`line/3`](Scenic.Primitives.html#line/3) | `Scenic.Primitive.Line` | Draw a line |
-  | [`path/3`](Scenic.Primitives.html#path/3) | `Scenic.Primitive.Path` | Draw a complicated path |
-  | [`quad/3`](Scenic.Primitives.html#quad/3) | `Scenic.Primitive.Quad` | Draw a quad |
-  | [`rect/3`](Scenic.Primitives.html#rect/3) | `Scenic.Primitive.Rectangle` | Draw a rectangle |
-  | [`rrect/3`](Scenic.Primitives.html#rrect/3) | `Scenic.Primitive.RoundedRectangle` | Draw a rounded rectangle |
-  | [`script/3`](Scenic.Primitives.html#script/3) | `Scenic.Primitive.Script` | Run a referenced draw script |
-  | [`sector/3`](Scenic.Primitives.html#sector/3) | `Scenic.Primitive.Sector` | A boolean toggle control. |
-  | [`sprites/3`](Scenic.Primitives.html#sprites/3) | `Scenic.Primitive.Sprites` | Draw a sector |
-  | [`text/3`](Scenic.Primitives.html#text/3) | `Scenic.Primitive.Text` | Draw a string of text |
-  | [`triangle/3`](Scenic.Primitives.html#triangle/3) | `Scenic.Primitive.Triangle` | Draw a triangle |
+  | [`arc/3`](`Scenic.Primitives.arc/3`) | `Scenic.Primitive.Arc` | Draw an arc around a circle |
+  | [`circle/3`](`Scenic.Primitives.circle/3`) | `Scenic.Primitive.Circle` | Draw a full circle |
+  | [`ellipse/3`](`Scenic.Primitives.ellipse/3`) | `Scenic.Primitive.Ellipse` | Draw an ellipse |
+  | [`group/3`](`Scenic.Primitives.group/3`) | `Scenic.Primitive.Group` | Create a group |
+  | [`line/3`](`Scenic.Primitives.line/3`) | `Scenic.Primitive.Line` | Draw a line |
+  | [`path/3`](`Scenic.Primitives.path/3`) | `Scenic.Primitive.Path` | Draw a complicated path |
+  | [`quad/3`](`Scenic.Primitives.quad/3`) | `Scenic.Primitive.Quad` | Draw a quad |
+  | [`rect/3`](`Scenic.Primitives.rect/3`) | `Scenic.Primitive.Rectangle` | Draw a rectangle |
+  | [`rrect/3`](`Scenic.Primitives.rrect/3`) | `Scenic.Primitive.RoundedRectangle` | Draw a rounded rectangle |
+  | [`script/3`](`Scenic.Primitives.script/3`) | `Scenic.Primitive.Script` | Run a referenced draw script |
+  | [`sector/3`](`Scenic.Primitives.sector/3`) | `Scenic.Primitive.Sector` | A boolean toggle control. |
+  | [`sprites/3`](`Scenic.Primitives.sprites/3`) | `Scenic.Primitive.Sprites` | Draw a sector |
+  | [`text/3`](`Scenic.Primitives.text/3`) | `Scenic.Primitive.Text` | Draw a string of text |
+  | [`triangle/3`](`Scenic.Primitives.triangle/3`) | `Scenic.Primitive.Triangle` | Draw a triangle |
   """
 
   alias Scenic.Graph
@@ -145,12 +144,8 @@ defmodule Scenic.Primitive do
                      contains_point?: 2,
                      default_pin: 1
     end
-
-    # quote
   end
 
-  # defmacro
-
   # ============================================================================
   # build and add
 
@@ -163,7 +158,7 @@ defmodule Scenic.Primitive do
   Generic builder to create a new primitive.
 
   This function is used internally. You should almost always use the helpers in
-  [Scenic.Primitives](Scenic.Primitives.html) instead.
+  `Scenic.Primitives` instead.
 
   Parameters:
   * `module` - The module of the primitive you are building
@@ -501,8 +496,8 @@ defmodule Scenic.Primitive do
   @doc """
   Put primitive-specific data onto the primitive.
 
-  Like many of the functions in the Scenic.Primitive module, you are usually better
-  off using the helper functions in [`Scenic.Primitives`](Scenic.Primitives.html) instead.
+  Like many of the functions in the `Scenic.Primitive` module, you are usually better
+  off using the helper functions in `Scenic.Primitives` instead.
 
   Parameters:
   * `primitive` - The primitive

lib/scenic/primitive/component.ex

@@ -7,28 +7,28 @@ defmodule Scenic.Primitive.Component do
   @moduledoc """
   Add a child component to a graph.
 
-  When a scene pushes a graph containing a Component to it's ViewPort,
+  When a scene pushes a graph containing a Component to its ViewPort,
   a new scene, containing the component, is created and added as a child
   to the scene that created it.
 
   Any events the new component creates are sent up the parent. The parent
-  can use functions in the Scenic.Scene module to manage it's children,
+  can use functions in the `Scenic.Scene` module to manage its children,
   send them messages and such.
 
   The standard components, such as button, slider, etc. have wrapper functions
   making them very easy to add to a graph. However, if you have a custom
-  component you can add it to any graph manually using the add_to_graph
+  component you can add it to any graph manually using the `add_to_graph/3`
   function.
 
-  You typically want to give components an :id. This will be used to identify
+  You typically want to give components an `:id`. This will be used to identify
   events coming from that components back to your scene.
 
   ```elixir
   import Components  # contains the button helper
 
   graph
-    |> button( "Press Me", id: :press_me )
-    |> MyComponent.add_to_graph( {"Some data", 123}, id: :my_component )
+  |> button("Press Me", id: :press_me)
+  |> MyComponent.add_to_graph({"Some data", 123}, id: :my_component)
   ```
 
   """

lib/scenic/primitive/style/text_align.ex

@@ -11,7 +11,7 @@ defmodule Scenic.Primitive.Style.TextAlign do
 
   ```elixir
   graph
-    |> text( "Some Text", text_align: :center_middle )
+  |> text("Some Text", text_align: :center)
   ```
 
   ### Data Format