UI:Main Page - Revision history

DrunkFlamingo at 14:55, 4 May 2022

2022-05-04T14:55:28Z

← Older revision		Revision as of 10:55, 4 May 2022
Line 237:		Line 237:
	As you might have guessed, this is a function that returns your new UI Component. The function first attempts to 'get' a component which already exists, and then creates the component if it doesn't.		As you might have guessed, this is a function that returns your new UI Component. The function first attempts to 'get' a component which already exists, and then creates the component if it doesn't.

	Why do we do it that way? Because UIComponents are often destroyed as the player navigates the UI and causes it to refresh. That means that every time we want to reference our UIC, we also want to make sure it ~~doesn't exist~~, and presumably we also want to make it exist if it doesn't. Rather than messy code that manually checks this every time, we formalize it into a single function.		Why do we do it that way? Because UIComponents are often destroyed as the player navigates the UI and causes it to refresh. That means that every time we want to reference our UIC, we also want to make sure it exists, and presumably we also want to make it exist if it doesn't. Rather than messy code that manually checks this every time, we formalize it into a single function.

	The most simple get or create function is the one that CA provides: <code>core:get_or_create_component("name", "ui/path/to/layout", parentComponent)</code>		The most simple get or create function is the one that CA provides: <code>core:get_or_create_component("name", "ui/path/to/layout", parentComponent)</code>

	This command is suitable in ~~most~~ cases, but you may want to define your own. A simple get or create function is as follows:		This command is suitable in many cases, but you may want to define your own. A simple get or create function is as follows:

	<nowiki>local function get_or_create_my_button()		<nowiki>local function get_or_create_my_button()

DrunkFlamingo at 14:50, 4 May 2022

2022-05-04T14:50:34Z

← Older revision		Revision as of 10:50, 4 May 2022
Line 219:		Line 219:

	==Implementation Patterns==		==Implementation Patterns==
	This section describes a basic ~~pattern~~ for ~~implementing a new~~ UI ~~Component using Lua~~. ~~This is~~ far from the only ~~way to do~~ things, but it should ~~provide~~ you ~~with a decent template for how to begin building your own UI features~~.		This section describes some basic patterns for creating UI mods. These are far from the only ways of doing things, but they should help you get started.

			=== Basic Button Pattern in Lua by Drunk Flamingo ===
	The example used here is to create a button on the character panel which costs 1000 gold and levels the character up to level 50.		The example used here is to create a button on the character panel which costs 1000 gold and levels the character up to level 50.

	~~=== Basic Button Pattern in Lua by Drunk Flamingo ===~~
	The pattern has five parts:		The pattern has five parts:

DrunkFlamingo: Finished simple UI impl pattern

2022-05-04T14:42:47Z

Finished simple UI impl pattern

Show changes

DrunkFlamingo: Added layouts section

2022-04-04T12:54:05Z

Added layouts section

