59
edits
Changes
Created page with "'''Text components''' (base interface <code>ITextComponent</code>) are forms of text used by Minecraft and Forge to concisely hold data relating to text. They form the basis o..."
'''Text components''' (base interface <code>ITextComponent</code>) are forms of text used by Minecraft and Forge to concisely hold data relating to text. They form the basis of the chat system used in Minecraft. They are used for serializing and sending text data over network to players, displaying on clients, and styling for how the text appears with modifiers like bold and coloration.
There are two main types of text components: <code>StringTextComponent</code>s and <code>TranslationTextComponent</code>s. Both serve different purposes, although you should prefer the latter one for most general mod development. Both of these also extend from a base class of <code>TextComponent</code>, which has some important properties.
== TextComponent ==
Text components at their most basic level hold a <code>Style</code> object and a list of "sibling" text components named <code>siblings</code>. In reality, these "siblings" are actually children of the main text component, and are treated as such when formatting with the <code>Style</code> object. A style can be applied to a text component by calling <code>withStyle</code> and <code>setStyle</code>. <code>withStyle</code> modifies the existing <code>Style</code> object with the given property, while <code>setStyle</code> replaces the current <code>Style</code> object. By default, text components use a style of <code>Style.EMPTY</code>, with an empty color representing white and empty properties meaning no special text formatting. To add a light blue color for example, one could simple call <code>theTextComponent.withStyle(TextFormatting.BLUE)</code>. This will merge the <code>BLUE</code> color with the existing <code>Style</code> object. When applying a parent text component's <code>Style</code> to its children text components, a non-null property of a child <code>Style</code> will take precedence over its parent <code>Style</code>. This means that if the color is set for both a child and parent text component, the child's color will be displayed. Otherwise, non-null properties from a parent text component's <code>Style</code> override properties from the child <code>Style</code> if they are null.
=== Appending siblings ===
Siblings can be appended to text components similar to the plus (+) operator with Strings. Either <code>TextComponent#append(ITextComponent)</code> or <code>TextComponent#append(String)</code> can be called. The latter is an overload for the first function, and simply creates a new <code>StringTextComponent</code> with the provided String.
== StringTextComponent ==
String text components are the most basic form of text components. They are raw text components that contain a single String object. These are not preferred for general mod development as they cannot be translated into other languages. All properties of the base <code>TextComponent</code> apply to string text components.
== TranslationTextComponent ==
Translation text components are a more advanced form of text components that support String formatting and translation into multiple languages. Translation text components hold a '''translation key''', which is integral to translation into other languages. Translation keys are then mapped with a language file (commonly know as a lang file) to their appropriate entry for each translated language. It is important to note that the translation key is translated by the client, not the server. The server sends the translation key to the player, and the player's client converts the translation key into its fully expanded form when rendering depending on the player's selected language. If a player selects a specific language for which a translation key is not mapped, it will default to English.
=== Format modifiers ===
Translation text components also support format modifiers like used in <code>String#format</code>. These format modifiers are declared by using the string <code>%s</code> when creating a translation entry for a given translation key. This format modifier will then be expanded and replaced with the provided object when rendered by the client. Any other format modifiers like <code>%d</code> or <code>%n</code> are ''not supported'' and will throw a formatting error. The list of arguments to expand these are passed to the constructor of the <code>TranslationTextComponent</code> using an Object varargs parameter, similar to <code>String#format</code>. Any objects that are not an instance of <code>ITextComponent</code> will have <code>Object#toString</code> called during expansion.
There are two main types of text components: <code>StringTextComponent</code>s and <code>TranslationTextComponent</code>s. Both serve different purposes, although you should prefer the latter one for most general mod development. Both of these also extend from a base class of <code>TextComponent</code>, which has some important properties.
== TextComponent ==
Text components at their most basic level hold a <code>Style</code> object and a list of "sibling" text components named <code>siblings</code>. In reality, these "siblings" are actually children of the main text component, and are treated as such when formatting with the <code>Style</code> object. A style can be applied to a text component by calling <code>withStyle</code> and <code>setStyle</code>. <code>withStyle</code> modifies the existing <code>Style</code> object with the given property, while <code>setStyle</code> replaces the current <code>Style</code> object. By default, text components use a style of <code>Style.EMPTY</code>, with an empty color representing white and empty properties meaning no special text formatting. To add a light blue color for example, one could simple call <code>theTextComponent.withStyle(TextFormatting.BLUE)</code>. This will merge the <code>BLUE</code> color with the existing <code>Style</code> object. When applying a parent text component's <code>Style</code> to its children text components, a non-null property of a child <code>Style</code> will take precedence over its parent <code>Style</code>. This means that if the color is set for both a child and parent text component, the child's color will be displayed. Otherwise, non-null properties from a parent text component's <code>Style</code> override properties from the child <code>Style</code> if they are null.
=== Appending siblings ===
Siblings can be appended to text components similar to the plus (+) operator with Strings. Either <code>TextComponent#append(ITextComponent)</code> or <code>TextComponent#append(String)</code> can be called. The latter is an overload for the first function, and simply creates a new <code>StringTextComponent</code> with the provided String.
== StringTextComponent ==
String text components are the most basic form of text components. They are raw text components that contain a single String object. These are not preferred for general mod development as they cannot be translated into other languages. All properties of the base <code>TextComponent</code> apply to string text components.
== TranslationTextComponent ==
Translation text components are a more advanced form of text components that support String formatting and translation into multiple languages. Translation text components hold a '''translation key''', which is integral to translation into other languages. Translation keys are then mapped with a language file (commonly know as a lang file) to their appropriate entry for each translated language. It is important to note that the translation key is translated by the client, not the server. The server sends the translation key to the player, and the player's client converts the translation key into its fully expanded form when rendering depending on the player's selected language. If a player selects a specific language for which a translation key is not mapped, it will default to English.
=== Format modifiers ===
Translation text components also support format modifiers like used in <code>String#format</code>. These format modifiers are declared by using the string <code>%s</code> when creating a translation entry for a given translation key. This format modifier will then be expanded and replaced with the provided object when rendered by the client. Any other format modifiers like <code>%d</code> or <code>%n</code> are ''not supported'' and will throw a formatting error. The list of arguments to expand these are passed to the constructor of the <code>TranslationTextComponent</code> using an Object varargs parameter, similar to <code>String#format</code>. Any objects that are not an instance of <code>ITextComponent</code> will have <code>Object#toString</code> called during expansion.