Context (Civ5 Type)

From Civilization Modding Wiki
Revision as of 16:17, 19 September 2012 by DonQuich (talk | contribs) (Bot update)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

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


Usage

  • Lua.png Contexts are defined through the <Context> XML tag. They are the root of every UI file.
  • Lua.png They are linked in another context through the <LuaContext> XML tag.
  • UI.png A global Lua object is associated with the current context: ContextPtr
  • UI.png 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>)

Base game Gods & Kings ___________________________
Check.png Check.png Star.png Speech.png BuildInstance(string arg0, table arg1)
Check.png Check.png Star.png Speech.png BuildInstanceForControl(string arg0, table arg1, Stack arg2)
Check.png Check.png Star.png Speech.png BuildInstanceForControlAtIndex(string arg0, table controlTable, Stack arg2, int arg3)
Check.png Check.png Star.png Speech.png CallParentShowHideHandler(bool arg0)
Question.png Question.png Star.png Speech.png Question-blue.png CallShowHideHandler
Check.png Check.png Star.png Speech.png ClearUpdate()
Question.png Question.png Star.png Speech.png Question-blue.png DoDeferredLoad
Check.png Check.png Star.png Speech.png bool IsHotLoad()
Check.png Check.png Star.png Speech.png Context LoadNewContext(string path)
Check.png Check.png Star.png Speech.png Container LookUpControl(string arg0)
Question.png Question.png Star.png Speech.png Question-blue.png Reload
Check.png Check.png Star.png Speech.png SetInputHandler((void func(MouseEventType uiMsg, KeyType wParam, unknown lParam)) InputHandler)
Question.png Question.png Star.png Speech.png Question-blue.png SetPostInit
Check.png Check.png Star.png Speech.png SetShowHideHandler((void func(bool isHide, int bInitState)) ShowHide)
Check.png Check.png Star.png Speech.png SetShutdown((void func()) OnShutdown)
Check.png Check.png Star.png Speech.png SetUpdate((void func(float fTimeDelta)) UpdateHandler)
Question.png Question.png Star.png Speech.png SetTextureOffset(Vector2 questionOffset)


Inherited from ControlBase

XML Properties: none.

Base game Gods & Kings ___________________________
Check.png Check.png Star.png Speech.png BuildEntry(string arg0, table arg1)
Check.png Check.png Star.png Speech.png CalculateInternals()
Check.png Check.png Star.png Speech.png CalculateInternalSize()
Check.png Check.png Star.png Speech.png CalculateSize()
Check.png Check.png Star.png Speech.png ClearEntries()
Check.png Check.png Star.png Speech.png Button GetButton()
Check.png Check.png Star.png Speech.png RegisterCheckHandler((void func(bool bIsChecked)) OnPolicyInfo)
Question.png Check.png Star.png Speech.png RegisterSelectionCallback((void func(FaithPurchaseType v1, int v2)) OnChatTarget)
Check.png Check.png Star.png Speech.png SetCheck(bool cityBanners)
Check.png Check.png Star.png Speech.png SetPercent(int percentDone)
Check.png Check.png Star.png Speech.png SetPercents(float productionProgressPercent, float productionProgressPlusThisTurnPercent)
Check.png Check.png Star.png Speech.png SetScrollValue(int arg0)
Check.png Check.png Star.png Speech.png SetTexture(string textureName)
Question.png Check.png Star.png Speech.png SetTextureOffsetVal(int arg0, int offset)
Check.png Check.png Star.png Speech.png UnloadTexture()
Check.png Check.png Star.png Speech.png SetVoid2(ProcessType process)
Check.png Check.png Star.png Speech.png SetVoids(ResourceType building, ResourceType addToList)
Check.png Check.png Star.png Speech.png string GetText()
Check.png Check.png Star.png Speech.png 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)
Check.png Check.png Star.png Speech.png RegisterCallback(MouseType OnSearchTextEnter, (void func(PolicyBranchType policyBranchIndex, UnitType y, Button button)) OnClose = nil)
Check.png Check.png Star.png Speech.png SetText(string localizedString)
Check.png Check.png Star.png Speech.png SetVoid1(OrderType MAINTAIN_GOLD)


Common

XML Properties: IDDisabled

