LUADOC - Farming Simulator 22

Script v1_7_1_0

Engine v1_7_1_0

Foundation Reference

GuiElement

Description

GUI Element base class. All elements displayed in the game UI must be instances or descendants of this class. All XML configuration properties as declared below (and in subclasses) are mirrored in guiProfiles.xml as key-value pairs in the form of <Value name="property_name" value="value" />. Profiles are able to inherit from other profiles, so take care to check their hierarchy if any of your settings do not seem to have any effect. Directly set properties in the XML configuration will always override profile values, however. Layer properties, prefixed with "[layer]", interact with an overlay system and provide display images. Usable layers, whose names are substituted for the prefix, are primarily "image" and "icon". UI elements define layer names on their own and read them from these generated properties. Whenever an element requires a layer, it is described in its documentation such as this one. Example for an icon layer focus color property: iconFocusedColor="0.9 0.1 0.5 1.0". A note regarding callbacks: All callbacks are called on an element's target first. When GUI elements are created from configuration, their top-level view (e.g. MainScreen) is the callback target, i.e. MainScreen:callbackName() is executed. Unless an element's target has been set to another value explicitly via code, this will always be the case.

XML Configuration Parameters

GuiElement#id	string [optional] Element ID. Must be unique per GUI screen. If set on an element, will expose it as an indexable field on the view class (e.g. id="buttonOk" -> MainScreen.buttonOk). Use this feature sparingly, as it creates implicit coupling which leads to tedious debugging.
GuiElement#name	string [optional] Element name. Used to distinguish elements, but not as strongly as #id.
GuiElement#profile	[optional] Element GUI profile name. Targets a profile from guiProfiles.xml to set initial values for this element. Any direct configuration in XML will override the profile.
GuiElement#outputSize	string [optional] Reference resolution for size settings, defaults to 1920:1080. Format: "[width]px [height]px", e.g. outputSize="1920px 1080px"
GuiElement#position	string [optional] Position of the element relative to its parent (or screen) origin point in reference resolution, defaults to {0, 0}. Format: "[x]px [y]px", e.g. position="20px -40px"
GuiElement#size	string [optional] Outer boundary pixel size of this element in reference resolution, defaults to cover the entire screen. Format: "[width]px [height]px", e.g. size="320px 200px"
GuiElement#imageSize	string [optional] If this element has an image component, this determines the dimensions of the image in reference resolution. Format: "[width]px [height]px", e.g. imageSize="64px 12px"
GuiElement#margin	string [optional] Pixel margin around outer border of element to leave free when layouting this element (e.g. in BoxLayout) in reference resolution, defaults to {0, 0, 0, 0}. Format: "[left]px [top]px [right]px [bottom]px", e.g. margin="4px 10px 6px 10px"
GuiElement#positionOrigin	string [optional] Origin of this element from which its size is projected, defaults to "bottomLeft" (width goes right, height goes up). Valid values are combinations of the "top", "middle", "bottom" vertical and "Left", "Center", "Right" keywords. Vertical keywords always come first, e.g. "topLeft", "bottomCenter".
GuiElement#screenAlign	string [optional] Alignment of this element's origin within its parent (or screen), defaults to no alignment. Valid values are the same as in #positionOrigin.
GuiElement#visible	bool [optional] If false, will make the element invisible on creation.
GuiElement#disabled	bool [optional] If true, will make the element disabled on creation.
GuiElement#newLayer	bool [optional] If true, will cause the element to have its own GUI layer.
GuiElement#debugEnabled	bool [optional] If true, will draw debug hints (e.g. borders, text alignment lines, etc.) from the element.
GuiElement#thinLineProtection	bool [optional] If false, will turn off ensurement that non-zero sizes are at least one screen pixel in width and height.
GuiElement#updateChildrenOverlayState	bool [optional] If true, will cause child elements to receive the same overlay state as this element.
GuiElement#fadeInTime	float [optional] Time in seconds the element needs to fade to visible, defaults to 0.
GuiElement#fadeOutTime	float [optional] Time in seconds the element needs to fade to invisible, defaults to 0.
GuiElement#toolTipElementId	string [optional] ID of element to use for tooltip display. The element must have a setText(str) method and #toolTipText must also be defined for the feature to work.
GuiElement#toolTipText	string [optional] Text to show in tool tips. Use a symbolic label prefixed with "$l10n_" to have the text resolved for each language from the I10n_[lang].xml files.
GuiElement#layoutIgnore	bool [optional] If true, this element will not be repositioned by layouting elements, defaults to false.
GuiElement#hasFrame	bool [optional] If true, this element draws a frame around its borders. Defaults to false.
GuiElement#frameThickness	[optional] Defines the frame thickness per side in reference resolution pixels, defaults to "1px 1px 1px 1px". Format is identical to #margin. The frame extends inwards, with the thickest parts being drawn on top.
GuiElement#frameTopColor	[optional] Defines the frame top line color, defaults to white. Format: "[r] [g] [b] [a]" where each value is in the range of [0.0, 1.0]. The first three values represent red, green and blue color channels and the last is the alpha (transparency) value. When setting this property in guiProfiles.xml, preset values as defined at the top of that file may also be used.
GuiElement#frameLeftColor	[optional] Defines the frame left line color, defaults to white. Format: "[r] [g] [b] [a]" where each value is in the range of [0.0, 1.0]. The first three values represent red, green and blue color channels and the last is the alpha (transparency) value. When setting this property in guiProfiles.xml, preset values as defined at the top of that file may also be used.
GuiElement#frameBottomColor	[optional] Defines the frame bottom line color, defaults to white. Format: "[r] [g] [b] [a]" where each value is in the range of [0.0, 1.0]. The first three values represent red, green and blue color channels and the last is the alpha (transparency) value. When setting this property in guiProfiles.xml, preset values as defined at the top of that file may also be used.
GuiElement#frameRightColor	[optional] Defines the frame right line color, defaults to white. Format: "[r] [g] [b] [a]" where each value is in the range of [0.0, 1.0]. The first three values represent red, green and blue color channels and the last is the alpha (transparency) value. When setting this property in guiProfiles.xml, preset values as defined at the top of that file may also be used.
GuiElement#soundDisabled	[optional] Disable the sound for this element (not its children), for fixing double-sounds.
GuiElement#handleFocus	bool [optional] If false, this element will not receive focus actions and state.
GuiElement#focusId	string [optional] ID of element for focus changes. This only needs to be assigned if specific focus navigation has to be configured. By default, the system will assign a generated ID.
GuiElement#focusInit	bool [optional] If the attribute is present, causes the element to receive focus when the screen is created. If a value of "onOpen" is set, makes this element receive focus any time the screen is opened.
GuiElement#focusChangeTop	string [optional] Focus ID of element to focus when an upward navigation input is received on the GUI. Automatically assigned by default.
GuiElement#focusChangeBottom	string [optional] Focus ID of element to focus when a downward navigation input is received on the GUI. Automatically assigned by default.
GuiElement#focusChangeLeft	string [optional] Focus ID of element to focus when an leftward navigation input is received on the GUI. Automatically assigned by default.
GuiElement#focusChangeRight	string [optional] Focus ID of element to focus when an rightward navigation input is received on the GUI. Automatically assigned by default.
GuiElement#consoleFocusChangeTop	string [optional] Focus ID of element to focus when an upward navigation input is received on the GUI in the console version. Automatically assigned by default.
GuiElement#consoleFocusChangeBottom	string [optional] Focus ID of element to focus when a downward navigation input is received on the GUI in the console version. Automatically assigned by default.
GuiElement#consoleFocusChangeLeft	string [optional] Focus ID of element to focus when an leftward navigation input is received on the GUI in the console version. Automatically assigned by default.
GuiElement#consoleFocusChangeRight	string [optional] Focus ID of element to focus when an rightward navigation input is received on the GUI in the console version. Automatically assigned by default.
GuiElement#[layer]Filename	string [optional] Relative file path to a display image from the game's root folder. A value of "g_baseUIFilename" will resolve to the default UI image atlas. Other file paths may contain the string "$l10nSuffix" which is replaced with the currently set language suffix to provide language-specific paths.
GuiElement#[layer]PreviewFilename	string [optional] Relative file path to a display image from the game's root folder. Defaults to a blank image. Will be used on a control to render a preview while the actual image is being loaded, for example.
GuiElement#[layer]UVs	string [optional] Texture coordinates to use for the displayed image (i.e. when treating it as an atlas). Defaults to use the full image. Format: "[u]px [v]px [width]px [height]px"
GuiElement#[layer]FocusedUVs	string [optional] Texture coordinates to use for the displayed image when the element is focused. Works like #imageUVs.
GuiElement#[layer]PressedUVs	string [optional] Texture coordinates to use for the displayed image when the element is pressed (e.g. buttons). Works like #imageUVs.
GuiElement#[layer]SelectedUVs	string [optional] Texture coordinates to use for the displayed image when the element is selected (e.g. list items). Works like #imageUVs.
GuiElement#[layer]HighlightedUVs	string [optional] Texture coordinates to use for the displayed image when the element is highlighted (e.g. on mouse over). Works like #imageUVs.
GuiElement#[layer]DisabledUVs	string [optional] Texture coordinates to use for the displayed image when the element is disabled. Works like #imageUVs.
GuiElement#[layer]Color	string [optional] Color tint for displayed image. Defaults to white (neutral). Format: "[r] [g] [b] [a]" where each value is in the range of [0.0, 1.0]. The first three values represent red, green and blue color channels and the last is the alpha (transparency) value. When setting this property in guiProfiles.xml, preset values as defined at the top of that file may also be used.
GuiElement#[layer]FocusedColor	string [optional] Color tint for displayed image when the element is focused. Works like #imageColor.
GuiElement#[layer]PressedColor	string [optional] Color tint for displayed image when the element is pressed. Works like #imageColor.
GuiElement#[layer]SelectedColor	string [optional] Color tint for displayed image when the element is selected. Works like #imageColor.
GuiElement#[layer]HighlightedColor	string [optional] Color tint for displayed image when the element is highlighted. Works like #imageColor.
GuiElement#[layer]DisabledColor	string [optional] Color tint for displayed image when the element is disabled. Works like #imageColor.
GuiElement#[layer]Rotation	float [optional] Rotation of displayed image in degrees. Positive values rotate clockwise, negative values rotate counter-clockwise around the image center.
GuiElement#[layer]IsWebOverlay	bool [optional] If true, interprets the #imageFilename as an URL and load the image from there. This will also require a suitable preview image to render during loading.
GuiElement#onCreateArgs	string [optional] Arguments which are supplied to the #onCreate callback in addition to the element itself
GuiElement#onCreate	callback [optional] Function to be called after all values have been loaded and the element's own initialization has completed.
GuiElement#onOpen	callback callback [optional] Function to be called when this element is opened and before any of its children are opened.
GuiElement#onClose	callback callback [optional] Function to be called when this element is closed and before any of its children are closed.
GuiElement#onDraw	callback callback [optional] Function to be called when this element is visible and being drawn and before any of its children are being drawn.
GuiElement#focusChangeOverride	callback [optional] Function to be called when this element loses focus and the default focus change logic needs to be overridden in that case.

