LUADOC - Farming Simulator 22

Script v1_7_1_0

Engine v1_7_1_0

Foundation Reference

FrameElement

Description
Base display frame element. All GUI views (partial and full screen) inherit from this. This element provides the functionality to register control IDs, which are then exposed as fields of the concrete descendant class (e.g. MainScreen or PasswordDialog). The control IDs must be assigned verbatim to any control in the corresponding configuration XML file. If a registered ID is not used, the field will not be assigned and access will fail. Available field IDs are documented as field properties per class. When creating a new view, take care to include the call to registerControls() in the constructor to declare and expose control elements as fields.
Parent
GuiElement
Functions

changeScreen

Description
Request a view change via the callback defined by setChangeScreenCallback().
Definition
changeScreen(table targetScreenClass)
Arguments
tabletargetScreenClassClass table of requested view (ScreenElement descendant, must be full view)
Code
191function FrameElement:changeScreen(targetScreenClass, returnScreenClass)
192 self.changeScreenCallback(self, targetScreenClass, returnScreenClass)
193end

clone

Description
Override of GuiElement:clone(). Also exposes registered control element fields.
Definition
clone()
Code
44function FrameElement:clone(parent, includeId, suppressOnCreate)
45 local ret = FrameElement:superClass().clone(self, parent, includeId, suppressOnCreate)
46 ret:exposeControlsAsFields(self.name)
47
48 ret.changeScreenCallback = self.changeScreenCallback
49 ret.toggleCustomInputContextCallback = self.toggleCustomInputContextCallback
50 ret.playSampleCallback = self.playSampleCallback
51 ret.hasCustomInputContext = self.hasCustomInputContext
52
53 return ret
54end

copyAttributes

Description
Override of GuiElement:copyAttributes(). Also resets registered control IDs so they can be exposed as fields again.
Definition
copyAttributes()
Code
59function FrameElement:copyAttributes(src)
60 FrameElement:superClass().copyAttributes(self, src)
61 for k, _ in pairs(src.controlIDs) do
62 self.controlIDs[k] = false
63 end
64end

delete

Description
Override of GuiElement:copyAttributes(). Also resets registered control IDs so they can be exposed as fields again.
Definition
delete()
Code
69function FrameElement:delete()
70 FrameElement:superClass().delete(self)
71
72 for k, _ in pairs(self.controlIDs) do
73 self.controlIDs[k] = nil
74 self[k] = nil
75 end
76end

disableInputForDuration

Description
Set input disabling to a given duration.
Definition
disableInputForDuration(float duration)
Arguments
floatdurationInput disabling duration in milliseconds
Code
146function FrameElement:disableInputForDuration(duration)
147 self.inputDisableTime = MathUtil.clamp(duration, 0, 10000) -- clamp to plausible range (up to 10s)
148end

exposeControlsAsFields

Description
Adds registered controls as fields to this FrameElement instance. Called by the GUI system after loading. The new fields will have the same name as the registered ID, so make sure there are no collision to avoid overrides and that IDs are also valid as identifiers in Lua. If a control has been registered but no corresponding element is available (e.g. when sub-classing and omitting some elements), the field will remain undefined. It's up to callers to ensure that field configuration and usage in views matches.
Definition
exposeControlsAsFields(viewName View)
Arguments
viewNameViewname of this frame element
Code
113function FrameElement:exposeControlsAsFields(viewName)
114 local allChildren = self:getDescendants()
115 for _, element in pairs(allChildren) do
116 if element.id and element.id ~= "" then
117 local index, varName = GuiElement.extractIndexAndNameFromID(element.id)
118 if self.controlIDs[varName] ~= nil then
119 if index then -- indexed field, expose as a list
120 if not self[varName] then
121 self[varName] = {}
122 end
123
124 self[varName][index] = element
125 else -- regular field, just assign to the element table
126 self[varName] = element
127 end
128
129 self.controlIDs[varName] = true -- mark as resolved
130 end
131 end
132 end
133
134 if self.debugEnabled or g_uiDebugEnabled then
135 for id, isResolved in pairs(self.controlIDs) do
136 if not isResolved then
137 Logging.warning("FrameElement for GUI view '%s' could not resolve registered control element ID '%s'. Check configuration.", tostring(viewName), tostring(id))
138 end
139 end
140 end
141end

getRootElement

