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.
- 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:
- component - simple default surface
- component_hover - highlighted surface if mouse is over the component
- 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