Window Class

Base class for user-interface dialogs.

Declared on: line 23 of Lua/window.lua.
Subclasses: Subtitles, TreeControl, UI, UIAdviser, UIBottomPanel, UIBuildRoom, UIConfirmDialog, UIFullscreen, UIFurnishCorridor, UIHireStaff, UIHotkeyAssignKeyPane, UIInformation, UIJukebox, UIMachine, UIMenuBar, UIMessage, UIPatient, UIPlaceObjects, UIPlaceStaff, UIQueue, UIQueuePopup, UIResizable, UIStaff, UIStaffRise, UIWatch

Method Index

addBevelPanel(x, y, w, h, colour, highlight_colour, shadow_colour, disabled_colour, lowered_colour, apply_ui_scale)
addColourPanel(x, y, w, h, r, g, b, apply_ui_scale)
addKeyHandler(key, handler, ...)
addPanel(sprite_index, x, y, w, h, apply_ui_scale, draw_flags)
addWindow(window)
afterLoad(old, new)
beginDrag(x, y)
bringToTop()
close()
draw(canvas, x, y)
getRealXY()
getSavedWindowPositionName()
getTooltipAt(x, y)
getTooltipForElement(elem, x, y)
getWindow(window_class)
getWindows(window_class)
hitTest(x, y)
hitTestPanel(x, y, panel)
hoverTest(active_hover, mouse_x, mouse_y, min_x, max_x, min_y, max_y)
makeButtonOnPanel(panel, x, y, w, h, sprite, on_click, on_click_self, on_rightclick)
makeDynamicTooltip(callback, x, y, r, b, tooltip_x, tooltip_y)
makeHotkeyBoxOnPanel(panel, confirm_callback, abort_callback)
makeScrollbarOnPanel(panel, slider_colour, callback, min_value, max_value, page_size, value)
makeTextboxOnPanel(panel, confirm_callback, abort_callback)
makeTooltip(text, x, y, r, b, tooltip_x, tooltip_y, apply_ui_scale)
mustPause()
onChangeLanguage()
onChangeResolution()
onCursorWorldPositionChange(x, y)
onMouseDown(button, x, y)
onMouseMove(x, y, dx, dy)
onMouseUp(button, x, y)
onMouseWheel(x, y)
onTick()
onWorldTick()
removeAllPanels()
removeKeyHandler(keys)
removeWindow(window)
sendToBottom(window)
sendToTop(window)
setDefaultPosition(x, y)
setPosition(x, y)
setSize(width, height, apply_ui_scale)
startButtonBlinking(button_index)
stopButtonBlinking()

Member Index

active_button
active_scrollbar
apply_ui_scale
blink_counter
blinking_button
btn_repeat_delay
buttons
buttons_down
closed
cursor_x
cursor_y
default_button_sound
draggable
dragging
height
hotkeyboxes
key_handlers
panel_sprites
panels
parent
scrollbars
textboxes
tooltip_regions
ui
visible
width
windows
x
x_original
y
y_original

function Window:Window()

Declared on: line 33 of Lua/window.lua.

function Window:addBevelPanel(x, y, w, h, colour, highlight_colour, shadow_colour, disabled_colour, lowered_colour, apply_ui_scale)

Add a beveled `Panel` to the window.

A bevel panel is similar to a solid colour panel, except that it features a highlight and a shadow that makes it appear either lowered or raised.

Parameters:

Name	Type	Description
x	integer	The X pixel position to start the panel at.
y	integer	The Y pixel position to start the panel at.
w	integer	The width of the panel, in pixels.
h	integer	The height of the panel, in pixels.
colour	colour or in or form or red or green or and or blue	The colour for the panel.
highlight_colour	colour or in or form or red or green or and or blue or or or nil	[optional] The colour for the highlight.
shadow_colour	colour or in or form or red or green or and or blue or or or nil	[optional] The colour for the shadow.
disabled_colour	colour or in or form or red or green or and or blue or or or nil	[optional] The colour for the disabled panel.
lowered_colour	colour or in or form or red or green or and or blue or or or nil	[optional] The colour for the lowered (toggled) panel.
apply_ui_scale	?	?

Declared on: line 474 of Lua/window.lua.

function Window:addColourPanel(x, y, w, h, r, g, b, apply_ui_scale)

Add a solid-colour `Panel` to the window.

A solid-colour panel is like a normal panel, expect it displays a solid colour rather than a bitmap.

Parameters:

Name	Type	Description
x	integer	The X pixel position to start the panel at.
y	integer	The Y pixel position to start the panel at.
w	integer	The width of the panel, in pixels.
h	integer	The height of the panel, in pixels.
r	integer	Value in [0, 255] giving the red component of the colour.
g	integer	Value in [0, 255] giving the green component of the colour.
b	integer	Value in [0, 255] giving the blue component of the colour.
apply_ui_scale	boolean	Whether to apply UI scale to position and size. Default is to match window.

