Skip to content

Commit af427d7

Browse files
boydmboydm
committed
improving docs. Add basic docs for components
1 parent 88e186c commit af427d7

21 files changed

+573
-55
lines changed

‎lib/scenic/component/button.ex‎

Lines changed: 72 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,77 @@
11
defmodule Scenic.Component.Button do
2-
@moduledoc false
2+
@moduledoc """
3+
Add a button to a graph
34
5+
A button is a small scene that is pretty much just some text drawn over a
6+
rounded rectangle. The button scene contains logic to detect when the button
7+
is pressed, tracks it as the pointer moves around, and when it is released.
8+
9+
## Data
10+
11+
`title`
12+
13+
* `title` - a bitstring describing the text to show in the button
14+
15+
## Messages
16+
17+
If a button press is successful, it sends an event message to the host scene
18+
in the form of:
19+
20+
{:click, id}
21+
22+
## Styles
23+
24+
Buttons honor the following standard styles
25+
26+
* `:hidden` - If `false` the component is rendered. If `true`, it is skipped.
27+
The default is `false`.
28+
* `:theme` - The color set used to draw. See below. The default is `:primary`
29+
30+
## Additional Styles
31+
32+
Buttons honor the following list of additional styles.
33+
34+
* `:width` - pass in a number to set the width of the button.
35+
* `:height` - pass in a number to set the height of the button.
36+
* `:radius` - pass in a number to set the radius of the button's rounded
37+
rectangle.
38+
* `:alignment` - set the alignment of the text inside the button. Can be one
39+
of `:left, :right, :center`. The default is `:center`.
40+
* `:button_font_size` - the size of the font in the button
41+
42+
Buttons do not use the inherited `:font_size` style as they should look
43+
consistent regardless of what size the surrounding text is.
44+
45+
## Theme
46+
47+
Buttons work well with the following predefined themes:
48+
`:primary`, `:secondary`, `:success`, `:danger`, `:warning`, `:info`,
49+
`:text`, `:light`, `:dark`
50+
51+
To pass in a custom theme, supply a map with at least the following entries:
52+
53+
* `:text` - the color of the text in the button
54+
* `:background` - the normal background of the button
55+
* `:active` - the background while the button is pressed
56+
57+
## Usage
58+
59+
You should add/modify components via the helper functions in
60+
[`Scenic.Components`](Scenic.Components.html#button/3)
61+
62+
### Examples
63+
64+
The following example creates a simple button and positions it on the screen.
65+
66+
graph
67+
|> button("Example", id: :button_id, translate: {20, 20})
68+
69+
The next example makes the same button as before, but colors it as a warning
70+
button. See the options list above for more details.
71+
72+
graph
73+
|> button("Example", id: :button_id, translate: {20, 20}, theme: :warning)
74+
"""
475
use Scenic.Component, has_children: false
576

677
alias Scenic.Graph

‎lib/scenic/component/input/checkbox.ex‎

Lines changed: 49 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,53 @@
11
defmodule Scenic.Component.Input.Checkbox do
2-
@moduledoc false
2+
@moduledoc """
3+
Add a checkbox to a graph
4+
5+
## Data
6+
7+
`{text, checked?}`
8+
9+
* `text` - must be a bitstring
10+
* `checked?` - must be a boolean and indicates if the checkbox is set.
11+
12+
## Messages
13+
14+
When the state of the checkbox, it sends an event message to the host scene
15+
in the form of:
16+
17+
`{:value_changed, id, checked?}`
18+
19+
## Styles
20+
21+
Buttons honor the following standard styles
22+
23+
* `:hidden` - If `false` the component is rendered. If `true`, it is skipped.
24+
The default is `false`.
25+
* `:theme` - The color set used to draw. See below. The default is `:dark`
26+
27+
## Theme
28+
29+
Checkboxes work well with the following predefined themes: `:light`, `:dark`
30+
31+
To pass in a custom theme, supply a map with at least the following entries:
32+
33+
* `:text` - the color of the text in the button
34+
* `:background` - the background of the box
35+
* `:border` - the border of the box
36+
* `:active` - the border of the box while the button is pressed
37+
* `:thumb` - the color of the check mark itself
38+
39+
## Usage
40+
41+
You should add/modify components via the helper functions in
42+
[`Scenic.Components`](Scenic.Components.html#checkbox/3)
43+
44+
### Examples
45+
46+
The following example creates a checkbox and positions it on the screen.
47+
48+
graph
49+
|> checkbox({"Example", true}, id: :checkbox_id, translate: {20, 20})
50+
"""
351

