This page is a part of the Lua and UI Reference (Civ5).

Usage

Contexts are defined through the <Context> XML tag. They are the root of every UI file.
They are linked in another context through the <LuaContext> XML tag.
A global Lua object is associated with the current context: ContextPtr
Another global Lua object, Controls, stores all the controls defined in the XML file, provided they have an ID associated with them.

Contexts are UI parts, but not reusable components

Contexts are static parts of the UI. They are used to split the UI into different files.

You can nest one context into another through LuaContext. With the following example, the new context will appear in the current one under Controls.LegalScreen and will behave as a new control.

	<!-- This includes in this context a context defined in another file. This new context will behave as a control and will be stored under Controls.LegalScreen -->
	<LuaContext FileName="Assets/UI/FrontEnd/LegalScreen" ID="LegalScreen"/>

Now contexts cannot be efficiently used as a way to implement reusable controls because of the isolation explained in the next section. While LuaEvents could be used to circumvent this isolation, it's not really suited to instancing. The main point of Lua contexts is just to split your UI into different files and to provide an isolation mechanism.

Contexts are isolation scopes

But UI contexts are not just parts of the UI. They also represent contexts in the meaning defined in Lua.

Lua contexts are static (non-instanced) isolation scopes. That is, a Lua variable defined in one context is not visible from other contexts. However some things are shared across contexts:

Any Instance defined in a context is visible in children contexts and further descendants.
The data tables, styles and colors are visible from all contexts and have the same value in all those contexts.
The events declared on LuaEvents are visible in all contexts and they are the only way to achieve inter-contexts communication and objects and tables across contexts.

Finally, while the game state is always the same in all contexts, the API objects are specific to every context. That is, if you try for example to compare a Player instance from one context with the same instance from the current context, the result will be false because they are different objects.

return pIndianPlayerFromContext1 == pIndianPlayerFromContext1 -- returns true
return pIndianPlayerFromContext1 == pIndianPlayerFromContext2 -- returns false
return pIndianPlayerFromContext1:GetCivilizationType() == pIndianPlayerFromContext2:GetCivilizationType() -- returns true

Contexts all execute on the same thread

A common misconception is that contexts are ran in different threads. This is absolutely wrong. Actually, Civ5 is almost a purely mono-threaded game since everything from the rendering to the Lua execution and the game logic all run on a single thread. As a result all contexts are executed one after the other and a mod can block the UI and make the game hang, for example through an infinite loop.

