• We created a new subforum for the Civ7 reviews, please check them here!

User Interface Components

whoward69

whoward69

DLL Minion
Joined
May 30, 2011
Messages
8,717
Location
Near Portsmouth, UK
The objective of these tutorials are to introduce the Civ 5 User Interface (UI) elements and controls needed to construct dialogs for presenting information to the user and receiving their decisions.

(Note: Due to size limitations, the PDF's attached to the following threads are in two parts. The single (hi-res) PDF is included in each mod.)


There are other references for the Civ 5 UI elements available, eg

All the code in these tutorials can be downloaded from my mods web-site from the "UI Tutorial" section. They are also available from the Civ 5 Fanatics Downloads area, although these versions may be slightly out of date.

Related tutorials and references
 
Part 1, The Basics

The objective of this tutorial is to introduce the basic Civ 5 User Interface (UI) elements and controls that are needed to construct dialogs for presenting information to the user and receiving their decisions (in the form of button clicks).

  • Dialog 1 - Hello World!
  • Dialog 1b - Text Attributes and Anchors
  • Dialog 2 - Borders (Grids)
  • Dialog 2b - Anchors Revisited
  • Dialog 2c - Containing the Mouse
  • Dialog 3 - Adding an OK Button
  • Dialog 4 - Static and Dynamic Decoration
  • Dialog 4b - Changing the Icon
  • Dialog 5 - More Buttons
  • Dialog 5b - Easier More Buttons
  • Dialog 6 - Odds and Ends





The tutorial covers the basic Civ 5 User Interface (UI) elements (and any Lua code needed to make them work), between them, these comprise around 80% of the elements used within the core game user interface.

  • Contexts
    • Context
  • Groupings
    • Grid
    • Box
    • Container
  • Visual Elements
    • Label
    • Image
  • Buttons
    • GridButton
    • TextButton
    • Button
  • Mouse Over Events
    • ShowOnMouseOver (also HideOnMouseOver)
    • AlphaAnim
  • Stacks
    • Stack

All the code in this tutorial can be downloaded from my mods web-site as "Test - UI Tutorial - 1 Basics".

Download part 1
Download part 2

Note: The PDF's are slightly out-of-date as Dialog 4c (below) has been added.
 
Part 2, Dynamic Buttons

The objective of this tutorial is to illustrate how to create Civ 5 User Interface (UI) elements (specifically buttons) from Lua code.

  • Button 1 - Review of Tutorial 1, Dialog 5b
  • Button 1b - Button Instances
  • Button 1c - Adding Another Language
  • Button 2 - City States List
  • Button 2b - Met City States List
  • Button 2c - Sorting Lists



The tutorial covers the Civ 5 User Interface (UI) elements and techniques for creating dynamic buttons and scrollable lists from Lua.

  • Dynamic Controls
    • Instance
    • :BuildInstanceForControl()
    • : DestroyAllChildren() and :ReleaseChild() (and why not to use them)
    • InstanceManager
  • Scrolling
    • ScrollPanel
    • DownButton
    • ScrollBar
    • UpButton
  • Sorting
    • :SortChildren()

All the code in this tutorial can be downloaded from my mods web-site as "Test - UI Tutorial - 2 Dynamic Buttons" and "Test - UI Tutorial - 2b Stacked Stacks"

Download part 1
Download part 2
 
Part 3, Drop-Down Menus

The objective of this tutorial is to illustrate how to create Civ 5 User Interface (UI) drop-down menus.

  • Menu 1 - Simple Drop-Down
  • Menu 1b - Sorting the Entries
  • Menu 2 - Entry Appearance
  • Menu 2b - Button Appearance
  • Menu 3 - Scroll Area Appearance



The tutorial covers the Civ 5 User Interface (UI) elements and techniques for creating drop-down menus

  • Menus
    • PullDown
    • StackData
    • InstanceData
    • ButtonData
    • GridData
    • ScrollPanelData

All the code in this tutorial can be downloaded from my mods web-site as "Test - UI Tutorial - 3 Menus".

Download part 1
Download part 2
 
Part 4, Other Input Controls

The objective of this tutorial is to cover the remaining Civ 5 User Interface (UI) input elements and controls - namely Check Boxes, Radio Buttons, Edit Boxes and Sliders.

  • Input 1 - Push Buttons
  • Input 2 - Edit Boxes
  • Input 3 - Sliders





The tutorial covers the remaining Civ 5 User Interface (UI) elements for obtaining input from the user

  • Selection Buttons
    • CheckBox
    • RadioButton
  • User Input
    • EditBox
  • Sliders
    • Slider

All the code in this tutorial can be downloaded from my mods web-site as "Test - UI Tutorial - 4 Other Input Controls".

Note: The PDF's are slightly out-of-date.

Download
 
Part 5, Feedback

The objective of this tutorial is to cover the Civ 5 User Interface (UI) elements and controls for providing feedback - namely ToolTips, Bars and Meters.

  • Feedback 1 - MouseOvers and ToolTips
  • Feedback 2 - Progress Bars
  • Feedback 2 - Texture Progress Bars
  • Feedback 3 - Meters
  • Feedback 4 - Percent Meter







The tutorial covers the Civ 5 User Interface (UI) elements for providing feedback to the user

  • Mouse Over Events
    • ShowOnMouseOver
    • HideOnMouseOver
    • ToolTipType
    • @ToolTipType
    • :SetToolTipCallback
  • Progress Meters
    • Bar
    • TextureBar
    • Meter
    • :SetPercent(fComplete)
    • :SetPercents(fComplete, fCompletePlusExtraTurn)

All the code in this tutorial can be downloaded from my mods web-site as "Test - UI Tutorial - 5 Feedback".

Note: The PDF's are slightly out-of-date

Download part 1
Download part 2
Download part 3
 
Part 6, World Placement

The objective of this tutorial is to illustrate how to place Civ 5 User Interface (UI) controls on the World Map.

  • World 1 - Hello World!
  • World 1b - City View Exclusion
  • World 2 - Battle Flags



The tutorial covers the Civ 5 User Interface (UI) elements and techniques for placing controls on the World Map

  • World Placement
    • WorldAnchor
    • :SetWorldPosition(HexToWorld(hexPos))

All the code in this tutorial can be downloaded from my mods web-site as "Test - UI Tutorial - 6 World Placement".

Note: The PDF's are slightly out-of-date.

Download part 1
Download part 2
 
Part 7, Animations

Part 8, Miscellanea

This tutorial wraps up with some of the less frequently used, but nonetheless useful, XML elements and attributes and also covers additional Lua code that occurs within most contexts to provide additional functionality.

  • Context Show/Hide Handling
  • City View Handling
  • Keyboard and Mouse Event Handling
  • Text Truncation & Wrapping
  • Focus Control
  • Colours
  • Line Element
  • Timers
  • LuaContext Element

All the code in these tutorials can be downloaded from my mods web-site as "Test - UI Tutorial - 7 Animations" and "Test - UI Tutorial - 8 Miscellanea".

Download Part 7, Animations
Download Part 8, Miscellanea
 
Dialog 4c - Background Image

Derived from Dialog 4b, UI/Dialog.lua and XML/DialogText.xml have no changes, UI/Dialog.xml as follows (one line change highlighted)

7197731638_5c1cdf3a4b.jpg


Pulls a trick with the AlphaAnim element to place and "wash-out" an image as a background for the dialog

Code: 
<?xml version="1.0" encoding="utf-8" ?>
<Context">
  <Box Style="BGBlock_ClearTopBar" />

  <Grid Size="400,270" Anchor="C,C" Style="Grid9DetailFive140" ConsumeMouse="1">
    <Image Anchor="C,T" AnchorSide="I,O" Offset="0,-27" Size="256,64" Texture="DecTop256x64.dds">
      <Image Anchor="C,C" Offset="0,-6" Size="80,80" Texture="NotificationFrameBase.dds">
        <Image ID="DialogTopIcon" Anchor="C,C" Offset="0,0" Size="80,80" Texture="NotificationGeneric.dds" />
      </Image>
    </Image>

    <Image Anchor="L,C" AnchorSide="O,I" Offset="-17,0" Size="32,64" Texture="Dec32x64Left.dds" />
    <Image Anchor="R,C" AnchorSide="O,I" Offset="-17,0" Size="32,64" Texture="Dec32x64Right.dds" />

[COLOR="Red"][B]    <AlphaAnim ID="BgImage" Anchor="L,T" Offset="17,43" Size="367,185" TextureOffset="200,35" Texture="ERA_Classical.dds" Cycle="Once" Stopped="1" AlphaStart="0.4" AlphaEnd="0.4" Speed="1"/>[/B][/COLOR]
 
    <Label ID="Message" Anchor="C,C" Font="TwCenMT24" FontStyle="Shadow" ColorSet="Beige_Black_Alpha" String="TXT_KEY_TEST_DIALOG_MESSAGE"/>

    <GridButton ID="OK" Size="140,36" Anchor="C,B" Offset="0,50" Style="BaseButton" ToolTip="TXT_KEY_TEST_DIALOG_BUTTON_OK_TT">
      <ShowOnMouseOver>
        <AlphaAnim Anchor="L,C" AnchorSide="O,O" Size="16,32" TextureOffset="0,0" Texture="buttonsidesglow.dds" Cycle="Bounce" Speed="1" AlphaStart=".99" AlphaEnd=".25"/>
        <Image     Anchor="L,C" AnchorSide="O,O" Size="8,16"  TextureOffset="0,0" Texture="buttonsides.dds" />

        <AlphaAnim Anchor="R,C" AnchorSide="O,O" Size="16,32" TextureOffset="16,0" Texture="buttonsidesglow.dds" Cycle="Bounce" Speed="1" AlphaStart=".99" AlphaEnd=".25"/>
        <Image     Anchor="R,C" AnchorSide="O,O" Size="8,16"  TextureOffset="8,0"  Texture="buttonsides.dds" />
      </ShowOnMouseOver>

      <Label Anchor="C,C" Offset="0,-2" String="TXT_KEY_TEST_DIALOG_BUTTON_OK" Font="TwCenMT24" FontStyle="Shadow" ColorSet="Beige_Black_Alpha" />
    </GridButton>
  </Grid>
</Context>
 
Alphabetical list of UI elements with the section they are described in

AlphaAnim Tutorial 7
Bar Tutorial 5
Box Tutorial 1
Button Tutorial 1
ButtonData Tutorial 3
CheckBox Tutorial 4
Container Tutorial 1
Context Tutorial 1
DownButton Tutorial 2
EditBox Tutorial 4
FlipAnim Tutorial 7
Grid Tutorial 1
GridButton Tutorial 1
GridData Tutorial 3
HideOnMouseOver Tutorial 5
Image Tutorial 1
Instance Tutorial 2
InstanceData Tutorial 3
Label Tutorial 1
Line Tutorial 8
LuaContext Tutorial 8
Meter Tutorial 5
PullDown Tutorial 3
RadioButton Tutorial 4
ScrollAnim Tutorial 7
ScrollBar Tutorial 2
ScrollPanel Tutorial 2
ScrollPanelData Tutorial 3
ShowOnMouseOver Tutorial 5
SlideAnim Tutorial 7
Slider Tutorial 4
Stack Tutorial 1
StackData Tutorial 3
TextButton Tutorial 1
TextureBar Tutorial 5
ToolTipType Tutorial 5
UpButton Tutorial 2
WorldAnchor Tutorial 6

(When you can honestly say you know what they all do and how to use them, you can give yourself a well deserved pat on the back!)
 
Alphabetical list of UI elements with (most of) their known (ie used by the core game xml files) attributes

Most UI elements support the Anchor, Font, FontStyle, ID, Hidden, Offset, Size and ToolTip attributes (so these have been removed from the table below)


AlphaAnim AlphaEnd AlphaStart AnchorSide Cycle Pause Speed Stopped Style Texture TextureOffset
Bar BGColor Direction FGColor
Box AnchorSide Color ConsumeMouse ConsumeMouseButton ConsumeMouseOver HideBox Padding String Style
Button AnchorSide Color Color0 ColorSet ConsumeMouse ConsumeMouseOver Disabled NoDefaultSound NoStateChange Sampler StateOffsetIncrement String Style TextAnchor TextOffset Texture TextureOffset ToolTipType TruncateWidth
CheckBox AnchorSide ButtonTexture CheckTexture ColorLayer0 ColorLayer1 ConsumeMouse Disabled IsChecked LeadingOffset MouseOver NoStateChange NormalState RadioGroup String Style TextAnchor TextAnchorSide TextOffset Texture WrapWidth
Container AnchorSide Color ConsumeMouse ConsumeMouseButton
DownButton AnchorSide Style
EditBox CallOnChar Color0 Color1 ColorSet CursorColor EditMode FocusStop KeepFocus MaxLength NumberInput Obscure
FlipAnim Columns EndPause FrameCount Pause Speed StepSize Texture
Grid AnchorSide AutoSize BranchAlpha Color ConsumeMouse ConsumeMouseButton ConsumeMouseOver NoClip NoStateChange Padding StateOffsetIncrement Style Texture
GridButton AnchorSide Color Color0 Color1 ColorSet ConsumeMouse Disabled StateOffsetIncrement String Style TextOffset ToolTipType TruncateWidth
Image AnchorSide Color ConsumeMouse ConsumeMouseOver Disabled NoStateChange Texture TextureOffset
Label AnchorSide Color Color0 Color1 Color2 ColorLayer0 ColorLayer1 ColorSet ConsumeMouse LeadingOffset String Style TextAnchor TextAnchorSide TruncateWidth WrapWidth
Line Color End Start Width
LuaContext DeferLoad FileName
Meter Color HasShadow ShadowColor Texture
PullDown AnchorSide AutoSizePopUp ConsumeMouse ScrollThreshold SpaceForScroll Style
RadioButton ButtonTexture ColorLayer0 ColorLayer1 IsChecked RadioGroup String TextAnchor TextAnchorSide
ScrollAnim MaskTexture Pause Speed Texture
ScrollBar AnchorSide Color Length Style
ScrollPanel AnchorSide AutoScrollBar Color ConsumeMouseOver Disabled FullClip Vertical
SlideAnim Cycle End Pause Speed Start Stopped Style
Slider Gutter Length Style Value
Stack AnchorSide Color ConsumeMouse Padding StackGrowth Style
TextButton AnchorSide ButtonDown Color Color0 Color1 ColorLayer0 ColorSet ConsumeMouse MouseOver MouseOverStyle NormalState String Style ToolTipType
TextureBar Direction HasShadow ShadowColor Texture
UpButton AnchorSide Style
WorldAnchor DepthAdjust Scaling

A few esoteric attributes have been removed for brevity
 
Minor changes to
  • Part 1 - Added Dialog 4c (above)
  • Part 4 - Added notes about :SetText() on a RadioButton control
  • Part 5 - Minor typos
  • Part 6 - Change to link to Part 7
  • Part 7 - Misc is now Part 8, Animations have been added as Part 7

Major changes to
  • Part 8 - Old Part 7, updated with extra information
 
Errata

Part 8 - Colours (stating on page 3)
  • Page 4 - "The pre-defined colours can be found in ColorAtlas.lua ..." should be "The pre-defined colours can be found in ColorAtlas.xml ..."
 
A quick analysis of the Gods and Kings UI files reveals that there are NO new UI elements/controls in the expansion.
 
Accessing UI controls

The following are identical

Code: 
Controls.Button2:SetHide(true)

Code: 
local button2 = Controls.Button2
button2:SetHide(true)

Code: 
Controls["Button2"]:SetHide(true)

Code: 
local sButton = "Button2"
Controls[sButton]:SetHide(true)

Code: 
local iButton = 2
Controls[string.format("Button%i", iButton)]:SetHide(true)

The last one is especially useful when in a loop

Code: 
for i=1, 5, 1 do
  Controls[string.format("Button%i", i)]:SetHide(true)
end

So no need for

Code: 
Controls.Button1:SetHide(true)
Controls.Button2:SetHide(true)
Controls.Button3:SetHide(true)
Controls.Button4:SetHide(true)
Controls.Button5:SetHide(true)
 
UI Control "Gottcha's"

  • Control names cannot be longer than 31 characters
 
I've started a thread in the General forum for asking questions as I'd like to try and keep this thread for "answers".

So if you think I've missed something or have any questions please post here - http://forums.civfanatics.com/showthread.php?t=461735

Thanks

W
 
You must log in or register to reply here.

Similar threads

Bonyduck Campersang
Adding Ability/Trait to Custom Civ
Replies
2
Views
441
Bonyduck Campersang
Bonyduck Campersang
Ryan F. Mercer
WhysMod Template VI
2
Replies
21
Views
2K
Ryan F. Mercer
Ryan F. Mercer
W
Stacking Relic Bonus
Replies
5
Views
203
WeaponizedIncontinence
W
KayAU
ARA UI tips and tricks
Replies
11
Views
2K
xphantomx
X
UncivilizedGuy
Historical Timeline Project
Replies
0
Views
1K
UncivilizedGuy
UncivilizedGuy
Top Bottom