Base game Gods & Kings ___________________________
Question.png Question.png Star.png Speech.png ChangeParent(Image parent)
Question.png Question.png Star.png Speech.png DestroyAllChildren()
Question.png Question.png Star.png Speech.png string GetID()
Question.png Question.png Star.png Speech.png Question-blue.png GetNumChildren
Question.png Question.png Star.png Speech.png Question-blue.png IsDisabled
Question.png Question.png Star.png Speech.png ReleaseChild(WorldAnchor arg0)
Check.png Check.png Star.png Speech.png SetDisabled(bool disableBanners)
Check.png Check.png Star.png Speech.png SortChildren((void func(unknown a, unknown b)) SortFunction)


Layout

XML Properties: SizeOffsetAnchorAnchorSide

Base game Gods & Kings ___________________________
Question.png Question.png Star.png Speech.png unknown, int GetOffsetVal()
Question.png Question.png Star.png Speech.png int GetOffsetX()
Question.png Question.png Star.png Speech.png int GetOffsetY()
Check.png Check.png Star.png Speech.png Vector2 GetSize()
Question.png Question.png Star.png Speech.png int, int GetSizeVal()
Question.png Question.png Star.png Speech.png int GetSizeX()
Question.png Question.png Star.png Speech.png int GetSizeY()
Check.png Check.png Star.png Speech.png ReprocessAnchoring()
Question.png Question.png Star.png Speech.png SetAnchor(string arg0)
Check.png Check.png Star.png Speech.png SetOffset(Vector2 offset)
Check.png Check.png Star.png Speech.png SetOffsetVal(int xOffset, int yOffset)
Question.png Question.png Star.png Speech.png SetOffsetX(int xOffset)
Question.png Question.png Star.png Speech.png SetOffsetY(int TOP_COMPENSATION)
Check.png Check.png Star.png Speech.png SetSize(table blockSize)
Check.png Check.png Star.png Speech.png SetSizeVal(int baseWidth, int newHeight)
Question.png Question.png Star.png Speech.png SetSizeX(int width)
Question.png Question.png Star.png Speech.png SetSizeY(int newSizeY)


Appearance

XML Properties: HiddenStyleNoClipColorBranchAlpha

Base game Gods & Kings ___________________________
Question.png Question.png Star.png Speech.png BranchResetAnimation()
Question.png Question.png Star.png Speech.png Question-blue.png CalculateVisibilityBox
Check.png Check.png Star.png Speech.png int IsHidden()
Question.png Question.png Star.png Speech.png SetAlpha(float DimAlpha)
Check.png Check.png Star.png Speech.png SetColor(table fadeColor, int arg1)
Check.png Check.png Star.png Speech.png SetColorByName(string colorSet)
Check.png Check.png Star.png Speech.png SetColorChannel(int arg0, float arg1)
Question.png Check.png Star.png Speech.png SetColorVal(int arg0, int arg1 = nil, int arg2 = nil, int arg3 = nil)
Check.png Check.png Star.png Speech.png SetHide(int disablePolicies)
Question.png Question.png Star.png Speech.png Question-blue.png SetNoClip


Interaction

XML Properties: NeedsMouseOverConsumeMouseConsumeMouseOverConsumeMouseWheelConsumeMouseButton

Base game Gods & Kings ___________________________
Question.png Question.png Star.png Speech.png Question-blue.png GetConsumeMouseButton
Question.png Question.png Star.png Speech.png Question-blue.png GetConsumeMouseOver
Question.png Question.png Star.png Speech.png Question-blue.png GetConsumeMouseWheel
Question.png Question.png Star.png Speech.png bool HasMouseOver()
Question.png Question.png Star.png Speech.png Question-blue.png SetConsumeMouseButton
Question.png Question.png Star.png Speech.png SetConsumeMouseOver(bool arg0)
Question.png Question.png Star.png Speech.png Question-blue.png SetConsumeMouseWheel


Tool Tip

XML Properties: ToolTipToolTipType

Base game Gods & Kings ___________________________
Question.png Question.png Star.png Speech.png EnableToolTip(bool arg0)
Question.png Question.png Star.png Speech.png Question-blue.png GetToolTipString
Question.png Question.png Star.png Speech.png Question-blue.png IsToolTipEnabled
Check.png Check.png Star.png Speech.png 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)
Question.png Question.png Star.png Speech.png SetToolTipCallback((void func(Slider control)) TipHandler)
Check.png Check.png Star.png Speech.png SetToolTipString(string foodToolTip)
Question.png Question.png Star.png Speech.png 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.