LUADOC - Farming Simulator 19

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#idstring [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#namestring [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#outputSizestring [optional] Reference resolution for size settings, defaults to 1920:1080. Format: "[width]px [height]px", e.g. outputSize="1920px 1080px"
GuiElement#positionstring [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#sizestring [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#imageSizestring [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#marginstring [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#positionOriginstring [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#screenAlignstring [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#fixedHeightbool [optional] If true, will prevent height values to be scaled with changing aspect ratios of the screen. Cannot be enabled at the same time as #fixedWidth.
GuiElement#fixedWidthbool [optional] If true, will prevent width values to be scaled with changing aspect ratios of the screen. Cannot be enabled at the same time as #fixedHeight.
GuiElement#visiblebool [optional] If false, will make the element invisible on creation.
GuiElement#disabledbool [optional] If true, will make the element disabled on creation.
GuiElement#newLayerbool [optional] If true, will cause the element to have its own GUI layer.
GuiElement#debugEnabledbool [optional] If true, will draw debug hints (e.g. borders, text alignment lines, etc.) from the element.
GuiElement#thinLineProtectionbool [optional] If false, will turn off ensurement that non-zero sizes are at least one screen pixel in width and height.
GuiElement#updateChildrenOverlayStatebool [optional] If true, will cause child elements to receive the same overlay state as this element.
GuiElement#fadeInTimefloat [optional] Time in seconds the element needs to fade to visible, defaults to 0.
GuiElement#fadeOutTimefloat [optional] Time in seconds the element needs to fade to invisible, defaults to 0.
GuiElement#toolTipElementIdstring [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#toolTipTextstring [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#layoutIgnorebool [optional] If true, this element will not be repositioned by layouting elements, defaults to false.
GuiElement#hasFramebool [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#handleFocusbool [optional] If false, this element will not receive focus actions and state.
GuiElement#focusIdstring [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#focusInitbool [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#focusChangeTopstring [optional] Focus ID of element to focus when an upward navigation input is received on the GUI. Automatically assigned by default.
GuiElement#focusChangeBottomstring [optional] Focus ID of element to focus when a downward navigation input is received on the GUI. Automatically assigned by default.
GuiElement#focusChangeLeftstring [optional] Focus ID of element to focus when an leftward navigation input is received on the GUI. Automatically assigned by default.
GuiElement#focusChangeRightstring [optional] Focus ID of element to focus when an rightward navigation input is received on the GUI. Automatically assigned by default.
GuiElement#consoleFocusChangeTopstring [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#consoleFocusChangeBottomstring [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#consoleFocusChangeLeftstring [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#consoleFocusChangeRightstring [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]Filenamestring [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]PreviewFilenamestring [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]UVsstring [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]FocusedUVsstring [optional] Texture coordinates to use for the displayed image when the element is focused. Works like #imageUVs.
GuiElement#[layer]PressedUVsstring [optional] Texture coordinates to use for the displayed image when the element is pressed (e.g. buttons). Works like #imageUVs.
GuiElement#[layer]SelectedUVsstring [optional] Texture coordinates to use for the displayed image when the element is selected (e.g. list items). Works like #imageUVs.
GuiElement#[layer]HighlightedUVsstring [optional] Texture coordinates to use for the displayed image when the element is highlighted (e.g. on mouse over). Works like #imageUVs.
GuiElement#[layer]DisabledUVsstring [optional] Texture coordinates to use for the displayed image when the element is disabled. Works like #imageUVs.
GuiElement#[layer]Colorstring [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]FocusedColorstring [optional] Color tint for displayed image when the element is focused. Works like #imageColor.
GuiElement#[layer]PressedColorstring [optional] Color tint for displayed image when the element is pressed. Works like #imageColor.
GuiElement#[layer]SelectedColorstring [optional] Color tint for displayed image when the element is selected. Works like #imageColor.
GuiElement#[layer]HighlightedColorstring [optional] Color tint for displayed image when the element is highlighted. Works like #imageColor.
GuiElement#[layer]DisabledColorstring [optional] Color tint for displayed image when the element is disabled. Works like #imageColor.
GuiElement#[layer]Rotationfloat [optional] Rotation of displayed image in degrees. Positive values rotate clockwise, negative values rotate counter-clockwise around the image center.
GuiElement#[layer]IsWebOverlaybool [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#onCreateArgsstring [optional] Arguments which are supplied to the #onCreate callback in addition to the element itself
GuiElement#onCreatecallback [optional] Function to be called after all values have been loaded and the element's own initialization has completed.
GuiElement#onOpencallback callback [optional] Function to be called when this element is opened and before any of its children are opened.
GuiElement#onClosecallback callback [optional] Function to be called when this element is closed and before any of its children are closed.
GuiElement#onDrawcallback callback [optional] Function to be called when this element is visible and being drawn and before any of its children are being drawn.
GuiElement#focusChangeOverridecallback [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

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
xmlFileXMLfile handle
keyXMLnode path of this GuiElement's definition.
funcNameNameof the callback function
Code
1414function GuiElement:addCallback(xmlFile, key, funcName)
1415 local callbackName = getXMLString(xmlFile, key)
1416 if callbackName ~= nil then
1417 if self.target ~= nil then
1418 self[funcName] = self.target[callbackName]
1419 else
1420 self[funcName] = ClassUtil.getFunction(callbackName)
1421 end
1422 end
1423end

addElement

Description
Add a child GuiElement to this GuiElement.
Definition
addElement()
Code
848function GuiElement:addElement(element)
849 if element.parent ~= nil then
850 element.parent:removeElement(element)
851 end
852
853 table.insert(self.elements, element)
854 element.parent = self
855end

applyElementAspectScale

Description
Apply element aspect scale transformations.
Definition
applyElementAspectScale(bool ignorePosition)
Arguments
boolignorePositionIf true, will not apply aspect scaling to this element's position
Code
1361function GuiElement:applyElementAspectScale(ignorePosition)
1362 local scaleX, scaleY = self:getAspectScale()
1363
1364 self.size[1] = self.size[1] * scaleX
1365 self.margin[1] = self.margin[1] * scaleX
1366 self.margin[3] = self.margin[3] * scaleX
1367
1368 self.size[2] = self.size[2] * scaleY
1369 self.margin[2] = self.margin[2] * scaleY
1370 self.margin[4] = self.margin[4] * scaleY
1371
1372 if not ignorePosition then
1373 self.position[1] = self.position[1] * scaleX
1374 self.position[2] = self.position[2] * scaleY
1375 end
1376end

applyProfile

Description
Apply a GUI profile with a given name to this element.
Definition
applyProfile(profileName Name, bool force)
Arguments
profileNameNameof the profile to apply to this element
boolforce[optional] If true, will apply all profile settings, including position and size.
Code
366function GuiElement:applyProfile(profileName, force)
367 if profileName then
368 self:deleteFrame()
369
370 local pro = g_gui:getProfile(profileName)
371 if pro ~= nil then
372 self.profile = profileName
373 self:loadProfile(pro, not force)
374 end
375
376 if self.hasFrame then
377 self:createFrame()
378 end
379 end
380end

applyScreenAlignment

