# Class: Component

### LuxModule: gui

A Component is a 2D object on the screen that allows interaction with the mouse and keyboard of the user.

All coordinates are always relative to the parent's Component.

All components will propagate mouseevents to its parents! If the mouse is moved on a child, the parent that cannot "see" the mouse will receive events, too. This change was done in 0.93a. The reason is, that it is easier for the parent components to trace the mouse actions (i.e. mousewheel) in an easy manner. Most mouse actions are now receiving a second argument that tells, if the component is the owner of the mouse, which means that it is the topmost component at the mouse cursor's position.

## Hierarchy

    o-+ Component
      o-+ Button
      | o-- CheckBox
      o-+ Container
      | o-- ComboBox
      | o-- GroupFrame
      | o-- ListBox
      | o-- TitleFrame
      o-- ContainerMover
      o-- ContainerResizer
      o-- ImageComponent
      o-+ Label
      | o-- MultiLineLabel
      o-- Slider
      o-- TextField

## Methods:

### Method overview:

- acceptSkinBounds
- addKeyListener
- addMouseListener
- addTooltipListener
- clipinsets
- colors
- contains
- createVisibles
- delete
- deleteVisibles
- fadeTo
- focus
- focuscolors
- getBottom
- getBounds
- getClipRect
- getFocusComponentAt
- getFocusElement
- getFocusIndex
- getHeight
- getLocation
- getMinSize
- getMouseLock
- getMouseLockPos
- 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
- setDefaultUI
- 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

new (table class, int x,y,w,h, [Skin2D skin])
  returns: (Component)
  creates a component with the given bounds of type class. A Component may optionally be initialized with a Skin2D skin, a visual representation of the Component.
acceptSkinBounds (Component,[accepts])
  returns: ([accepts])

  sets or gets behaviour of sizing. A skin may have other preferred sizes than chosen by the component. In that case, the component may have different preferred sizes than expected. Per default, this value is true.

  If no skin is set, this value has no meaning
addKeyListener (Component self, KeyListener kl)
  returns: ()
  add a keylistener to the component
addMouseListener (Component self, MouseListener ml)
  returns: ()
  add a mouselistener to the component
addTooltipListener (Component self, function)
  returns: (function)
  adds a tooltiplistener. The function will receive a Tooltipevent as only argument when fired.
clipinsets
  [table] - top, right, bottom, left inset values, default = 0,0,0,0
colors
  [table] - array containing all defaultcolors
contains (Component self, float x,y)
  returns: (boolean)
  checks if the given point is inside the component. Overload this method if you need more specific hittests than a rectangletest. Coordinates are relative.
