1688 posts
'MURICA
Posted 22 December 2013 - 02:34 AM
This is essentially a nice, nameless GUI library that utilizes the concept of an immediate mode GUI. The way it works is that you call a function to create a GUI element, while checking the state of said GUI element at that very instant. As an example for buttons:
The function here creates and "registers" a draw command in the library, while also telling you whether the mouse clicked in the area of that theoretical button. The concept of an IMGUI is to store the state of buttons in the program itself, rather than keep a reference of API-generated classes or objects. In this system, hiding an element is as easy as not calling the function.
Because the GUI functions in this libraries use tables, you can change the properties of buttons if you store them beforehand:
The library right now only supports buttons and sliders.
With the introduction out of the way, onto usage.
imgui.label - Draws a static label with the given text, x and y values in the table. Example:
imgui.button - A regular button. Returns true when clicked, false otherwise. text, x, and y all must be given. width and height default to the size of the text itself, with padding. bgColor and textColor default to the value in the program's defaults table.
Example:
imgui.slider - A slider. x and y must be defined. Can be vertical or horizontal. min and max determine the upper and lower values of the slider, and value determines the value itself of the slider. value defaults to the midpoint between max and min. length is the visual length of the slider.
Example:
imgui.setDefaults(defaults) - Where "defaults" is a table that defines the default values that should be used in drawing GUI elements. The default defaults table:
Any of these values can be redefined using this function.
imgui.clear(color) - Convenience, clears the screen using the given color. If color is not given, will use the current background color.
imgui.register(func) - Used to "register" a function to draw on imgui.draw(). Used by all GUI functions in the library, and can be used to implement custom GUI elements.
imgui.draw - Draws all of the GUI elements.
imgui.pullEvent(filter) - Updates the libraries state, and returns events pulled. Example:
And a much more "colorful" example written to test the library:
You can grab the code from pastebin: pastebin get 5AcWhbc8 imgui
And as always, comments, suggestions, and bug reports are appreciated.
if imgui.button{ text = 'Some Button', x = 5, y = 3 } then
print "I was clicked!"
end
The function here creates and "registers" a draw command in the library, while also telling you whether the mouse clicked in the area of that theoretical button. The concept of an IMGUI is to store the state of buttons in the program itself, rather than keep a reference of API-generated classes or objects. In this system, hiding an element is as easy as not calling the function.
Because the GUI functions in this libraries use tables, you can change the properties of buttons if you store them beforehand:
local button = { text = 'I was not clicked yet', x = 1, y = 1 }
if imgui.button(button) then
button.text = 'I am clicked!'
end
The library right now only supports buttons and sliders.
With the introduction out of the way, onto usage.
imgui.label - Draws a static label with the given text, x and y values in the table. Example:
imgui.label{ text = "Label Text", x = [xpos], y = [ypos] }imgui.button - A regular button. Returns true when clicked, false otherwise. text, x, and y all must be given. width and height default to the size of the text itself, with padding. bgColor and textColor default to the value in the program's defaults table.
Example:
--# all default properties of the button (except text, x, and y which must be defined)
local defaultbutton = {
text = "Button Text";
x = 1, y = 1;
bgColor = colors.blue;
textColor = colors.white;
width = (the width of text);
height = (the height of text);
}
--# a normal button
local button = { text = 'This is a button!', x = 1, y = 1 }
if imgui.button(button) then
button.text = 'I was clicked!'
end
--# a red button
local red = { text = 'This button is red!', x = 1, y = 1, bgColor = colors.red }
if imgui.button(red) then
--# turns into a blue button
red.bgColor = blue
end
imgui.slider - A slider. x and y must be defined. Can be vertical or horizontal. min and max determine the upper and lower values of the slider, and value determines the value itself of the slider. value defaults to the midpoint between max and min. length is the visual length of the slider.
Example:
--# All default slider values (except x and y, which must be defined):
local slider = {
x = 1, y = 1;
bgColor = colors.gray;
fgColor = colors.blue;
length = 20;
orientation = 'horizontal'; --# can also be vertical
min = 0;
max = 1;
value = 0.5;
}
--# regular slider with min and max values 0 and 10
--# will have a default value of 5 unless given
slider = { x = 1, y = 1, min = 0, max = 10 }
--# imgui will update the slider automatically.
imgui.slider(slider)
imgui.setDefaults(defaults) - Where "defaults" is a table that defines the default values that should be used in drawing GUI elements. The default defaults table:
Spoiler
local defaults = {
label = {
bgColor = colors.black;
textColor = colors.white;
};
button = {
bgColor = colors.blue;
textColor = colors.white;
padding = {2, 1};
};
slider = {
orientation = 'horizontal';
length = 20;
bgColor = colors.gray;
fgColor = colors.blue;
min = 0;
max = 1;
};
}imgui.clear(color) - Convenience, clears the screen using the given color. If color is not given, will use the current background color.
imgui.register(func) - Used to "register" a function to draw on imgui.draw(). Used by all GUI functions in the library, and can be used to implement custom GUI elements.
imgui.draw - Draws all of the GUI elements.
imgui.pullEvent(filter) - Updates the libraries state, and returns events pulled. Example:
os.loadAPI('imgui')
local button = { text = "Hello World!", x = 2, y = 2 }
while true do
if imgui.button(button) then
button.bgColor = 2 ^ math.random(14) --# button changes to a random color when clicked
end
imgui.clear(colors.black)
imgui.draw()
ev, p1 = imgui.pullEvent()
if ev == 'key' and p1 == keys.backspace then
return
end
end
And a much more "colorful" example written to test the library:
Spoiler
os.loadAPI('imgui')
-- a regular old button
local button = { text = 'This is a button!', x = 2, y = 4, width = 23 }
-- a toggleable button
-- each property can be mapped to an "on" an "off" state
local toggleable = {
text = 'Toggle button', x = 2, y = 8, width = 23, bgColor = colors.red
}
-- default slider, minimum value 0, maximum value 10
-- value starts at middle by default
local slider1 = { x = 2, y = 14, min = 0, max = 10 }
-- rainbow slider! :D/>/>/>/>/>
local rainbow = {
colors.red, colors.orange, colors.yellow,
colors.lime, colors.green, colors.lightBlue,
colors.blue, colors.purple}
local slider2 = { x = 2, y = 16, min = 1, max = 8, value = 1,
fgColor = colors.red }
-- vertical slider
local vslider = { x = 26, y = 4, length = 10, orientation = 'vertical' }
local timer = os.startTimer(1) -- just to update the clock
while true do
imgui.label{ text = "A simple label", x = 2, y = 2 }
if imgui.button(button) then
button.text = 'I was clicked!'
end
if imgui.button(toggleable) then
toggleable.active = not toggleable.active
toggleable.bgColor = toggleable.active and colors.green or colors.red
end
imgui.label{ text = 'Sliders!', x = 2, y = 13 }
imgui.slider(slider1)
imgui.label{ text = ("%d"):format(slider1.value), x = 23, y = slider1.y }
if imgui.slider(slider2) then
slider2.fgColor = rainbow[math.ceil(slider2.value)]
end
imgui.slider(vslider)
local w,h = term.getSize()
imgui.label{ text = textutils.formatTime(os.time()), x = w - 5, y = h - 1}
imgui.clear(colors.black)
imgui.draw()
ev, p1, p2, p3 = imgui.pullEvent()
if ev == 'key' and p1 == keys.backspace then
break
elseif ev == 'timer' and p1 == timer then
timer = os.startTimer(1)
end
end
You can grab the code from pastebin: pastebin get 5AcWhbc8 imgui
And as always, comments, suggestions, and bug reports are appreciated.
Edited on 22 December 2013 - 10:15 AM
