Script v1_7_1_0
- AI
- Animals
- Collections
- Contracts
- Debug
- Economy
- Elements
- EnvironmentalScore
- Errors
- Events
- GUI
- Handtools
- Hud
- I3d
- Input
- Jobs
- Maps
- Materials
- Misc
- Objects
- Parameters
- Placeables
- Placement
- Player
- Shop
- Sounds
- Specialization
- Specializations
- StateMachine
- Statistics
- Tasks
- Triggers
- Utils
- Vehicles
Engine v1_7_1_0
- AI
- Animation
- Camera
- Entity
- Fillplanes
- general
- General
- I3D
- Input
- Lighting
- Math
- Network
- Node
- NoteNode
- Overlays
- Particle System
- Physics
- Rendering
- Scenegraph
- Shape
- Sound
- Spline
- String
- Terrain Detail
- Text Rendering
- Tire Track
- VoiceChat
- XML
Foundation Reference
GuiUtils
DescriptionGUI utility functionsFunctions
checkOverlayOverlap
DescriptionCheck if a point lies within or a hotspot overlaps an overlay.Definition
checkOverlayOverlap(posX Point, posY Point, overlayX Overlay, overlayY Overlay, overlaySizeX Overlay, overlaySizeY Overlay, hotspot If)Arguments
posX | Point | or hotspot x position |
posY | Point | or hotspot y position |
overlayX | Overlay | x position |
overlayY | Overlay | y position |
overlaySizeX | Overlay | width |
overlaySizeY | Overlay | height |
hotspot | If | provided as an array having 4 numbers for the bounding points of a rectangle {minX, minY, maxX, maxY}, will be checked if it overlaps the overlay area given by the other parameters. |
192 | function GuiUtils.checkOverlayOverlap(posX, posY, overlayX, overlayY, overlaySizeX, overlaySizeY, hotspot) |
193 | if hotspot ~= nil and #hotspot == 4 then |
194 | return overlaySizeX > 0 and overlaySizeY > 0 |
195 | and posX >= overlayX + hotspot[1] |
196 | and posX <= overlayX + overlaySizeX + hotspot[3] |
197 | and posY >= overlayY + hotspot[2] |
198 | and posY <= overlayY + overlaySizeY + hotspot[4] |
199 | else |
200 | return overlaySizeX > 0 and overlaySizeY > 0 |
201 | and posX >= overlayX |
202 | and posX <= overlayX + overlaySizeX |
203 | and posY >= overlayY |
204 | and posY <= overlayY + overlaySizeY |
205 | end |
206 | end |
get2DArray
DescriptionTransform an attribute string representing a 2D array into an actual array.Definition
get2DArray(str Attribute, defaultValue Default)Arguments
str | Attribute | string containing exactly 2 numbers |
defaultValue | Default | value to return if the "str" parameter value is nil or invalid for transformation. |
Array | of | the 2 converted values as numbers: {value1, value2} |
106 | function GuiUtils.get2DArray(str, defaultValue) |
107 | if str ~= nil then |
108 | local parts = str:split(" ") |
109 | local x,y = unpack(parts) |
110 | if x ~= nil and y ~= nil then |
111 | return {Utils.evaluateFormula(x), Utils.evaluateFormula(y)} |
112 | end |
113 | end |
114 | |
115 | return defaultValue |
116 | end |
get4DArray
DescriptionTransform an attribute string representing a 4D array into an actual array.Definition
get4DArray(str Attribute, defaultValue Default)Arguments
str | Attribute | string containing exactly 4 numbers |
defaultValue | Default | value to return if the "str" parameter value is nil or invalid for transformation. |
Array | of | the 4 converted values as numbers: {value1, value2, value3, value4} |
123 | function GuiUtils.get4DArray(str, defaultValue) |
124 | local data = string.getVectorN(str) |
125 | if data ~= nil and #data == 4 then |
126 | return data |
127 | end |
128 | |
129 | return defaultValue |
130 | end |
getColorArray
DescriptionTransform an attribute string representing a 4D color array into an actual array.Definition
getColorArray(str Attribute, defaultValue Default)Arguments
str | Attribute | string containing exactly 4 numbers |
defaultValue | Default | value to return if the "str" parameter value is nil or invalid for transformation. |
Array | of | the 4 converted values as numbers: {red, green, blue, alpha} |
137 | function GuiUtils.getColorArray(colorStr, defaultValue) |
138 | local data = string.getVectorN(colorStr) |
139 | if data ~= nil and #data == 4 then |
140 | return data |
141 | end |
142 | return defaultValue |
143 | end |
getColorGradientArray
DescriptionTransform an attribute string representing a 4D color array into an actual array.Definition
getColorGradientArray(str Attribute, defaultValue Default)Arguments
str | Attribute | string containing exactly 4 numbers |
defaultValue | Default | value to return if the "str" parameter value is nil or invalid for transformation. |
Array | of | the 4 converted values as numbers: {red, green, blue, alpha}, or 16 numbers: 4x rgba. |
150 | function GuiUtils.getColorGradientArray(colorStr, defaultValue) |
151 | local data = string.getVectorN(colorStr) |
152 | if data ~= nil and (#data == 4 or #data == 16) then |
153 | return data |
154 | end |
155 | return defaultValue |
156 | end |
getNormalizedValues
DescriptionTransform an attribute string representing a list of numbers into an array and normalize the values.Definition
getNormalizedValues(str Attribute, refSize Reference, defaultValue Default)Arguments
str | Attribute | string containing numbers, either raw or with a pixel unit designation on each number (e.g. "12 24" or "12px 24px") |
refSize | Reference | size for normalization, e.g. a reference screen resolution used to scale pixel values, {sizeX, sizeY} |
defaultValue | Default | value to return if the "str" parameter value is nil |
Array | of | normalized values |
18 | function GuiUtils.getNormalizedValues(data, refSize, defaultValue) |
19 | if data ~= nil then |
20 | local parts = data |
21 | local isString = type(data) == "string" |
22 | if isString then |
23 | parts = data:split(" ") |
24 | end |
25 | local values = {} |
26 | for k, part in pairs(parts) do |
27 | local value = part |
28 | |
29 | if isString then |
30 | local isPixelValue, isDisplayPixelValue = false, false |
31 | if string.find(value, "px") ~= nil then |
32 | isPixelValue = true |
33 | value = string.gsub(value, "px", "") |
34 | elseif string.find(value, "dp") ~= nil then |
35 | isDisplayPixelValue = true |
36 | value = string.gsub(value, "dp", "") |
37 | end |
38 | |
39 | value = Utils.evaluateFormula(value) |
40 | |
41 | if isDisplayPixelValue then |
42 | local s = (k + 1) % 2 |
43 | if s == 0 then -- horizontal |
44 | value = value / g_screenWidth |
45 | else -- vertical |
46 | value = value / g_screenHeight |
47 | end |
48 | elseif isPixelValue then |
49 | -- refSize stores only 2 values (width, height). As str can contains more than 2 values we have to do a |
50 | -- loop match with this modulo operation (1->1, 2->2, 3->1, 4->2, 5->1, 6->1...) |
51 | value = value / refSize[((k + 1) % 2) + 1] |
52 | end |
53 | else |
54 | value = value / refSize[((k + 1) % 2) + 1] |
55 | end |
56 | |
57 | table.insert(values, value) |
58 | end |
59 | |
60 | if defaultValue ~= nil and #defaultValue > #parts then |
61 | -- Repeat missing values, so that 0 -> 0 0 or 0 0 0 0, and 0 1 -> 0 1 0 1. |
62 | -- This is also what CSS effectively does |
63 | local wrap = #parts |
64 | for i = #parts + 1, #defaultValue do |
65 | table.insert(values, values[(i - 1) % wrap + 1]) |
66 | end |
67 | end |
68 | |
69 | return values |
70 | end |
71 | |
72 | return defaultValue |
73 | end |
getUVs
DescriptionTransform an attribute string representing a UV array into an actual array and normalize the values.Definition
getUVs(str Attribute, ref Texture, defaultValue Default)Arguments
str | Attribute | string containing exactly 4 numbers, order and format: "x[px] y[px] sizeX[px] sizeY[px]" |
ref | Texture | reference size used to normalize pixel UV coordinates into unit sized UV coordinates |
defaultValue | Default | value to return if the "str" parameter value is nil or invalid for transformation. |
Array | of | the UV coordinates as {u1, v1, u2, v2, u3, v3, u4, v4} |
164 | function GuiUtils.getUVs(str, ref, defaultValue, rotation) |
165 | if str ~= nil then |
166 | local uvs = GuiUtils.getNormalizedValues(str, ref or {1024, 1024}) |
167 | if uvs[1] ~= nil then |
168 | local result = {uvs[1], 1 - uvs[2] - uvs[4], uvs[1], 1 - uvs[2], uvs[1] + uvs[3], 1 - uvs[2] - uvs[4], uvs[1] + uvs[3], 1 - uvs[2]} |
169 | |
170 | if rotation ~= nil then |
171 | GuiUtils.rotateUVs(result, rotation) |
172 | end |
173 | |
174 | return result |
175 | else |
176 | Logging.devError("GuiUtils.getUVs() Unable to get uvs for '%s'", str) |
177 | end |
178 | end |
179 | |
180 | return defaultValue |
181 | end |