createVisibles (Component self,l2dnode basel2d)
  returns: ()
  called when a Component is now displayable (doesn't have to be visible)
delete (Component self)
  returns: ()
  deletes the component. Removes the component from any parent object and calls Component.onDestroy, that is also called when the Component is garbagecollected. Never overload delete, use onDestroy for custom actions instead.
deleteVisibles (Component self)
  returns: ()
  called when a Component is no longer displayed
fadeTo (Component self, table skincolor,table labelcololor, table iconcolor, speed,delay,onfinish,oncancel)
  returns: ()

focus (Component self)
  returns: ()
  registers an element as the new focusowner.
focuscolors
  [table] - array containing all defaultcolors on focus
getBottom ()
  returns: (int)
  returns y+height, which is the bottomline of the component
getBounds ()
  returns: (Rectangle rect)
  returns a copy of the current bounds, EVEN if the component hasn't been validated yet.
getClipRect (Component)
  returns: (Rectangle)
  returns clipping of the component. The function traverses to the root to find out the clipping region until the component has no parent any more.
getFocusComponentAt ([Component], int direction)
  returns: (Component)
  returns focuselement. If Component is given, the direction is relative to the component, if not, the absolute focuselement is returned. Only elements that return true on isFocusable are counted.
getFocusElement ()
  returns: ([Component])
  returns the current element of focus if available
getFocusIndex (Component self)
  returns: ()
  returns absolute index of the focusorder
getHeight ()
  returns: (int)
  returns current height
getLocation ()
  returns: (int x,y)
  returns current Location
getMinSize (Component self)
  returns: (Rectangle)
  returns minimum size of component
getMouseLock ()
  returns: (Component)
  returns the Component that is currently locking the mouse.
getMouseLockPos ([Component])
  returns: ([x,y])
  returns the coordinates of the MouseCursor when lock occured in component's space or nil.
getParent ()
  returns: (Container)
  returns parent container if exists
getRight ()
  returns: (int)
  returns x+width, which is the rightmostline of the component
getSize (Component self)
  returns: (float w,h)
  gets size of the Component
getSkin (Component)
  returns: ([Skin2D])
  returns the skin used for this component
getTooltip (Component self)
  returns: ([string text / Component component])
  returns the set tooltip information or nil if not present
getWidth ()
  returns: (int)
  returns current width
getX ()
  returns: (int)
  returns current local x origin
getY ()
  returns: (int)
  returns current local y origin
hasFocus (Component)
  returns: (boolean)
  returns true if the element is focused
hideVisibles (Component self)
  returns: ()
  called when visible objects (l2ds) are no longer visible
index
  {[int]} - index id of the component
invalidate (Component self)
  returns: ()
  marks component to be updated on next validation
isClipped ([Component])
  returns: (boolean)
  returns state of clipping, is the global or of the component
isDisplayedFlag
  {[boolean]} - true if the component is on the rootpane
isFocusable (Component)
  returns: (boolean)

  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

isMouseLocker (Component)
  returns: (boolean)
  returns true if the component is locking the mouse
isVisible (Component self)
  returns: (boolean)
  returns true if the component is displayable and visible, otherwise false
isVisibleFlag
  {[boolean]} - true if the component is visible
keyEvent ([Component],KeyEvent)
  returns: ()
  called if a keyevent occurred and the component has the focus. If a tab was pressed and transferFocusOnTab returns true, the focus is transfered. If enter was pressed and a onAction function is present, onAction is called. Otherwise the components keylisteners are called.
keylisteners
  {[table]} - list of keylisteners
local2world (int localx,localy)
  returns: (int worldx,worldy)
  returns world coordinates
lockMouse (Component)
  returns: ()
  locks the mouse to this component. As long as the mouse is locked, no other component will receive mouseevents. This does not affect MouseListeners that are attached to the MouseCursor. The current MouseCursor coordinates are stored and can be queried later with Component.getMouseLockPos.
mouseClicked (Component self, MouseEvent e, boolean mouseover)
  returns: ()
  called if the mouse was clicked on the component.
mouseEntered (Component self, MouseEvent e, boolean mouseover)
  returns: ()
  called if the mouse is entered the Component
mouseEvent (Component self, MouseEvent e)
  returns: ()
  called if a mouseevent occurred that is interesting to this component. It will informa all mouselisteners of the component of this action.
mouseExited (Component self, MouseEvent e)
  returns: ()
  called if the mouse is exited the component
mouseMoved (Component self, MouseEvent e, boolean mouseover)
  returns: ()
  called if the mouse actually moved over the Component.
mousePressed (Component self, MouseEvent e, boolean mouseover)
  returns: ()
  called if the mouse was pressed on the component. If mouseover is true, the mouse is actually on THIS component and not on one of its childs, which will create events too.
mouseReleased (Component self, MouseEvent e, boolean mouseover)
  returns: ()

       called if the mouse was released on the component

mouseWheeled (Component self, MouseEvent e, boolean mouseover)
  returns: ()
  called if the mousewheel was moved on the component
mouselisteners
  {[table]} - list of mouselisteners
moveToRect (Component self, x,y,w,h,speed,[delay],[onfinish],[oncancel])
  returns: ()

  moves a component animated to a certain target. The given x,y, w,h are the target bounds. The speed must be a factor between 0 and 1, where 1 is the fastest while 0 will never reach the target. The delay is the amount of milliseconds to be waited after each step (it is using a TimerTask to perform the animation). The onfinish function is the function to be called if the target is reached.

  If the animation is interupted by another animation call, the oncancel function will be called.
newFocusOrder (table new)
  returns: (table old)
  Sets a new focus order list as given in the passed table. It returns the old focuslist then and sets the current focuselement to nil. This method can be used to create modal dialogs, though you have to watch out to restore the list again, once the old elements should be accesible again.
onDestroy (Component self)
  returns: ()
  called if the garbage collector collects the object or if the component was deleted. Overload this method for custom actions, i.e. deleting all l2dnodes etc.
onDisplayChange (Component self, boolean isDisplayed)
  returns: ()

  called whenever the displaystate is changed, i.e. if the component was made invisible, or it's parent was removed from the rootpane etc.

  A component that is displayed has not to be visible.
onGainedFocus (Component,Component fromcomponent)
  returns: ()
  event if the component gained the focus from fromcomponent.
onLostFocus (Component,Component tocomponent)
  returns: ()
  event if the component lost the focus to tocomponent.
onVisibilityChange (Component self, boolean isVisible)
  returns: ()
  called whenever the component is made visible / invisible.
positionUpdate (Component self,int zindex,Rectangle clip)
  returns: (int newz)
  called when the component was moved or resized. Overload this method for visual appearance. The zindex is the id to use for zordering the components. Return the newz value, reserving all the values that you require for your visual nodes.
remove (Component self)
  returns: ()
  removes the Component from its parent object.
removeKeyListener (Component self, KeyListener kl)
  returns: ()
  removes kl from the list of keylisteners
removeMouseListener (Component self, MouseListener ml)
  returns: ()
  removes ml from the list of mouselisteners
removeTooltipListener (Component self, function)
  returns: ()
  removes all functions that are equal to entries in the tooltiplistener list
setBounds (Component self, float x,y,w,h)
  returns: ()
  sets bounds of the Component. Changes will be done when validate is called, which is done every frame once for all (drawn) components.
setClip ([Component],boolean on)
  returns: ()
  Disables/Enables the clipping of the component(s). If no Component is passed, this is used as a GLOBAL parameter, not per component. It will affect only components that are going to be created. Clipping is done using the scissortest of OpenGL. These areas however can only be rectangular and may produce unwanted sideeffects if you use a different window.refsize than the screen resolution or if you want to rotate the components (which is possible but yet supported). Setting the clip to nil for a component will make it use the global parameter value. Currently, this parameter is only working correctly if disabled globally.
setColor (Component self, table skincolor,table labelcololor, table iconcolor, [mix a=0], [mix b=1])
  returns: ()

setDefaultUI ([skin],[icons])
  returns: ()
  sets the skin and iconset to be used as default. this will not affect existing GUI components, only new GUI elements are affected.
setDisabled (Component,boolean yes)
  returns: ()

  disabled components won't generate mouse or keyevents. The Component's skin is set to half transparent, storing the previous alpha value and keeping the current rgb value.

setDisplayable (Component self, boolean displayable)
  returns: ()
  a displayable component should create all it needs to be displayed (l2dnodes & stuff).
setFont (Component,[string font])
  returns: ()
  sets fontname to be used. Pass noting if you want to use the defaultfont again.
setLocation (Component self, float x,y)
  returns: ()
  sets location of the Component
setSize (Component self, float w,h)
  returns: ()
  sets size of the Component
setSkin (Component, [Skin2D,[boolean copy] ])
  returns: ()

  sets a skin to be used for displaying this component. If no value is set, the skin is removed. Invalidates the Component.

  If then skin is a string named "default" a default skin is used.

  If copy is true, the skin's cloning function is called to create a copy of that skin.

  The Component class is using following skin surface mappings:

  1. component - simple default surface
  2. component_hover - highlighted surface if mouse is over the component
  3. component_pressed - if the mouse is clicked on the component
setTooltip (Component self, [nil / string text / Component component])
  returns: ()
  Sets tooltip information for this component, which is shown if the mouse holding its position. Passing nil will delete the tooltip information, setting a string will show the string as a simple textlabel, which is multilinecapable. If a component is passed, this component will be shown in the quickinfobox or whatever is showing the results. Setting the tooltip while it is shown will not affect the way it is displayed
setVisibility (Component self)
  returns: (boolean)
  returns true if the component is displayed (is actually on the rootpane) and is visible.
showTooltipInformation (Component self)
  returns: ()
  triggers displaying the tooltip information. It will look if the component has a function set named
showVisibles (Component self)
  returns: ()
  called when visible objects (l2ds) are now visible
skinnames.defaultskin
  {[string]} = component - default skin-string for default cases
skinnames.focusedskin
  {[string]} = component_focus - default skin-string for focused cases
skinnames.hoveredskin
  {[string]} = component_hover - default skin-string for hovered cases
skinnames.pressedskin
  {[string]} = component_pressed - default skin-string for pressed cases
think (Component self)
  returns: ()
  called each frame if the component is visible and inserted in the rootpane or one of its ancestors. Overload this method to perform your own operations here
toString (Component self)
  returns: (string)
  returns a simple string representation of this component
transferFocus (Component self, int direction)
  returns: ()
  call this to transfer the focus in a direction relative to the component (forward/backward
transferFocusOnArrows (Component)
  returns: (boolean)
  returns true if the component transfers the focus if an arrow is pressed is pressed
transferFocusOnTab (Component)
  returns: (boolean)
  returns true if the component transfers the focus if tab is pressed
unlockMouse (Component)
  returns: ()
  releases the mouselock, but only if the Component is also the locker of the mouse.
updateSkin (Component self)
  returns: ()
  updates skin information
validate (Component self, [int z])
  returns: ([int z])
  validates the new position of the component. don't call this method during a mouseevent or strange things may happen. If the Component's bounds were changed, positionUpdate will be called. The z parameter is the z-sort order and the component should return an incremented z value, reserving the z-values it needs for its own (validation is down in z-sorted order). If no z is given, no reordering is done.
validateFocus (Component self)
  returns: ()

  Called once a frame and build a list of focusable components

white
  [texture] - a 2x2 sized white texture for general purpose
world2local (int worldx,worldy)
  returns: (int localx,localy)
  returns local coordinates
zorderoffset
  [int] - sortid offset for l2dnodes