LUADOC - Farming Simulator 19

Script v1.7.1.0

Engine v1.7.1.0

Foundation Reference

Gui

Description
Graphical User Interface controller. Builds UI from configurations, provides dialog display and propagates UI input.
Functions

addFrame

Description
Add the instance of a specific reusable GUI frame.
Definition
addFrame()
Code
837function Gui:addFrame(frameController, frameRootElement)
838 -- TODO: switch to class keys like screens
839 self.frames[frameController.name] = frameRootElement
840
841 frameController:setChangeScreenCallback(self.changeScreenClosure)
842 frameController:setInputContextCallback(self.toggleCustomInputContextClosure)
843 frameController:setPlaySampleCallback(self.playSampleClosure)
844end

addScreen

Description
Add the instance of a specific GUI screen.
Definition
addScreen()
Code
848function Gui:addScreen(screenClass, screenInstance, screenRootElement)
849 self.screens[screenClass] = screenRootElement
850 self.screenControllers[screenClass] = screenInstance
851
852 -- TODO: use the same pattern for dialog calling from screens
853 screenInstance:setChangeScreenCallback(self.changeScreenClosure)
854 screenInstance:setInputContextCallback(self.toggleCustomInputContextClosure)
855 screenInstance:setPlaySampleCallback(self.playSampleClosure)
856end

assignPlaySampleCallback

Description
Assign the play sample closure to a GUI element which has the PlaySampleMixin included.
Definition
assignPlaySampleCallback(table guiElement)
Arguments
tableguiElementGuiElement instance
Return Values
tableTheGuiElement instance given in the guiElement parameter
Code
806function Gui:assignPlaySampleCallback(guiElement)
807 if guiElement:hasIncluded(PlaySampleMixin) then
808 guiElement:setPlaySampleCallback(self.playSampleClosure)
809 end
810
811 return guiElement
812end

changeScreen

Description
Change the currently displayed screen.
Definition
changeScreen(table source, table screenClass, table returnScreenClass)
Arguments
tablesourceSource screen instance
tablescreenClassClass table of the requested screen to change to or nil to close the GUI
tablereturnScreenClass[optional] Class table of the screen which will be opened on a "back" action in the new screen.
Return Values
tableRootGuiElement instance of target screen
Code
721function Gui:changeScreen(source, screenClass, returnScreenClass)
722 self:closeAllDialogs()
723
724 local isMenuOpening = not self:getIsGuiVisible()
725 local screenElement = self.screens[screenClass]
726
727 if source ~= nil then
728 source:onClose()
729 end
730
731 if source == nil and self.currentGui ~= nil then
732 self.currentGui:onClose()
733 end
734
735 local screenName = screenElement and screenElement.name or ""
736 self.currentGui = screenElement
737 self.currentGuiName = screenName
738 self.currentListener = screenElement
739
740 if screenElement ~= nil and isMenuOpening then
741 self.messageCenter:publish(MessageType.GUI_BEFORE_OPEN)
742 self:enterMenuContext()
743 end
744
745 FocusManager:setGui(screenName)
746
747 local screenController = self.screenControllers[screenClass]
748 if screenElement ~= nil and screenController ~= nil then
749 screenController:setReturnScreenClass(returnScreenClass or screenController.returnScreenClass) -- it's fine if its nil, the value is being checked
750 screenElement:onOpen()
751
752 if isMenuOpening then
753 self.messageCenter:publish(MessageType.GUI_AFTER_OPEN)
754 end
755 end
756
757 if not self:getIsGuiVisible() then
758 self.messageCenter:publish(MessageType.GUI_BEFORE_CLOSE)
759 -- clear input context if GUI is now completely closed (including dialogs)
760 self:leaveMenuContext()
761 self.messageCenter:publish(MessageType.GUI_AFTER_CLOSE)
762 end
763
764 return screenElement -- required by some screens to transfer state to the next view
765end

closeAllDialogs

Description
Close all open dialogs.
Definition
closeAllDialogs()
Code
524function Gui:closeAllDialogs()
525 for _,v in ipairs(self.dialogs) do
526 self:closeDialog(v)
527 end
528end

closeDialog

