Button Objects

#Overview Button objects can only be created after you have a gui object, by calling the gui's addButton method. They are slightly more interesting than labels, being able not only to say things, but, upon being clicked, or having enter pressed when selected, causing things to happen. What kind of things? Whatever things the function you tell it to call does. The limit is your imagination!

Members:

Properties

posX, posY, width, height

The position and dimensions of the button, in screen coordinates.

text

The text of the button. What it says, basically.

onClick

A function that will be called when the button is activated, by clicking or by pressing "enter" when it has focus.

style

The style table to use on this button. By default, inherits the style of it's parent gui object.

gui

the gui object this Button is contained by.

Methods

button:hide()

Hides the button, preventing it from saying it's thing or being clicked and caused to do it's thing.

button:show()

Unhides, or shows, the button, allowing it to once again say it's thing and be clicked to do it's thing.

button:draw()

Forces the button to be redrawn immediately. Useful if you've been directly manipulating it's style or properties from code and need those changes to update.

Handlers

Handlers are properties that can be set to functions that will be called when certain events happen. Some handlers are common to all components, like onClick, while others are specific to certain types, like onScroll. However, some common handlers are implemented internally, and overriding them can cause undesired results. Only those events listed on these pages for a given element type should be assigned in your programs.

onClick(button,mouseX,mouseY,button)

Called whenever the button is clicked on.

onDoubleClick(button,mouseX,mouseY,button)

Called when you double-click on the button.

onBeginDrag(button,mouseX,mouseY,button)

Called when the player begins to drag after clicking and holding on a button. Always follows an onBeginDrag, many of these can be received, and then a final onDrop event will be received when the user released the button. This function can optionally return a drag proxy, an object which will be held on to by the gui and send the remaining onDrag and onDrop events.

onDrag(button,mouseX,mouseY)

called when the player drags after clicking on a button. Always follows an onBeginDrag, many of these can be received, and then a final onDrop event will be received.

onDrop(button,mouseX,mouseY,dropOver)

Called when the player releases the mouse button after dragging a button. The dropOver argument is the gui element the mouse was over when the drop occurred.

Styles

Styles specific to buttons are applied in gui style sheets using the selector "button". Buttons are focusable, so they can be affected styles with the :focus state.

Buttons will inherit the style table used by their containing gui, unless they are explicitly given their own style table. Individual style properties can also be set as values directly on the Button object, ex, "button.text-color=0x00ffff" would make the button's label text bright cyan.

For more general information on styles, see the styles page

###Style Properties

Propery	Value Type	Description
border	boolean	should this button have a border
border-top	boolean	is there a border on the top edge?
border-buttom	boolean	bottom...
border-left	boolean	no other border properties have any
border-right	boolean	effect unless "border" is true
border-color-fg	int1	the fg color of characters in the border
border-color-bg	int1	the bg color used for the border
border-ch-top	char2	the character or unicode hex value used for top border
border-ch-bottom	char2	character used for the bottom border
border-ch-left	char2	character used to draw the left border
border-ch-right	char2	character used to draw the right border
border-ch-corner-topleft	char2	character used to draw the top-left corner
border-ch-corner-bottomleft	char2	character used to draw the bottom-left corner
border-ch-corner-topright	char2	character used to draw the top-right corner
border-ch-corner-bottomright	char2	character used to draw the bottom-right corner
fill-color-fg	int1	fg color of the char filling the body of the window
fill-color-bg	int1	bg color to fill the body of the button
fill-ch	char2	character to fill the body of the button
text-color	int1	color used for the button's label
text-background	int1	background color used for button's label

¹colors are 24-bit, with 8 bits each R, G, and B, and can be given as normal integers, like 0 (which would be black), or hex values, like 0xff0000 (red).

²Characters can be single-character strings, like "+", or hexadecimal unicode identifiers in the format "U+xxxx", ex, U+263a is a smiley face symbol.