Creation/Dev/Script/Client/GuiControl

From Graal Bible
This article is information on a script object - a pre-defined type of variable with its own set of static variables and functions. It is intended for use with the GS2 scripting language.


Inherits from TGraalVar.

Description

Guicontrol panel.png

GuiControl is the base GUI control, therefore general functions listed here are available to all GUI controls. Most of the time it is used as container for positioning groups of other controls. It can either have a border (border=1..5) or just be plain transparent, and just display its child controls.

Variables

Name Type Description
active boolean whether the control can be used (e.g. a button can be clicked only if active)
awake boolean (read only)
canmove boolean allows the control to be moved by the mouse
canresize boolean allows the control to be resized by dragging the corner or side with the mouse
clipchildren boolean by default true; specifies if child controls are clipped to their bounds (text or graphics outside of the bounds will not be shown); if not working, try also setting cliptobounds=false
clipmove boolean when the user moves the control (see canMove) then this makes sure that the control is not moving outside the parents bounds, by default true
cliptobounds boolean by default true; specifies if the control should be clipped (might be usefull for GuiShowImgCtrl to disable this); this is ignored if parent.clipchildren is already false
controls object (read only; see addControl()) array of GuiControl (subcontrols)
cursor int cursor when the mouse is hovered over the control - options are default, hand/pointer, text, crosshair, column-reisze, row-resize, wait, progress, and help (some are not available based on platform)
editing boolean
extent string Can be used instead of width and height. Used like this: "123 456", where 123 is width and 456 is height. There is some syntactic sugar that allows you to treat it like an array, but it is not a good idea to do this because it does not work when you try to assign to e.g extent[0]. See 'width' and 'height' instead for this.
flickering boolean Allows the control to periodically show/hide itself.
flickertime integer The time between the show and hides in flickering.
height integer can be used instead of extent
hint string tooltip text displayed when you hover the mouse over the control
horizsizing string specifies the horizontal resizing behaviour when the parent control is resized: right, width, left, center or relative
layer integer (read only) image layer the control is on
minextent string minimum size as a string like "200 300", though there is some support for arrays which is not complete (e.g. you cannot set minextent[0])
minsize string the same as "minextent"
parent object (read only) the parent GuiControl
position string Can be used instead of x and y. Used like this: "123 456", where 123 is x and 456 is y. There is some syntactic sugar that allows you to treat it like an array, which does not work when you try to assign to e.g position[0]. See 'x' and 'y' instead for this.
profile object controls the way the profile looks and acts - see GuiControlProfile
resizeheight boolean
resizewidth boolean
scrolllinex integer lines to scroll vertically
scrollliney integer lines to scroll horizontally
showhint boolean whether to show the hint or not
useownprofile boolean allows you to set custom variables for the profile without modifying the profile at every instance it is used, set it to true before changing things
vertsizing string specifies the vertical resizing behaviour when the parent control is resized: bottom, height, top, center or relative
visible boolean whether the control can be seen or is hidden
width integer can be used instead of extent
x integer can be used instead of position
y integer can be used instead of position

Functions

Name Return Type Description
addcontrol(obj) adds the control inside another control
bringtofront() bring the control to the front
clearControls() removes all controls inside the control at once
destroy()
getparent() object returns parent object
globaltolocalcoord({x,y}) {x,y} converts global screen coordinates to a position relative to the controls origin (0,0), can be used to know where exactly the user has clicked inside a control
hide() Hide the control
isfirstresponder() boolean Returns whether or not this control is the first responder
localtoglobalcoord({x,y}) {x,y} converts a position relative to the controls origin (0,0) to global screen coordinates, can be used to know where on the screen a control is displayed in case it is a child of another control (e.g. GuiWindowCtrl or GuiScrollCtrl)
makefirstresponder(bool) makes the control the first responder for key input
pushtoback() pushes the control to the back
resize(int x, int y, int width, int height) resizes the control to the specified dimensions
show() shows the control
showtop() calls show(), tabfirst() and bringtofront()
tabfirst() object when tab is pressed, the control is selected first, similar to web forms

Events

onAdd() - is invoked when the control is added to another control (addcontrol function)

onRemove() - is invoked when the control is removed from its parent

onShow() - is invoked when the control is shown or gets awakened while being 'visible'

onHide() - is invoked when the control is made hidden

onWake() - is invoked when the control is awakened and becomes visible on the screen

onSleep() - is invoked for windows when a dialog window is removed from the screen

onMove(newx,newy) - is invoked when the control is moved

onResize(newwidth,newheight) - is invoked when the control is resized

onAction() - is invoked when a button control is pressed, you press the enter-key in a text edit control, or move a slider control,

onDialogPush() - is invoked when a dialog control is placed on the screen (using pushDialog(control))

onDialogPop() - is invoked when a dialog control is removed from the screen again (using popDialog())

onKeyDown(keycode,keystring,scancode) - a key has been pressed while the control had the input focus (makeFirstResponder())

onKeyUp(keycode,keystring,scancode) - the key has been released

onMouseYawPitch(xaxis,yaxis) - mouse event in Graal3D when the mouse has been turned off

onMouseDown(keymodifier,mousescreenx,mousescreeny,clickcount) - the left mouse button has been pressed inside this control

onMouseUp(keymodifier,mousescreenx,mousescreeny) - the left mouse button has been released

onMouseEnter(keymodifier,mousescreenx,mousescreeny) - the mouse moved inside this control

onMouseLeave(keymodifier,mousescreenx,mousescreeny) - the mouse left the control

onMouseDragged(keymodifier,mousescreenx,mousescreeny) - the mouse is moved while the left mouse button is pressed

onMouseMove(keymodifier,mousescreenx,mousescreeny) - the mouse has been moved

onRightMouseDown(keymodifier,mousescreenx,mousescreeny,clickcount) - the right mouse button has been pressed

onRightMouseUp(keymodifier,mousescreenx,mousescreeny) - the right mouse button has been released

onRightMouseDragged(keymodifier,mousescreenx,mousescreeny) - the mouse has been moved while the right mouse button is pressed

onMouseWheelUp(keymodifier) - the mouse wheel has been scrolled up

onMouseWheelDown(keymodifier) - the mouse wheel has been scrolled down

Example

 new GuiControl("Test_Back") {
   useownprofile = true;
   profile.border = 3;
   x = 10;
   y = 10;
   width = 160;
   height = 80;
 }


Object Navigation