Functions

addCallback
addElement
applyElementAspectScale
applyProfile
applyScreenAlignment
canReceiveFocus
clone
copyAttributes
cutFrameBordersHorizontal
cutFrameBordersVertical
delete
draw
extractIndexAndNameFromID
fadeIn
fadeOut
findDescendantsRec
fixThinLines
getAspectScale
getBorders
getCenter
getClipArea
getDescendantById
getDescendantByName
getDescendants
getFirstDescendant
getFocusTarget
getHandleFocus
getIsActive
getIsActiveNonRec
getIsDisabled
getIsHighlighted
getIsSelected
getIsVisible
getIsVisibleNonRec
getOverlayState
getParentBorders
getSoundSuppressed
include
inputEvent
isChildOf
keyEvent
loadFromXML
loadProfile
mouseEvent
move
new
onClose
onFocusActivate
onFocusEnter
onFocusLeave
onGuiSetupFinished
onHighlight
onHighlightRemove
onOpen
raiseCallback
removeElement
reset
restoreOverlayState
setAbsolutePosition
setAlpha
setDisabled
setHandleFocus
setId
setOverlayState
setPosition
setSize
setSoundSuppressed
setVisible
shouldFocusChange
storeOverlayState
toggleFrameSide
toString
touchEvent
unlinkElement
update
updateAbsolutePosition
updateFramePosition
updatePositionForOrigin
updateScreenAlign

addCallback

Description

Add a callback to this element which was defined in its XML definition. If this element has a target, the given function name will be called on the target. Otherwise, the function is assumed to be global.

Definition

addCallback(xmlFile XML, key XML, funcName Name)

Arguments

xmlFile	XML	file handle
key	XML	node path of this GuiElement's definition.
funcName	Name	of the callback function

Code

1522	function GuiElement:addCallback(xmlFile, key, funcName)
1523	local callbackName = getXMLString(xmlFile, key)
1524	if callbackName ~= nil then
1525	if self.target ~= nil then
1526	self[funcName] = self.target[callbackName]
1527	else
1528	self[funcName] = ClassUtil.getFunction(callbackName)
1529	end
1530	end
1531	end

addElement

Description

Add a child GuiElement to this GuiElement.

Definition

addElement()

Code

903	function GuiElement:addElement(element)
904	if element.parent ~= nil then
905	element.parent:removeElement(element)
906	end
907
908	table.insert(self.elements, element)
909	element.parent = self
910	end

applyElementAspectScale

Description

Apply element aspect scale transformations.

Definition

applyElementAspectScale(bool ignorePosition)

Arguments

bool

ignorePosition

If true, will not apply aspect scaling to this element's position

Code

1469	function GuiElement:applyElementAspectScale(ignorePosition)
1470	local scaleX, scaleY = self:getAspectScale()
1471
1472	self.size[1] = self.size[1] * scaleX
1473	self.margin[1] = self.margin[1] * scaleX
1474	self.margin[3] = self.margin[3] * scaleX
1475
1476	self.size[2] = self.size[2] * scaleY
1477	self.margin[2] = self.margin[2] * scaleY
1478	self.margin[4] = self.margin[4] * scaleY
1479
1480	if not ignorePosition then
1481	self.position[1] = self.position[1] * scaleX
1482	self.position[2] = self.position[2] * scaleY
1483	end
1484	end

applyProfile

Description

Apply a GUI profile with a given name to this element.

Definition

applyProfile(profileName Name, bool force)

Arguments

profileName	Name	of the profile to apply to this element
bool	force	[optional] If true, will apply all profile settings, including position and size.

Code

380	function GuiElement:applyProfile(profileName, force)
381	if profileName then
382	local pro = g_gui:getProfile(profileName)
383	if pro ~= nil then
384	self.profile = profileName
385	self:loadProfile(pro, not force)
386	end
387	end
388	end

applyScreenAlignment

Description

Apply screen alignment to this element and its children. Scales size, position and margin depending on alignment settings.

Definition

applyScreenAlignment()

Code

1489	function GuiElement:applyScreenAlignment()
1490	self:applyElementAspectScale()
1491
1492	for _,child in ipairs(self.elements) do
1493	child:applyScreenAlignment()
1494	end
1495	end

canReceiveFocus

Description

Determine if this GuiElement can receive focus.

Definition

canReceiveFocus()

Code

801	function GuiElement:canReceiveFocus()
802	return false -- default is not focusable, subclasses need to make themselves available
803	end

clone

Description

Create a deep copy clone of this GuiElement.

Definition