Description
Apply screen alignment to this element and its children. Scales size, position and margin depending on alignment settings.
Definition
applyScreenAlignment()
Code
1381function GuiElement:applyScreenAlignment()
1382 self:applyElementAspectScale()
1383
1384 for _,child in ipairs(self.elements) do
1385 child:applyScreenAlignment()
1386 end
1387end

canReceiveFocus

Description
Determine if this GuiElement can receive focus.
Definition
canReceiveFocus()
Code
751function GuiElement:canReceiveFocus()
752 return false -- default is not focusable, subclasses need to make themselves available
753end

clone

Description
Create a deep copy clone of this GuiElement.
Definition
clone(parent Target, includeId [optional,, suppressOnCreate [optional,)
Arguments
parentTargetparent 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
414function GuiElement:clone(parent, includeId, suppressOnCreate)
415 local ret = self:new()
416 ret:copyAttributes(self)
417
418 if ret.hasFrame then
419 ret:createFrame()
420 end
421
422 if parent ~= nil then
423 parent:addElement(ret)
424 end
425
426 for i = 1, table.getn(self.elements) do
427 local clonedChild = self.elements[i]:clone(ret, includeId, suppressOnCreate)
428 if includeId then
429 clonedChild.id = self.elements[i].id
430 end
431 end
432
433 if not suppressOnCreate then
434 ret:raiseCallback("onCreateCallback", ret, ret.onCreateArgs)
435 end
436
437 return ret
438end

copyAttributes

Description
Copy all attributes from a source GuiElement to this GuiElement.
Definition
copyAttributes()
Code
442function GuiElement:copyAttributes(src)
443 self.visible = src.visible
444 self.name = src.name
445 self.typeName = src.typeName
446 self.disabled = src.disabled
447 self.positionOrigin = src.positionOrigin
448 self.screenAlign = src.screenAlign
449 self.newLayer = src.newLayer
450 self.debugEnabled = src.debugEnabled
451 self.fixedHeight = src.fixedHeight
452 self.fixedWidth = src.fixedWidth
453 self.size = ListUtil.copyTable(src.size)
454 self.margin = ListUtil.copyTable(src.margin)
455 self.onCreateCallback = src.onCreateCallback
456 self.onCreateArgs = src.onCreateArgs
457 self.onCloseCallback = src.onCloseCallback
458 self.onOpenCallback = src.onOpenCallback
459 self.onDrawCallback = src.onDrawCallback
460 self.target = src.target
461 self.targetName = src.targetName
462 self.profile = src.profile
463 self.outputSize = ListUtil.copyTable(src.outputSize)
464 self.imageSize = ListUtil.copyTable(src.imageSize)
465 self.fadeInTime = src.fadeInTime
466 self.fadeOutTime = src.fadeOutTime
467 self.alpha = src.alpha
468 self.fadeDirection = src.fadeDirection
469 self.updateChildrenOverlayState = src.updateChildrenOverlayState
470 self.toolTipElementId = src.toolTipElementId
471 self.toolTipText = src.toolTipText
472 self.handleFocus = src.handleFocus
473
474 self.ignoreLayout = src.ignoreLayout
475 self.soundDisabled = src.soundDisabled
476
477 self.hasFrame = src.hasFrame
478 self.frameThickness = src.frameThickness
479 self.frameLeftColor = src.frameLeftColor
480 self.frameTopColor = src.frameTopColor
481 self.frameRightColor = src.frameRightColor
482 self.frameBottomColor = src.frameBottomColor
483
484 self.focusId = src.focusId
485 self.focusChangeData = ListUtil.copyTable(src.focusChangeData)
486 self.focusActive = src.focusActive
487 self.isAlwaysFocusedOnOpen = src.isAlwaysFocusedOnOpen
488
489 self.position = ListUtil.copyTable(src.position)
490 self.absPosition = ListUtil.copyTable(src.absPosition)
491end

createFrame

Description
Create frame overlays if this element has a frame.
Definition
createFrame()
Code
517function GuiElement:createFrame()
518 self:deleteFrame() -- clear first
519
520 local leftOverlay = Overlay:new(g_baseUIFilename, 0, 0, 1, 1)
521 leftOverlay:setColor(unpack(self.frameLeftColor))
522 leftOverlay:setAlignment(Overlay.ALIGN_VERTICAL_BOTTOM, Overlay.ALIGN_HORIZONTAL_LEFT)
523 local topOverlay = Overlay:new(g_baseUIFilename, 0, 0, 1, 1)
524 topOverlay:setColor(unpack(self.frameTopColor))
525 topOverlay:setAlignment(Overlay.ALIGN_VERTICAL_TOP, Overlay.ALIGN_HORIZONTAL_LEFT)
526 local rightOverlay = Overlay:new(g_baseUIFilename, 0, 0, 1, 1)
527 rightOverlay:setColor(unpack(self.frameRightColor))
528 rightOverlay:setAlignment(Overlay.ALIGN_VERTICAL_BOTTOM, Overlay.ALIGN_HORIZONTAL_RIGHT)
529 local bottomOverlay = Overlay:new(g_baseUIFilename, 0, 0, 1, 1)
530 bottomOverlay:setColor(unpack(self.frameBottomColor))
531 bottomOverlay:setAlignment(Overlay.ALIGN_VERTICAL_BOTTOM, Overlay.ALIGN_HORIZONTAL_LEFT)
532
533 self.frameOverlays = {leftOverlay, topOverlay, rightOverlay, bottomOverlay}
534 for _, overlay in pairs(self.frameOverlays) do
535 overlay:setUVs(g_colorBgUVs)
536 end
537
538 self:updateFramePosition()
539end

cutFrameBordersHorizontal

Description
Cut horizontal frame borders if a vertical frame side is thicker.
Definition
cutFrameBordersHorizontal()
Code
583function GuiElement:cutFrameBordersHorizontal(verticalPart, horizontalPart, isLeft)
584 if verticalPart.width > horizontalPart.height then -- equals test for thickness
585 if isLeft then
586 horizontalPart.x = horizontalPart.x + verticalPart.width
587 end
588
589 horizontalPart.width = horizontalPart.width - verticalPart.width
590 end
591end

cutFrameBordersVertical

Description
Cut vertical frame borders if a horizontal frame side is thicker.
Definition
cutFrameBordersVertical()
Code
595function GuiElement:cutFrameBordersVertical(horizontalPart, verticalPart, isBottom)
596 if horizontalPart.width >= verticalPart.height then -- test for greater or equals here to avoid overlaps when thickness is the same
597 if isBottom then
598 verticalPart.y = verticalPart.y + horizontalPart.height
599 end
600
601 verticalPart.height = verticalPart.height - horizontalPart.height
602 end
603end

delete

Description
Delete this GuiElement. Also deletes all child elements and removes itself from its parent and focus.
Definition
delete()
Code
394function GuiElement:delete()
395 for i = #self.elements, 1, -1 do
396 self.elements[i].parent = nil
397 self.elements[i]:delete()
398 end
399
400 self:deleteFrame()
401
402 if self.parent ~= nil then
403 self.parent:removeElement(self)
404 end
405 -- unset focus data
406 FocusManager:removeElement(self)
407end

deleteFrame

Description
Delete any created frame overlays.
Definition
deleteFrame()
Code
384function GuiElement:deleteFrame()
385 for k, overlay in pairs(self.frameOverlays) do
386 overlay:delete()
387 self.frameOverlays[k] = nil
388 end
389end

draw

Description
Draw this GuiElement. If defined, triggers the "onDrawCallback".
Definition
draw()
Code
686function GuiElement:draw()
687 if self.newLayer then
688 new2DLayer()
689 end
690
691 self:raiseCallback("onDrawCallback", self)
692
693 if self.hasFrame then
694 for _, frameOverlay in pairs(self.frameOverlays) do
695 frameOverlay:render()
696 end
697 end
698
699 if self.debugEnabled or g_uiDebugEnabled then
700 local xPixel = 1 / g_screenWidth
701 local yPixel = 1 / g_screenHeight
702 setOverlayColor(GuiElement.debugOverlay, 1, 0, 0, 1)
703 renderOverlay(GuiElement.debugOverlay, self.absPosition[1] - xPixel, self.absPosition[2] - yPixel, self.size[1] + 2 * xPixel, yPixel)
704 renderOverlay(GuiElement.debugOverlay, self.absPosition[1] - xPixel, self.absPosition[2] + self.size[2], self.size[1] + 2 * xPixel, yPixel)
705 renderOverlay(GuiElement.debugOverlay, self.absPosition[1] - xPixel, self.absPosition[2], xPixel, self.size[2])
706 renderOverlay(GuiElement.debugOverlay, self.absPosition[1] + self.size[1], self.absPosition[2], xPixel, self.size[2])
707 end
708
709 for _,v in ipairs(self.elements) do
710 if v:getIsVisibleNonRec() then
711 v:draw()
712 end
713 end
714end

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
elementIdElementID, to be used as a field name on a ScreenElement view.
Return Values
Indexornil, field name
Code
1444function GuiElement.extractIndexAndNameFromID(elementId)
1445 local len = elementId:len()
1446 local varName = elementId
1447 local index = nil
1448 if len >= 4 and elementId:sub(len, len) == "]" then
1449 local startI = elementId:find("[", 1, true)
1450 if startI ~= nil and startI > 1 and startI < len-1 then
1451 index = Utils.evaluateFormula(elementId:sub(startI + 1, len - 1))
1452 if index ~= nil then
1453 varName = elementId:sub(1, startI - 1)
1454 end
1455 end
1456 end
1457 return index, varName
1458end

fadeIn

Description
Fade this element into visibility.
Definition
fadeIn()
Code
1087function GuiElement:fadeIn(factor)
1088 if self.fadeInTime > 0 then
1089 self.fadeDirection = 1 * Utils.getNoNil(factor, 1)
1090 self:setAlpha(math.max(self.alpha, 0.0001)) -- Ensure that we are considered visible and get an update
1091 else
1092 self.fadeDirection = 0
1093 self:setAlpha(1)
1094 end
1095end

fadeOut

Description
Fade this element out of visibility.
Definition
fadeOut()
Code
1099function GuiElement:fadeOut(factor)
1100 if self.fadeOutTime > 0 then
1101 self.fadeDirection = -1 * Utils.getNoNil(factor, 1)
1102 else
1103 self.fadeDirection = 0
1104 self:setAlpha(0)
1105 end
1106end

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
accumulatorListwhich receives descendant elements
rootElementCurrentelement root whose direction children are added (after optional evaluation)
predicateFunction[optional]If specified, will be evaluated per element (see getDescendants)
Code
1162function GuiElement:findDescendantsRec(accumulator, rootElement, predicateFunction)
1163 if not rootElement then return end -- safety
1164 for _, element in ipairs(rootElement.elements) do
1165 self:findDescendantsRec(accumulator, element, predicateFunction) -- depth first
1166 if not predicateFunction or predicateFunction(element) then
1167 table.insert(accumulator, element)
1168 end
1169 end
1170end

fixThinLines

Description
Definition
fixThinLines()
Code
1289function GuiElement:fixThinLines()
1290 if self.thinLineProtection then
1291 if self.size[1] ~= 0 then
1292 self.size[1] = math.max(self.size[1], 1 / g_screenWidth)
1293 end
1294
1295 if self.size[2] ~= 0 then
1296 self.size[2] = math.max(self.size[2], 1 / g_screenHeight)
1297 end
1298
1299 self:updateAbsolutePosition()
1300 end
1301end

getAspectScale

Description
Get aspect scaling values for this element's settings and the game's resolution.
Definition
getAspectScale()
Return Values
floatXaspect scale factor
floatYaspect scale factor
Code
1332function GuiElement:getAspectScale()
1333 local scaleX = 1
1334 if bitAND(self.screenAlign, GuiElement.SCREEN_ALIGN_XNONE) == 0 then
1335 if not self.fixedWidth then
1336 scaleX = scaleX * g_aspectScaleX
1337 end
1338
1339 if self.fixedHeight then
1340 scaleX = scaleX / g_aspectScaleY
1341 end
1342 end
1343
1344 local scaleY = 1
1345 if bitAND(self.screenAlign, GuiElement.SCREEN_ALIGN_YNONE) == 0 then
1346 if not self.fixedHeight then
1347 scaleY = scaleY * g_aspectScaleY
1348 end
1349
1350 if self.fixedWidth then
1351 scaleY = scaleY / g_aspectScaleX
1352 end
1353 end
1354
1355 return scaleX, scaleY
1356end

getBorders

Description
Get this element's border rectangle represented by minimum and maximum points.
Definition
getBorders()
Return Values
Elementbordersin an array: {minX, minY, maxX, maxY}
Code
1318function GuiElement:getBorders()
1319 return {self.absPosition[1], self.absPosition[2], self.absPosition[1] + self.size[1], self.absPosition[2] + self.size[2]}
1320end

getCenter

Description
Get this element's center position.
Definition
getCenter()
Code
1324function GuiElement:getCenter()
1325 return {self.absPosition[1] + self.size[1] * 0.5, self.absPosition[2] + self.size[2] * 0.5}
1326end

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
idElementid
Return Values
Elementornil
Code
1208function GuiElement:getDescendantById(id)
1209 local element = nil
1210 if id then
1211 local function findId(element)
1212 return element.id and element.id == id
1213 end
1214
1215 element = self:getFirstDescendant(findId)
1216 end
1217 return element
1218end

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
nameElementname
Return Values
Elementornil
Code
1225function GuiElement:getDescendantByName(name)
1226 local element = nil
1227 if name then
1228 local function findId(element)
1229 return element.name and element.name == name
1230 end
1231
1232 element = self:getFirstDescendant(findId)
1233 end
1234 return element
1235end

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
Listofthis element's descendants in depth-first order with contiguous numeric indices.
Code
1181function GuiElement:getDescendants(predicateFunction)
1182 local descendants = {}
1183 self:findDescendantsRec(descendants, self, predicateFunction)
1184 return descendants
1185end

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
predicateFunctionAfunction 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
Firstmatchingdescendant element in depth-first order or nil, if no element matched the predicate function
Code
1194function GuiElement:getFirstDescendant(predicateFunction)
1195 local element = nil
1196 local res = self:getDescendants(predicateFunction)
1197 if #res > 0 then
1198 element = res[1]
1199 end
1200 return element
1201end

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
GuiElementActualelement to focus.
Code
960function GuiElement:getFocusTarget(incomingDirection, moveDirection)
961 return self
962end

getHandleFocus

Description
Determine if this element can receive focus.
Definition
getHandleFocus()
Code
836function GuiElement:getHandleFocus()
837 return self.handleFocus
838end

getIsActive

Description
Determine if this element is active (not disabled and visible).
Definition
getIsActive()
Code
1127function GuiElement:getIsActive()
1128 return not self.disabled and self:getIsVisible()
1129end

getIsActiveNonRec

Description
Determine if this element is active (not disabled and visible) without checking the parents
Definition
getIsActiveNonRec()
Code
1133function GuiElement:getIsActiveNonRec()
1134 return not self.disabled and self:getIsVisibleNonRec()
1135end

getIsDisabled

Description
Determine if this element is disabled.
Definition
getIsDisabled()
Code
1061function GuiElement:getIsDisabled()
1062 return self.disabled
1063end

getIsHighlighted

Description
Determine if this element is currently highlighted.
Definition
getIsHighlighted()
Code
1077function GuiElement:getIsHighlighted()
1078 if self.parent ~= nil then
1079 return self.parent:getIsHighlighted()
1080 end
1081
1082 return false
1083end

getIsSelected

Description
Determine if this element is currently selected.
Definition
getIsSelected()
Code
1067function GuiElement:getIsSelected()
1068 if self.parent ~= nil then
1069 return self.parent:getIsSelected()
1070 end
1071
1072 return false
1073end

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
1027function GuiElement:getIsVisible()
1028 if not self.visible or self.alpha == 0 then
1029 return false
1030 end
1031
1032 if self.parent ~= nil then
1033 return self.parent:getIsVisible()
1034 end
1035
1036 return true
1037end

getIsVisibleNonRec

Description
Determine if this element is visible without checking the parents
Definition
getIsVisibleNonRec()
Code
1041function GuiElement:getIsVisibleNonRec()
1042 return self.visible and self.alpha > 0
1043end

getOverlayState

Description
Get this element's overlay state.
Definition
getOverlayState()
Code
1403function GuiElement:getOverlayState()
1404 return self.overlayState
1405end

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
Parentelementor full screen borders in an array: {minX, minY, maxX, maxY}
Code
1307function GuiElement:getParentBorders()
1308 if self.parent ~= nil then
1309 return {self.parent.absPosition[1], self.parent.absPosition[2], self.parent.absPosition[1] + self.parent.size[1], self.parent.absPosition[2] + self.parent.size[2]}
1310 end
1311
1312 return {0, 0, 1, 1}
1313end

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
1151function GuiElement:getSoundSuppressed()
1152 return self.isSoundSuppressed
1153end

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
guiMixinTypeClasstable reference of a descendant of GuiMixin
Code
1484function GuiElement:include(guiMixinType)
1485 guiMixinType.new():addTo(self)
1486end

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
actionNameof input action which was triggered.
valueInputvalue in the range of [-1, 1] for full axes and [0, 1] for half axes (includes buttons)
eventUsedIftrue, the event has been used by an input handler and should only be acted upon in exceptional cases.
Return Values
Trueifthe input event has been handled, false otherwise.
Code
634function GuiElement:inputEvent(action, value, eventUsed)
635 if not eventUsed then
636 eventUsed = self.parent and self.parent:inputEvent(action, value, eventUsed)
637 if eventUsed == nil then
638 eventUsed = false
639 end
640 end
641
642 return eventUsed
643end

isChildOf

Description
Check if this element is the child of another element. This checks the full parent hierarchy.
Definition
isChildOf()
Code
934function GuiElement:isChildOf(element)
935 if element == self then
936 return false
937 end
938
939 local p = self.parent
940 while p do
941 if p == self then
942 return false
943 end
944
945 if p == element then
946 return true
947 end
948
949 p = p.parent
950 end
951
952 return false
953end

keyEvent

Description
Key event hook for raw keyboard input.
Definition
keyEvent()
Return Values
Trueifthe keyboard input has been processed by this element.
Code
648function GuiElement:keyEvent(unicode, sym, modifier, isDown, eventUsed)
649 if eventUsed == nil then
650 eventUsed = false
651 end
652
653 if self.visible then
654 for i=table.getn(self.elements), 1, -1 do
655 local v = self.elements[i]
656 if v:keyEvent(unicode, sym, modifier, isDown, eventUsed) then
657 eventUsed = true
658 end
659 end
660 end
661
662 return eventUsed
663end

loadFromXML

Description
Load element data from an XML definition file.
Definition
loadFromXML(xmlFile Definition, key XML)
Arguments
xmlFileDefinitionXML file handle
keyXMLnode path to this element's definition
Code
206function GuiElement:loadFromXML(xmlFile, key)
207 local profile = getXMLString(xmlFile, key .. "#profile")
208 if profile ~= nil then
209 self.profile = profile
210
211 local pro = g_gui:getProfile(profile) -- defaults to base reference if profile name is invalid, also prints warning in that case
212 self:loadProfile(pro)
213 end
214
215 self:setId(xmlFile, key)
216
217 self.onCreateArgs = getXMLString(xmlFile, key.."#onCreateArgs")
218 self:addCallback(xmlFile, key.."#onCreate", "onCreateCallback")
219 self:addCallback(xmlFile, key.."#onOpen", "onOpenCallback")
220 self:addCallback(xmlFile, key.."#onClose", "onCloseCallback")
221 self:addCallback(xmlFile, key.."#onDraw", "onDrawCallback")
222
223 self.name = Utils.getNoNil(getXMLString(xmlFile, key.."#name"), self.name)
224 self.imageSize = GuiUtils.get2DArray(getXMLString(xmlFile, key.."#imageSize"), self.imageSize)
225 self.outputSize = GuiUtils.get2DArray(getXMLString(xmlFile, key.."#outputSize"), self.outputSize)
226 self.position = GuiUtils.getNormalizedValues(getXMLString(xmlFile, key.."#position"), self.outputSize, self.position)
227 self.size = GuiUtils.getNormalizedValues(getXMLString(xmlFile, key.."#size"), self.outputSize, self.size)
228 self.margin = GuiUtils.getNormalizedValues(getXMLString(xmlFile, key.."#margin"), self.outputSize, self.margin)
229
230 self.thinLineProtection = Utils.getNoNil(getXMLBool(xmlFile, key.."#thinLineProtection"), self.thinLineProtection)
231 self.positionOriginStr = Utils.getNoNil(getXMLString(xmlFile, key.."#positionOrigin"), self.positionOriginStr)
232 self.screenAlignStr = Utils.getNoNil(getXMLString(xmlFile, key.."#screenAlign"), self.screenAlignStr)
233 self.fixedHeight = Utils.getNoNil(getXMLBool(xmlFile, key.."#fixedHeight"), self.fixedHeight)
234 self.fixedWidth = Utils.getNoNil(getXMLBool(xmlFile, key.."#fixedWidth"), self.fixedWidth)
235 self.visible = Utils.getNoNil(getXMLBool(xmlFile, key.."#visible"), self.visible)
236 self.disabled = Utils.getNoNil(getXMLBool(xmlFile, key.."#disabled"), self.disabled)
237 self.newLayer = Utils.getNoNil(getXMLBool(xmlFile, key.."#newLayer"), self.newLayer)
238 self.debugEnabled = Utils.getNoNil(getXMLBool(xmlFile, key.."#debugEnabled"), self.debugEnabled)
239 self.updateChildrenOverlayState = Utils.getNoNil(getXMLBool(xmlFile, key.."#updateChildrenOverlayState"), self.updateChildrenOverlayState)
240 self.toolTipText = getXMLString(xmlFile, key.."#toolTipText")
241 self.toolTipElementId = getXMLString(xmlFile, key.."#toolTipElementId")
242 self.layoutIgnore = Utils.getNoNil(getXMLBool(xmlFile, key .. "#layoutIgnore"), self.layoutIgnore)
243
244 self.handleFocus = Utils.getNoNil(getXMLBool(xmlFile, key.."#handleFocus"), self.handleFocus)
245 self.soundDisabled = Utils.getNoNil(getXMLBool(xmlFile, key .. "#soundDisabled"), self.soundDisabled)
246
247 self.hasFrame = Utils.getNoNil(getXMLBool(xmlFile, key .. "#hasFrame"), self.hasFrame)
248 if self.hasFrame then
249 local thickness = getXMLString(xmlFile, key .. "#frameThickness")
250 self.frameThickness = GuiUtils.getNormalizedValues(thickness, self.outputSize) or self.frameThickness
251
252 local color = getXMLString(xmlFile, key .. "#frameLeftColor")
253 self.frameLeftColor = GuiUtils.getColorArray(color) or self.frameLeftColor
254 color = getXMLString(xmlFile, key .. "#frameTopColor")
255 self.frameTopColor = GuiUtils.getColorArray(color) or self.frameTopColor
256 color = getXMLString(xmlFile, key .. "#frameRightColor")
257 self.frameRightColor = GuiUtils.getColorArray(color) or self.frameRightColor
258 color = getXMLString(xmlFile, key .. "#frameBottomColor")
259 self.frameBottomColor = GuiUtils.getColorArray(color) or self.frameBottomColor
260 end
261
262 local fadeInTime = getXMLFloat(xmlFile, key.."#fadeInTime")
263 if fadeInTime ~= nil then
264 self.fadeInTime = fadeInTime*1000
265 end
266
267 local fadeOutTime = getXMLFloat(xmlFile, key.."#fadeOutTime")
268 if fadeOutTime ~= nil then
269 self.fadeOutTime = fadeOutTime*1000
270 end
271
272 if self.fixedHeight and self.fixedWidth then
273 print("Error: It's not allowed to use fixedHeight and fixedWidth!")
274 end
275
276 self:fixThinLines()
277 self:updateScreenAlign(self.screenAlignStr)
278 self:updatePositionForOrigin(self.positionOriginStr)
279
280 if self.toolTipText ~= nil then
281 if self.toolTipText:sub(1,6) == "$l10n_" then
282 self.toolTipText = g_i18n:getText(self.toolTipText:sub(7))
283 end
284 end
285
286 -- load focus properties
287 FocusManager:loadElementFromXML(xmlFile, key, self)
288
289 self:verifyConfiguration()
290end

loadProfile

Description
Load profile data for this element.
Definition
loadProfile(profile Loaded, applyProfile If)
Arguments
profileLoadedGUI profile
applyProfileIftrue, will re-calculate some dynamic properties. Use this when setting profiles dynamically at run time.
Code
296function GuiElement:loadProfile(profile, applyProfile)
297 local imageSize = profile:getValue("imageSize")
298 if (imageSize ~= nil) then
299 local x,y = StringUtil.getVectorFromString(imageSize)
300 if x ~= nil and y ~= nil then
301 self.imageSize = { x, y }
302 end
303 end
304
305 local outputSize = profile:getValue("outputSize")
306 if (outputSize ~= nil) then
307 local x,y = StringUtil.getVectorFromString(outputSize)
308 if x ~= nil and y ~= nil then
309 self.outputSize = { x, y }
310 end
311 end
312
313
314 local positionValue = profile:getValue("position")
315 self.position = GuiUtils.getNormalizedValues(positionValue, self.outputSize, self.position)
316 self.size = GuiUtils.getNormalizedValues(profile:getValue("size"), self.outputSize, self.size)
317 self.margin = GuiUtils.getNormalizedValues(profile:getValue("margin"), self.outputSize, self.margin)
318
319 self.positionOriginStr = profile:getValue("positionOrigin", self.positionOriginStr)
320 self.name = profile:getValue("name", self.name)
321 self.screenAlignStr = profile:getValue("screenAlign", self.screenAlignStr)
322 self.fixedHeight = profile:getBool("fixedHeight", self.fixedHeight)
323 self.fixedWidth = profile:getBool("fixedWidth", self.fixedWidth)
324 self.visible = profile:getBool("visible", self.visible)
325 self.disabled = profile:getBool("disabled", self.disabled)
326 self.newLayer = profile:getBool("newLayer", self.newLayer)
327 self.debugEnabled = profile:getBool("debugEnabled", self.debugEnabled)
328 self.updateChildrenOverlayState = profile:getBool("updateChildrenOverlayState", self.updateChildrenOverlayState)
329 self.toolTipText = profile:getValue("toolTipText", self.toolTipText)
330 self.layoutIgnore = profile:getBool("layoutIgnore", self.layoutIgnore)
331 self.thinLineProtection = profile:getBool("thinLineProtection", self.thinLineProtection)
332
333 self.hasFrame = profile:getBool("hasFrame", self.hasFrame)
334 if self.hasFrame then
335 self.frameThickness = GuiUtils.getNormalizedValues(profile:getValue("frameThickness"), self.outputSize) or self.frameThickness
336 self.frameLeftColor = GuiUtils.getColorArray(profile:getValue("frameLeftColor"), self.frameLeftColor)
337 self.frameTopColor = GuiUtils.getColorArray(profile:getValue("frameTopColor"), self.frameTopColor)
338 self.frameRightColor = GuiUtils.getColorArray(profile:getValue("frameRightColor"), self.frameRightColor)
339 self.frameBottomColor = GuiUtils.getColorArray(profile:getValue("frameBottomColor"), self.frameBottomColor)
340 end
341
342 self.handleFocus = profile:getBool("handleFocus", self.handleFocus)
343 self.soundDisabled = profile:getBool("soundDisabled", self.soundDisabled)
344
345 local fadeInTime = profile:getValue("fadeInTime")
346 if fadeInTime ~= nil then
347 self.fadeInTime = tonumber(fadeInTime) * 1000
348 end
349
350 local fadeOutTime = profile:getValue("fadeOutTime")
351 if fadeOutTime ~= nil then
352 self.fadeOutTime = tonumber(fadeOutTime) * 1000
353 end
354
355 if applyProfile then
356 self:applyElementAspectScale(positionValue == nil)
357 self:fixThinLines()
358 self:updateAbsolutePosition()
359 end
360end

mouseEvent

Description
Mouse event hook for mouse movement checks.
Definition
mouseEvent()
Code
607function GuiElement:mouseEvent(posX, posY, isDown, isUp, button, eventUsed)
608 if eventUsed == nil then
609 eventUsed = false
610 end
611
612 if self.visible then
613 for i=table.getn(self.elements), 1, -1 do
614 local v = self.elements[i]
615 if v:mouseEvent(posX, posY, isDown, isUp, button, eventUsed) then
616 eventUsed = true
617 end
618 end
619 end
620
621 return eventUsed
622end

move

Description
Modify this element's position (i.e. translate position).
Definition
move()
Code
975function GuiElement:move(dx, dy)
976 self.position = {self.position[1] + dx,self.position[2] + dy}
977 self:updateAbsolutePosition()
978end

new

Description
Create a new GuiElement.
Definition
new(target Target)
Arguments
targetTargetScreenElement instance
Code
136function GuiElement:new(target, custom_mt)
137 if custom_mt == nil then
138 custom_mt = GuiElement_mt
139 end
140
141 local self = setmetatable({}, custom_mt)
142 self:include(GuiMixin) -- adds hasIncluded() method to check for included mixins
143
144 self.elements = {}
145 self.target = target
146 if target ~= nil then
147 self.targetName = target.name
148 end
149
150 self.profile = ""
151 self.name = nil
152 self.screenAlign = 0
153 self.screenAlignStr = nil
154 self.positionOrigin = 0
155 self.positionOriginStr = nil
156 self.debugEnabled = false
157 self.position = {0, 0}
158 self.absPosition = {0, 0}
159 self.size = {1, 1}
160 self.margin = {0, 0, 0, 0} -- left, top, right, bottom
161 self.outputSize = {g_referenceScreenWidth, g_referenceScreenHeight}
162 self.imageSize = {1024, 1024}
163 self.visible = true
164 self.disabled = false
165 self.fixedHeight = false
166 self.fixedWidth = false
167 self.thinLineProtection = true
168
169 self.alpha = 1
170 self.fadeInTime = 0
171 self.fadeOutTime = 0
172 self.fadeDirection = 0
173 self.newLayer = false
174 self.toolTipText = nil
175 self.toolTipElementId = nil
176 self.toolTipElement = nil
177 self.layoutIgnore = false
178
179 self.hasFrame = false
180 self.frameThickness = {0, 0, 0, 0} -- left, top, right, bottom
181 self.frameLeftColor = {1, 1, 1, 1}
182 self.frameTopColor = {1, 1, 1, 1}
183 self.frameRightColor = {1, 1, 1, 1}
184 self.frameBottomColor = {1, 1, 1, 1}
185 self.frameOverlays = {} -- array of frame overlays in order of thickness definition
186
187 self.updateChildrenOverlayState = true
188 self.overlayState = GuiOverlay.STATE_NORMAL
189 self.previousOverlayState = nil -- remembers the current overlay state when it needs to be temporarily overridden(e.g. STATE_PRESSED)
190
191 self.isSoundSuppressed = false
192 self.soundDisabled = false
193
194 self.handleFocus = true
195 self.focusChangeData = {}
196 self.focusId = nil
197 self.focusActive = false
198
199 return self
200end

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
729function GuiElement:onClose()
730 self:raiseCallback("onCloseCallback", self)
731 for _,child in ipairs(self.elements) do
732 child:onClose()
733 end
734end

onFocusActivate

Description
Called when this element has focus and the focus activation action is triggered. This propagates to all children.
Definition
onFocusActivate()
Code
784function GuiElement:onFocusActivate()
785 for _, v in ipairs(self.elements) do
786 if v.handleFocus then
787 v:onFocusActivate()
788 end
789 end
790end

onFocusEnter

Description
Called when this element becomes focused. This propagates to all children.
Definition
onFocusEnter()
Code
771function GuiElement:onFocusEnter()
772 for _, v in ipairs(self.elements) do
773 v:onFocusEnter()
774 end
775
776 if self.toolTipElement ~= nil and self.toolTipText ~= nil then
777 self.toolTipElement:setText(self.toolTipText)
778 end
779end

onFocusLeave

Description
Called when this element loses focus. This propagates to all children.
Definition
onFocusLeave()
Code
758function GuiElement:onFocusLeave()
759 for _, v in ipairs(self.elements) do
760 v:onFocusLeave()
761 end
762
763 if self.toolTipElement ~= nil and self.toolTipText ~= nil then
764 self.toolTipElement:setText("")
765 end
766end

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
496function GuiElement:onGuiSetupFinished()
497 for _, elem in ipairs(self.elements) do
498 elem:onGuiSetupFinished()
499 end
500
501 if self.toolTipElementId ~= nil then
502 local toolTipElement = self.target:getDescendantById(self.toolTipElementId)
503 if toolTipElement ~= nil then
504 self.toolTipElement = toolTipElement
505 else
506 g_logManager:warning("toolTipElementId '%s' not found for '%s'!", self.toolTipElementId, self.target.name)
507 end
508 end
509
510 if self.hasFrame then
511 self:createFrame()
512 end
513end

onHighlight

Description
Called when this element is highlighted. This propagates to all children.
Definition
onHighlight()
Code
795function GuiElement:onHighlight()
796 for _, v in ipairs(self.elements) do
797 v:onHighlight()
798 end
799
800 if self.toolTipElement ~= nil and self.toolTipText ~= nil then
801 self.toolTipElement:setText(self.toolTipText)
802 end
803end

onHighlightRemove

Description
Called when this element loses the highlight. This propagates to all children.
Definition
onHighlightRemove()
Code
808function GuiElement:onHighlightRemove()
809 for _, v in ipairs(self.elements) do
810 v:onHighlightRemove()
811 end
812
813 if self.toolTipElement ~= nil and self.toolTipText ~= nil then
814 self.toolTipElement:setText("")
815 end
816end

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
719function GuiElement:onOpen()
720 self:raiseCallback("onOpenCallback", self)
721 for _, child in ipairs(self.elements) do
722 child:onOpen()
723 end
724end

raiseCallback

Description
Raise a previously added callback by name.
Definition
raiseCallback()
Code
1427function GuiElement:raiseCallback(name, ...)
1428 if self[name] ~= nil then
1429 if self.target ~= nil then
1430 return self[name](self.target, ...)
1431 else
1432 return self[name](...)
1433 end
1434 end
1435 return nil
1436end

removeElement

Description
Remove a child GuiElement from this GuiElement.
Definition
removeElement()
Code
859function GuiElement:removeElement(element)
860 for i,v in ipairs(self.elements) do
861 if v == element then
862 table.remove(self.elements, i)
863 element.parent = nil
864 break
865 end
866 end
867end

reset

Description
Resets the state of this GuiElement and its children.
Definition
reset()
Code
925function GuiElement:reset()
926 for _,child in ipairs(self.elements) do
927 child:reset()
928 end
929end

restoreOverlayState

Description
Restore a previously stored overlay state after an overriding state has expired
Definition
restoreOverlayState()
Code
827function GuiElement:restoreOverlayState()
828 if self.previousOverlayState then -- restore overlay state from before
829 self:setOverlayState(self.previousOverlayState)
830 self.previousOverlayState = nil
831 end
832end

setAbsolutePosition

Description
Directly set the absolute screen position of this GuiElement. Also updates children accordingly.
Definition
setAbsolutePosition()
Code
983function GuiElement:setAbsolutePosition(x, y)
984 local xDif = x - self.absPosition[1]
985 local yDif = y - self.absPosition[2]
986 self.absPosition = {x, y}
987
988 for _, childElem in ipairs(self.elements) do
989 childElem:setAbsolutePosition(childElem.absPosition[1] + xDif, childElem.absPosition[2] + yDif)
990 end
991
992 if self.hasFrame and next(self.frameOverlays) ~= nil then
993 self:updateFramePosition()
994 end
995end

setAlpha

Description
Directly set this element's alpha (transparency) value
Definition
setAlpha(alpha Transparency)
Arguments
alphaTransparencyvalue in the floating point range of [0, 1], where 0 is invisible and 1 is opaque.
Code
1111function GuiElement:setAlpha(alpha)
1112 if alpha ~= self.alpha then
1113
1114 self.alpha = MathUtil.clamp(alpha, 0, 1)
1115 for _, childElem in pairs(self.elements) do
1116 childElem:setAlpha(self.alpha)
1117 end
1118
1119 if self.alpha == 1 or self.alpha == 0 then
1120 self.fadeDirection = 0
1121 end
1122 end
1123end

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
disabledIftrue, disables the element. False enables it again.
doNotUpdateChildrenIftrue, does not apply the disabled state to child elements.
Code
1050function GuiElement:setDisabled(disabled, doNotUpdateChildren)
1051 self.disabled = disabled
1052 if doNotUpdateChildren == nil or not doNotUpdateChildren then
1053 for i=1, table.getn(self.elements) do
1054 self.elements[i]:setDisabled(disabled)
1055 end
1056 end
1057end

setHandleFocus

Description
Set this elements capability to receive focus.
Definition
setHandleFocus()
Code
842function GuiElement:setHandleFocus(handleFocus)
843 self.handleFocus = handleFocus
844end

setId

Description
Try setting this element's ID from its XML definition.
Definition
setId()
Code
1462function GuiElement:setId(xmlFile, key)
1463 local id = getXMLString(xmlFile, key.."#id")
1464 if id ~= nil then
1465 local valid = true
1466
1467 local _, varName = GuiElement.extractIndexAndNameFromID(id)
1468
1469 if varName:find("[^%w_]") ~= nil then
1470 print("Error: Invalid gui element id "..id)
1471 valid = false
1472 end
1473
1474 if valid then
1475 self.id = id
1476 end
1477 end
1478end

setOverlayState

Description
Set this element's overlay state
Definition
setOverlayState(overlayState Overlay)
Arguments
overlayStateOverlaystate identified by one of the GuiOverlay.STATE_[...] constants.
Code
1392function GuiElement:setOverlayState(overlayState)
1393 self.overlayState = overlayState
1394 if self.updateChildrenOverlayState then
1395 for _, child in pairs(self.elements) do
1396 child:setOverlayState(overlayState)
1397 end
1398 end
1399end

setPosition

Description
Set this element's position.
Definition
setPosition()
Code
966function GuiElement:setPosition(x, y)
967 x = Utils.getNoNil(x, self.position[1])
968 y = Utils.getNoNil(y, self.position[2])
969 self.position = {x, y}
970 self:updateAbsolutePosition()
971end

setSize

Description
Set this element's size.
Definition
setSize()
Code
999function GuiElement:setSize(x, y)
1000 x = Utils.getNoNil(x, self.size[1])
1001 y = Utils.getNoNil(y, self.size[2])
1002
1003 if self.thinLineProtection then
1004 if x ~= 0 then
1005 x = math.max(x, 1 / g_screenWidth)
1006 end
1007
1008 if y ~= 0 then
1009 y = math.max(y, 1 / g_screenHeight)
1010 end
1011 end
1012
1013 self.size = {x, y}
1014 self:updateAbsolutePosition()
1015end

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
1140function GuiElement:setSoundSuppressed(doSuppress)
1141 self.isSoundSuppressed = doSuppress
1142
1143 for _, child in pairs(self.elements) do
1144 child:setSoundSuppressed(doSuppress)
1145 end
1146end

setVisible

Description
Set this element's visibility.
Definition
setVisible()
Code
1019function GuiElement:setVisible(visible)
1020 self.visible = visible
1021end

shouldFocusChange

Description
Determine if this GuiElement should change focus in a given direction.
Definition
shouldFocusChange()
Code
738function GuiElement:shouldFocusChange(direction)
739 -- focus should only change if all sub elements allow the change
740 for _, v in ipairs(self.elements) do
741 if (not v:shouldFocusChange(direction)) then
742 return false
743 end
744 end
745
746 return true
747end

storeOverlayState

Description
Store the current overlay state while another overrides it (e.g. pressed state)
Definition
storeOverlayState()
Code
821function GuiElement:storeOverlayState()
822 self.previousOverlayState = self:getOverlayState()
823end

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
intsideIndexIndex of the frame side, use one of GuiElement.FRAME_...
Code
545function GuiElement:toggleFrameSide(sideIndex, isVisible)
546 if self.hasFrame then
547 self.frameOverlays[sideIndex]:setIsVisible(isVisible)
548 end
549end

toString

Description
Get a nice string representation for this GUI element.
Definition
toString()
Code
1493function GuiElement:toString()
1494 return string.format(
1495 "[ID: %s, FocusID: %s, GuiProfile: %s, Position: %g, %g]",
1496 tostring(self.id),
1497 tostring(self.focusId),
1498 tostring(self.profile),
1499 self.absPosition[1], self.absPosition[2]
1500 )
1501end

unlinkElement

Description
Safely remove this GuiElement from its parent, if it has a parent.
Definition
unlinkElement()
Code
871function GuiElement:unlinkElement()
872 if self.parent ~= nil then
873 self.parent:removeElement(self)
874 end
875end

update

Description
Update this GuiElement.
Definition
update()
Code
667function GuiElement:update(dt)
668 if self.fadeDirection ~= 0 then
669 if self.fadeDirection > 0 then
670 self:setAlpha(self.alpha + self.fadeDirection * (dt / self.fadeInTime))
671 else
672 self:setAlpha(self.alpha + self.fadeDirection * (dt / self.fadeOutTime))
673 end
674 end
675
676 for _,v in ipairs(self.elements) do
677 if v:getIsActiveNonRec() then
678 v:update(dt)
679 end
680 end
681end

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
880function GuiElement:updateAbsolutePosition()
881 local borders = self:getParentBorders()
882
883 if bitAND(self.screenAlign, GuiElement.SCREEN_ALIGN_RIGHT) ~= 0 then
884 self.absPosition[1] = borders[3]
885 elseif bitAND(self.screenAlign, GuiElement.SCREEN_ALIGN_CENTER) ~= 0 then
886 self.absPosition[1] = borders[1] + (borders[3]-borders[1])/2
887 else
888 self.absPosition[1] = borders[1]
889 end
890
891 if bitAND(self.screenAlign, GuiElement.SCREEN_ALIGN_TOP) ~= 0 then
892 self.absPosition[2] = borders[4]
893 elseif bitAND(self.screenAlign, GuiElement.SCREEN_ALIGN_MIDDLE) ~= 0 then
894 self.absPosition[2] = borders[2]+(borders[4]-borders[2])/2
895 else
896 self.absPosition[2] = borders[2]
897 end
898
899 self.absPosition[1] = self.absPosition[1] + self.position[1]
900 self.absPosition[2] = self.absPosition[2] + self.position[2]
901
902 if bitAND(self.positionOrigin, GuiElement.ORIGIN_RIGHT) ~= 0 then
903 self.absPosition[1] = self.absPosition[1] - self.size[1]
904 elseif bitAND(self.positionOrigin, GuiElement.ORIGIN_CENTER) ~= 0 then
905 self.absPosition[1] = self.absPosition[1] - self.size[1]*0.5
906 end
907
908 if bitAND(self.positionOrigin, GuiElement.ORIGIN_TOP) ~= 0 then
909 self.absPosition[2] = self.absPosition[2] - self.size[2]
910 elseif bitAND(self.positionOrigin, GuiElement.ORIGIN_MIDDLE) ~= 0 then
911 self.absPosition[2] = self.absPosition[2] - self.size[2]*0.5
912 end
913
914 for _,child in ipairs(self.elements) do
915 child:updateAbsolutePosition()
916 end
917
918 if self.hasFrame and next(self.frameOverlays) ~= nil then
919 self:updateFramePosition()
920 end
921end

updateFramePosition

Description
Update the frame overlay positions if necessary.
Definition
updateFramePosition()
Code
553function GuiElement:updateFramePosition()
554 local x, y = unpack(self.absPosition)
555 local width, height = unpack(self.size)
556
557 local left, top, right, bottom = 1, 2, 3, 4
558 local partBorders = {
559 [left] = {x=x, y=y, width=self.frameThickness[left], height=height},
560 [top] = {x=x, y=y + height, width=width, height=self.frameThickness[top]},
561 [right] = {x=x + width, y=y, width=self.frameThickness[right], height=height},
562 [bottom] = {x=x, y=y, width=width, height=self.frameThickness[bottom]},
563 }
564
565 self:cutFrameBordersHorizontal(partBorders[left], partBorders[top], true)
566 self:cutFrameBordersHorizontal(partBorders[left], partBorders[bottom], true)
567 self:cutFrameBordersHorizontal(partBorders[right], partBorders[top], false)
568 self:cutFrameBordersHorizontal(partBorders[right], partBorders[bottom], false)
569
570 self:cutFrameBordersVertical(partBorders[bottom], partBorders[left], true)
571 self:cutFrameBordersVertical(partBorders[bottom], partBorders[right], true)
572 self:cutFrameBordersVertical(partBorders[top], partBorders[left], false)
573 self:cutFrameBordersVertical(partBorders[top], partBorders[right], false)
574
575 for side = left, bottom do -- from left to bottom in order
576 self.frameOverlays[side]:setPosition(partBorders[side].x, partBorders[side].y)
577 self.frameOverlays[side]:setDimension(partBorders[side].width, partBorders[side].height)
578 end
579end

updatePositionForOrigin

Description
Get the bit mask value for a position origin string value.
Definition
updatePositionForOrigin()
Code
1239function GuiElement:updatePositionForOrigin(origin)
1240 if origin == "topLeft" then
1241 self.positionOrigin = GuiElement.ORIGIN_TOP + GuiElement.ORIGIN_LEFT
1242 elseif origin == "topCenter" then
1243 self.positionOrigin = GuiElement.ORIGIN_CENTER + GuiElement.ORIGIN_TOP
1244 elseif origin == "topRight" then
1245 self.positionOrigin = GuiElement.ORIGIN_RIGHT + GuiElement.ORIGIN_TOP
1246 elseif origin == "middleLeft" then
1247 self.positionOrigin = GuiElement.ORIGIN_MIDDLE + GuiElement.ORIGIN_LEFT
1248 elseif origin == "middleCenter" then
1249 self.positionOrigin = GuiElement.ORIGIN_CENTER + GuiElement.ORIGIN_MIDDLE
1250 elseif origin == "middleRight" then
1251 self.positionOrigin = GuiElement.ORIGIN_RIGHT + GuiElement.ORIGIN_MIDDLE
1252 elseif origin == "bottomCenter" then
1253 self.positionOrigin = GuiElement.ORIGIN_CENTER + GuiElement.ORIGIN_BOTTOM
1254 elseif origin == "bottomRight" then
1255 self.positionOrigin = GuiElement.ORIGIN_RIGHT + GuiElement.ORIGIN_BOTTOM
1256 else -- bottomLeft
1257 self.positionOrigin = GuiElement.ORIGIN_BOTTOM + GuiElement.ORIGIN_LEFT
1258 end
1259end

updateScreenAlign

Description
Get the bit mask value for a screen alignment string value.
Definition
updateScreenAlign()
Code
1263function GuiElement:updateScreenAlign(align)
1264 if align == "topLeft" then
1265 self.screenAlign = GuiElement.SCREEN_ALIGN_LEFT + GuiElement.SCREEN_ALIGN_TOP
1266 elseif align == "topCenter" then
1267 self.screenAlign = GuiElement.SCREEN_ALIGN_CENTER + GuiElement.SCREEN_ALIGN_TOP
1268 elseif align == "topRight" then
1269 self.screenAlign = GuiElement.SCREEN_ALIGN_RIGHT + GuiElement.SCREEN_ALIGN_TOP
1270 elseif align == "middleLeft" then
1271 self.screenAlign = GuiElement.SCREEN_ALIGN_LEFT + GuiElement.SCREEN_ALIGN_MIDDLE
1272 elseif align == "middleCenter" then
1273 self.screenAlign = GuiElement.SCREEN_ALIGN_CENTER + GuiElement.SCREEN_ALIGN_MIDDLE
1274 elseif align == "middleRight" then
1275 self.screenAlign = GuiElement.SCREEN_ALIGN_RIGHT + GuiElement.SCREEN_ALIGN_MIDDLE
1276 elseif align == "bottomLeft" then
1277 self.screenAlign = GuiElement.SCREEN_ALIGN_LEFT + GuiElement.SCREEN_ALIGN_BOTTOM
1278 elseif align == "bottomCenter" then
1279 self.screenAlign = GuiElement.SCREEN_ALIGN_CENTER + GuiElement.SCREEN_ALIGN_BOTTOM
1280 elseif align == "bottomRight" then
1281 self.screenAlign = GuiElement.SCREEN_ALIGN_RIGHT + GuiElement.SCREEN_ALIGN_BOTTOM
1282 else
1283 self.screenAlign = GuiElement.SCREEN_ALIGN_XNONE + GuiElement.SCREEN_ALIGN_YNONE
1284 end
1285end