Each command that creates a widget returns a reference (handle) to the created widget. You can either store this handle within a variable at creation time or use the .GetHandle() command at any later time to get the handle of a certain widget.
The main purpose of the GetHandle() command is to eliminate the need to store any permanent references to your widgets. Remember, objects cannot be deleted from memory as long as a single reference to them exists, so it's a good programming style to NOT store any permanent references to your widgets, but to use the GetHandle() command any time you want to directly access a widget.
-- LOAD THE LIBRARY AND USE A GLOBAL VAR TO STORE A REFERENCE:
_G.GUI = require("widget_candy")
-- CREATE A BUTTON
x = 50,
y = 50,
theme = "MyTheme",
name = "Button1",
-- GET THE HANDLE OF THIS BUTTON
local MyButton = _G.GUI.GetHandle("Button1")
-- OR IN SHORT:
widgetName (String) The name of a widget.
Returns: (Widget Handle) A handle (reference) to the specified widget. This handle can then be used to access any widget methods or properties.