Script v1.7.1.0
- AI
- Animals
- Contracts
- Debug
- Economy
- Effects
- Events
- Farms
- GUI
- AnimalScreen
- AnimationElement
- BitmapElement
- BoxLayoutElement
- BreadcrumbsElement
- ButtonElement
- ButtonOverlay
- ChatWindow
- CheckedOptionElement
- ClearElement
- ContextActionDisplay
- DialogElement
- FieldInfoDisplay
- FillLevelsDisplay
- FlowLayoutElement
- FocusManager
- FrameElement
- FrameReferenceElement
- GameInfoDisplay
- GamePausedDisplay
- Gui
- GuiDataSource
- GuiElement
- GuiMixin
- GuiOverlay
- GuiProfile
- GuiSoundPlayer
- GuiTopDownCamera
- GuiUtils
- HUDDisplayElement
- HUDElement
- HUDFrameElement
- HUDPopupMessage
- HUDTextDisplay
- IndexChangeSubjectMixin
- IndexStateElement
- InGameIcon
- IngameMap
- IngameMapElement
- InputGlyphElement
- InputHelpDisplay
- ListElement
- ListItemElement
- MapHotspot
- MapOverlayGenerator
- MixerWagonHUDExtension
- MultiTextOptionElement
- MultiValueTween
- Overlay
- PagingElement
- PlaySampleMixin
- RenderElement
- RoundStatusBar
- ScreenElement
- SettingsModel
- SideNotification
- SliderElement
- SpeakerDisplay
- SpeedMeterDisplay
- StableListElement
- StatusBar
- TabbedMenu
- TabbedMenuFrameElement
- TabbedMenuWithDetails
- TableElement
- TableHeaderElement
- TextElement
- TextInputElement
- TimerElement
- ToggleButtonElement
- TopNotification
- Tween
- TweenSequence
- VehicleHUDExtension
- VehicleSchemaDisplay
- VideoElement
- Handtools
- I3d
- Materials
- Misc
- Objects
- Placeables
- Player
- Shop
- Sounds
- Specializations
- Triggers
- Utils
- Vehicles
- Weather
Engine v1.7.1.0
- AI
- Animation
- Camera
- Entity
- Fillplanes
- General
- I3D
- Input
- Lighting
- Math
- Network
- Node
- Overlays
- Particle System
- Physics
- Rendering
- Scenegraph
- Shape
- Sound
- Spline
- String
- Terrain Detail
- Text Rendering
- Tire Track
- XML
- general
Foundation Reference
FrameElement
DescriptionBase 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
GuiElementFunctions
- changeScreen
- clone
- copyAttributes
- disableInputForDuration
- exposeControlsAsFields
- getRootElement
- isInputDisabled
- new
- playSample
- registerControls
- setChangeScreenCallback
- setInputContextCallback
- setPlaySampleCallback
- toggleCustomInputContext
- update
changeScreen
DescriptionRequest a view change via the callback defined by setChangeScreenCallback().Definition
changeScreen(table targetScreenClass)Arguments
| table | targetScreenClass | Class table of requested view (ScreenElement descendant, must be full view) |
| 180 | function FrameElement:changeScreen(targetScreenClass, returnScreenClass) |
| 181 | self.changeScreenCallback(self, targetScreenClass, returnScreenClass) |
| 182 | end |
clone
DescriptionOverride of GuiElement:clone(). Also exposes registered control element fields.Definition
clone()Code
| 45 | function FrameElement:clone(parent, includeId, suppressOnCreate) |
| 46 | local ret = FrameElement:superClass().clone(self, parent, includeId, suppressOnCreate) |
| 47 | ret:exposeControlsAsFields(self.name) |
| 48 | |
| 49 | ret.changeScreenCallback = self.changeScreenCallback |
| 50 | ret.toggleCustomInputContextCallback = self.toggleCustomInputContextCallback |
| 51 | ret.playSampleCallback = self.playSampleCallback |
| 52 | ret.hasCustomInputContext = self.hasCustomInputContext |
| 53 | |
| 54 | return ret |
| 55 | end |
copyAttributes
DescriptionOverride of GuiElement:copyAttributes(). Also resets registered control IDs so they can be exposed as fields again.Definition
copyAttributes()Code
| 60 | function FrameElement:copyAttributes(src) |
| 61 | FrameElement:superClass().copyAttributes(self, src) |
| 62 | for k, v in pairs(src.controlIDs) do |
| 63 | self.controlIDs[k] = false |
| 64 | end |
| 65 | end |
disableInputForDuration
DescriptionSet input disabling to a given duration.Definition
disableInputForDuration(float duration)Arguments
| float | duration | Input disabling duration in milliseconds |
| 135 | function FrameElement:disableInputForDuration(duration) |
| 136 | self.inputDisableTime = MathUtil.clamp(duration, 0, 10000) -- clamp to plausible range (up to 10s) |
| 137 | end |
exposeControlsAsFields
DescriptionAdds 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
| viewName | View | name of this frame element |
| 102 | function FrameElement:exposeControlsAsFields(viewName) |
| 103 | local allChildren = self:getDescendants() |
| 104 | for _, element in pairs(allChildren) do |
| 105 | if element.id and element.id ~= "" then |
| 106 | local index, varName = GuiElement.extractIndexAndNameFromID(element.id) |
| 107 | if self.controlIDs[varName] ~= nil then |
| 108 | if index then -- indexed field, expose as a list |
| 109 | if not self[varName] then |
| 110 | self[varName] = {} |
| 111 | end |
| 112 | |
| 113 | self[varName][index] = element |
| 114 | else -- regular field, just assign to the element table |
| 115 | self[varName] = element |
| 116 | end |
| 117 | |
| 118 | self.controlIDs[varName] = true -- mark as resolved |
| 119 | end |
| 120 | end |
| 121 | end |
| 122 | |
| 123 | if self.debugEnabled or g_uiDebugEnabled then |
| 124 | for id, isResolved in pairs(self.controlIDs) do |
| 125 | if not isResolved then |
| 126 | g_logManager:warning("FrameElement for GUI view '%s' could not resolve registered control element ID '%s'. Check configuration.", tostring(viewName), tostring(id)) |
| 127 | end |
| 128 | end |
| 129 | end |
| 130 | end |
getRootElement
DescriptionGet 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
| 71 | function FrameElement:getRootElement() |
| 72 | if #self.elements > 0 then |
| 73 | return self.elements[1] |
| 74 | else |
| 75 | local newRoot = GuiElement:new() |
| 76 | self:addElement(newRoot) |
| 77 | return newRoot |
| 78 | end |
| 79 | end |
isInputDisabled
DescriptionCheck if input is currently disabled.Definition
isInputDisabled()Code
| 141 | function FrameElement:isInputDisabled() |
| 142 | return self.inputDisableTime > 0 |
| 143 | end |
new
DescriptionDefinitionnew()Code
| 24 | function FrameElement:new(target, custom_mt) |
| 25 | local custom_mt = custom_mt or FrameElement_mt |
| 26 | local self = GuiElement:new(target, custom_mt) |
| 27 | |
| 28 | self.controlIDs = {} -- list of control element IDs to be resolved on loading |
| 29 | self.changeScreenCallback = NO_CALLBACK -- change view callback |
| 30 | self.toggleCustomInputContextCallback = NO_CALLBACK -- custom input context toggle callback |
| 31 | self.playSampleCallback = NO_CALLBACK -- play sound sample callback |
| 32 | self.hasCustomInputContext = false -- safety flag for input context stack handling |
| 33 | |
| 34 | self.time = 0 |
| 35 | self.inputDisableTime = 0 |
| 36 | |
| 37 | self.playHoverSoundOnFocus = false |
| 38 | |
| 39 | return self |
| 40 | end |
playSample
DescriptionRequest playing a sound sample identified by name.Definition
playSample(string sampleName)Arguments
| string | sampleName | Sample name, use one of GuiSoundPlayer.SOUND_SAMPLES |
| 199 | function FrameElement:playSample(sampleName) |
| 200 | if not self:getSoundSuppressed() then |
| 201 | self.playSampleCallback(sampleName) |
| 202 | end |
| 203 | end |
registerControls
DescriptionRegister a collection of control IDs for direct access in GUI views.Definition
registerControls(controlIDs Table)Arguments
| controlIDs | Table | which holds control IDs as values, as they are required to be present in the view configuration. |
| 84 | function FrameElement:registerControls(controlIDs) |
| 85 | for _, id in pairs(controlIDs) do |
| 86 | if self.controlIDs[id] then |
| 87 | g_logManager:warning("Registered multiple control elements with the same ID '%s'. Check screen setup.", tostring(id)) |
| 88 | else |
| 89 | self.controlIDs[id] = false -- hash it for ease of access |
| 90 | end |
| 91 | end |
| 92 | end |
setChangeScreenCallback
DescriptionSet a callback for requesting a view change from within a frame or screen view.Definition
setChangeScreenCallback(func callback)Arguments
| func | callback | Function reference, signature: function(sourceFrameElement, targetScreenClass, returnScreenClass) |
| 159 | function FrameElement:setChangeScreenCallback(callback) |
| 160 | self.changeScreenCallback = callback or NO_CALLBACK |
| 161 | end |
setInputContextCallback
DescriptionSet a callback function for requesting a custom menu input context for this frame.Definition
setInputContextCallback(func callback)Arguments
| func | callback | Function reference, signature: function(isContextActive) |
| 166 | function FrameElement:setInputContextCallback(callback) |
| 167 | self.toggleCustomInputContextCallback = callback or NO_CALLBACK |
| 168 | end |
setPlaySampleCallback
DescriptionSet a callback function for requesting to play a sound sample.Definition
setPlaySampleCallback(func callback)Arguments
| func | callback | Function reference, signature: function(sampleName) |
| 173 | function FrameElement:setPlaySampleCallback(callback) |
| 174 | self.playSampleCallback = callback or NO_CALLBACK |
| 175 | end |
toggleCustomInputContext
DescriptionRequest toggling of a custom menu input context for this frame via the callback defined by setInputContextCallback().Definition
toggleCustomInputContext(bool isContextActive, string contextName)Arguments
| bool | isContextActive | If true, will activate a custom menu input context. Otherwise, will clear a previously activated context. |
| string | contextName | Name of the custom input context. Use a unique identifier value. |
| 189 | function FrameElement:toggleCustomInputContext(isContextActive, contextName) |
| 190 | if self.hasCustomInputContext and not isContextActive or not self.hasCustomInputContext and isContextActive then |
| 191 | self.toggleCustomInputContextCallback(isContextActive, contextName) |
| 192 | self.hasCustomInputContext = isContextActive |
| 193 | end |
| 194 | end |
update
DescriptionDefinitionupdate()Code
| 147 | function FrameElement:update(dt) |
| 148 | FrameElement:superClass().update(self, dt) |
| 149 | |
| 150 | self.time = self.time + dt |
| 151 | if self.inputDisableTime > 0 then |
| 152 | self.inputDisableTime = self.inputDisableTime - dt |
| 153 | end |
| 154 | end |