LUADOC - Farming Simulator 19

Script v1.7.1.0

Engine v1.7.1.0

Foundation Reference

StableListElement

Description
Displays variable data with a stable number of child elements, swapping data between existing elements as needed. Use this element instead of ListElement when the changing nature of underlying data requires regular visual updates, modifying the displayed list item count or when the performance cost of rebuilding a list becomes too high. Usage: A view which uses this list should provide a GuiDataSource instance via StableListElement:setDataSource() and an item assignment function via StableListElement:setAssignItemDataFunction() which uses a data item from the data source to change the view state of a list item. Whenever the data source is changed (or gets an external call to GuiDataSource:notifyChange(), this list will also be notified to change its focus state and any slider coupled to the list. A view should add itself as a listener to data source changes to then update this list's display by calling StableListElement:updateItemPositions(). The list display is not updated automatically to allow views to have full control over the timing of the update and to perform other actions around the view update in arbitrary order.
Parent
ListElement
XML Configuration Parameters
GuiElement#itemTemplateIdstring ID of list item template which is replicated on creation as many times as visible items are configured.

Functions

addElement

Description
Definition
addElement()
Code
182function StableListElement:addElement(element)
183 if self.allowChildModification then
184 -- only support adding elements during initialization or deletion
185 StableListElement:superClass().addElement(self, element)
186 end
187end

buildListItems

Description
Build the stable list items which are modified instead of rebuilt on each visual update.
Definition
buildListItems()
Code
93function StableListElement:buildListItems()
94 local itemTemplate = self:getDescendantById(self.itemTemplateId)
95
96 if itemTemplate ~= nil then
97 self:removeElement(itemTemplate)
98
99 self:deleteListItems()
100 self.selectedIndex = 0 -- set selection to zero to avoid updating it while creating elements
101 for i = 1, self.visibleItems do
102 local listItem = itemTemplate:clone()
103 self:addElement(listItem)
104 end
105
106 itemTemplate:delete()
107
108 -- run the parent class layout
109 StableListElement:superClass().updateItemPositionsInRange(self, 1, #self.elements)
110 else
111 g_logManager:devWarning("Cannot find StableListElement item template with ID '%s', check configuration.", self.itemTemplateId)
112 end
113end

clone

Description
Create a deep copy clone of this StableListElement. Override from GuiElement to handle list element addition and layout in cloned element.
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
57function StableListElement:clone(parent, includeId, suppressOnCreate)
58 local cloned = StableListElement:superClass().clone(self, parent, includeId, suppressOnCreate)
59 -- apply alternating background profiles with a forced load to update list item aspect scaling
60 cloned:updateAlternatingBackground(true)
61 -- run the parent class layout on the clone
62 StableListElement:superClass().updateItemPositionsInRange(cloned, 1, #cloned.elements)
63 -- set the child modification flag after cloning, otherwise the list items cannot be added
64 cloned.allowChildModification = cloned.allowChildModification or self.allowChildModification
65 return cloned
66end

copyAttributes

Description
Definition
copyAttributes()
Code
70function StableListElement:copyAttributes(src)
71 StableListElement:superClass().copyAttributes(self, src)
72
73 self.dataSource = src.dataSource
74 self.assignItemDataFunction = src.assignItemDataFunction
75
76 self.isLoaded = src.isLoaded
77end

delete

Description
Definition
delete()
Code
117function StableListElement:delete()
118 self.allowChildModification = true -- enable removal of child elements
119 self.dataSource:removeChangeListener(self)
120 StableListElement:superClass().delete(self)
121end

getItemCount

Description
Get the number of list items in the list's data source.
Definition
getItemCount()
Return Values
Numberoflist items in data source
Code
142function StableListElement:getItemCount()
143 return self.dataSource:getCount()
144end

getSelectedDataIndex

Description
Get the index of the currently selected data item.
Definition
getSelectedDataIndex()
Code
148function StableListElement:getSelectedDataIndex()
149 return self.selectedIndex
150end

getSelectedElementIndex

Description
Get the currently selected list element's index. This shadows the parent's implementation to compensate for the different internal usage of self.selectedIndex.
Definition
getSelectedElementIndex()
Code
176function StableListElement:getSelectedElementIndex()
177 return self.selectedIndex - self.firstVisibleItem + 1
178end

loadFromXML

Description
Definition
loadFromXML()
Code
45function StableListElement:loadFromXML(xmlFile, key)
46 StableListElement:superClass().loadFromXML(self, xmlFile, key)
47
48 self.itemTemplateId = getXMLString(xmlFile, key .. "#itemTemplateId") or ""
49end

new

Description
Definition
new()
Code
30function StableListElement:new(target, custom_mt)
31 local self = ListElement:new(target, custom_mt or StableListElement_mt)
32 self:include(IndexChangeSubjectMixin) -- add index change subject mixin for index state observers
33
34 self.dataSource = GuiDataSource.EMPTY_SOURCE
35 self.assignItemDataFunction = NO_ASSIGNMENT_FUNCTION
36 self.allowChildModification = true
37
38 self.isLoaded = false
39
40 return self
41end

notifyClick

Description
Definition
notifyClick()
Code
322function StableListElement:notifyClick(clickedElementIndex)
323 self:raiseCallback("onClickCallback", self.selectedIndex, self.elements[clickedElementIndex])
324end

notifyDoubleClick

Description
Definition
notifyDoubleClick()
Code
316function StableListElement:notifyDoubleClick(clickedElementIndex)
317 self:raiseCallback("onDoubleClickCallback", self.selectedIndex, self.elements[clickedElementIndex])
318end

onDataSourceChanged

Description
Called when the data source changes. Update list properties based on data source.
Definition
onDataSourceChanged()
Code
164function StableListElement:onDataSourceChanged()
165 self.handleFocus = self.dataSource:getCount() > 0
166 self:raiseSliderUpdateEvent()
167end

onGuiSetupFinished

Description
Definition
onGuiSetupFinished()
Code
81function StableListElement:onGuiSetupFinished()
82 StableListElement:superClass().onGuiSetupFinished(self)
83
84 if self.itemTemplateId ~= "" and not self.isLoaded then
85 self:buildListItems()
86 self.allowChildModification = false
87 self.isLoaded = true
88 end
89end

removeElement

Description
Definition
removeElement()
Code
191function StableListElement:removeElement(element)
192 if self.allowChildModification then
193 -- only support removing elements during initialization or deletion
194 StableListElement:superClass().removeElement(self, element)
195 end
196end

setAssignItemDataFunction

Description
Set the reference to a data assignment function which takes data from a data source and applies it to list items. When updating this list's view, this function is run for each list element and assigns selected data according to the current view position.
Definition
setAssignItemDataFunction(function assignItemDataFunction)
Arguments
functionassignItemDataFunctionAssignment function, signature: function(guiElement, dataItem)
Code
157function StableListElement:setAssignItemDataFunction(assignItemDataFunction)
158 self.assignItemDataFunction = assignItemDataFunction or NO_ASSIGNMENT_FUNCTION
159end

setDataSource

Description
Set the data source for this list.
Definition
setDataSource(table guiDataSource)
Arguments
tableguiDataSourceGuiDataSource instance
Code
130function StableListElement:setDataSource(guiDataSource)
131 self.dataSource:removeChangeListener(self)
132
133 self.dataSource = guiDataSource or GuiDataSource.EMPTY_SOURCE
134 self.dataSource:addChangeListener(self, self.onDataSourceChanged)
135
136 self:raiseSliderUpdateEvent()
137end

setSelectedIndex

Description
Set the selected data index. Shadows parent ListElement implementation to work on the underlying data source.
Definition
setSelectedIndex()
Code
207function StableListElement:setSelectedIndex(index, forceChangeEvent, direction)
208 local numItems = self.dataSource:getCount()
209 local newIndex = MathUtil.clamp(index, 0, numItems)
210
211 if newIndex ~= self.selectedIndex then
212 self.lastClickTime = nil
213 end
214
215 -- skip non-selectable items
216 local nextItem = self.elements[newIndex - self.firstVisibleItem + 1]
217
218 if nextItem ~= nil then
219 if nextItem.disabled or not nextItem.allowFocus then
220 -- check if any list item is selectable at all, otherwise we risk an endless recursion
221 local anySelectable = false
222 for _, element in pairs(self.elements) do
223 if not element.disabled and element.allowFocus then
224 anySelectable = true
225 break
226 end
227 end
228
229 if anySelectable then
230 newIndex = newIndex + (direction or 1)
231
232 -- If we can't, stay where we are
233 if newIndex > numItems or newIndex < 1 then
234 if newIndex == 0 then
235 -- make sure we are scrolled to the top
236 self:scrollTo(1)
237 end
238
239 return
240 end
241
242 -- Force no change when direction is explicitly absent (mouse clicks on an item)
243 if direction == 0 then
244 return
245 end
246
247 return self:setSelectedIndex(newIndex, forceChangeEvent, direction or 1)
248 end
249 end
250 end
251
252 local hasChanged = self.selectedIndex ~= newIndex
253 self.selectedIndex = newIndex
254
255 local newFirstVisibleItem = self:calculateFirstVisibleItem(newIndex)
256 if hasChanged or newFirstVisibleItem ~= self.firstVisibleItem then
257 self:scrollTo(newFirstVisibleItem)
258 end
259
260 if hasChanged and self.isLoaded or forceChangeEvent then
261 self:notifyIndexChange(newIndex, numItems)
262 self:raiseCallback("onSelectionChangedCallback", newIndex)
263 end
264
265 self:applyElementSelection()
266end

updateItemPositionsInRange

Description
Update list items using data within the given range. Shadows ListElement parent's implementation with data-swapping instead of UI element moving.
Definition
updateItemPositionsInRange()
Code
271function StableListElement:updateItemPositionsInRange(startIndex, endIndex)
272 local topPos = self.size[2] - self.listItemStartYOffset - self.listItemHeight
273 local leftPos = self.listItemStartXOffset
274
275 for i, element in pairs(self.elements) do
276 element:setVisible(false)
277 end
278
279 local dataStartIndex = self.firstVisibleItem
280 local dataEndIndex = self.firstVisibleItem + (endIndex - startIndex)
281 local elementIndex = 1
282 for _, dataEntry in self.dataSource:iterateRange(dataStartIndex, dataEndIndex) do
283 local element = self.elements[elementIndex]
284 if element == nil then
285 break
286 end
287
288 element:reset()
289 element:setVisible(true)
290 element:fadeIn()
291 self.assignItemDataFunction(element, dataEntry)
292
293 elementIndex = elementIndex + 1
294 end
295
296 if self.dataSource:getCount() > 0 then
297 self:updateAlternatingBackground()
298
299 local selectedElement = self:getSelectedElement()
300 if selectedElement ~= nil and (selectedElement.disabled or not selectedElement.allowFocus) then
301 self:setSelectedIndex(self.selectedIndex) -- re-apply selection to be able to skip newly non-selectable items
302 end
303
304 self:applyElementSelection() -- apply visual selection
305
306 -- restore element positions after data and alternating background profile assignments
307 for i, element in ipairs(self.elements) do
308 local xPos, yPos = self:getItemPosition(leftPos, topPos, i - 1, element)
309 element:setPosition(xPos, yPos)
310 end
311 end
312end