452
use Scenic.Component, has_children: false
553

‎lib/scenic/component/input/dropdown.ex‎

Lines changed: 75 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,82 @@
44
#
55

66
defmodule Scenic.Component.Input.Dropdown do
7-
@moduledoc false
7+
@moduledoc """
8+
Add a dropdown to a graph
89
10+
## Data
11+
12+
`{items, initial_item}`
13+
14+
* `items` - must be a list of items, each of which is: `{text, id}`. See below...
15+
* `initial_item` - the `id` of the initial selected item. It can be any term
16+
you want, however it must be an `item_id` in the `items` list. See below.
17+
18+
Per item data:
19+
20+
`{text, item_id}`
21+
22+
* `text` - a string that will be shown in the dropdown.
23+
* `item_id` - any term you want. It will identify the item that is
24+
currently selected in the dropdown and will be passed back to you during
25+
event messages.
26+
27+
## Messages
28+
29+
When the state of the checkbox, it sends an event message to the host scene
30+
in the form of:
31+
32+
`{:value_changed, id, selected_item_id}`
33+
34+
## Options
35+
36+
Dropdowns honor the following list of options.
37+
38+
## Styles
39+
40+
Buttons honor the following styles
41+
42+
* `:hidden` - If `false` the component is rendered. If `true`, it is skipped.
43+
The default is `false`.
44+
* `:theme` - The color set used to draw. See below. The default is `:dark`
45+
46+
## Additional Styles
47+
48+
Buttons honor the following list of additional styles.
49+
50+
* `:width` - pass in a number to set the width of the button.
51+
* `:height` - pass in a number to set the height of the button.
52+
* `:direction` - what direction should the menu drop. Can be either `:down`
53+
or `:up`. The default is `:down`.
54+
55+
## Theme
56+
57+
Dropdowns work well with the following predefined themes: `:light`, `:dark`
58+
59+
To pass in a custom theme, supply a map with at least the following entries:
60+
61+
* `:text` - the color of the text
62+
* `:background` - the background of the component
63+
* `:border` - the border of the component
64+
* `:active` - the background of selected item in the dropdown list
65+
* `:thumb` - the color of the item being hovered over
66+
67+
## Usage
68+
69+
You should add/modify components via the helper functions in
70+
[`Scenic.Components`](Scenic.Components.html#dropdown/3)
71+
72+
## Examples
73+
74+
The following example creates a dropdown and positions it on the screen.
75+
76+
graph
77+
|> dropdown({[
78+
{"Dashboard", :dashboard},
79+
{"Controls", :controls},
80+
{"Primitives", :primitives}
81+
], :controls}, id: :dropdown_id, translate: {20, 20})
82+
"""
983
use Scenic.Component, has_children: false
1084

1185
alias Scenic.Graph

‎lib/scenic/component/input/radio_group.ex‎