So if you need to perform long-running computations, you need to split this task into multiple parts (Lua coroutines may be used for that purpose) and run one part anytime the update callback is invoked (see #Update).

New Properties

Color0

Format: Unknown.

Usage: Unknown.

Color1

Format: Unknown.

Usage: Unknown.

ColorSet

Format: Unknown.

Usage: Unknown.

Context

Format: Unknown.

Usage: Unknown.

DeferLoad

Format: Unknown.

Usage: Unknown.

FileName

Format: Unknown.

Usage: Unknown.

Font

Format: Unknown.

Usage: Unknown.

FontStyle

Format: Unknown.

Usage: Unknown.

Name

Format: Unknown.

Usage: Unknown.

New Instance Methods

Methods are functions that belong to an object. Instance methods are invoked through a colon, as in caller:SomeMethod(<args>), where caller is an instance of Context.
A colon implictly passes the caller object as the first argument. That is, the former call is equivalent to this one: caller.SomeMethod(caller, <args>)

				`___________________________`
					`BuildInstance(string arg0, table arg1)`
					`BuildInstanceForControl(string arg0, table arg1, Stack arg2)`
					`BuildInstanceForControlAtIndex(string arg0, table controlTable, Stack arg2, int arg3)`
					`CallParentShowHideHandler(bool arg0)`
					`CallShowHideHandler`
					`ClearUpdate()`
					`DoDeferredLoad`
				`bool`	`IsHotLoad()`
				`Context`	`LoadNewContext(string path)`
				`Container`	`LookUpControl(string arg0)`
					`Reload`
					`SetInputHandler((void func(MouseEventType uiMsg, KeyType wParam, unknown lParam)) InputHandler)`
					`SetPostInit`
					`SetShowHideHandler((void func(bool isHide, int bInitState)) ShowHide)`
					`SetShutdown((void func()) OnShutdown)`
					`SetUpdate((void func(float fTimeDelta)) UpdateHandler)`
					`SetTextureOffset(Vector2 questionOffset)`

Inherited from ControlBase

XML Properties: none.

				`___________________________`
					`BuildEntry(string arg0, table arg1)`
					`CalculateInternals()`
					`CalculateInternalSize()`
					`CalculateSize()`
					`ClearEntries()`
				`Button`	`GetButton()`
					`RegisterCheckHandler((void func(bool bIsChecked)) OnPolicyInfo)`
					`RegisterSelectionCallback((void func(FaithPurchaseType v1, int v2)) OnChatTarget)`
					`SetCheck(bool cityBanners)`
					`SetPercent(int percentDone)`
					`SetPercents(float productionProgressPercent, float productionProgressPlusThisTurnPercent)`
					`SetScrollValue(int arg0)`
					`SetTexture(string textureName)`
					`SetTextureOffsetVal(int arg0, int offset)`
					`UnloadTexture()`
					`SetVoid2(ProcessType process)`
					`SetVoids(ResourceType building, ResourceType addToList)`
				`string`	`GetText()`
					`LocalizeAndSetText(string name, int searchString = nil, string minFaithForProphet = nil, unknown arg3, unknown arg4, unknown arg5, unknown arg6, unknown arg7, unknown arg8, string arg9, unknown arg10, unknown arg11)`
					`RegisterCallback(MouseType OnSearchTextEnter, (void func(PolicyBranchType policyBranchIndex, UnitType y, Button button)) OnClose = nil)`
					`SetText(string localizedString)`
					`SetVoid1(OrderType MAINTAIN_GOLD)`

Common

XML Properties: IDDisabled

				`___________________________`
					`ChangeParent(Image parent)`
					`DestroyAllChildren()`
				`string`	`GetID()`
					`GetNumChildren`
					`IsDisabled`
					`ReleaseChild(WorldAnchor arg0)`
					`SetDisabled(bool disableBanners)`
					`SortChildren((void func(unknown a, unknown b)) SortFunction)`

Layout

XML Properties: SizeOffsetAnchorAnchorSide

				`___________________________`
				`unknown, int`	`GetOffsetVal()`
				`int`	`GetOffsetX()`
				`int`	`GetOffsetY()`
				`Vector2`	`GetSize()`
				`int, int`	`GetSizeVal()`
				`int`	`GetSizeX()`
				`int`	`GetSizeY()`
					`ReprocessAnchoring()`
					`SetAnchor(string arg0)`
					`SetOffset(Vector2 offset)`
					`SetOffsetVal(int xOffset, int yOffset)`
					`SetOffsetX(int xOffset)`
					`SetOffsetY(int TOP_COMPENSATION)`
					`SetSize(table blockSize)`
					`SetSizeVal(int baseWidth, int newHeight)`
					`SetSizeX(int width)`
					`SetSizeY(int newSizeY)`

Appearance

XML Properties: HiddenStyleNoClipColorBranchAlpha

				`___________________________`
					`BranchResetAnimation()`
					`CalculateVisibilityBox`
				`int`	`IsHidden()`
					`SetAlpha(float DimAlpha)`
					`SetColor(table fadeColor, int arg1)`
					`SetColorByName(string colorSet)`
					`SetColorChannel(int arg0, float arg1)`
					`SetColorVal(int arg0, int arg1 = nil, int arg2 = nil, int arg3 = nil)`
					`SetHide(int disablePolicies)`
					`SetNoClip`

Interaction

XML Properties: NeedsMouseOverConsumeMouseConsumeMouseOverConsumeMouseWheelConsumeMouseButton

				`___________________________`
					`GetConsumeMouseButton`
					`GetConsumeMouseOver`
					`GetConsumeMouseWheel`
				`bool`	`HasMouseOver()`
					`SetConsumeMouseButton`
					`SetConsumeMouseOver(bool arg0)`
					`SetConsumeMouseWheel`

Tool Tip

XML Properties: ToolTipToolTipType

				`___________________________`
					`EnableToolTip(bool arg0)`
					`GetToolTipString`
					`IsToolTipEnabled`
					`LocalizeAndSetToolTip(string description, string minFaithForProphet = nil, string threshold, string moodText, string spyRank, string spyName, string spyRank, string spyName, unknown arg8, unknown arg9, string arg10, unknown arg11, unknown arg12)`
					`SetToolTipCallback((void func(Slider control)) TipHandler)`
					`SetToolTipString(string foodToolTip)`
					`SetToolTipType(string arg0)`

Source code samples

Too many occurences. Only 10 out of 517 are listed.

EmptyPopup.xml

UI/InGame/Popups/EmptyPopup.xml


`0002`	<Context/>

FrontEnd.xml

UI/FrontEnd/FrontEnd.xml


`0002`	<Context ColorSet="Beige_Black_Alpha" Font="TwCenMT22" FontStyle="Shadow" Name="FrontEnd" >

GameMenu.xml

UI/InGame/Menus/GameMenu.xml


`0289`	<LuaContext FileName="Assets/UI/InGame/Menus/SaveMapMenu" ID="SaveMapMenu" Hidden="True" />

InGame.xml

UI/InGame/InGame.xml


`0041`	<LuaContext FileName="Assets/UI/InGame/Popups/TechAwardPopup" ID="TechAwardPopup" Hidden="True" />

InGame.xml (G&K)

DLC/Expansion/UI/InGame/InGame.xml


`0025`	<LuaContext FileName="Assets/UI/InGame/Popups/GoodyHutPopup" ID="GoodyHutPopup" Hidden="True"/>

`0029`	<LuaContext FileName="Assets/UI/InGame/Popups/CityStateGreetingPopup" ID="CityStateGreetingPopup" Hidden="True"/>

`0054`	<LuaContext FileName="Assets/UI/InGame/TopPanel" ID="TopPanel"/>

MainMenu.xml

UI/FrontEnd/MainMenu.xml


`0184`	<LuaContext FileName="Assets/UI/FrontEnd/SinglePlayer" ID="SinglePlayerScreen" Hidden="1"/>

NotificationPanel.xml

UI/InGame/WorldView/NotificationPanel.xml


`0002`	<Context >

OtherMenu.xml

UI/FrontEnd/OtherMenu.xml


`0118`	<LuaContext FileName="Assets/UI/FrontEnd/LatestNews" ID="LatestNews" Hidden="1" DeferLoad="1"/>

The initial version of this page was created by the Civ5 API Bot, see the Civ5 API Reference FAQ. Some of the texts come from the 2kgames' wiki and most of code samples are copyrighted to Firaxis.
Functions' signatures were either copied from the 2kgames' wiki, or infered from the Lua source files and the binaries. Errors are possible.
Contributors may find help in the Contributors guide to the Civ5 API.

Context (Civ5 Type)

Contents

Usage

Contexts are UI parts, but not reusable components

Contexts are isolation scopes

Contexts all execute on the same thread

New Properties

New Instance Methods

Inherited from ControlBase

Common

Layout

Appearance

Interaction

Tool Tip

Source code samples

Navigation menu

Page actions

Page actions

Personal tools

Navigation

Search

Tools