Description
Close a dialog identified by its root GuiElement. This is always called when a dialog is closed, usually by itself.
Definition
closeDialog()
Code
482function Gui:closeDialog(gui)
483 for k,v in ipairs(self.dialogs) do
484 if v == gui then
485 v:onClose()
486 table.remove(self.dialogs, k)
487
488 if self.currentListener == gui then
489 if #self.dialogs > 0 then
490 self.currentListener = self.dialogs[#self.dialogs]
491 else
492 if self.currentGui == gui then
493 self.currentListener = nil
494 self.currentGui = nil
495 else
496 self.currentListener = self.currentGui
497 end
498 end
499
500 if self.currentListener ~= nil then
501 FocusManager:setGui(self.currentListener.name)
502 if self.focusElements[self.currentListener] ~= nil then
503 FocusManager:setFocus(self.focusElements[self.currentListener])
504 self.focusElements[self.currentListener] = nil
505 end
506 end
507 end
508
509 -- revert dialog input context
510 self.inputManager:revertContext(false)
511
512 break
513 end
514 end
515
516 if not self:getIsGuiVisible() then
517 -- trigger close screen which dispatches required messages and adjusts input context:
518 self:changeScreen(nil)
519 end
520end

closeDialogByName

Description
Close a dialog identified by name.
Definition
closeDialogByName()
Code
472function Gui:closeDialogByName(guiName)
473 local gui = self.guis[guiName]
474 if gui ~= nil then
475 self:closeDialog(gui)
476 end
477end

draw

Description
Draw the GUI. Propagates draw calls to all active UI elements.
Definition
draw()
Code
621function Gui:draw()
622 if self.currentGui ~= nil then
623 self.currentGui:draw()
624 if self.currentGui.target ~= nil then
625 if self.currentGui.target.draw ~= nil then
626 self.currentGui.target:draw()
627 end
628 end
629 end
630
631 for _,v in pairs(self.dialogs) do
632 v:draw()
633 if v.target ~= nil then
634 v.target:draw()
635 end
636 end
637end

enterMenuContext

Description
Enter a new menu input context. Menu views which require special input should provide a context name to not collide with the base menu input scheme.
Definition
enterMenuContext(string contextName)
Arguments
stringcontextName[optional] Custom menu input context name
Code
818function Gui:enterMenuContext(contextName)
819 self.inputManager:setContext(contextName or Gui.INPUT_CONTEXT_MENU, true, false)
820 self:registerMenuInput()
821 self.isInputListening = true
822end

getActionEventId

Description
Get a menu action event ID by its name. Modify GUI action events with care, as they are globally defined for an entire session.
Definition
getActionEventId()
Code
415function Gui:getActionEventId(actionName)
416 return self.actionEventIds[actionName]
417end

getIsDialogVisible

Description
Determine if any dialog is visible.
Definition
getIsDialogVisible()
Code
402function Gui:getIsDialogVisible()
403 return #self.dialogs > 0
404end

getIsGuiVisible

Description
Determine if any menu or dialog is visible.
Definition
getIsGuiVisible()
Code
396function Gui:getIsGuiVisible()
397 return self.currentGui ~= nil or self:getIsDialogVisible()
398end

getIsOverlayGuiVisible

Description
Determine if an overlaid UI view with regular game display is visible, e.g. placement or landscaping.
Definition
getIsOverlayGuiVisible()
Code
408function Gui:getIsOverlayGuiVisible()
409 return self.currentGui == self.screens[PlacementScreen] or self.currentGui == self.screens[LandscapingScreen]
410end

getProfile

Description
Get a UI profile by name.
Definition
getProfile()
Code
356function Gui:getProfile(profileName)
357 if profileName ~= nil then
358 if GS_PLATFORM_TYPE == GS_PLATFORM_TYPE_PS4 then
359 local terrPrefix = ""
360 local territory = getGameTerritory()
361 if territory ~= nil and territory ~= "" then
362 terrPrefix = territory .. "_"
363 end
364
365 local ps4ProfileName = g_plattformPrefix .. terrPrefix .. profileName
366 if self.profiles[ps4ProfileName] then
367 profileName = ps4ProfileName
368 end
369 else
370 local platformProfileName = g_plattformPrefix .. profileName
371 if self.profiles[platformProfileName] then
372 profileName = platformProfileName
373 elseif GS_IS_CONSOLE_VERSION then
374 local consoleProfileName = "consoles_" .. profileName
375 if self.profiles[consoleProfileName] then
376 profileName = consoleProfileName
377 end
378 end
379 end
380 end
381
382 if not profileName or not self.profiles[profileName] then
383 -- only warn if profile name is wrong, undefined is fine
384 if profileName and profileName ~= "" then
385 g_logManager:warning("Could not retrieve GUI profile '%s'. Using base reference profile instead.", tostring(profileName))
386 end
387
388 profileName = Gui.GUI_PROFILE_BASE
389 end
390
391 return self.profiles[profileName]
392end

getScreenInstanceByClass

Description
Get a screen controller instance by class for special cases.
Definition
getScreenInstanceByClass(table screenClass)
Arguments
tablescreenClassClass table of the requested screen
Return Values
tableScreenElementdescendant instance of the given class or nil if no such instance was registered
Code
710function Gui:getScreenInstanceByClass(screenClass)
711 return self.screenControllers[screenClass]
712end

hasElementInputFocus

Description
Determine if a given GuiElement has input focus.
Definition
hasElementInputFocus()
Code
698function Gui:hasElementInputFocus(element)
699 return self.currentListener ~= nil and self.currentListener.target == element
700end

initGuiLibrary

Description
Source in UI modules.
Definition
initGuiLibrary(baseDir Base)
Arguments
baseDirBasescripts directory
Code
1124function Gui.initGuiLibrary(baseDir)
1125 source(baseDir .. "/base/GuiProfile.lua")
1126 source(baseDir .. "/base/GuiUtils.lua")
1127 source(baseDir .. "/base/GuiOverlay.lua")
1128
1129 source(baseDir .. "/base/GuiDataSource.lua")
1130
1131 source(baseDir .. "/base/GuiMixin.lua")
1132 source(baseDir .. "/base/IndexChangeSubjectMixin.lua")
1133 source(baseDir .. "/base/PlaySampleMixin.lua")
1134
1135 source(baseDir .. "/base/Tween.lua")
1136 source(baseDir .. "/base/MultiValueTween.lua")
1137 source(baseDir .. "/base/TweenSequence.lua")
1138
1139 source(baseDir .. "/elements/GuiElement.lua")
1140 source(baseDir .. "/elements/FrameElement.lua")
1141 source(baseDir .. "/elements/ScreenElement.lua")
1142 source(baseDir .. "/elements/DialogElement.lua")
1143 source(baseDir .. "/elements/BitmapElement.lua")
1144 source(baseDir .. "/elements/ClearElement.lua")
1145 source(baseDir .. "/elements/TextElement.lua")
1146 source(baseDir .. "/elements/ButtonElement.lua")
1147 source(baseDir .. "/elements/ToggleButtonElement.lua") -- not used anywhere
1148 source(baseDir .. "/elements/VideoElement.lua")
1149 source(baseDir .. "/elements/SliderElement.lua")
1150 source(baseDir .. "/elements/TextInputElement.lua")
1151 source(baseDir .. "/elements/ListElement.lua")
1152 source(baseDir .. "/elements/StableListElement.lua")
1153 source(baseDir .. "/elements/MultiTextOptionElement.lua")
1154 source(baseDir .. "/elements/CheckedOptionElement.lua")
1155 source(baseDir .. "/elements/ListItemElement.lua")
1156 source(baseDir .. "/elements/AnimationElement.lua")
1157 source(baseDir .. "/elements/TimerElement.lua") -- not used anywhere
1158 source(baseDir .. "/elements/BoxLayoutElement.lua")
1159 source(baseDir .. "/elements/FlowLayoutElement.lua") -- in principle obsoleted by BoxLayout
1160 source(baseDir .. "/elements/PagingElement.lua")
1161 source(baseDir .. "/elements/TableElement.lua")
1162 source(baseDir .. "/elements/TableHeaderElement.lua")
1163 source(baseDir .. "/elements/IngameMapElement.lua")
1164 source(baseDir .. "/elements/IndexStateElement.lua")
1165 source(baseDir .. "/elements/FrameReferenceElement.lua")
1166 source(baseDir .. "/elements/RenderElement.lua")
1167 source(baseDir .. "/elements/BreadcrumbsElement.lua")
1168
1169 -- Add new elements here and just above to make them available.
1170 local mapping = Gui.CONFIGURATION_CLASS_MAPPING
1171 mapping["button"] = ButtonElement
1172 mapping["toggleButton"] = ToggleButtonElement
1173 mapping["video"] = VideoElement
1174 mapping["slider"] = SliderElement
1175 mapping["text"] = TextElement
1176 mapping["textInput"] = TextInputElement
1177 mapping["bitmap"] = BitmapElement
1178 mapping["clear"] = ClearElement
1179 mapping["list"] = ListElement
1180 mapping["stableList"] = StableListElement
1181 mapping["multiTextOption"] = MultiTextOptionElement
1182 mapping["checkedOption"] = CheckedOptionElement
1183 mapping["listItem"] = ListItemElement
1184 mapping["animation"] = AnimationElement
1185 mapping["timer"] = TimerElement
1186 mapping["boxLayout"] = BoxLayoutElement
1187 mapping["flowLayout"] = FlowLayoutElement
1188 mapping["paging"] = PagingElement
1189 mapping["table"] = TableElement
1190 mapping["tableHeader"] = TableHeaderElement
1191 mapping["ingameMap"] = IngameMapElement
1192 mapping["indexState"] = IndexStateElement
1193 mapping["frameReference"] = FrameReferenceElement
1194 mapping["render"] = RenderElement
1195 mapping["breadcrumbs"] = BreadcrumbsElement
1196
1197 -- Add element processing function mappings in the same format:
1198 local procFuncs = Gui.ELEMENT_PROCESSING_FUNCTIONS
1199 procFuncs["frameReference"] = Gui.resolveFrameReference
1200 procFuncs["button"] = Gui.assignPlaySampleCallback
1201 procFuncs["slider"] = Gui.assignPlaySampleCallback
1202 procFuncs["multiTextOption"] = Gui.assignPlaySampleCallback
1203 procFuncs["checkedOption"] = Gui.assignPlaySampleCallback
1204end

keyEvent

Description
GUI key event hook. This is used for GuiElements which need to have direct access to raw key input, such as TextInputElement.
Definition
keyEvent()
Code
573function Gui:keyEvent(unicode, sym, modifier, isDown)
574 local eventUsed = false
575 if self.currentListener ~= nil then
576 eventUsed = self.currentListener:keyEvent(unicode, sym, modifier, isDown)
577 end
578
579 if self.currentListener ~= nil and self.currentListener.target ~= nil and not eventUsed then
580 if self.currentListener.target.keyEvent ~= nil then
581 self.currentListener.target:keyEvent(unicode, sym, modifier, isDown, eventUsed)
582 end
583 end
584end

leaveMenuContext

Description
Leave a menu input context. This wraps the input context setting to check if the menu is actually active and the context should be reverted to the state before entering the menu (or a custom menu input context within the menu).
Definition
leaveMenuContext()
Code
828function Gui:leaveMenuContext()
829 if self.isInputListening then
830 self.inputManager:revertContext(false)
831 self.isInputListening = self:getIsGuiVisible() -- keep listening if still visible
832 end
833end

loadGui

Description
Load a UI screen view's elements from an XML definition.
Definition
loadGui(xmlFilename View, name Screen, controller FrameElement, isFrame [optional,)
Arguments
xmlFilenameViewdefinition XML file path, relative to application root.
nameScreenname
controllerFrameElementinstance which serves as the controller for loaded elements
isFrame[optional,default=false] If true, will interpret the loaded view as a frame to be used in multiple places.
Return Values
RootGuiElementinstance of loaded view or nil if the definition XML file could not be loaded.
Code
196function Gui:loadGui(xmlFilename, name, controller, isFrame)
197 local xmlFile = loadXMLFile("Temp", xmlFilename)
198
199 local gui = nil
200 if xmlFile ~= nil and xmlFile ~= 0 then
201 FocusManager:setGui(name)
202
203 gui = GuiElement:new(controller)
204 gui.name = name
205 gui.xmlFilename = xmlFilename
206 controller.name = name
207
208 gui:loadFromXML(xmlFile, "GUI")
209
210 if isFrame then
211 controller.name = gui.name
212 end
213
214 self:loadGuiRec(xmlFile, "GUI", gui, controller)
215
216 if not isFrame then -- frames must only be scaled as part of screens, do not scale them on loading
217 gui:applyScreenAlignment()
218 gui:updateAbsolutePosition()
219 end
220
221 controller:addElement(gui)
222 controller:exposeControlsAsFields(name)
223
224 controller:onGuiSetupFinished()
225 -- call onCreate of configuration root node --> targets onCreate on view
226 gui:raiseCallback("onCreateCallback", gui, gui.onCreateArgs)
227
228 if isFrame then
229 self:addFrame(controller, gui)
230 else
231 self.guis[name] = gui
232 self.nameScreenTypes[name] = controller:class() -- TEMP, until showGui is replaced
233 -- store screen by its class for symbolic access
234 self:addScreen(controller:class(), controller, gui)
235 end
236
237 delete(xmlFile)
238 else
239 g_logManager:error("Could not open gui-config '%s'!", xmlFilename)
240 end
241
242 return gui
243end

loadGuiRec

Description
Recursively load and build a UI configuration.
Definition
loadGuiRec(xmlFile Opened, xmlNodePath Current, parentGuiElement Current, target Target)
Arguments
xmlFileOpenedGUI configuration XML file
xmlNodePathCurrentXML node path
parentGuiElementCurrentparent GuiElement
targetTargetof newly instantiated elements
Code
251function Gui:loadGuiRec(xmlFile, xmlNodePath, parentGuiElement, target)
252 local i = 0
253 while true do
254 local currentXmlPath = xmlNodePath .. ".GuiElement(" .. i .. ")"
255 local typeName = getXMLString(xmlFile, currentXmlPath .. "#type")
256 if typeName == nil then
257 break
258 end
259
260 -- instantiate element and load attribute values
261 local newGuiElement = nil
262 local elementClass = Gui.CONFIGURATION_CLASS_MAPPING[typeName]
263 if elementClass then -- instantiate mapped class
264 newGuiElement = elementClass:new(target)
265 else -- instantiate base GuiElement as fallback or empty panel
266 newGuiElement = GuiElement:new(target)
267 end
268 newGuiElement.typeName = typeName
269
270 newGuiElement:loadFromXML(xmlFile, currentXmlPath)
271 parentGuiElement:addElement(newGuiElement)
272
273 -- run any processing resolution functions for specific types:
274 local processingFunction = Gui.ELEMENT_PROCESSING_FUNCTIONS[typeName]
275 if processingFunction then
276 newGuiElement = processingFunction(self, newGuiElement)
277 end
278
279 -- recurse on children
280 self:loadGuiRec(xmlFile, currentXmlPath, newGuiElement, target)
281
282 -- raise callback after all child nodes have been processed
283 newGuiElement:raiseCallback("onCreateCallback", newGuiElement, newGuiElement.onCreateArgs)
284 i = i + 1
285 end
286end

loadMapData

Description
Let the GUI (and its components) process map data when it's loaded.
Definition
loadMapData(int mapXmlFile)
Arguments
intmapXmlFileMap configuration XML file handle, do not close, will be handled by caller.
Code
874function Gui:loadMapData(mapXmlFile, missionInfo, baseDirectory)
875 self.screenControllers[ShopConfigScreen]:loadMapData(mapXmlFile, missionInfo, baseDirectory)
876 self.screenControllers[LandscapingScreen]:loadMapData(mapXmlFile, missionInfo, baseDirectory)
877end

loadPresets

Description
Definition
loadPresets()
Code
94function Gui:loadPresets(xmlFile, rootKey)
95 local presets = {}
96
97 local i = 0
98 while true do
99 local key = string.format("%s.Preset(%d)", rootKey, i)
100 if not hasXMLProperty(xmlFile, key) then
101 break
102 end
103
104 local name = getXMLString(xmlFile, key .. "#name")
105 local value = getXMLString(xmlFile, key .. "#value")
106 if name ~= nil and value ~= nil then
107 if StringUtil.startsWith(value, "$preset_") then
108 local preset = string.gsub(value, "$preset_", "")
109 if presets[preset] ~= nil then
110 value = presets[preset]
111 else
112 g_logManager:devWarning("Preset '%s' is not defined in Preset!", preset)
113 end
114 end
115
116 presets[name] = value
117 end
118
119 i = i + 1
120 end
121
122 return presets
123end

loadProfiles

Description
Load UI profile data from XML.
Definition
loadProfiles(xmlFilename UI)
Arguments
xmlFilenameUIprofiles definition XML file path, relative to application root.
Code
160function Gui:loadProfiles(xmlFilename)
161 local xmlFile = loadXMLFile("Temp", xmlFilename)
162
163 if xmlFile ~= nil and xmlFile ~= 0 then
164 local presets = self:loadPresets(xmlFile, "GuiProfiles.Presets")
165
166 self:loadTraits(xmlFile, "GuiProfiles.Traits", presets)
167 self:loadProfileSet(xmlFile, "GuiProfiles", presets)
168
169 local i = 0
170 while true do
171 local key = string.format("GuiProfiles.Category(%d)", i)
172 if not hasXMLProperty(xmlFile, key) then
173 break
174 end
175
176 local categoryName = getXMLString(xmlFile, key .. "#name")
177
178 self:loadProfileSet(xmlFile, key, presets, categoryName)
179
180 i = i + 1
181 end
182
183 delete(xmlFile)
184 else
185 g_logManager:error("Could not open guiProfile-config '%s'!", xmlFilename)
186 end
187end

loadProfileSet

Description
Definition
loadProfileSet()
Code
142function Gui:loadProfileSet(xmlFile, rootKey, presets, categoryName)
143 local i = 0
144 while true do
145 local profile = GuiProfile:new(self.profiles, self.traits)
146 if not profile:loadFromXML(xmlFile, rootKey .. ".Profile(" .. i .. ")", presets, false) then
147 break
148 end
149
150 profile.category = categoryName -- for debugging
151
152 self.profiles[profile.name] = profile
153 i = i + 1
154 end
155end

loadTraits

Description
Definition
loadTraits()
Code
127function Gui:loadTraits(xmlFile, rootKey, presets)
128 local i = 0
129 while true do
130 local trait = GuiProfile:new(self.profiles, self.traits)
131 if not trait:loadFromXML(xmlFile, rootKey .. ".Trait(" .. i .. ")", presets, true) then
132 break
133 end
134
135 self.traits[trait.name] = trait
136 i = i + 1
137 end
138end

makeChangeScreenClosure

Description
Make a change screen callback function which encloses the Gui self reference. This avoids passing the reference around as a parameter or global reference.
Definition
makeChangeScreenClosure()
Code
770function Gui:makeChangeScreenClosure()
771 return function(source, screenClass, returnScreenClass)
772 self:changeScreen(source, screenClass, returnScreenClass)
773 end
774end

makePlaySampleClosure

Description
Make a play sample function which encloses the Gui self reference.
Definition
makePlaySampleClosure()
Code
796function Gui:makePlaySampleClosure()
797 return function(sampleName)
798 self.soundPlayer:playSample(sampleName)
799 end
800end

makeToggleCustomInputContextClosure

Description
Make a toggle custom input context function which encloses the Gui self reference.
Definition
makeToggleCustomInputContextClosure()
Code
788function Gui:makeToggleCustomInputContextClosure()
789 return function(isActive, contextName)
790 self:toggleCustomInputContext(isActive, contextName)
791 end
792end

mouseEvent

Description
GUI mouse event hook. This is used primarily for mouse location checks, as button inputs are handled by InputBinding.
Definition
mouseEvent()
Code
556function Gui:mouseEvent(posX, posY, isDown, isUp, button)
557 local eventUsed = false
558
559 if self.currentListener ~= nil then
560 eventUsed = self.currentListener:mouseEvent(posX, posY, isDown, isUp, button)
561 end
562
563 if not eventUsed and self.currentListener ~= nil and self.currentListener.target ~= nil then
564 if self.currentListener.target.mouseEvent ~= nil then
565 self.currentListener.target:mouseEvent(posX, posY, isDown, isUp, button)
566 end
567 end
568end

new

Description
Definition
new()
Code
51function Gui:new(messageCenter, languageSuffix, inputManager, guiSoundPlayer)
52 local self = setmetatable({}, Gui_mt)
53
54 self.messageCenter = messageCenter
55 self.languageSuffix = languageSuffix
56 -- input manager reference for event registration
57 self.inputManager = inputManager
58 self.soundPlayer = guiSoundPlayer
59 FocusManager:setSoundPlayer(guiSoundPlayer)
60
61 self.screens = {} -- screen class -> screen root element
62 self.screenControllers = {} -- screen class -> screen instance
63 self.dialogs = {}
64 self.profiles = {}
65 self.traits = {}
66 self.focusElements = {}
67 self.guis = {}
68 self.nameScreenTypes = {}
69 self.currentGuiName = ""
70
71 -- registered frame elements which can be referenced to be displayed in multiple places / on multiple screen views
72 self.frames = {} -- frame name -> frame controller element
73
74 -- state flag to check if the GUI input context is active (context can be multiple levels deep)
75 self.isInputListening = false
76 -- stores event IDs of GUI button/key actions (no movement)
77 self.actionEventIds = {}
78 -- current frame's input target, all inputs of one frame go to this target
79 self.frameInputTarget = nil
80 -- flag for handling of current frame's input, avoids reacting to multiple events per frame for double bindings (e.g. ESC on PC)
81 self.frameInputHandled = false
82 -- subscribers for network events which trigger a local GUI response
83 self.networkEventSubscribers = {}
84
85 self.changeScreenClosure = self:makeChangeScreenClosure()
86 self.toggleCustomInputContextClosure =self:makeToggleCustomInputContextClosure()
87 self.playSampleClosure = self:makePlaySampleClosure()
88
89 return self
90end

notifyControls

Description
Notify controls of an action input with a value.
Definition
notifyControls(action Action, value Action)
Arguments
actionActionname as defined by loaded actions, see also scripts/input/InputAction.lua
valueActionvalue [-1, 1]
Return Values
Trueifany control has consumed the action event
Code
644function Gui:notifyControls(action, value)
645 local eventUsed = false
646
647 -- Ensure that only one component receives input per frame, otherwise we risk some unwanted input handling chains
648 -- when GUI current listeners (or similar) change.
649 if self.frameInputTarget == nil then
650 self.frameInputTarget = self.currentListener
651 end
652
653 -- check with focus manager if it currently blocks this input
654 local locked = FocusManager:isFocusInputLocked(action, value)
655
656 if not locked then
657 -- try notifying current listener element or its target (usually either of these is a ScreenElement)
658 if not eventUsed and self.frameInputTarget ~= nil then
659 eventUsed = self.frameInputTarget:inputEvent(action, value)
660 end
661
662 if not eventUsed and self.frameInputTarget ~= nil and self.frameInputTarget.target ~= nil then
663 eventUsed = self.frameInputTarget.target:inputEvent(action, value)
664 end
665
666 -- send input to the currently focused element if it's active
667 local focusedElement = FocusManager:getFocusedElement()
668 if not eventUsed and focusedElement ~= nil and focusedElement:getIsActive() then
669 eventUsed = focusedElement:inputEvent(action, value)
670 end
671
672 -- always notify the focus manager, but pass in event usage information
673 if not eventUsed then
674 eventUsed = FocusManager:inputEvent(action, value, eventUsed)
675 end
676 end
677
678 -- lock down input for the current frame if we have reacted on the current input action
679 self.frameInputHandled = eventUsed
680end

onMenuInput

Description
Event callback for menu input.
Definition
onMenuInput()
Code
684function Gui:onMenuInput(actionName, inputValue)
685 if not self.frameInputHandled and self.isInputListening then
686 self:notifyControls(actionName, inputValue)
687 end
688end

onReleaseMovement

Description
Event callback for released movement menu input.
Definition
onReleaseMovement()
Code
692function Gui:onReleaseMovement(actionName)
693 FocusManager:releaseMovementFocusInput(actionName)
694end

registerMenuInput

Description
Register menu input.
Definition
registerMenuInput()
Code
532function Gui:registerMenuInput()
533 -- register the menu input event for all menu navigation actions on button up
534 for _, actionName in ipairs(Gui.NAV_ACTIONS) do -- use ipairs to enforce action order
535 local _, eventId = self.inputManager:registerActionEvent(actionName, self, self.onMenuInput, false, true, false, true)
536 self.inputManager:setActionEventTextVisibility(eventId, false)
537 self.actionEventIds[actionName] = eventId
538 end
539
540 -- register input events for navigation movement actions for each input change
541 for _, actionName in pairs(Gui.NAV_AXES) do
542 -- react to any axis value changes:
543 local _, eventId = self.inputManager:registerActionEvent(actionName, self, self.onMenuInput, false, true, true, true)
544 self.inputManager:setActionEventTextVisibility(eventId, false)
545 -- react to movement input stops ("up" state), releases locks on focus manager input:
546 _, eventId = self.inputManager:registerActionEvent(actionName, self, self.onReleaseMovement, true, false, false, true)
547 self.inputManager:setActionEventTextVisibility(eventId, false)
548 end
549
550 self.isInputListening = true
551end

resolveFrameReference

Description
Tries resolving a frame reference. If no frame has been loaded with the name given by the reference, then the reference element itself is returned. Otherwise, the registered frame is cloned and returned.
Definition
resolveFrameReference(self Gui, frameRefElement FrameReferenceElement)
Arguments
selfGuiinstance
frameRefElementFrameReferenceElementinstance to resolve
Return Values
ClonedFrameElementinstance or frameRefElement if resolution failed.
Code
295function Gui:resolveFrameReference(frameRefElement)
296 local refName = frameRefElement.referencedFrameName or ""
297 local frame = self.frames[refName]
298
299 if frame ~= nil then
300 local frameName = frameRefElement.name or refName
301 -- "frame" is the artificial root GuiElement instance holding the frame,
302 -- its parent is the controller FrameElement instance which needs to be cloned
303 local frameController = frame.parent
304 -- clone the controller, including element IDs and suppressing the onCreate callback for all elements
305 FocusManager:setGui(frameName) -- set focus data context
306 local frameParent = frameRefElement.parent
307 local controllerClone = frameController:clone(frameParent, true, true)
308 controllerClone.name = frameName
309
310 -- re-size and re-orient frame controller and its root to fit the new parent element (required for resolution stability)
311 controllerClone.positionOrigin = frameParent.positionOrigin
312 controllerClone.screenAlign = frameParent.screenAlign
313 controllerClone:setSize(unpack(frameParent.size))
314 local cloneRoot = controllerClone:getRootElement()
315 cloneRoot.positionOrigin = frameParent.positionOrigin
316 cloneRoot.screenAlign = frameParent.screenAlign
317 cloneRoot:setSize(unpack(frameParent.size))
318
319 -- replace previous controller target reference with cloned controller as target for callbacks
320 local targetingChildren = controllerClone:getDescendants(
321 function(element)
322 return element.target == frameController
323 end
324 )
325
326 -- set target to resolved controller, raise onCreate callback now
327 for _, element in pairs(targetingChildren) do
328 element.target = controllerClone
329 element.targetName = controllerClone.name
330 element:raiseCallback("onCreateCallback", element, element.onCreateArgs)
331 end
332
333 local frameId = frameRefElement.id
334 controllerClone.id = frameId -- swap ID
335
336 if frameRefElement.target then
337 -- swap frame reference field value for clone frame controller
338 frameRefElement.target[frameId] = controllerClone
339 end
340
341 -- add cloned frame elements to focus system, would not support navigation otherwise
342 FocusManager:loadElementFromCustomValues(controllerClone, nil, nil, false, false)
343
344 -- safely discard reference element
345 frameRefElement:unlinkElement()
346 frameRefElement:delete()
347
348 return controllerClone
349 else
350 return frameRefElement
351 end
352end

setClient

Description
Set the network client reference for GUI screens.
Definition
setClient()
Code
889function Gui:setClient(client)
890end

setCurrentMission

Description
Set the current mission reference for GUI screens.
Definition
setCurrentMission()
Code
860function Gui:setCurrentMission(currentMission)
861 self.screenControllers[ShopConfigScreen]:setCurrentMission(currentMission)
862end

setEconomyManager

Description
Set the current economy manager for GUI screens. The manager is initialized during mission loading.
Definition
setEconomyManager()
Code
867function Gui:setEconomyManager(economyManager)
868 self.screenControllers[ShopConfigScreen]:setEconomyManager(economyManager)
869end

showAnimalDialog

Description
Definition
showAnimalDialog()
Code
1030function Gui:showAnimalDialog(args)
1031 local dialog = self:showDialog("AnimalDialog")
1032 if dialog ~= nil and args ~= nil then
1033 dialog.target:setTitle(args.title)
1034 dialog.target:setText(args.text)
1035 dialog.target:setHusbandries(args.husbandries)
1036 dialog.target:setCallback(args.callback, args.target, args.args)
1037 end
1038end

showColorPickerDialog

Description
Definition
showColorPickerDialog()
Code
913function Gui:showColorPickerDialog(args)
914 local dialog = self:showDialog("ColorPickerDialog")
915 if dialog ~= nil and args ~= nil then
916 dialog.target:setColors(args.colors, args.defaultColor)
917 dialog.target:setCallback(args.callback, args.target, args.args)
918 end
919end

showConnectionFailedDialog

Description
Definition
showConnectionFailedDialog()
Code
994function Gui:showConnectionFailedDialog(args)
995 local dialog = self:showDialog("ConnectionFailedDialog", true)
996 if dialog ~= nil and args ~= nil then
997 dialog.target:setDialogType(Utils.getNoNil(args.dialogType, DialogElement.TYPE_WARNING))
998 dialog.target:setText(args.text)
999 dialog.target:setCallback(args.callback, args.target, args.args)
1000 dialog.target:setButtonTexts(args.okText)
1001 end
1002end

showDenyAcceptDialog

Description
Definition
showDenyAcceptDialog()
Code
1006function Gui:showDenyAcceptDialog(args)
1007 self:showGui("")
1008 local dialog = self:showDialog("DenyAcceptDialog")
1009 if dialog ~= nil and args ~= nil then
1010 dialog.target:setCallback(args.callback, args.target)
1011 dialog.target:setConnection(args.connection, args.nickname)
1012 dialog.target:setTitle(args.nickname)
1013 end
1014end

showDialog

Description
Display a dialog identified by name.
Definition
showDialog()
Return Values
RootGuiElementof dialog or nil if the name did not match any known dialog.
Code
434function Gui:showDialog(guiName, closeAllOthers)
435 local gui = self.guis[guiName]
436 if gui ~= nil then
437 if closeAllOthers then
438 local list = self.dialogs
439 for _,v in ipairs(list) do
440 if v ~= gui then
441 self:closeDialog(v)
442 end
443 end
444 end
445
446 if self.currentListener == gui then
447 return gui
448 end
449
450 if self.currentListener ~= nil then
451 self.focusElements[self.currentListener] = FocusManager:getFocusedElement()
452 end
453
454 if not self:getIsGuiVisible() then
455 self:enterMenuContext()
456 end
457
458 -- set distinct dialog context which can be reverted on dialog closing if we are in menu already
459 self:enterMenuContext(Gui.INPUT_CONTEXT_DIALOG .. "_" .. tostring(guiName))
460
461 FocusManager:setGui(guiName)
462 table.insert(self.dialogs, gui)
463 gui:onOpen()
464 self.currentListener = gui
465 end
466
467 return gui
468end

showDirectSellDialog

Description
Definition
showDirectSellDialog()
Code
1052function Gui:showDirectSellDialog(args)
1053 local dialog = self:showDialog("DirectSellDialog")
1054 if dialog ~= nil and args ~= nil then
1055 dialog.target:setVehicle(args.vehicle, args.owner, args.ownWorkshop)
1056 end
1057end

showEditFarmDialog

Description
Definition
showEditFarmDialog()
Code
1061function Gui:showEditFarmDialog(args)
1062 local dialog = self:showDialog("EditFarmDialog")
1063 if dialog ~= nil and args ~= nil then
1064 dialog.target:setExistingFarm(args.farmId)
1065 dialog.target:setCallback(args.callback, args.target, args.args)
1066 end
1067end

showGui

Description
Display and return a screen identified by name.
Definition
showGui()
Return Values
RootGuiElementof screen or nil if the name did not match any known screen.
Code
422function Gui:showGui(guiName)
423 -- TODO: replace all calls to this with Gui:changeScreen
424 if guiName == nil then
425 guiName = ""
426 end
427
428 return self:changeScreen(self.guis[self.currentGui], self.nameScreenTypes[guiName])
429end

showInfoDialog

Description
Definition
showInfoDialog()
Code
962function Gui:showInfoDialog(args)
963 local dialog = self:showDialog("InfoDialog")
964 if dialog ~= nil and args ~= nil then
965 dialog.target:setDialogType(Utils.getNoNil(args.dialogType, DialogElement.TYPE_WARNING))
966 dialog.target:setText(args.text)
967 dialog.target:setCallback(args.callback, args.target, args.args)
968 dialog.target:setButtonTexts(args.okText)
969 dialog.target:setButtonAction(args.buttonAction)
970 end
971end

showMessageDialog

Description
Definition
showMessageDialog()
Code
975function Gui:showMessageDialog(args)
976 if args ~= nil then
977 if args.visible then
978 local dialog = self:showDialog("MessageDialog")
979 if dialog ~= nil then
980 dialog.target:setDialogType(Utils.getNoNil(args.dialogType, DialogElement.TYPE_LOADING))
981 dialog.target:setIsCloseAllowed(Utils.getNoNil(args.isCloseAllowed, true))
982 dialog.target:setText(args.text)
983 dialog.target:setUpdateCallback(args.updateCallback, args.updateTarget, args.updateArgs)
984 dialog.target:setCustomButtons(args.customButtons)
985 end
986 else
987 self:closeDialogByName("MessageDialog")
988 end
989 end
990end

showPasswordDialog

Description
Definition
showPasswordDialog()
Code
936function Gui:showPasswordDialog(args)
937 local dialog = self.guis["PasswordDialog"]
938 if dialog ~= nil and args ~= nil then
939 dialog.target:setText(args.text)
940 dialog.target:setCallback(args.callback, args.target, args.defaultPassword, nil, nil, nil, args.args, true)
941 dialog.target:setButtonTexts(args.startText, args.backText)
942
943 self:showDialog("PasswordDialog")
944 end
945end

showSellItemDialog

Description
Definition
showSellItemDialog()
Code
1042function Gui:showSellItemDialog(args)
1043 local dialog = self:showDialog("SellItemDialog")
1044 if dialog ~= nil and args ~= nil then
1045 dialog.target:setItem(args.item, args.price, args.storeItem)
1046 dialog.target:setCallback(args.callback, args.target, args.args)
1047 end
1048end

showServerSettingsDialog

Description
Definition
showServerSettingsDialog()
Code
1102function Gui:showServerSettingsDialog(args)
1103 local dialog = self:showDialog("ServerSettingsDialog")
1104 if dialog ~= nil and args ~= nil then
1105 dialog.target:setCallback(args.callback, args.target, args.args)
1106 end
1107end

showSiloDialog

Description
Definition
showSiloDialog()
Code
1018function Gui:showSiloDialog(args)
1019 local dialog = self:showDialog("SiloDialog")
1020 if dialog ~= nil and args ~= nil then
1021 dialog.target:setTitle(args.title)
1022 dialog.target:setText(args.text)
1023 dialog.target:setFillLevels(args.fillLevels, args.capacity, args.hasInfiniteCapacity)
1024 dialog.target:setCallback(args.callback, args.target, args.args)
1025 end
1026end

showSleepDialog

Description
Definition
showSleepDialog()
Code
1080function Gui:showSleepDialog(args)
1081 local dialog = self:showDialog("SleepDialog")
1082 if dialog ~= nil and args ~= nil then
1083 dialog.target:setTitle(g_i18n:getText("ui_inGameSleep"))
1084 dialog.target:setText(args.text)
1085 dialog.target:setMaxDuration(args.maxDuration)
1086 dialog.target:setCallback(args.callback, args.target, args.args)
1087 end
1088end

showTextInputDialog

Description
Definition
showTextInputDialog()
Code
923function Gui:showTextInputDialog(args)
924 local dialog = self.guis["TextInputDialog"]
925 if dialog ~= nil and args ~= nil then
926 dialog.target:setText(args.text)
927 dialog.target:setCallback(args.callback, args.target, args.defaultText, args.dialogPrompt, args.imePrompt, args.maxCharacters, args.args, false, args.disableFilter)
928 dialog.target:setButtonTexts(args.confirmText, args.backText, args.activateInputText)
929
930 self:showDialog("TextInputDialog")
931 end
932end

showTransferMoneyDialog

Description
Definition
showTransferMoneyDialog()
Code
1092function Gui:showTransferMoneyDialog(args)
1093 local dialog = self:showDialog("TransferMoneyDialog")
1094 if dialog ~= nil and args ~= nil then
1095 dialog.target:setTargetFarm(args.farm)
1096 dialog.target:setCallback(args.callback, args.target, args.args)
1097 end
1098end

showUnBanDialog

Description
Definition
showUnBanDialog()
Code
1071function Gui:showUnBanDialog(args)
1072 local dialog = self:showDialog("UnBanDialog")
1073 if dialog ~= nil and args ~= nil then
1074 dialog.target:setCallback(args.callback, args.target)
1075 end
1076end

showVoteDialog

Description
Definition
showVoteDialog()
Code
1111function Gui:showVoteDialog(args)
1112 local dialog = self:showDialog("VoteDialog")
1113 if dialog ~= nil and args ~= nil then
1114 dialog.target:setValue(args.value)
1115 dialog.target:setCallback(args.callback, args.target, args.args)
1116 end
1117end

showYesNoDialog

Description
Definition
showYesNoDialog()
Code
949function Gui:showYesNoDialog(args)
950 local dialog = self:showDialog("YesNoDialog")
951 if dialog ~= nil and args ~= nil then
952 dialog.target:setText(args.text)
953 dialog.target:setTitle(args.title)
954 dialog.target:setDialogType(Utils.getNoNil(args.dialogType, DialogElement.TYPE_QUESTION))
955 dialog.target:setCallback(args.callback, args.target)
956 dialog.target:setButtonTexts(args.yesText, args.noText)
957 end
958end

toggleCustomInputContext

Description
Toggle a custom menu input context for one of the managed frames or screens.
Definition
toggleCustomInputContext()
Code
778function Gui:toggleCustomInputContext(isActive, contextName)
779 if isActive then
780 self:enterMenuContext(contextName)
781 else
782 self:leaveMenuContext()
783 end
784end

unloadMapData

Description
Definition
unloadMapData()
Code
881function Gui:unloadMapData()
882 self.screenControllers[ShopConfigScreen]:unloadMapData()
883 self.screenControllers[LandscapingScreen]:unloadMapData()
884 self.screenControllers[InGameMenu]:unloadMapData()
885end

update

Description
Update the GUI. Propagates update to all active UI elements.
Definition
update()
Code
589function Gui:update(dt)
590 for _,v in pairs(self.dialogs) do
591 v:update(dt)
592 if v.target ~= nil then
593 v.target:update(dt)
594 end
595 end
596
597 local currentGui = self.currentGui
598 if currentGui ~= nil then
599 if currentGui.target ~= nil and currentGui.target.preUpdate ~= nil then
600 currentGui.target:preUpdate(dt)
601 end
602
603 if currentGui == self.currentGui then -- self.currentGui can change during update
604 currentGui:update(dt)
605 if currentGui == self.currentGui then -- self.currentGui can change during update
606 if currentGui.target ~= nil and currentGui.target.update ~= nil then
607 currentGui.target:update(dt)
608 end
609 end
610 end
611 end
612
613 -- reset input fields for next frame
614 self.frameInputTarget = nil
615 self.frameInputHandled = false
616end