# Class: Button

### LuxModule: gui

A Button is a Component that reacts on mouseclicks and other mouseactions.

Creating a simple button that reacts on mouseclicks is as easy as this:

     btn = Button:new(10,10,80,30,"Hello") -- create button
     function btn:onClicked()  -- function that is called on click events
       print("Hello") -- do whatever you like
     end
       -- put the button now on the root container
     Container.getRootContainer():add(btn)
       -- otherwise it won't be visible

## Hierarchy

    o-+ Component
      o-+ Button
        o-- Checkbox

## Methods:

### Method overview:

- actionListeners
- addActionListener
- clicked
- dataButton
- dataButton.isFocusable
- dataButton.mouseover
- dataButton.pressed
- dataButton.pressedMouseButton
- dataButton.pressedSince
- deleteVisibles
- hideVisibles
- isFocusable
- isPushButton
- isPushed
- mouseEntered
- mouseExited
- mouseMoved
- mousePressed
- mouseReleased
- new
- onAction
- onClicked
- positionUpdate
- removeActionListener
- setCustomL2d
- setDisplayable
- setIcon
- setPushState
- setPushable
- setText
- setVisibility
- toString

new (table class, float x,y,w,h, string caption, [Skin2D skin])
  returns: (Button)

  creates a new Button object.

  The Skin should have 8 states:

  1. button
  2. button_hover
  3. button_pressed
  4. button_hover_pressed
  5. button_focus
  6. button_focus_hover
  7. button_focus_pressed
  8. button_focus_hover_pressed

  If no skin is passed the default skin is cloned.
actionListeners
  {[table]} - a list of all actionlisteners
addActionListener (function action,[string/any description])
  returns: ()
  Adds a function that is called when the button is clicked. The description is optionial. The action function signature:

       function actionfunction (buttonobject,datatable)

  the datatable contains at index 1 the function and at index 2 the description. You can change the datatable in any way you want - however, the function at index 1 will be the function that is being called if an action occurs.
clicked (Button self)
  returns: ()
  called if the button was actually clicked. Is called if the mouse is clicked, but can be called by other sources, too. Calls all actionlistener functions. This method calls the actionlisteners. Overload onClicked instead for simple use.
dataButton
  {[table]} - the current state info of the button.
dataButton.isFocusable
  {[boolean=true]} - can gain focus if true
dataButton.mouseover
  {[boolean]} - true if the mouse is over the button
dataButton.pressed
  {[boolean]} - true if the button is hold down
dataButton.pressedMouseButton
  {[int]} - the mousebuttonid that holds the button down
dataButton.pressedSince
  {[int]} - if button is pressed, this value stores the frame when the mousebutton was pressed
deleteVisibles (Button self)
  returns: ()
  called when a Component is no longer displayed
hideVisibles (Button self)
  returns: ()
  called when visible objects (l2ds) are no longer visible
isFocusable (Component)
  returns: (boolean)

  description from overloaded method of Component:

  returns true if the component can be focused. If you overload this method, please remember that you should return false if your element is current not focusable, ie. if not visible or not enabled.

  For example:

       function TextField.isFocusable()
         return true and self:isVisible()
       end

isPushButton (Button)
  returns: (boolean)
  returns true if the Button is a pushbutton
isPushed (Button)
  returns: (boolean)
  returns true if the Button is pushed
mouseEntered (Button self)
  returns: ()
  sets mouseinside to true
mouseExited (Button self)
  returns: ()
  sets mouseinside and mousedown to false
mouseMoved (Button self, MouseEvent e)
  returns: ()
  called if the mouse actually moved over the button
mousePressed (Button self, MouseEvent e)
  returns: ()
  called if the mouse was pressed on the button
mouseReleased (Button self, MouseEvent e)
  returns: ()
  called if the mouse was released on the button
onAction (Button self)
  returns: ()
  calls directly clicked (invoked by actioncommands such as ENTER on focused buttons
onClicked (Button self, boolean state)
  returns: ()
  simple callback function that can be overloaded without calling the superclass etc. Is called after all ActionListeners has been processed. The state boolean flag is true if the button is currently pushed, which matters only for pushable buttons - otherwise it is always false.
positionUpdate (Button self)
  returns: ()
  updates all the position info
removeActionListener (function/any key)
  returns: ([function,description])
  removes the actionlistener from the object where the key can be the function or the description itself.
setCustomL2d (Component self,[l2dnode, float x, y,z])
  returns: ([l2dnode])
  set a custom l2dnode for own purpose. The previously set custom l2dnode is deleted. The new customl2dnode ist also deleted if the button is deleted. The new customl2dnode is returned by this function. If no l2dnode is given, the old customl2dnode is deleted.
setDisplayable (Component self, boolean displayable)
  returns: ()

  description from overloaded method of Component:

  a displayable component should create all it needs to be displayed (l2dnodes & stuff).
setIcon (texture/string icon, width,height,uvx,uvy,uvw,uvh, [blendmode])
  returns: ()
  sets icon for the button. This is only a forwarder on the Skin2D.setIcon function and will throw an error if no skin is set for this button. The default blendmode is decal. If false is passed as blendmode, no blend is used.
setPushState (Button,boolean)
  returns: ()
  pass true if the button should be pushed. Setting The pushstate won't affect actionlisteners and click functions.
setPushable (Button, pushable, [state])
  returns: ()
  Makes the button pushable. A pushbutton switches between the normal and pressed state. You can use a third optional parameter to set the state to an initial value.
setText ()
  returns: ()
  sets text of button
setVisibility (Component self)
  returns: (boolean)

  description from overloaded method of Component:

  returns true if the component is displayed (is actually on the rootpane) and is visible.
toString (Button self)
  returns: ()
  returns simple string representation of the button

## Inherited Methods:

### From Component

acceptSkinBounds, addKeyListener, addMouseListener, addTooltipListener, clipinsets, colors, contains, createVisibles, delete, deleteVisibles, fadeTo, focus, focuscolors, getBottom, getBounds, getClipRect, getFocusComponentAt, getFocusElement, getFocusIndex, getHeight, getLocation, getMinSize, getMouseLock, getParent, getRight, getSize, getSkin, getTooltip, getWidth, getX, getY, hasFocus, hideVisibles, index, invalidate, isClipped, isDisplayedFlag, isFocusable, isMouseLocker, isVisible, isVisibleFlag, keyEvent, keylisteners, local2world, lockMouse, mouseClicked, mouseEntered, mouseEvent, mouseExited, mouseMoved, mousePressed, mouseReleased, mouseWheeled, mouselisteners, moveToRect, new, newFocusOrder, onDestroy, onDisplayChange, onGainedFocus, onLostFocus, onVisibilityChange, positionUpdate, remove, removeKeyListener, removeMouseListener, removeTooltipListener, setBounds, setClip, setColor, setDisabled, setDisplayable, setFont, setLocation, setSize, setSkin, setTooltip, setVisibility, showTooltipInformation, showVisibles, skinnames.defaultskin, skinnames.focusedskin, skinnames.hoveredskin, skinnames.pressedskin, think, toString, transferFocus, transferFocusOnArrows, transferFocusOnTab, unlockMouse, updateSkin, validate, validateFocus, white, world2local, zorderoffset