Declared on: line 428 of Lua/window.lua.

function Window:addKeyHandler(key, handler, ...)

Parameters:

Name	Type	Description
key	?	?
handler	?	?
...	?	?

Declared on: line 151 of Lua/window.lua.

function Window:addPanel(sprite_index, x, y, w, h, apply_ui_scale, draw_flags)

Add a `Panel` to the window.

Panels form the basic building blocks of most windows. A panel is a small bitmap coupled with a position, and by combining several panels, a window can be made. By using panels to construct windows, all of the common tasks like drawing and hit-testing are provided for you by the base class methods, thus reducing the amount of code required elsewhere.

Parameters:

Name	Type	Description
sprite_index	integer	Index into the window's sprite table of the bitmap to be displayed.
x	integer	The X pixel position to display the bitmap at.
y	integer	The Y pixel position to display the bitmap at.
w	integer or nil	If the panel is totally opaque, and the width of the panel (in pixels) is known, it should be specified here to speed up hit-tests.
h	integer or nil	If the panel is totally opaque, and the height of the panel (in pixels) is known, it should be specified here to speed up hit-tests.
apply_ui_scale	bool or nil	If true apply the ui_scale to the dimensions when doing the draw and hit test. If nil then apply_ui_scale if enabled for the parent window.
draw_flags	integer	Draw flags to apply to the sprite

Declared on: line 380 of Lua/window.lua.

function Window:addWindow(window)

Parameters:

Name	Type	Description
window	?	?

Declared on: line 525 of Lua/window.lua.

function Window:afterLoad(old, new)

Stub to be extended in subclasses, if needed.

Parameters:

Name	Type	Description
old	?	?
new	?	?

Declared on: line 2140 of Lua/window.lua.

function Window:beginDrag(x, y)

Initiate dragging of the window.

Parameters:

Name	Type	Description
x	?	The X position of the cursor in window coordinates.
y	?	The Y position of the cursor in window coordinates.

Declared on: line 1802 of Lua/window.lua.

function Window:bringToTop()

Bring the window to the top of its parent

Declared on: line 1957 of Lua/window.lua.

function Window:close()

Called before the window is closed

Declared on: line 130 of Lua/window.lua.

function Window:draw(canvas, x, y)

Parameters:

Name	Type	Description
canvas	?	?
x	?	?
y	?	?

Declared on: line 1510 of Lua/window.lua.

function Window:getRealXY()

Return the X and Y coordinates of the window as drawn on the screen after factoring in the ui_scale.

Declared on: line 1503 of Lua/window.lua.

function Window:getSavedWindowPositionName()

Get the name of the saved window position group.

When the user drags a window, the new position of the window is saved, and then when any windows in the same group are opened in the future, the position of the new window is set to the saved position. By default, each window class is its own group, but by overriding this method, that can be changed.

Declared on: line 1690 of Lua/window.lua.

function Window:getTooltipAt(x, y)

Tooltips are either associated with buttons, panels, or a region. (see Button:setTooltip, Panel:setTooltip, Window:make[Dynamic]Tooltip)

Button tooltips take precedence over region tooltips, which again take precedence over panels. Returns tooltip in form of { text = .. , x = .. , y = .. } or nil for no tooltip.

Parameters:

Name	Type	Description
x	integer	The X coordinate relative to the top-left corner.
y	integer	The Y coordinate relative to the top-left corner.

Declared on: line 2091 of Lua/window.lua.

function Window:getTooltipForElement(elem, x, y)

An 'element' can either be a panel, a button, or a tooltip region.

Parameters:

Name	Type	Description
elem	?	?
x	?	?
y	?	?

Declared on: line 2065 of Lua/window.lua.

function Window:getWindow(window_class)