Description
Get the frame's root GuiElement instance. This is the first and only direct child of a FrameElement, as defined by the GUI instantiation logic. This method will always return a GuiElement instance, even if a new one must be created first.
Definition
getRootElement()
Code
82function FrameElement:getRootElement()
83 if #self.elements > 0 then
84 return self.elements[1]
85 else
86 local newRoot = GuiElement.new()
87 self:addElement(newRoot)
88 return newRoot
89 end
90end

isInputDisabled

Description
Check if input is currently disabled.
Definition
isInputDisabled()
Code
152function FrameElement:isInputDisabled()
153 return self.inputDisableTime > 0
154end

new

Description
Definition
new()
Code
24function FrameElement.new(target, customMt)
25 local self = GuiElement.new(target, customMt or FrameElement_mt)
26
27 self.controlIDs = {} -- list of control element IDs to be resolved on loading
28 self.changeScreenCallback = NO_CALLBACK -- change view callback
29 self.toggleCustomInputContextCallback = NO_CALLBACK -- custom input context toggle callback
30 self.playSampleCallback = NO_CALLBACK -- play sound sample callback
31 self.hasCustomInputContext = false -- safety flag for input context stack handling
32
33 self.time = 0
34 self.inputDisableTime = 0
35
36 self.playHoverSoundOnFocus = false
37
38 return self
39end

playSample

Description
Request playing a sound sample identified by name.
Definition
playSample(string sampleName)
Arguments
stringsampleNameSample name, use one of GuiSoundPlayer.SOUND_SAMPLES
Code
210function FrameElement:playSample(sampleName)
211 if not self:getSoundSuppressed() then
212 self.playSampleCallback(sampleName)
213 end
214end

registerControls

Description
Register a collection of control IDs for direct access in GUI views.
Definition
registerControls(controlIDs Table)
Arguments
controlIDsTablewhich holds control IDs as values, as they are required to be present in the view configuration.
Code
95function FrameElement:registerControls(controlIDs)
96 for _, id in pairs(controlIDs) do
97 if self.controlIDs[id] then
98 Logging.warning("Registered multiple control elements with the same ID '%s'. Check screen setup.", tostring(id))
99 else
100 self.controlIDs[id] = false -- hash it for ease of access
101 end
102 end
103end

setChangeScreenCallback

Description
Set a callback for requesting a view change from within a frame or screen view.
Definition
setChangeScreenCallback(func callback)
Arguments
funccallbackFunction reference, signature: function(sourceFrameElement, targetScreenClass, returnScreenClass)
Code
170function FrameElement:setChangeScreenCallback(callback)
171 self.changeScreenCallback = callback or NO_CALLBACK
172end

setInputContextCallback

Description
Set a callback function for requesting a custom menu input context for this frame.
Definition
setInputContextCallback(func callback)
Arguments
funccallbackFunction reference, signature: function(isContextActive)
Code
177function FrameElement:setInputContextCallback(callback)
178 self.toggleCustomInputContextCallback = callback or NO_CALLBACK
179end

setPlaySampleCallback

Description
Set a callback function for requesting to play a sound sample.
Definition
setPlaySampleCallback(func callback)
Arguments
funccallbackFunction reference, signature: function(sampleName)
Code
184function FrameElement:setPlaySampleCallback(callback)
185 self.playSampleCallback = callback or NO_CALLBACK
186end

toggleCustomInputContext

Description
Request toggling of a custom menu input context for this frame via the callback defined by setInputContextCallback().
Definition
toggleCustomInputContext(bool isContextActive, string contextName)
Arguments
boolisContextActiveIf true, will activate a custom menu input context. Otherwise, will clear a previously activated context.
stringcontextNameName of the custom input context. Use a unique identifier value.
Code
200function FrameElement:toggleCustomInputContext(isContextActive, contextName)
201 if self.hasCustomInputContext and not isContextActive or not self.hasCustomInputContext and isContextActive then
202 self.toggleCustomInputContextCallback(isContextActive, contextName)
203 self.hasCustomInputContext = isContextActive
204 end
205end

update

Description
Definition
update()
Code
158function FrameElement:update(dt)
159 FrameElement:superClass().update(self, dt)
160
161 self.time = self.time + dt
162 if self.inputDisableTime > 0 then
163 self.inputDisableTime = self.inputDisableTime - dt
164 end
165end