clone(parent Target, includeId [optional,, suppressOnCreate [optional,)

Arguments

parent	Target	parent element of the cloned element
includeId	[optional,	default=false] If true, will also clone ID values
suppressOnCreate	[optional,	default=false] If true, will not trigger the "onCreate" callback

Code

411	function GuiElement:clone(parent, includeId, suppressOnCreate)
412	local ret = self.new()
413	ret:copyAttributes(self)
414
415	if parent ~= nil then
416	parent:addElement(ret)
417	end
418
419	for i=1, #self.elements do
420	local clonedChild = self.elements[i]:clone(ret, includeId, suppressOnCreate)
421	if includeId then
422	clonedChild.id = self.elements[i].id
423	end
424	end
425
426	if not suppressOnCreate then
427	ret:raiseCallback("onCreateCallback", ret, ret.onCreateArgs)
428	end
429
430	return ret
431	end

copyAttributes

Description

Copy all attributes from a source GuiElement to this GuiElement.

Definition

copyAttributes()

Code

435	function GuiElement:copyAttributes(src)
436	self.visible = src.visible
437	self.name = src.name
438	self.typeName = src.typeName
439	self.disabled = src.disabled
440	self.positionOrigin = src.positionOrigin
441	self.screenAlign = src.screenAlign
442	self.newLayer = src.newLayer
443	self.debugEnabled = src.debugEnabled
444
445	self.size = table.copy(src.size)
446	self.margin = table.copy(src.margin)
447	self.onCreateCallback = src.onCreateCallback
448	self.onCreateArgs = src.onCreateArgs
449	self.onCloseCallback = src.onCloseCallback
450	self.onOpenCallback = src.onOpenCallback
451	self.onDrawCallback = src.onDrawCallback
452
453	self.target = src.target
454	self.targetName = src.targetName
455	self.profile = src.profile
456	self.outputSize = table.copy(src.outputSize)
457	self.imageSize = table.copy(src.imageSize)
458	self.fadeInTime = src.fadeInTime
459	self.fadeOutTime = src.fadeOutTime
460	self.alpha = src.alpha
461	self.fadeDirection = src.fadeDirection
462	self.updateChildrenOverlayState = src.updateChildrenOverlayState
463	self.toolTipElementId = src.toolTipElementId
464	self.toolTipText = src.toolTipText
465	self.handleFocus = src.handleFocus
466	self.clipping = src.clipping
467	self.focusFallthrough = src.focusFallthrough
468	self.disallowFlowCut = src.disallowFlowCut
469
470	self.ignoreLayout = src.ignoreLayout
471	self.soundDisabled = src.soundDisabled
472
473	self.hasFrame = src.hasFrame
474	self.frameThickness = src.frameThickness
475	self.frameColors = table.copy(src.frameColors, math.huge)
476	self.frameOverlayVisible = table.copy(src.frameOverlayVisible)
477
478	self.focusId = src.focusId
479	self.focusChangeData = table.copy(src.focusChangeData)
480	self.focusActive = src.focusActive
481	self.isAlwaysFocusedOnOpen = src.isAlwaysFocusedOnOpen
482
483	self.position = table.copy(src.position)
484	self.absPosition = table.copy(src.absPosition)
485	self.absSize = table.copy(src.absSize)
486	self.anchors = table.copy(src.anchors)
487	self.pivot = table.copy(src.pivot)
488	end

cutFrameBordersHorizontal

Description

Cut horizontal frame borders if a vertical frame side is thicker.

Definition

cutFrameBordersHorizontal()

Code

576	function GuiElement:cutFrameBordersHorizontal(verticalPart, horizontalPart, isLeft)
577	if verticalPart.width > horizontalPart.height then -- equals test for thickness
578	if isLeft then
579	horizontalPart.x = horizontalPart.x + verticalPart.width
580	end
581
582	horizontalPart.width = horizontalPart.width - verticalPart.width
583	end
584	end

cutFrameBordersVertical

Description

Cut vertical frame borders if a horizontal frame side is thicker.

Definition

cutFrameBordersVertical()

Code

588	function GuiElement:cutFrameBordersVertical(horizontalPart, verticalPart, isBottom)
589	if horizontalPart.width >= verticalPart.height then -- test for greater or equals here to avoid overlaps when thickness is the same
590	if isBottom then
591	verticalPart.y = verticalPart.y + horizontalPart.height
592	end
593
594	verticalPart.height = verticalPart.height - horizontalPart.height
595	end
596	end

delete

Description

Delete this GuiElement. Also deletes all child elements and removes itself from its parent and focus.

Definition

delete()

Code

393	function GuiElement:delete()
394	for i = #self.elements, 1, -1 do
395	self.elements[i].parent = nil
396	self.elements[i]:delete()
397	end
398
399	if self.parent ~= nil then
400	self.parent:removeElement(self)
401	end
402	-- unset focus data
403	FocusManager:removeElement(self)
404	end

draw

Description

Draw this GuiElement. If defined, triggers the "onDrawCallback".

Definition

draw()

Code

711	function GuiElement:draw(clipX1, clipY1, clipX2, clipY2)
712	if self.newLayer then
713	new2DLayer()
714	end
715
716	-- update clip with own element clipping
717	clipX1, clipY1, clipX2, clipY2 = self:getClipArea(clipX1, clipY1, clipX2, clipY2)
718
719	self:raiseCallback("onDrawCallback", self)
720
721	if self.debugEnabled or g_uiDebugEnabled then
722	local xPixel = 1 / g_screenWidth
723	local yPixel = 1 / g_screenHeight
724
725	drawFilledRect(self.absPosition[1] - xPixel, self.absPosition[2] - yPixel, self.absSize[1] + 2 * xPixel, yPixel, 1, 0, 0, 1)
726	drawFilledRect(self.absPosition[1] - xPixel, self.absPosition[2] + self.absSize[2], self.absSize[1] + 2 * xPixel, yPixel, 1, 0, 0, 1)
727	drawFilledRect(self.absPosition[1] - xPixel, self.absPosition[2], xPixel, self.absSize[2], 1, 0, 0, 1)
728	drawFilledRect(self.absPosition[1] + self.absSize[1], self.absPosition[2], xPixel, self.absSize[2], 1, 0, 0, 1)
729	end
730
731	for i = 1, #self.elements do
732	local child = self.elements[i]
733	if child:getIsVisibleNonRec() then
734	-- Clip beforehand so not every element class has to do it
735	child:draw(child:getClipArea(clipX1, clipY1, clipX2, clipY2))
736	end
737	end
738
739	if self.hasFrame then
740	for i = 1, 4 do
741	if self.frameOverlayVisible[i] then
742	local frame = self.frameBounds[i]
743	local color = self.frameColors[i]
744
745	drawFilledRect(frame.x, frame.y, frame.width, frame.height, color[1], color[2], color[3], color[4], clipX1, clipY1, clipX2, clipY2)
746	end
747	end
748	end
749
750	if g_uiFocusDebugEnabled and self.focusId ~= nil and self:canReceiveFocus() then
751	setTextColor(1, 0, 0, 1)
752	local size = 0.008
753	local y = self.absPosition[2] + self.absSize[2]
754	renderText(self.absPosition[1], y-1*size, size, " FocusId: " .. tostring(self.focusId) .. " " .. tostring(ClassUtil.getClassNameByObject(self)))
755	renderText(self.absPosition[1], y-2*size, size, " T: " .. tostring(self.focusChangeData[FocusManager.TOP]))
756	renderText(self.absPosition[1], y-3*size, size, " B: " .. tostring(self.focusChangeData[FocusManager.BOTTOM]))
757	renderText(self.absPosition[1], y-4*size, size, " L: " .. tostring(self.focusChangeData[FocusManager.LEFT]))
758	renderText(self.absPosition[1], y-5*size, size, " R: " .. tostring(self.focusChangeData[FocusManager.RIGHT]))
759
760	setTextColor(1, 1, 1, 1)
761	end
762	end

extractIndexAndNameFromID

Description

Try to extract a field name and index from an element ID. IDs in configurations may be indexed on definition (e.g. fillTypes[2]). This function extracts the list name and index if such a case is found. Otherwise, it will return no index and the original element ID.

Definition

extractIndexAndNameFromID(elementId Element)

Arguments

elementId

Element

ID, to be used as a field name on a ScreenElement view.

Return Values

Index

nil, field name

Code

1560	function GuiElement.extractIndexAndNameFromID(elementId)
1561	local len = elementId:len()
1562	local varName = elementId
1563	local index = nil
1564	if len >= 4 and elementId:sub(len, len) == "]" then
1565	local startI = elementId:find("[", 1, true)
1566	if startI ~= nil and startI > 1 and startI < len-1 then
1567	index = Utils.evaluateFormula(elementId:sub(startI + 1, len - 1))
1568	if index ~= nil then
1569	varName = elementId:sub(1, startI - 1)
1570	end
1571	end
1572	end
1573	return index, varName
1574	end

fadeIn

Description

Fade this element into visibility.

Definition

fadeIn()

Code

1160	function GuiElement:fadeIn(factor)
1161	if self.fadeInTime > 0 then
1162	self.fadeDirection = 1 * Utils.getNoNil(factor, 1)
1163	self:setAlpha(math.max(self.alpha, 0.0001)) -- Ensure that we are considered visible and get an update
1164	else
1165	self.fadeDirection = 0
1166	self:setAlpha(1)
1167	end
1168	end

fadeOut

Description

Fade this element out of visibility.

Definition

fadeOut()

Code

1172	function GuiElement:fadeOut(factor)
1173	if self.fadeOutTime > 0 then
1174	self.fadeDirection = -1 * Utils.getNoNil(factor, 1)
1175	else
1176	self.fadeDirection = 0
1177	self:setAlpha(0)
1178	end
1179	end

findDescendantsRec

Description

Recursively add descendant elements of a root to an accumulator list. If a predicate function is given, it is evaluated per element and only elements which yield a true value for the function are added to the accumulator.

Definition

findDescendantsRec(accumulator List, rootElement Current, predicateFunction [optional])

Arguments

accumulator	List	which receives descendant elements
rootElement	Current	element root whose direction children are added (after optional evaluation)
predicateFunction	[optional]	If specified, will be evaluated per element (see getDescendants)

Code

1248	function GuiElement:findDescendantsRec(accumulator, rootElement, predicateFunction)
1249	if not rootElement then return end -- safety
1250	for _, element in ipairs(rootElement.elements) do
1251	self:findDescendantsRec(accumulator, element, predicateFunction) -- depth first
1252	if not predicateFunction or predicateFunction(element) then
1253	table.insert(accumulator, element)
1254	end
1255	end
1256	end

fixThinLines

Description

Definition

fixThinLines()

Code

1419	function GuiElement:fixThinLines()
1420	if self.thinLineProtection then
1421	if self.size[1] ~= 0 then
1422	self.size[1] = math.max(self.size[1], 1 / g_screenWidth)
1423	end
1424
1425	if self.size[2] ~= 0 then
1426	self.size[2] = math.max(self.size[2], 1 / g_screenHeight)
1427	end
1428
1429	self:updateAbsolutePosition()
1430	end
1431	end

getAspectScale

Description

Get aspect scaling values for this element's settings and the game's resolution.

Definition

getAspectScale()

Return Values

float	X	aspect scale factor
float	Y	aspect scale factor

Code

1462	function GuiElement:getAspectScale()
1463	return g_aspectScaleX, g_aspectScaleY
1464	end

getBorders

Description

Get this element's border rectangle represented by minimum and maximum points.

Definition

getBorders()

Return Values

Element

borders

in an array: {minX, minY, maxX, maxY}

Code

1448	function GuiElement:getBorders()
1449	return {self.absPosition[1], self.absPosition[2], self.absPosition[1] + self.absSize[1], self.absPosition[2] + self.absSize[2]}
1450	end

getCenter

Description

Get this element's center position.

Definition

getCenter()

Code

1454	function GuiElement:getCenter()
1455	return {self.absPosition[1] + self.absSize[1] * 0.5, self.absPosition[2] + self.absSize[2] * 0.5}
1456	end

getClipArea

Description

Update given clip area with clip settings

Definition

getClipArea()

Code

1212	function GuiElement:getClipArea(clipX1, clipY1, clipX2, clipY2)
1213	if self.clipping then
1214	clipX1 = math.max(clipX1 or 0, self.absPosition[1])
1215	clipY1 = math.max(clipY1 or 0, self.absPosition[2])
1216	clipX2 = math.min(clipX2 or 1, self.absPosition[1] + self.absSize[1])
1217	clipY2 = math.min(clipY2 or 1, self.absPosition[2] + self.absSize[2])
1218	end
1219
1220	return clipX1, clipY1, clipX2, clipY2
1221	end

getDescendantById

Description

Get a descendant element of this element by its ID. This is a shorthand for getDescendants() with an ID matching predicate function.

Definition

getDescendantById(id Element)

Arguments

Element

Return Values

Element

nil

Code

1309	function GuiElement:getDescendantById(id)
1310	local element = nil
1311	if id then
1312	local function findId(e)
1313	return e.id and e.id == id
1314	end
1315
1316	element = self:getFirstDescendant(findId)
1317	end
1318	return element
1319	end

getDescendantByName

Description

Get a descendant element of this element by its name. This is a shorthand for getDescendants() with an ID matching predicate function.

Definition

getDescendantByName(name Element)

Arguments

name

Element

name

Return Values

Element

nil

Code

1326	function GuiElement:getDescendantByName(name)
1327	local element = nil
1328	if name then
1329	local function findId(e)
1330	return e.name and e.name == name
1331	end
1332
1333	element = self:getFirstDescendant(findId)
1334	end
1335	return element
1336	end

getDescendants

Description

Get all contained elements of this element in the entire hierarchy. Descendants are traversed depth-first, meaning that if elements have been properly added, the element order mirrors the order in the XML configuration (lines). Use this method sparingly, especially on high-level elements. Optionally, a predicate function can be passed which filters descendant elements. The function must return true for any desired element and false otherwise.

Definition

getDescendants(predicateFunction [optional])

Arguments

predicateFunction

[optional]

A function which determines if a descendant element should be returned. Must take a GuiElement as an argument and return true if that element should be returned or false otherwise.

Return Values

List

this element's descendants in depth-first order with contiguous numeric indices.

Code

1267	function GuiElement:getDescendants(predicateFunction)
1268	local descendants = {}
1269	self:findDescendantsRec(descendants, self, predicateFunction)
1270	return descendants
1271	end

getFirstDescendant

Description

Get the first descendant element of this element which matches a predicate function. This is a shorthand for getDescendants() which returns just the first element matching the predicate function or nil if no matching element exists.

Definition

getFirstDescendant(predicateFunction A)

Arguments

predicateFunction

function which determines if a descendant element should be returned. Must take a GuiElement as an argument and return true if that element should be returned or false otherwise.

Return Values

First

matching

descendant element in depth-first order or nil, if no element matched the predicate function

Code

1295	function GuiElement:getFirstDescendant(predicateFunction)
1296	local element = nil
1297	local res = self:getDescendants(predicateFunction)
1298	if #res > 0 then
1299	element = res[1]
1300	end
1301	return element
1302	end

getFocusTarget

Description

Get the actual focus target, in case a child or parent element needs to be targeted instead.

Definition

getFocusTarget(incomingDirection (Optional), moveDirection (Optional))

Arguments

incomingDirection	(Optional)	If specified, may return different targets for different incoming directions.
moveDirection	(Optional)	Actual movement direction per input. This is the opposing direction of incomingDirection.

Return Values

GuiElement

Actual

element to focus.

Code

1030	function GuiElement:getFocusTarget(incomingDirection, moveDirection)
1031	return self
1032	end

getHandleFocus

Description

Determine if this element can receive focus.

Definition

getHandleFocus()

Code

891	function GuiElement:getHandleFocus()
892	return self.handleFocus
893	end

getIsActive

Description

Determine if this element is active (not disabled and visible).

Definition

getIsActive()

Code

1200	function GuiElement:getIsActive()
1201	return not self.disabled and self:getIsVisible()
1202	end

getIsActiveNonRec

Description

Determine if this element is active (not disabled and visible) without checking the parents

Definition

getIsActiveNonRec()

Code

1206	function GuiElement:getIsActiveNonRec()
1207	return not self.disabled and self:getIsVisibleNonRec()
1208	end

getIsDisabled

Description

Determine if this element is disabled.

Definition

getIsDisabled()

Code

1134	function GuiElement:getIsDisabled()
1135	return self.disabled
1136	end

getIsHighlighted

Description

Determine if this element is currently highlighted.

Definition

getIsHighlighted()

Code

1150	function GuiElement:getIsHighlighted()
1151	if self.parent ~= nil then
1152	return self.parent:getIsHighlighted()
1153	end
1154
1155	return false
1156	end

getIsSelected

Description

Determine if this element is currently selected.

Definition

getIsSelected()

Code

1140	function GuiElement:getIsSelected()
1141	if self.parent ~= nil then
1142	return self.parent:getIsSelected()
1143	end
1144
1145	return false
1146	end

getIsVisible

Description

Determine if this element is visible. This checks both its current alpha value (set by fadeIn() / fadeOut()) as well as the visibility flag. If the parent is invisible, then so is this element.

Definition

getIsVisible()

Code

1100	function GuiElement:getIsVisible()
1101	if not self.visible or self.alpha == 0 then
1102	return false
1103	end
1104
1105	if self.parent ~= nil then
1106	return self.parent:getIsVisible()
1107	end
1108
1109	return true
1110	end

getIsVisibleNonRec

Description

Determine if this element is visible without checking the parents

Definition

getIsVisibleNonRec()

Code

1114	function GuiElement:getIsVisibleNonRec()
1115	return self.visible and self.alpha > 0
1116	end

getOverlayState

Description

Get this element's overlay state.

Definition

getOverlayState()

Code

1511	function GuiElement:getOverlayState()
1512	return self.overlayState
1513	end

getParentBorders

Description

Get the bottom left and top right corners of this element's parent's border rectangle. If this element has no parent, the full screen's borders are returned (i.e. {0, 0, 1, 1})

Definition

getParentBorders()

Return Values

Parent

element

or full screen borders in an array: {minX, minY, maxX, maxY}

Code

1437	function GuiElement:getParentBorders()
1438	if self.parent ~= nil then
1439	return self.parent:getBorders()
1440	end
1441
1442	return {0, 0, 1, 1}
1443	end

getSoundSuppressed

Description

Get the sound suppression flag from this element. If the flag is set to true, no sounds should be played when interacting with this element.

Definition

getSoundSuppressed()

Code

1237	function GuiElement:getSoundSuppressed()
1238	return self.isSoundSuppressed
1239	end

include

Description

Include a mixin in this element. See GuiMixin.lua for the details on usage and implementation of mixins.

Definition

include(guiMixinType Class)

Arguments

guiMixinType

Class

table reference of a descendant of GuiMixin

Code

1600	function GuiElement:include(guiMixinType)
1601	guiMixinType.new():addTo(self)
1602	end

inputEvent

Description

Handles an input event on a menu input action. Input is first passed to the current GUI view, then to the focused element, then to the focus manager for navigation. When a GUI element receives input, it should always propagate the input to its parent element first so they may override behavior and/or set the event used flag. If properly inherited from GuiElement and descendants, this behavior is guaranteed.

Definition

inputEvent(action Name, value Input, eventUsed If)

Arguments

action	Name	of input action which was triggered.
value	Input	value in the range of [-1, 1] for full axes and [0, 1] for half axes (includes buttons)
eventUsed	If	true, the event has been used by an input handler and should only be acted upon in exceptional cases.

Return Values

True

the input event has been handled, false otherwise.

Code

646	function GuiElement:inputEvent(action, value, eventUsed)
647	if not eventUsed then
648	eventUsed = self.parent and self.parent:inputEvent(action, value, eventUsed)
649	if eventUsed == nil then
650	eventUsed = false
651	end
652	end
653
654	return eventUsed
655	end

isChildOf

Description

Check if this element is the child of another element. This checks the full parent hierarchy.

Definition

isChildOf()

Code

1004	function GuiElement:isChildOf(element)
1005	if element == self then
1006	return false
1007	end
1008
1009	local p = self.parent
1010	while p do
1011	if p == self then
1012	return false
1013	end
1014
1015	if p == element then
1016	return true
1017	end
1018
1019	p = p.parent
1020	end
1021
1022	return false
1023	end

keyEvent

Description

Key event hook for raw keyboard input.

Definition

keyEvent()

Return Values

True

the keyboard input has been processed by this element.

Code

671	function GuiElement:keyEvent(unicode, sym, modifier, isDown, eventUsed)
672	if eventUsed == nil then
673	eventUsed = false
674	end
675
676	if self.visible then
677	for i=#self.elements, 1, -1 do
678	local v = self.elements[i]
679	if v:keyEvent(unicode, sym, modifier, isDown, eventUsed) then
680	eventUsed = true
681	end
682	end
683	end
684
685	return eventUsed
686	end

loadFromXML

Description

Load element data from an XML definition file.

Definition

loadFromXML(xmlFile Definition, key XML)

Arguments

xmlFile	Definition	XML file handle
key	XML	node path to this element's definition

Code

207	function GuiElement:loadFromXML(xmlFile, key)
208	local profile = getXMLString(xmlFile, key .. "#profile")
209	if profile ~= nil then
210	self.profile = profile
211
212	local pro = g_gui:getProfile(profile) -- defaults to base reference if profile name is invalid, also prints warning in that case
213	self:loadProfile(pro)
214	end
215
216	self:setId(xmlFile, key)
217
218	self.onCreateArgs = getXMLString(xmlFile, key.."#onCreateArgs")
219	self:addCallback(xmlFile, key.."#onCreate", "onCreateCallback")
220	self:addCallback(xmlFile, key.."#onOpen", "onOpenCallback")
221	self:addCallback(xmlFile, key.."#onClose", "onCloseCallback")
222	self:addCallback(xmlFile, key.."#onDraw", "onDrawCallback")
223
224	self.name = Utils.getNoNil(getXMLString(xmlFile, key.."#name"), self.name)
225	self.imageSize = GuiUtils.get2DArray(getXMLString(xmlFile, key.."#imageSize"), self.imageSize)
226	self.outputSize = GuiUtils.get2DArray(getXMLString(xmlFile, key.."#outputSize"), self.outputSize)
227	self.position = GuiUtils.getNormalizedValues(getXMLString(xmlFile, key.."#position"), self.outputSize, self.position)
228	self.size = GuiUtils.getNormalizedValues(getXMLString(xmlFile, key.."#size"), self.outputSize, self.size)
229	self.margin = GuiUtils.getNormalizedValues(getXMLString(xmlFile, key.."#margin"), self.outputSize, self.margin)
230
231	self.pivot = GuiUtils.getNormalizedValues(getXMLString(xmlFile, key .. "#pivot"), self.outputSize, self.pivot)
232	self.anchors = GuiUtils.get4DArray(getXMLString(xmlFile, key .. "#anchors"), self.anchors)
233
234	self.thinLineProtection = Utils.getNoNil(getXMLBool(xmlFile, key.."#thinLineProtection"), self.thinLineProtection)
235
236	self.positionOriginStr = Utils.getNoNil(getXMLString(xmlFile, key.."#positionOrigin"), self.positionOriginStr)
237	self.screenAlignStr = Utils.getNoNil(getXMLString(xmlFile, key.."#screenAlign"), self.screenAlignStr)
238
239	self.visible = Utils.getNoNil(getXMLBool(xmlFile, key.."#visible"), self.visible)
240	self.disabled = Utils.getNoNil(getXMLBool(xmlFile, key.."#disabled"), self.disabled)
241	self.newLayer = Utils.getNoNil(getXMLBool(xmlFile, key.."#newLayer"), self.newLayer)
242	self.debugEnabled = Utils.getNoNil(getXMLBool(xmlFile, key.."#debugEnabled"), self.debugEnabled)
243	self.updateChildrenOverlayState = Utils.getNoNil(getXMLBool(xmlFile, key.."#updateChildrenOverlayState"), self.updateChildrenOverlayState)
244	self.toolTipText = getXMLString(xmlFile, key.."#toolTipText")
245	self.toolTipElementId = getXMLString(xmlFile, key.."#toolTipElementId")
246	self.layoutIgnore = Utils.getNoNil(getXMLBool(xmlFile, key .. "#layoutIgnore"), self.layoutIgnore)
247	self.clipping = Utils.getNoNil(getXMLBool(xmlFile, key .. "#clipping"), self.clipping)
248
249	self.handleFocus = Utils.getNoNil(getXMLBool(xmlFile, key.."#handleFocus"), self.handleFocus)
250	self.soundDisabled = Utils.getNoNil(getXMLBool(xmlFile, key .. "#soundDisabled"), self.soundDisabled)
251
252	self.focusFallthrough = Utils.getNoNil(getXMLBool(xmlFile, key .. "#focusFallthrough"), self.focusFallthrough)
253	self.disallowFlowCut = Utils.getNoNil(getXMLBool(xmlFile, key.."#disallowFlowCut"), self.disallowFlowCut)
254
255	self.hasFrame = Utils.getNoNil(getXMLBool(xmlFile, key .. "#hasFrame"), self.hasFrame)
256	if self.hasFrame then
257	local thickness = getXMLString(xmlFile, key .. "#frameThickness")
258	self.frameThickness = GuiUtils.getNormalizedValues(thickness, self.outputSize) or self.frameThickness
259
260	local color = getXMLString(xmlFile, key .. "#frameLeftColor")
261	self.frameColors[GuiElement.FRAME_LEFT] = GuiUtils.getColorArray(color) or self.frameColors[GuiElement.FRAME_LEFT]
262	color = getXMLString(xmlFile, key .. "#frameTopColor")
263	self.frameColors[GuiElement.FRAME_TOP] = GuiUtils.getColorArray(color) or self.frameColors[GuiElement.FRAME_TOP]
264	color = getXMLString(xmlFile, key .. "#frameRightColor")
265	self.frameColors[GuiElement.FRAME_RIGHT] = GuiUtils.getColorArray(color) or self.frameColors[GuiElement.FRAME_RIGHT]
266	color = getXMLString(xmlFile, key .. "#frameBottomColor")
267	self.frameColors[GuiElement.FRAME_BOTTOM] = GuiUtils.getColorArray(color) or self.frameColors[GuiElement.FRAME_BOTTOM]
268	end
269
270	local fadeInTime = getXMLFloat(xmlFile, key.."#fadeInTime")
271	if fadeInTime ~= nil then
272	self.fadeInTime = fadeInTime*1000
273	end
274
275	local fadeOutTime = getXMLFloat(xmlFile, key.."#fadeOutTime")
276	if fadeOutTime ~= nil then
277	self.fadeOutTime = fadeOutTime*1000
278	end
279
280	-- self:fixThinLines()
281
282	-- TODO
283	-- self:updateScreenAlign(self.screenAlignStr)
284	-- self:updatePositionForOrigin(self.positionOriginStr)
285
286	if self.toolTipText ~= nil then
287	if self.toolTipText:sub(1,6) == "$l10n_" then
288	self.toolTipText = g_i18n:getText(self.toolTipText:sub(7))
289	end
290	end
291
292	-- load focus properties
293	FocusManager:loadElementFromXML(xmlFile, key, self)
294
295	self:verifyConfiguration()
296	end

loadProfile

Description

Load profile data for this element.

Definition

loadProfile(profile Loaded, applyProfile If)

Arguments

profile	Loaded	GUI profile
applyProfile	If	true, will re-calculate some dynamic properties. Use this when setting profiles dynamically at run time.

Code

302	function GuiElement:loadProfile(profile, applyProfile)
303	local imageSize = profile:getValue("imageSize")
304	if (imageSize ~= nil) then
305	local x, y = imageSize:getVector()
306	if x ~= nil and y ~= nil then
307	self.imageSize = { x, y }
308	end
309	end
310
311	local outputSize = profile:getValue("outputSize")
312	if (outputSize ~= nil) then
313	local x, y = outputSize:getVector()
314	if x ~= nil and y ~= nil then
315	self.outputSize = { x, y }
316	end
317	end
318
319	local positionValue = profile:getValue("position")
320	self.position = GuiUtils.getNormalizedValues(positionValue, self.outputSize, self.position)
321	self.size = GuiUtils.getNormalizedValues(profile:getValue("size"), self.outputSize, self.size)
322	self.pivot = GuiUtils.getNormalizedValues(profile:getValue("pivot"), self.outputSize, self.pivot)
323	self.margin = GuiUtils.getNormalizedValues(profile:getValue("margin"), self.outputSize, self.margin)
324
325	local anchors = profile:getValue("anchors")
326	if anchors ~= nil then
327	self.anchors = GuiUtils.get4DArray(anchors, self.anchors)
328	end
329
330	self.name = profile:getValue("name", self.name)
331
332	self.positionOriginStr = profile:getValue("positionOrigin", self.positionOriginStr)
333	self.screenAlignStr = profile:getValue("screenAlign", self.screenAlignStr)
334
335	self.visible = profile:getBool("visible", self.visible)
336	self.disabled = profile:getBool("disabled", self.disabled)
337	self.newLayer = profile:getBool("newLayer", self.newLayer)
338	self.debugEnabled = profile:getBool("debugEnabled", self.debugEnabled)
339	self.updateChildrenOverlayState = profile:getBool("updateChildrenOverlayState", self.updateChildrenOverlayState)
340	self.toolTipText = profile:getValue("toolTipText", self.toolTipText)
341	self.layoutIgnore = profile:getBool("layoutIgnore", self.layoutIgnore)
342	self.thinLineProtection = profile:getBool("thinLineProtection", self.thinLineProtection)
343	self.clipping = profile:getBool("clipping", self.clipping)
344	self.focusFallthrough = profile:getBool("focusFallthrough", self.focusFallthrough)
345	self.disallowFlowCut = profile:getBool("disallowFlowCut", self.disallowFlowCut)
346
347	self.hasFrame = profile:getBool("hasFrame", self.hasFrame)
348	if self.hasFrame then
349	self.frameThickness = GuiUtils.getNormalizedValues(profile:getValue("frameThickness"), self.outputSize) or self.frameThickness
350	self.frameColors[GuiElement.FRAME_LEFT] = GuiUtils.getColorArray(profile:getValue("frameLeftColor"), self.frameColors[GuiElement.FRAME_LEFT])
351	self.frameColors[GuiElement.FRAME_TOP] = GuiUtils.getColorArray(profile:getValue("frameTopColor"), self.frameColors[GuiElement.FRAME_TOP])
352	self.frameColors[GuiElement.FRAME_RIGHT] = GuiUtils.getColorArray(profile:getValue("frameRightColor"), self.frameColors[GuiElement.FRAME_RIGHT])
353	self.frameColors[GuiElement.FRAME_BOTTOM] = GuiUtils.getColorArray(profile:getValue("frameBottomColor"), self.frameColors[GuiElement.FRAME_BOTTOM])
354	end
355
356	self.handleFocus = profile:getBool("handleFocus", self.handleFocus)
357	self.soundDisabled = profile:getBool("soundDisabled", self.soundDisabled)
358
359	local fadeInTime = profile:getValue("fadeInTime")
360	if fadeInTime ~= nil then
361	self.fadeInTime = tonumber(fadeInTime) * 1000
362	end
363
364	local fadeOutTime = profile:getValue("fadeOutTime")
365	if fadeOutTime ~= nil then
366	self.fadeOutTime = tonumber(fadeOutTime) * 1000
367	end
368
369	if applyProfile then
370	self:applyElementAspectScale(positionValue == nil)
371	self:fixThinLines()
372	self:updateAbsolutePosition()
373	end
374	end

mouseEvent

Description

Mouse event hook for mouse movement checks.

Definition

mouseEvent()

Code

600	function GuiElement:mouseEvent(posX, posY, isDown, isUp, button, eventUsed)
601	if eventUsed == nil then
602	eventUsed = false
603	end
604
605	if self.visible then
606	for i=#self.elements, 1, -1 do
607	local v = self.elements[i]
608	if v:mouseEvent(posX, posY, isDown, isUp, button, eventUsed) then
609	eventUsed = true
610	end
611	end
612	end
613
614	return eventUsed
615	end

move

Description

Modify this element's position (i.e. translate position).

Definition

move()

Code

1044	function GuiElement:move(dx, dy)
1045	self.position[1] = self.position[1] + dx
1046	self.position[2] = self.position[2] + dy
1047	self:updateAbsolutePosition()
1048	end

new

Description

Create a new GuiElement.

Definition

new(target Target)

Arguments

target

Target

ScreenElement instance

Code

134	function GuiElement.new(target, custom_mt)
135	local self = setmetatable({}, custom_mt or GuiElement_mt)
136	self:include(GuiMixin) -- adds hasIncluded() method to check for included mixins
137
138	self.elements = {}
139	self.target = target
140	if target ~= nil then
141	self.targetName = target.name
142	end
143
144	self.profile = ""
145	self.name = nil
146	self.screenAlign = 0
147	self.screenAlignStr = nil
148	self.positionOrigin = 0
149	self.positionOriginStr = nil
150	self.debugEnabled = false
151	self.position = {0, 0}
152	self.absPosition = {0, 0}
153	self.absSize = {1, 1}
154	self.size = {1 * g_aspectScaleX, 1 * g_aspectScaleY}
155	self.margin = {0, 0, 0, 0} -- left, top, right, bottom
156	self.anchors = {0, 1, 0, 1} -- top left
157	self.outputSize = {g_referenceScreenWidth, g_referenceScreenHeight}
158	self.imageSize = {1024, 1024}
159	self.visible = true
160	self.disabled = false
161	self.thinLineProtection = true
162	self.disallowFlowCut = false
163
164	self.alpha = 1
165	self.fadeInTime = 0
166	self.fadeOutTime = 0
167	self.fadeDirection = 0
168	self.newLayer = false
169	self.toolTipText = nil
170	self.toolTipElementId = nil
171	self.toolTipElement = nil
172	self.layoutIgnore = false
173
174	self.focusFallthrough = false
175
176	self.clipping = false
177
178	self.hasFrame = false
179	self.frameThickness = {0, 0, 0, 0} -- left, top, right, bottom
180	self.frameColors = {
181	[GuiElement.FRAME_LEFT] = {1, 1, 1, 1},
182	[GuiElement.FRAME_TOP] = {1, 1, 1, 1},
183	[GuiElement.FRAME_RIGHT] = {1, 1, 1, 1},
184	[GuiElement.FRAME_BOTTOM] = {1, 1, 1, 1},
185	}
186	self.frameOverlayVisible = {true, true, true, true}
187
188	self.updateChildrenOverlayState = true
189	self.overlayState = GuiOverlay.STATE_NORMAL
190	self.previousOverlayState = nil -- remembers the current overlay state when it needs to be temporarily overridden(e.g. STATE_PRESSED)
191
192	self.isSoundSuppressed = false
193	self.soundDisabled = false
194
195	self.handleFocus = true
196	self.focusChangeData = {}
197	self.focusId = nil
198	self.focusActive = false
199
200	return self
201	end

onClose

Description

Called on the root element of a screen view when it is closed. This raises the "onCloseCallback" if defined and propagates to all children.

Definition

onClose()

Code

778	function GuiElement:onClose()
779	self:raiseCallback("onCloseCallback", self)
780	for i = 1, #self.elements do
781	local child = self.elements[i]
782	child:onClose()
783	end
784	end

onFocusActivate

Description

Called when this element has focus and the focus activation action is triggered. This propagates to all children.

Definition

onFocusActivate()

Code

836	function GuiElement:onFocusActivate()
837	for i = 1, #self.elements do
838	local child = self.elements[i]
839	if child.handleFocus then
840	child:onFocusActivate()
841	end
842	end
843	end

onFocusEnter

Description

Called when this element becomes focused. This propagates to all children.

Definition

onFocusEnter()

Code

822	function GuiElement:onFocusEnter()
823	for i = 1, #self.elements do
824	local child = self.elements[i]
825	child:onFocusEnter()
826	end
827
828	if self.toolTipElement ~= nil and self.toolTipText ~= nil then
829	self.toolTipElement:setText(self.toolTipText)
830	end
831	end

onFocusLeave

Description

Called when this element loses focus. This propagates to all children.

Definition

onFocusLeave()

Code

808	function GuiElement:onFocusLeave()
809	for i = 1, #self.elements do
810	local child = self.elements[i]
811	child:onFocusLeave()
812	end
813
814	if self.toolTipElement ~= nil and self.toolTipText ~= nil then
815	self.toolTipElement:setText("")
816	end
817	end

onGuiSetupFinished

Description

Called on a screen view's root GuiElement when all elements in a screen view have been created. The event is propagated to all children, depth-first.

Definition

onGuiSetupFinished()

Code

493	function GuiElement:onGuiSetupFinished()
494	for _, elem in ipairs(self.elements) do
495	elem:onGuiSetupFinished()
496	end
497
498	if self.toolTipElementId ~= nil then
499	local toolTipElement = self.target:getDescendantById(self.toolTipElementId)
500	if toolTipElement ~= nil then
501	self.toolTipElement = toolTipElement
502	else
503	Logging.warning("toolTipElementId '%s' not found for '%s'!", self.toolTipElementId, self.target.name)
504	end
505	end
506	end

onHighlight

Description

Called when this element is highlighted. This propagates to all children.

Definition

onHighlight()

Code

848	function GuiElement:onHighlight()
849	for i = 1, #self.elements do
850	local child = self.elements[i]
851	child:onHighlight()
852	end
853
854	if self.toolTipElement ~= nil and self.toolTipText ~= nil then
855	self.toolTipElement:setText(self.toolTipText)
856	end
857	end

onHighlightRemove

Description

Called when this element loses the highlight. This propagates to all children.

Definition

onHighlightRemove()

Code

862	function GuiElement:onHighlightRemove()
863	for i = 1, #self.elements do
864	local child = self.elements[i]
865	child:onHighlightRemove()
866	end
867
868	if self.toolTipElement ~= nil and self.toolTipText ~= nil then
869	self.toolTipElement:setText("")
870	end
871	end

onOpen

Description

Called on the root element of a screen view when it is opened. This raises the "onOpenCallback" if defined and propagates to all children.

Definition

onOpen()

Code

767	function GuiElement:onOpen()
768	self:raiseCallback("onOpenCallback", self)
769	for i = 1, #self.elements do
770	local child = self.elements[i]
771	child:onOpen()
772	end
773	end

raiseCallback

Description

Raise a previously added callback by name.

Definition

raiseCallback()

Code

1543	function GuiElement:raiseCallback(name, ...)
1544	if self[name] ~= nil then
1545	if self.target ~= nil then
1546	return self[name](self.target, ...)
1547	else
1548	return self[name](...)
1549	end
1550	end
1551	return nil
1552	end

removeElement

Description

Remove a child GuiElement from this GuiElement.

Definition

removeElement()

Code

914	function GuiElement:removeElement(element)
915	for i = 1, #self.elements do
916	local child = self.elements[i]
917	if child == element then
918	table.remove(self.elements, i)
919	element.parent = nil
920	break
921	end
922	end
923	end

reset

Description

Resets the state of this GuiElement and its children.

Definition

reset()

Code

995	function GuiElement:reset()
996	for i = 1, #self.elements do
997	self.elements[i]:reset()
998	end
999	end

restoreOverlayState

Description

Restore a previously stored overlay state after an overriding state has expired

Definition

restoreOverlayState()

Code

882	function GuiElement:restoreOverlayState()
883	if self.previousOverlayState then -- restore overlay state from before
884	self:setOverlayState(self.previousOverlayState)
885	self.previousOverlayState = nil
886	end
887	end

setAbsolutePosition

Description

Directly set the absolute screen position of this GuiElement. Also updates children accordingly.

Definition

setAbsolutePosition()

Code

1053	function GuiElement:setAbsolutePosition(x, y)
1054	local xDif = x - self.absPosition[1]
1055	local yDif = y - self.absPosition[2]
1056	self.absPosition[1] = x
1057	self.absPosition[2] = y
1058
1059	for i = 1, #self.elements do
1060	local child = self.elements[i]
1061	child:setAbsolutePosition(child.absPosition[1] + xDif, child.absPosition[2] + yDif)
1062	end
1063
1064	if self.hasFrame then
1065	self:updateFramePosition()
1066	end
1067	end

setAlpha

Description

Directly set this element's alpha (transparency) value

Definition

setAlpha(alpha Transparency)

Arguments

alpha

Transparency

value in the floating point range of [0, 1], where 0 is invisible and 1 is opaque.

Code

1184	function GuiElement:setAlpha(alpha)
1185	if alpha ~= self.alpha then
1186
1187	self.alpha = MathUtil.clamp(alpha, 0, 1)
1188	for _, childElem in pairs(self.elements) do
1189	childElem:setAlpha(self.alpha)
1190	end
1191
1192	if self.alpha == 1 or self.alpha == 0 then
1193	self.fadeDirection = 0
1194	end
1195	end
1196	end

setDisabled

Description

Set this element's disabled state. Disabled elements can be displayed differently and do not respond to input actions.

Definition

setDisabled(disabled If, doNotUpdateChildren If)

Arguments

disabled	If	true, disables the element. False enables it again.
doNotUpdateChildren	If	true, does not apply the disabled state to child elements.

Code

1123	function GuiElement:setDisabled(disabled, doNotUpdateChildren)
1124	self.disabled = disabled
1125	if doNotUpdateChildren == nil or not doNotUpdateChildren then
1126	for i=1, #self.elements do
1127	self.elements[i]:setDisabled(disabled)
1128	end
1129	end
1130	end

setHandleFocus

Description

Set this elements capability to receive focus.

Definition

setHandleFocus()

Code

897	function GuiElement:setHandleFocus(handleFocus)
898	self.handleFocus = handleFocus
899	end

setId

Description

Try setting this element's ID from its XML definition.

Definition

setId()

Code

1578	function GuiElement:setId(xmlFile, key)
1579	local id = getXMLString(xmlFile, key.."#id")
1580	if id ~= nil then
1581	local valid = true
1582
1583	local _, varName = GuiElement.extractIndexAndNameFromID(id)
1584
1585	if varName:find("[^%w_]") ~= nil then
1586	print("Error: Invalid gui element id "..id)
1587	valid = false
1588	end
1589
1590	if valid then
1591	self.id = id
1592	end
1593	end
1594	end

setOverlayState

Description

Set this element's overlay state

Definition

setOverlayState(overlayState Overlay)

Arguments

overlayState

Overlay

state identified by one of the GuiOverlay.STATE_[...] constants.

Code

1500	function GuiElement:setOverlayState(overlayState)
1501	self.overlayState = overlayState
1502	if self.updateChildrenOverlayState then
1503	for _, child in ipairs(self.elements) do
1504	child:setOverlayState(overlayState)
1505	end
1506	end
1507	end

setPosition

Description

Set this element's position.

Definition

setPosition()

Code

1036	function GuiElement:setPosition(x, y)
1037	self.position[1] = Utils.getNoNil(x, self.position[1])
1038	self.position[2] = Utils.getNoNil(y, self.position[2])
1039	self:updateAbsolutePosition()
1040	end

setSize

Description

Set this element's size.

Definition

setSize()

Code

1071	function GuiElement:setSize(x, y)
1072	x = Utils.getNoNil(x, self.size[1])
1073	y = Utils.getNoNil(y, self.size[2])
1074
1075	if self.thinLineProtection then
1076	if x ~= 0 then
1077	x = math.max(x, 1 / g_screenWidth)
1078	end
1079
1080	if y ~= 0 then
1081	y = math.max(y, 1 / g_screenHeight)
1082	end
1083	end
1084
1085	self.size[1] = x
1086	self.size[2] = y
1087	self:updateAbsolutePosition()
1088	end

setSoundSuppressed

Description

Toggle a flag to suppress UI sounds issued by this element or by the FocusManager when handling this element. This setting will propagate to children.

Definition

setSoundSuppressed()

Code

1226	function GuiElement:setSoundSuppressed(doSuppress)
1227	self.isSoundSuppressed = doSuppress
1228
1229	for _, child in pairs(self.elements) do
1230	child:setSoundSuppressed(doSuppress)
1231	end
1232	end

setVisible

Description

Set this element's visibility.

Definition

setVisible()

Code

1092	function GuiElement:setVisible(visible)
1093	self.visible = visible
1094	end

shouldFocusChange

Description

Determine if this GuiElement should change focus in a given direction.

Definition

shouldFocusChange()

Code

788	function GuiElement:shouldFocusChange(direction)
789	-- focus should only change if all sub elements allow the change
790	for _, v in ipairs(self.elements) do
791	if (not v:shouldFocusChange(direction)) then
792	return false
793	end
794	end
795
796	return true
797	end

storeOverlayState

Description

Store the current overlay state while another overrides it (e.g. pressed state)

Definition

storeOverlayState()

Code

876	function GuiElement:storeOverlayState()
877	self.previousOverlayState = self:getOverlayState()
878	end

toggleFrameSide

Description

Toggle a frame side's visibility identified by index. If this element has no frame this will have no effect.

Definition

toggleFrameSide(int sideIndex)

Arguments

int

sideIndex

Index of the frame side, use one of GuiElement.FRAME_...

Code

512	function GuiElement:toggleFrameSide(sideIndex, isVisible)
513	if self.hasFrame then
514	self.frameOverlayVisible[sideIndex] = isVisible
515	end
516	end

toString

Description

Get a nice string representation for this GUI element.

Definition

toString()

Code

1653	function GuiElement:toString()
1654	return string.format(
1655	"[ID: %s, FocusID: %s, GuiProfile: %s, Position: %g, %g]",
1656	tostring(self.id),
1657	tostring(self.focusId),
1658	tostring(self.profile),
1659	self.absPosition[1], self.absPosition[2]
1660	)
1661	end

touchEvent

Description

Touch event hook for touch movement checks.

Definition

touchEvent()

Code

619	function GuiElement:touchEvent(posX, posY, isDown, isUp, touchId, eventUsed)
620	if eventUsed == nil then
621	eventUsed = false
622	end
623
624	if self.visible then
625	for i=#self.elements, 1, -1 do
626	local v = self.elements[i]
627	if v:touchEvent(posX, posY, isDown, isUp, touchId, eventUsed) then
628	eventUsed = true
629	end
630	end
631	end
632
633	return eventUsed
634	end

unlinkElement

Description

Safely remove this GuiElement from its parent, if it has a parent.

Definition

unlinkElement()

Code

927	function GuiElement:unlinkElement()
928	if self.parent ~= nil then
929	self.parent:removeElement(self)
930	end
931	end

update

Description

Update this GuiElement.

Definition

update()

Code

690	function GuiElement:update(dt)
691	if self.fadeDirection ~= 0 then
692	if self.fadeDirection > 0 then
693	self:setAlpha(self.alpha + self.fadeDirection * (dt / self.fadeInTime))
694	else
695	self:setAlpha(self.alpha + self.fadeDirection * (dt / self.fadeOutTime))
696	end
697	end
698
699	for i = 1, #self.elements do
700	local child = self.elements[i]
701	if child:getIsActiveNonRec() then
702	-- if child:getIsVisibleNonRec() then
703	child:update(dt)
704	end
705	end
706	end

updateAbsolutePosition

Description

Update this elements absolute screen position. This needs to be called whenever a position, alignment, origin or size value changes.

Definition

updateAbsolutePosition()

Code

936	function GuiElement:updateAbsolutePosition()
937	local borders = self:getParentBorders()
938
939	-- Get absolute anchor position
940	local ax1 = borders[1] + (borders[3] - borders[1]) * self.anchors[1]
941	local ax2 = borders[1] + (borders[3] - borders[1]) * self.anchors[2]
942	local ay1 = borders[2] + (borders[4] - borders[2]) * self.anchors[3]
943	local ay2 = borders[2] + (borders[4] - borders[2]) * self.anchors[4]
944
945
946	local tlX = ax1 + self.position[1]
947	local tlY = ay1 + self.position[2]
948	local trX = ax2 + self.position[1]
949	local blY = ay2 + self.position[2]
950
951	local isStretchingX = self.anchors[1] < self.anchors[2]
952	local isStretchingY = self.anchors[3] < self.anchors[4]
953
954	local width = self.size[1]
955	local height = self.size[2]
956
957	if not isStretchingX then
958	if self.pivot ~= nil then
959	tlX = tlX - width * self.pivot[1]
960	trX = trX + width - width * self.pivot[1]
961	else
962	tlX = tlX - width * self.anchors[1]
963	trX = trX + width - width * self.anchors[2]
964	end
965	end
966
967	if not isStretchingY then
968	if self.pivot ~= nil then
969	tlY = tlY - height * self.pivot[2]
970	blY = blY + height - height * self.pivot[2]
971	else
972	tlY = tlY - height * self.anchors[3]
973	blY = blY + height - height * self.anchors[4]
974	end
975	end
976
977	self.absPosition[1] = tlX
978	self.absPosition[2] = tlY
979
980	self.absSize[1] = trX - tlX
981	self.absSize[2] = blY - tlY
982
983
984	for i = 1, #self.elements do
985	self.elements[i]:updateAbsolutePosition()
986	end
987
988	if self.hasFrame then
989	self:updateFramePosition()
990	end
991	end

updateFramePosition

Description

Update the frame overlay positions if necessary.

Definition

updateFramePosition()

Code

520	function GuiElement:updateFramePosition()
521	local x, y = unpack(self.absPosition)
522	local width, height = unpack(self.absSize)
523
524	local xPixel = 1 / g_screenWidth
525	local yPixel = 1 / g_screenHeight
526	width = math.max(width, xPixel)
527	height = math.max(height, yPixel)
528
529	if self.frameBounds == nil then
530	self.frameBounds = {{}, {}, {}, {}}
531	end
532
533	local frameLeft = GuiElement.FRAME_LEFT
534	local frameRight = GuiElement.FRAME_RIGHT
535	local frameTop = GuiElement.FRAME_TOP
536	local frameBottom = GuiElement.FRAME_BOTTOM
537
538
539	local left = self.frameBounds[frameLeft]
540	left.x = x
541	left.y = y
542	left.width = self.frameThickness[frameLeft]
543	left.height = height
544
545	local top = self.frameBounds[frameTop]
546	top.x = x
547	top.y = y + height - self.frameThickness[frameTop]
548	top.width = width
549	top.height = self.frameThickness[frameTop]
550
551	local right = self.frameBounds[frameRight]
552	right.x = x + width - self.frameThickness[frameRight]
553	right.y = y
554	right.width = self.frameThickness[frameRight]
555	right.height = height
556
557	local bottom = self.frameBounds[frameBottom]
558	bottom.x = x
559	bottom.y = y
560	bottom.width = width
561	bottom.height = self.frameThickness[frameBottom]
562
563	self:cutFrameBordersHorizontal(self.frameBounds[frameLeft], self.frameBounds[frameTop], true)
564	self:cutFrameBordersHorizontal(self.frameBounds[frameLeft], self.frameBounds[frameBottom], true)
565	self:cutFrameBordersHorizontal(self.frameBounds[frameRight], self.frameBounds[frameTop], false)
566	self:cutFrameBordersHorizontal(self.frameBounds[frameRight], self.frameBounds[frameBottom], false)
567
568	self:cutFrameBordersVertical(self.frameBounds[frameBottom], self.frameBounds[frameLeft], true)
569	self:cutFrameBordersVertical(self.frameBounds[frameBottom], self.frameBounds[frameRight], true)
570	self:cutFrameBordersVertical(self.frameBounds[frameTop], self.frameBounds[frameLeft], false)
571	self:cutFrameBordersVertical(self.frameBounds[frameTop], self.frameBounds[frameRight], false)
572	end

updatePositionForOrigin

Description

Get the bit mask value for a position origin string value.

Definition

updatePositionForOrigin()

Code

1340	function GuiElement:updatePositionForOrigin(origin)
1341	if origin == "topLeft" then
1342	-- self.positionOrigin = GuiElement.ORIGIN_TOP + GuiElement.ORIGIN_LEFT
1343	self.pivot = {0, 0}
1344	elseif origin == "topCenter" then
1345	-- self.positionOrigin = GuiElement.ORIGIN_CENTER + GuiElement.ORIGIN_TOP
1346	self.pivot = {0.5, 0}
1347	elseif origin == "topRight" then
1348	-- self.positionOrigin = GuiElement.ORIGIN_RIGHT + GuiElement.ORIGIN_TOP
1349	self.pivot = {1, 0}
1350	elseif origin == "middleLeft" then
1351	-- self.positionOrigin = GuiElement.ORIGIN_MIDDLE + GuiElement.ORIGIN_LEFT
1352	self.pivot = {0, 0.5}
1353	elseif origin == "middleCenter" then
1354	-- self.positionOrigin = GuiElement.ORIGIN_CENTER + GuiElement.ORIGIN_MIDDLE
1355	self.pivot = {0.5, 0.5}
1356	elseif origin == "middleRight" then
1357	-- self.positionOrigin = GuiElement.ORIGIN_RIGHT + GuiElement.ORIGIN_MIDDLE
1358	self.pivot = {1, 0.5}
1359	elseif origin == "bottomCenter" then
1360	-- self.positionOrigin = GuiElement.ORIGIN_CENTER + GuiElement.ORIGIN_BOTTOM
1361	self.pivot = {0, 1}
1362	elseif origin == "bottomRight" then
1363	-- self.positionOrigin = GuiElement.ORIGIN_RIGHT + GuiElement.ORIGIN_BOTTOM
1364	self.pivot = {0.5, 1}
1365	else -- bottomLeft
1366	-- self.positionOrigin = GuiElement.ORIGIN_BOTTOM + GuiElement.ORIGIN_LEFT
1367	self.pivot = {1, 1}
1368	end
1369	end

updateScreenAlign

Description

Get the bit mask value for a screen alignment string value.

Definition

updateScreenAlign()

Code

1373	function GuiElement:updateScreenAlign(align)
1374	if align == "topLeft" then
1375	-- self.screenAlign = GuiElement.SCREEN_ALIGN_LEFT + GuiElement.SCREEN_ALIGN_TOP
1376	self:setAnchor(0, 1)
1377	elseif align == "topCenter" then
1378	-- self.screenAlign = GuiElement.SCREEN_ALIGN_CENTER + GuiElement.SCREEN_ALIGN_TOP
1379	self:setAnchor(0.5, 1)
1380	elseif align == "topRight" then
1381	-- self.screenAlign = GuiElement.SCREEN_ALIGN_RIGHT + GuiElement.SCREEN_ALIGN_TOP
1382	self:setAnchor(1, 1)
1383	elseif align == "middleLeft" then
1384	-- self.screenAlign = GuiElement.SCREEN_ALIGN_LEFT + GuiElement.SCREEN_ALIGN_MIDDLE
1385	self:setAnchor(0, 0.5)
1386	elseif align == "middleCenter" then
1387	-- self.screenAlign = GuiElement.SCREEN_ALIGN_CENTER + GuiElement.SCREEN_ALIGN_MIDDLE
1388	self:setAnchor(0.5, 0.5)
1389	elseif align == "middleRight" then
1390	-- self.screenAlign = GuiElement.SCREEN_ALIGN_RIGHT + GuiElement.SCREEN_ALIGN_MIDDLE
1391	self:setAnchor(1, 0.5)
1392	elseif align == "bottomLeft" then
1393	-- self.screenAlign = GuiElement.SCREEN_ALIGN_LEFT + GuiElement.SCREEN_ALIGN_BOTTOM
1394	self:setAnchor(0, 0)
1395	elseif align == "bottomCenter" then
1396	-- self.screenAlign = GuiElement.SCREEN_ALIGN_CENTER + GuiElement.SCREEN_ALIGN_BOTTOM
1397	self:setAnchor(0.5, 0)
1398	elseif align == "bottomRight" then
1399	-- self.screenAlign = GuiElement.SCREEN_ALIGN_RIGHT + GuiElement.SCREEN_ALIGN_BOTTOM
1400	self:setAnchor(1, 0)
1401	else
1402	self:setAnchors(0, 1, 0, 1)
1403	-- self.screenAlign = GuiElement.SCREEN_ALIGN_XNONE + GuiElement.SCREEN_ALIGN_YNONE
1404	end
1405	end

GDN

LUADOC - Farming Simulator 22

Script v1_7_1_0

Engine v1_7_1_0

Foundation Reference

GuiElement

addCallback

addElement

applyElementAspectScale

applyProfile

applyScreenAlignment

canReceiveFocus

clone

copyAttributes

cutFrameBordersHorizontal

cutFrameBordersVertical

delete

draw

extractIndexAndNameFromID

fadeIn

fadeOut

findDescendantsRec

fixThinLines

getAspectScale

getBorders

getCenter

getClipArea

getDescendantById

getDescendantByName

getDescendants

getFirstDescendant

getFocusTarget

getHandleFocus

getIsActive

getIsActiveNonRec

getIsDisabled

getIsHighlighted

getIsSelected

getIsVisible

getIsVisibleNonRec

getOverlayState

getParentBorders

getSoundSuppressed

include

inputEvent

isChildOf

keyEvent

loadFromXML

loadProfile

mouseEvent

move

new

onClose

onFocusActivate

onFocusEnter

onFocusLeave

onGuiSetupFinished

onHighlight

onHighlightRemove

onOpen

raiseCallback

removeElement

reset

restoreOverlayState

setAbsolutePosition

setAlpha

setDisabled

setHandleFocus

setId

setOverlayState

setPosition

setSize

setSoundSuppressed

setVisible

shouldFocusChange

storeOverlayState

toggleFrameSide

toString

touchEvent

unlinkElement