Searches (direct) child windows for window of the given class, and returns one (or nil if there weren't any at all).

Parameters:

Name	Type	Description
window_class	class	The class of window to search for.

Declared on: line 566 of Lua/window.lua.

function Window:getWindows(window_class)

Searches (direct) child windows for window of the given class, and returns a (potentially empty) list of matching windows.

Parameters:

Name	Type	Description
window_class	class	The class of window to search for.

Declared on: line 579 of Lua/window.lua.

function Window:hitTest(x, y)

Used to test if the window has a (non-transparent) pixel at the given position.

Parameters:

Name	Type	Description
x	integer	The X coordinate of the pixel to test, relative to the top-left corner of the window.
y	integer	The Y coordinate of the pixel to test, relative to the top-left corner of the window.

Declared on: line 1609 of Lua/window.lua.

function Window:hitTestPanel(x, y, panel)

Parameters:

Name	Type	Description
x	?	?
y	?	?
panel	?	?

Declared on: line 1572 of Lua/window.lua.

function Window:hoverTest(active_hover, mouse_x, mouse_y, min_x, max_x, min_y, max_y)

Used to test if cursor is currently hovering over certain area in dialog.

Parameters:

Name	Type	Description
active_hover	bool	Is cursor already hovers over it?
mouse_x	integer	Mouse X coordinate
mouse_y	integer	Mouse Y coordinate
min_x	integer	Minimum X area
max_x	integer	Maximum X area
min_y	integer	Minimum Y area
max_y	integer	Maximum Y area

Declared on: line 1589 of Lua/window.lua.

function Window:makeButtonOnPanel(panel, x, y, w, h, sprite, on_click, on_click_self, on_rightclick)

Convert a static panel into a clickable button.

Parameters:

Name	Type	Description
panel	Panel	The panel to convert into a button.
x	integer	The X coordinate of the clickable rectangle on the panel.
y	integer	The Y coordinate of the clickable rectangle on the panel.
w	integer	The width of the clickable rectangle on the panel.
h	integer	The height of the clickable rectangle on the panel.
sprite	integer	An index into the window's sprite sheet. The panel will display this sprite when the button is being pressed.
on_click	function	The function to be run when the user left-clicks the button. Takes three arguments: `on_click_self`, the toggle state (nil for normal buttons, true/false for toggle buttons), the button itself.
on_click_self	function or nil	The first value to pass to `on_click`. If nil or not given, then the window is passed as the first argument.
on_rightclick	function or nil	The function to be called when the user right-clicks the button.

Declared on: line 787 of Lua/window.lua.

function Window:makeDynamicTooltip(callback, x, y, r, b, tooltip_x, tooltip_y)

Create a dynamic tooltip to be displayed in a certain region.

tooltip_x and tooltip_y are optional; if not specified, it will default to top center of region.

Parameters:

Name	Type	Description
callback	function	A function that returns the string to display or nil for no tooltip.
x	integer	The X coordinate relative to the top-left corner.
y	integer	The Y coordinate relative to the top-left corner.
r	integer	The right (X + width) coordinate relative to the top-left corner.
b	integer	The bottom (Y + height) coordinate relative to the top-left corner.
tooltip_x	integer	[optional] The X coordinate to display the tooltip at.
tooltip_y	integer	[optional] The Y coordinate to display the tooltip at.

Declared on: line 2046 of Lua/window.lua.

function Window:makeHotkeyBoxOnPanel(panel, confirm_callback, abort_callback)

Convert a static panel into a hotkeybox.

hotkeyboxes consist of the panel given as a parameter, which is made into a ToggleButton automatically, and handle keyboard input while active.

Parameters:

Name	Type	Description
panel	panel	The panel that will serve as the hotkeybox base.
confirm_callback	function	The function to call when text is confirmed.
abort_callback	function	The function to call when entering is aborted.

Declared on: line 1465 of Lua/window.lua.

function Window:makeScrollbarOnPanel(panel, slider_colour, callback, min_value, max_value, page_size, value)

Convert a static panel into a scrollbar.

Scrollbars consist of a base panel (the panel given as a parameter) and an additional slider panel (automatically created BevelPanel).

Parameters:

Name	Type	Description
panel	panel	The panel that will serve as the scrollbar base.
slider_colour	colour or in or form or red or green or and or blue	The colour for the slider.
callback	function	Function that is called whenever the slider position changes.
min_value	integer	The minimum value the scrollbar can represent.
max_value	integer	The maximum value the scrollbar can represent.
page_size	integer	The amount of objects represented on one page.
value	integer or nil	The current value, or min_value if not specified.

Declared on: line 912 of Lua/window.lua.

function Window:makeTextboxOnPanel(panel, confirm_callback, abort_callback)

Convert a static panel into a textbox.

Textboxes consist of the panel given as a parameter, which is made into a ToggleButton automatically, and handle keyboard input while active.

Parameters:

Name	Type	Description
panel	panel	The panel that will serve as the textbox base.
confirm_callback	function	The function to call when text is confirmed.
abort_callback	function	The function to call when entering is aborted.

Declared on: line 1306 of Lua/window.lua.

function Window:makeTooltip(text, x, y, r, b, tooltip_x, tooltip_y, apply_ui_scale)

Create a static (non-changeable) tooltip to be displayed in a certain region.

tooltip_x and tooltip_y are optional; if not specified, it will default to top center of region.

Parameters:

Name	Type	Description
text	string	The string to display.
x	integer	The X coordinate relative to the top-left corner.
y	integer	The Y coordinate relative to the top-left corner.
r	integer	The right (X + width) coordinate relative to the top-left corner.
b	integer	The bottom (Y + height) coordinate relative to the top-left corner.
tooltip_x	integer	[optional] The X coordinate to display the tooltip at.
tooltip_y	integer	[optional] The Y coordinate to display the tooltip at.
apply_ui_scale	?	?

Declared on: line 2027 of Lua/window.lua.

function Window:mustPause()

Most windows don't pause the game. Specific windows: fax, annual report, staff rise, and errors do pause and are set in the specific files

Declared on: line 63 of Lua/window.lua.

function Window:onChangeLanguage()

Declared on: line 1552 of Lua/window.lua.

function Window:onChangeResolution()

Called after the resolution of the game window changes

Declared on: line 123 of Lua/window.lua.

function Window:onCursorWorldPositionChange(x, y)

Parameters:

Name	Type	Description
x	?	?
y	?	?

Declared on: line 1560 of Lua/window.lua.

function Window:onMouseDown(button, x, y)

Parameters:

Name	Type	Description
button	?	?
x	?	?
y	?	?

Declared on: line 1634 of Lua/window.lua.

function Window:onMouseMove(x, y, dx, dy)

Called when the user moves the mouse.

Parameters:

Name	Type	Description
x	integer	The new X coordinate of the cursor, relative to the top-left corner of the window.
y	integer	The new Y coordinate of the cursor, relative to the top-left corner of the window.
dx	integer	The number of pixels which the cursor moved horizontally.
dy	integer	The number of pixels which the cursor moved vertically.

Declared on: line 1844 of Lua/window.lua.

function Window:onMouseUp(button, x, y)

Parameters:

Name	Type	Description
button	?	?
x	?	?
y	?	?

Declared on: line 1700 of Lua/window.lua.

function Window:onMouseWheel(x, y)

Override this function in derived classes, with what you'd like to happen

on this event.

Parameters:

Name	Type	Description
x	int	Mousewheel has moved on the horizontal axis (-1 is leftward movement, +1 is rightward movement)
y	int	Mousewheel has moved on the vertical axis (-1 is downward movement, +1 is upward movement)

Declared on: line 1757 of Lua/window.lua.

function Window:onTick()

Called regularly at a rate independent of the game speed.

Declared on: line 1909 of Lua/window.lua.

function Window:onWorldTick()

Called regularly at the same rate that entities are ticked.

Declared on: line 1948 of Lua/window.lua.

function Window:removeAllPanels()

Declared on: line 415 of Lua/window.lua.

function Window:removeKeyHandler(keys)

Parameters:

Name	Type	Description
keys	string or or or table	The key or a list containing the key & its modifiers, previously passed to Window:addKeyHandler(keys).

Declared on: line 156 of Lua/window.lua.

function Window:removeWindow(window)

Parameters:

Name	Type	Description
window	?	?

Declared on: line 550 of Lua/window.lua.

function Window:sendToBottom(window)

Tell the window to bring the specified sub-window to its bottom

Parameters:

Name	Type	Description
window	?	?

Declared on: line 1995 of Lua/window.lua.

function Window:sendToTop(window)

Tell the window to bring the specified sub-window to its top

Parameters:

Name	Type	Description
window	?	?

Declared on: line 1964 of Lua/window.lua.

function Window:setDefaultPosition(x, y)

Sets the window's default onscreen position and onscreen position. The given x and y are interpreted as for setPosition(x, y), and are the default position for the window. If the user has previously repositioned a window of the same type, then setDefaultPosition() will set the window to that previous position, otherwise it sets it to the default position.

Parameters:

Name	Type	Description
x	?	?
y	?	?

Declared on: line 105 of Lua/window.lua.

function Window:setPosition(x, y)

Sets the window's onscreen position. Each of x and y can be: Integers >= 0 - Absolute pixel positions of top/left edge of window relative to top/left edge of screen Integers < 0 - Absolute pixel positions of right/bottom edge of window relative to right/bottom edge of screen. Use -0.1 to mean -0. Reals in [0, 1) -

Parameters:

Name	Type	Description
x	?	?
y	?	?

Declared on: line 74 of Lua/window.lua.

function Window:setSize(width, height, apply_ui_scale)

Parameters:

Name	Type	Description
width	?	?
height	?	?
apply_ui_scale	?	?

Declared on: line 68 of Lua/window.lua.

function Window:startButtonBlinking(button_index)

Parameters:

Name	Type	Description
button_index	?	?

Declared on: line 2008 of Lua/window.lua.

function Window:stopButtonBlinking()

Declared on: line 2016 of Lua/window.lua.