# | *Sav***IO**
[![Gem Version](https://badge.fury.io/rb/savio.svg)](https://badge.fury.io/rb/savio)
## What is it?

SavIO is an input/output library created to be used with **Ruby2D**. It adds multiple ways for the user to interact with your application, including :

 - Sliders
 - Buttons
 - Text Input
 - Color Picker (Work In Progress)

## How to install?

Easy! do:

    gem install savio

then in your program do:

    require "savio"

## How do they work?


 Good question! Part of the goal when developing SavIO was to make it as **intuitive** and **simple** as possible, while also being highly **versatile**, **powerful**, and **customizable**.

# | ALL OBJECTS
#### All SavIO objects inherit these basic properties.

#### You can access an array of all SavIO Objects by using Savio.elements
##### Example:

    Savio.elements.each do |element|
	    element.x += 1 #Moves all elements over by 1 pixel
    end

##### SavIO Commands:
    Savio.hide         #This will hide all elements
    Savio.unhide       #This will bring them all back
    Savio.stop         #This stops the mouse and keyboard event listeners
    Savio.listen       #Starts the mouse and keyboard event listeners
    Savio.listening    #returns true or false if its listening or not


## **Creation:**

    myAwesomeOBJECT = OBJECTNAME.new(params)

### Params:

all SavIO object's parameters are optional, if it is not defined then it will use the default.

| Variable | Description | Default |
|--|--|--|
| x | The x position | 0
| y | The y Position | 0
| z | The z Position | 1
| size | The scaling value | 10
| enabled | If the object can be interacted with by the user | true
| displayName | The name of the object | ""
| draggingEnabled | If the object itself can be moved around the window | false
| dragType | "move" or "duplicate" If draggingEnabled is true, this is what happens when it drags | "move"
| shown | If the object is shown or not | true

### Example:

`myAwesomeOBJECT = OBJECTNAME.new(x: 100, y: 30, z:2, size: 13, displayName: "Swag")`


### Methods:
----
| Method | Description |
|--|--|
|.remove() | removes the object from the screen |
| .add() | adds the object back to the screen |
|.rebuild() | rebuilds the object |
|.context() | returns a hash with all the variables that make the object |

# | Sliders:
**On top of** all the basic parameters and methods a **Slider** can **also** use these:

### Params:
| Variable | Description | Default |
|--|--|--|
|length | How long the slider is | 100
|min | The minimum value of the slider | 0
|max | The maximum value of the slider | 100
|value| The value of the slider | Random between min and max
|style|'knob' or 'fill' changes the style the slider is shown with|'knob' |
|showValue| If the value label should be shown| true
|labelColor| The color of the labels| '#F5F5F5'
|sliderColor| Color of the slider line | '#757575'
|knobColor| Color of the sliders knob | '#5BB36A'

### Example:

    slippyTheSlider = Slider.new(x: 830, y: 40, length: 220, draggingEnabled: true, dragType: "duplicate")

### Methods:
----
| Method | Description |
|--|--|
|.moveKnob(**x**) | Moves the knob to that **x** pixel location on the screen and finds and sets equivalent value for the slider |
|.setValue(**value**)|Sets the sliders value to that value and moves the knob there (same as .value=)|
| .value = **value** | Sets the sliders value to that **value** and moves the knob there (same as .setValue)|
|.onChange| Calls the given proc any time the sliders **value** is updated(see basic usage)|

### Basic Usage:

    if slippyTheSlider.value == 69
	    puts "nice"
    end

-----

    slippyTheSlider.onChange do
      puts "Value Changed! new value is: " + slippyTheSlider.value.to_s
    end

# | Buttons:
**On top of** all the basic parameters and methods a **Button** can **also** use these:

### Params:
| Variable | Description | Default |
|--|--|--|
|selected | Whether the button is selected or not | false
|type | Whether the button will act normally('toggle') or instantly deselect itself('clicker') | 'toggle'
|style|'box' or 'badge'. Determines the style the button should be rendered with| 'badge'
|length|Only used for the 'box' style. Determines the length of the button| @size * 10
|height|Only used for the 'box' style. Determines the height of the button| @size * 1.2
|cooldownTime|Time needed to wait in seconds until the button may be clicked again| 0.0
|buttonManager | The manager that controls this button | nil
|enforceManager| When a manager is defined, whether the manager should force this button to follow its rule | true
|baseColor| Color shown when the button is deselected| '#F5F5F5'
|selectedColor|Color shown when the button is selected | '#00B3EC'
|labelColor| Color of the buttons displayName label | '#F5F5F5'

### Example:

    clickyBob = Button.new(
      x: 830, y: 90,
      displayName: "Enable Bob?",
      selectedColor: "purple",
      type : 'clicker'
    )
-----
    anotherButton = Button.new(
      x: 830, y: 150,
      displayName: "Enable flux capacitors?",
    )


### Methods:
----
| Method | Description |
|--|--|
|.select(*enforce*) | Selects the button. if left empty *enforce* will be the buttons **@enforceManager** state. when true the manager will enforce its rule on the button. when false, the button will perform as if it were not controlled. |
|.deselect(*enforce*) | Deselects the button. *enforce* works the same as .select() *(see above)* |
|.toggle(*enforce*) | Toggles the buttons Selection state. *enforce* works the same as .select() *(see above)*
|.selected = **bool** | Selects or deselects the button whether given true or false |
|.timeLastClicked| returns the unix time of the last click
| .onClick | Takes in a proc that will be ran every time the button gets selected (See example and basic usage)|

### Basic Usage:

    clickyBob.onClick do
	    puts "Bob is now enabled! Hi Bob!"
    end
-----
    if anotherButton.selected == true do
      puts "Flux capacitors now enabled"
    end

# | ButtonManager:
Now I'm sure after reading how a **button** works you're saying, "What in the hell is a **manager**?"

## Let me explain, it's **very simple**.
A **ButtonManager** is a simple and easy way to **manage a group of multiple buttons**.  More specifically, it **controls** the state of **all the buttons** in its group **depending on** the state of **all the other buttons** in its group.

## This is not considered a standard SavIO Object and does not inherit the typical parameters and methods.

### Creation:

    theSwagMaster = ButtonManager.new(type: "checkbox")


### Params:
| Param |Description  | Default|
|--|--|--|
| type | either "radio" or "checkbox" Decides how the manager should control its buttons | "radio"

### Methods:
----
| Method | Description |
|--|--|
|.addButton(**button**) | Adds the **button** to the group of buttons controlled by the manager. This is done automatically when a buttons **@buttonManager** is set to the manager. If called this way however, it will also automatically set the buttons **@buttonManager** to this manager, so they will always be linked.|
|.removeButton(**button**, *overwrite*) | Removes the **button** from the group of buttons controlled by the manager. This is done automatically when a buttons **@buttonManager** is changed or removed. *overwrite* is not required and is automatically set to true. When true, this will overwrite the **button**'s **@buttonManager** and set it to nil. When false it will not overwrite the buttons **@buttonManager**. **It is highly recommended not to change this since** it will desynchronize the button and manager and cause issues. It is used internally to prevent recursion when removed the manager from the **button** rather than from the **manager**
|.toggle(**button**) | Toggles the **button** according to the rule of the manager. This is done automatically by the **button** when **button**.toggle() is called and this manager is used. This is true also for .select() and .deselect().
| .select(**button**) | Selects the **button** according to the rule of the manager.
| .deselect(**button**) | Deselects the **button** according to the rule of the manager |

### Variables :
|Variable|Description  | Type |
|--|--|--|
| buttons |an array of all the buttons that are controlled by this manager  |array |
| selected | an array of all the buttons that are currently selected and in control of this manager | array |


### Basic Usage:

    theSwagMaster.selected.each do |button|
	    puts button.to_s + " Is currently selected!"
    end
--

    if theSwagMaster.selected.include?(button)
	    puts "This button is currently selected!"
    end

# | InputBox:
**On top of** all the basic parameters and methods an **InputBox** can **also** use these:
### Params:
| Variable | Description | Default |
|--|--|--|
|selected | Whether it is currently focused | false
|value | The current text input in the field | **@displayName**
|displayName | The value shown in the text field when nothing is in it. AKA the default value. if a value was specified, this will be overwritten with it. | **@value** or "Default"
|length| The length of the text box | **@size** * 10
|width| The width of the text box| **@size** * 1.2
|color| The color of the box when not focused| '#F5F5F5'
|activeColor|The color of the box when focused | '#5BB36A'
|activeTextColor| The color of the text when focused | '#F5F5F5'
|inactiveTextColor| The color of the text when not focused | '#757575'

### Example:

    askMeAnything = InputBox.new(
      x: 830, y: 180, size: 30,
      activeColor: 'purple',
      displayName: "What would you like to ask?"
    )

### Methods:
----
| Method | Description |
|--|--|
|.addKey(**key**) | Simulates a key input of given **key** |
| .updateDisplay() | Adds the line follower marker to the text box |
|.select() | Focuses the text box and lets you type in it |
|.deselect() | Loses focus of the text box and finalizes value|
|.toggle() | Toggles the selection value of the text box |
|.selected=(**bool**) | Selects or deselects the text box based on the **bool**  |

### Basic Usage:

    if askMeAnything.value == "Favorite Color?"
	    puts "Purple"
    end

# | ColorSlider:
These technically work but I'm not done with them so for now I wont bother with documentation.