Lines changed: 74 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,78 @@
11
defmodule Scenic.Component.Input.RadioGroup do
2-
@moduledoc false
2+
3+
@moduledoc """
4+
Add a radio group to a graph
5+
6+
## Data
7+
8+
`radio_buttons`
9+
10+
* `radio_buttons` must be a list of radio button data. See below.
11+
12+
Radio button data:
13+
14+
`{text, radio_id, checked? \\\\ false}`
15+
16+
* `text` - must be a bitstring
17+
* `button_id` - can be any term you want. It will be passed back to you as the
18+
group's value.
19+
* `checked?` - must be a boolean and indicates if the button is selected.
20+
`checked?` is not required and will default to `false` if not supplied.
21+
22+
## Messages
23+
24+
When the state of the radio group changes, it sends an event message to the
25+
host scene in the form of:
26+
27+
`{:value_changed, id, radio_id}`
28+
29+
## Options
30+
31+
Radio Buttons honor the following list of options.
32+
33+
* `:theme` - This sets the color scheme of the button. This can be one of
34+
pre-defined button schemes `:light`, `:dark`, or it can be a completely custom
35+
scheme like this: `{text_color, box_background, border_color, pressed_color,
36+
checkmark_color}`.
37+
38+
## Styles
39+
40+
Radio Buttons honor the following styles
41+
42+
* `:hidden` - If `false` the component is rendered. If `true`, it is skipped.
43+
The default is `false`.
44+
* `:theme` - The color set used to draw. See below. The default is `:dark`
45+
46+
## Theme
47+
48+
Radio buttons work well with the following predefined themes: `:light`,
49+
`:dark`
50+
51+
To pass in a custom theme, supply a map with at least the following entries:
52+
53+
* `:text` - the color of the text
54+
* `:background` - the background of the component
55+
* `:border` - the border of the component
56+
* `:active` - the background of the circle while the button is pressed
57+
* `:thumb` - the color of inner selected-mark
58+
59+
## Usage
60+
61+
You should add/modify components via the helper functions in
62+
[`Scenic.Components`](Scenic.Components.html#radio_group/3)
63+
64+
## Examples
65+
66+
The following example creates a radio group and positions it on the screen.
67+
68+
graph
69+
|> radio_group([
70+
{"Radio A", :radio_a},
71+
{"Radio B", :radio_b, true},
72+
{"Radio C", :radio_c},
73+
], id: :radio_group_id, translate: {20, 20})
74+
"""
75+
376
use Scenic.Component, has_children: true
477

578
alias Scenic.Graph

‎lib/scenic/component/input/slider.ex‎

Lines changed: 66 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,70 @@
11
defmodule Scenic.Component.Input.Slider do
2-
@moduledoc false
2+
@moduledoc """
3+
Add a slider to a graph
4+
5+
## Data
6+
7+
`{ extents, initial_value}`
8+
9+
* `extents` gives the range of values. It can take several forms...
10+
* `{min, max}` If `min` and `max` are integers, then the slider value will
11+
be an integer.
12+
* `{min, max}` If `min` and `max` are floats, then the slider value will be
13+
an float.
14+
* `[a, b, c]` A list of terms. The value will be one of the terms
15+
* `initial_value` Sets the initial value (and position) of the slider. It
16+
must make sense with the extents you passed in.
17+
18+
## Messages
19+
20+
When the state of the slider changes, it sends an event message to the host
21+
scene in the form of:
22+
23+
`{:value_changed, id, value}`
24+
25+
### Options
26+
27+
Sliders honor the following list of options.
28+
29+
## Styles
30+
31+
Sliders honor the following styles
32+
33+
* `:hidden` - If `false` the component is rendered. If `true`, it is skipped.
34+
The default is `false`.
35+
* `:theme` - The color set used to draw. See below. The default is `:dark`
36+
37+
## Theme
38+
39+
Sliders work well with the following predefined themes: `:light`, `:dark`
40+
41+
To pass in a custom theme, supply a map with at least the following entries:
42+
43+
* `:border` - the color of the slider line
44+
* `:thumb` - the color of slider thumb
45+
46+
## Usage
47+
48+
You should add/modify components via the helper functions in
49+
[`Scenic.Components`](Scenic.Components.html#slider/3)
50+
51+
## Examples
52+
53+
The following example creates a numeric slider and positions it on the screen.
54+
55+
graph
56+
|> slider({{0,100}, 0}, id: :num_slider, translate: {20,20})
57+
58+
The following example creates a list slider and positions it on the screen.
59+
60+
graph
61+
|> slider({[
62+
:white,
63+
:cornflower_blue,
64+
:green,
65+
:chartreuse
66+
], :cornflower_blue}, id: :slider_id, translate: {20,20})
67+
"""
368

469
use Scenic.Component, has_children: false
570

0 commit comments

Comments
 (0)