← Older revision		Revision as of 08:54, 4 April 2022
Line 37:		Line 37:
	Documentation for Component Context Objects can be found locally in the data.pack, in the /documentation/ folder. However, [https://chadvandy.github.io/tw_modding_resources/WH3/cco/documentation.html it is also hosted here for convienience].		Documentation for Component Context Objects can be found locally in the data.pack, in the /documentation/ folder. However, [https://chadvandy.github.io/tw_modding_resources/WH3/cco/documentation.html it is also hosted here for convienience].

	==~~Relevant~~ Interfaces ~~Types~~==		==UI Lua Interfaces==
	The interface (or userdata, I'm going to use interface) types that are necesssary for UI modding using Lua are: UIComponents, CampaignUI, and the cco script interface.		The interface (or userdata, I'm going to use interface) types that are necesssary for UI modding using Lua are: UIComponents, CampaignUI, and the cco script interface.

Line 204:		Line 204:

	[[UI:Context Expressions\|You can learn more about context expressions on their page.]]		[[UI:Context Expressions\|You can learn more about context expressions on their page.]]

			== Layout Files ==
			UIComponents are defined in and created from layout files which specify the hierarchical relationships and properties of each element.

			In games previous to Warhammer 3, UI Layout files are extensionless binary files found in the ui folder and its subfolders. They can be edited using a hex editor.

			In Warhammer 3, Layout files are .twui.xml files. They can still be found in the UI folder, and are much easier to edit.

			=== Binary Layout Files ===
			Editing binary layout files is necessary for creating your own layouts in games prior to Warhammer 3. This is typically done using a hex editor.

			=== TWUI.XML Layout Files ===
			Each .twui.xml file has two parts: the hierarchy definition, and the components list.

	==Implementation Patterns==		==Implementation Patterns==

DrunkFlamingo at 20:29, 30 March 2022

2022-03-30T20:29:47Z

← Older revision		Revision as of 16:29, 30 March 2022
Line 260:		Line 260:
	A simple populate function is as follows:		A simple populate function is as follows:

	~~<nowiki>~~function populate_my_button(MyButton)		function populate_my_button(MyButton)
	if not is_uicomponent(MyButton) then		if not is_uicomponent(MyButton) then
	out("The button passed to populate_my_button is not a valid UIC! We're probably calling these functions at the wrong time")		out("The button passed to populate_my_button is not a valid UIC! We're probably calling these functions at the wrong time")
	return		return
	end		end
	local character = cm:get_character_by_cqi(cm:get_campaign_ui_manager():get_char_selected_cqi())		local character = cm:get_character_by_cqi(cm:get_campaign_ui_manager():get_char_selected_cqi())
	~~local ssm = cm:model():shared_states_manager()~~		if character:faction():treasury() < 1000 then
	~~local script_state_key = "already_pressed_my_button"~~		MyButton:SetState("inactive")
	if ~~ssm:get_state_as_bool_value(character, script_state_key) or~~ character:faction():treasury() < 1000 then		MyButton:SetTooltipText("Go Away!", true)
	MyButton:SetState("inactive")		else
	MyButton:SetTooltipText("Go Away!", true)		MyButton:SetState("active")
	else		MyButton:SetTooltipText("Click me!", true)
	MyButton:SetState("active")		end
	MyButton:SetTooltipText("Click me!", true)		end
	end
	end~~</nowiki>~~

	You can expand your elseif chains as needed.		You can expand your elseif chains as needed.

DrunkFlamingo at 20:26, 30 March 2022

2022-03-30T20:26:51Z

← Older revision		Revision as of 16:26, 30 March 2022
Line 209:		Line 209:

	=== Basic Button Pattern by Drunk Flamingo ===		=== Basic Button Pattern by Drunk Flamingo ===
	The pattern has ~~four~~ parts:		The pattern has five parts:

	# The Get or Create function.		# The Get or Create function.

DrunkFlamingo: Implementation Patterns ctd.

2022-03-30T20:26:08Z

Implementation Patterns ctd.

Show changes

DrunkFlamingo: /* Implementation Patterns */

2022-03-30T19:34:23Z

Implementation Patterns

← Older revision		Revision as of 15:34, 30 March 2022
Line 208:		Line 208:
	This section describes a basic pattern for implementing a new UI Component using Lua. This is far from the only way to do things, but it should provide you with a decent template for how to begin building your own UI features.		This section describes a basic pattern for implementing a new UI Component using Lua. This is far from the only way to do things, but it should provide you with a decent template for how to begin building your own UI features.

			=== Basic Button Pattern by Drunk Flamingo ===
	The pattern has four parts:		The pattern has four parts:

Line 218:		Line 219:
	In the case of images, text displays, or other visual elements, only the first three elements are required. The final two elements are specific to adding buttons to the UI.		In the case of images, text displays, or other visual elements, only the first three elements are required. The final two elements are specific to adding buttons to the UI.

	=== Get or Create ===		==== Get or Create ====
	As you might have guessed, this is a function that returns your new UI Component. The function first attempts to 'get' a component which already exists, and then creates the component if it doesn't.		As you might have guessed, this is a function that returns your new UI Component. The function first attempts to 'get' a component which already exists, and then creates the component if it doesn't.

Line 237:		Line 238:
	end		end
	end</nowiki>		end</nowiki>
			Note that the only thing being done to this UI element is creating it, and setting up aspects of it which don't change: in this case, the image. As a general rule, your 'get or create' function should never include references to gameplay values or bother with setting the dynamic aspects of the element.

	=== ~~Update Listeners~~ ===		==== Populate ====
			This function's job is to apply any dynamic aspects of your UI component based on the game state. Common examples of things that happen in the populate phase are:

	~~=== Click Listener ===~~		* Locking or unlocking buttons based on whether the player can afford some cost associated with pressing them.
			* Showing or hiding elements based on what region/character the player has selected.
			* Building and setting custom tooltips with information from the game.

	=== Multiplayer Safe Trigger Listener ===		Essentially: it should make the element look correct and display the correct information based on what the context is.

			A simple populate function is as follows:

			<nowiki>function populate_my_button(MyButton)
			local character = cm:get_character_by_cqi(cm:get_campaign_ui_manager():get_char_selected_cqi())
			local ssm = cm:model():shared_states_manager()
			local script_state_key = "already_pressed_my_button"
			if ssm:get_state_as_bool_value(character, script_state_key) or character:faction():treasury() < 1000 then
			MyButton:SetState("inactive")
			MyButton:SetTooltipText("Go Away!", true)
			else
			MyButton:SetState("active")
			MyButton:SetTooltipText("Click me!", true)
			end
			end</nowiki>


			==== Update Listeners ====

			==== Click Listener ====

			==== Multiplayer Safe Trigger Listener ====
	[[Category:Unfinished]]		[[Category:Unfinished]]

DrunkFlamingo: /* Implementation Patterns */

2022-03-30T19:14:33Z

Implementation Patterns

@@ Line 206: / Line 206: @@
 ==Implementation Patterns==
-This section describes a basic pattern for implementing a new UI Component using Lua. This is far from the only way to do things, but it should provide you with a decent template for how to
+This section describes a basic pattern for implementing a new UI Component using Lua. This is far from the only way to do things, but it should provide you with a decent template for how to begin building your own UI features.
 [[Category:Unfinished]]

DrunkFlamingo: AddScriptEventReporter

2022-03-30T18:40:58Z

AddScriptEventReporter

← Older revision		Revision as of 14:40, 30 March 2022
Line 93:		Line 93:

	Note that these commands return an address, so make sure to pass this address to UIComponent() in order to get the script object for your new UI component before trying to call methods on it.		Note that these commands return an address, so make sure to pass this address to UIComponent() in order to get the script object for your new UI component before trying to call methods on it.

			==== AddScriptEventReporter (Warhammer 3) ====
			UIComponents fire certain Lua events by default when they are interacted with. For example, most UI elements will notify the script when they are clicked using the ComponentLClickUp event.

			However, there are more detailed events which are not fired by most UIComponents by default in the most recent titles. Examples of this include ComponentMouseOn and ComponentMouseOff, which help modders to detect when elements are hovered.

			You can use the AddScriptEventReporter() method on any UIComponent to cause it to begin firing all events. For some elements, this is already enabled by default.

			In Warhammer 2 and previous games, all events are fired by all UIComponents without needing to call this command - this is less complicated, but it also means that there is more of a performance impact for using those events.

	===CampaignUI===		===CampaignUI===