| 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 ||
puts .to_s + " Is currently selected!"
end
--
if theSwagMaster.selected.include?()
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.