JsMacrosCE

Appearance

TextBuilder ​

com.jsmacrosce.jsmacros.client.api.classes.TextBuilder

Since1.3.0

Builds styled text by appending sections and applying styles to the latest section. Obtain it with Chat.createTextBuilder() and pass build() to text-display APIs.

js
// a line with two colours in it: the styling applies to what comes
// after it, so the second append needs its own withColor
const text = Chat.createTextBuilder()
  .append("hello, ").withColor(0xc).append(" World!").withColor(0x6)
  .build();  
Chat.actionbar(text);

Constructors ​

new TextBuilder ​

new TextBuilder()Since1.3.0#
Creates an empty text builder. Style calls before the first append affect the empty root component, not a text section.

Methods ​

append ​

append(Object text): TextBuilderSince1.3.0#
Appends a section and makes it the target of subsequent style calls. A TextHelper contributes its underlying component by reference; a TextBuilder contributes its built component, while other values are converted with toString(). 
// three sections in one line, each with its own colour
const text = Chat.createTextBuilder()
  .append("first ")
  .withColor(0x6)
  .append("second ")
  .withColor(0xc)
  .append("third")
  .build();
Chat.actionbar(text);

Parameters:

Returns: this builder, for chaining

build ​

build(): TextHelperSince1.3.0#
Returns a TextHelper wrapping the builder's text component. The returned helper reflects later appends and style changes to this builder.
Returns: a TextHelper over the text built so far

getWidth ​

getWidth(): intSince1.8.4#
Returns the pixel width of the text currently built, measured with the game's font.
Returns: the width of this text.

withClickEvent ​

withClickEvent(String action, String value): TextBuilderSince1.3.0#
Sets a built-in click action on the current section. The action name is case-insensitive; the value is interpreted according to the action (for example, a URL for open_url or a page number for change_page). show_dialog resolves the value as a registered dialog identifier. 
// a section that opens a url when clicked. open_url takes the url
// itself as the value, and the action name is case insensitive
const text = Chat.createTextBuilder()
  .append("the docs")
  .withClickEvent("open_url", "https://jsmacrosce.github.io/")
  .build();
Chat.actionbar(text);

Parameters:

  • action: the click action, named in any case: open_url, open_file, run_command, suggest_command, change_page, copy_to_clipboard, show_dialog or custom
  • value: the argument for that action, whose meaning is decided by which one it is
Returns: this builder, for chaining

withColor ​

withColor(int color): TextBuilderSince1.3.0#
Sets the current section's color using one of the game's sixteen color codes, such as 0x6 for gold or 0xc for red. The argument is the numeric value of the code character, not an RGB value. Decoration formats do not have color-code IDs and cannot be selected here; use withFormatting(boolean, boolean, boolean, boolean, boolean) for them. An unmapped non-negative ID supplies no color; a negative ID selects the reset format. 
// gold then red, using the game's color IDs
const text = Chat.createTextBuilder()
  .append("gold ").withColor(0x6)
  .append("red").withColor(0xc)
  .build();
Chat.actionbar(text);

Parameters:

  • color: the numeric value of a chat color code from 0 to 0xf
Returns: this builder, for chaining
withColor(int r, int g, int b): TextBuilderSince1.3.1#
Sets the current section's color from RGB channel values. This is a true rgb value rather than one of the sixteen codes, so it is the form to reach for when the colour is not one the game has a code for. Each channel is masked to a single byte, so a value outside 0-255 is wrapped into range rather than refused, and the colour is opaque: there is no alpha to set here. A colour set this way replaces one set by withColor(int) on the same section rather than adding to it, since the section has one colour. 
// an rgb colour, which is the form for a shade the game's own
// sixteen codes do not cover
const text = Chat.createTextBuilder()
  .append("custom ")
  .withColor(255, 85, 85)
  .append("colour")
  .build();
Chat.actionbar(text);

Parameters:

  • r: red 0-255
  • g: green 0-255
  • b: blue 0-255
Returns: this builder, for chaining

withCustomClickEvent ​

withCustomClickEvent(MethodWrapper<Object, Object, Object, ?> action): TextBuilderSince1.3.0#
Runs a script function when the current section is clicked. The function takes no arguments; thrown exceptions are caught and logged. 
// a section that runs a script function when it is clicked
const text = Chat.createTextBuilder()
  .append("click me")
  .withCustomClickEvent(JavaWrapper.methodToJava(function () {
    Chat.log("clicked");
  }))
  .build();
Chat.actionbar(text);

Parameters:

  • action: the function to run on click, which takes nothing
Returns: this builder, for chaining

withFormatting ​

withFormatting(boolean underline, boolean bold, boolean italic, boolean strikethrough, boolean magic): TextBuilderSince1.3.0#
Sets the current section's decorations. The five flags are the game's five decorations and they are independent, so any combination of them can be set at once. The order of the parameters is underline, bold, italic, strikethrough and the obscuring one, which is not the order the chat codes are usually written in, so a positional call is worth reading twice. This is a separate call from withColor(int) rather than part of it, so a section can have both a colour and decorations. Setting decorations on a section that already has some replaces them rather than adding to them, since the same call also drops the ones set to false. 
// underline, bold, italic, strikethrough and obscured, in that order.
// Only the first two are asked for here
const text = Chat.createTextBuilder()
  .append("underlined and bold")
  .withColor(0xe)
  .withFormatting(true, true, false, false, false)
  .build();
Chat.actionbar(text);

Parameters:

  • underline: whether to underline the current section
  • bold: whether to embolden the current section
  • italic: whether to italicise the current section
  • strikethrough: whether to strike the current section through
  • magic: whether to obscure the current section
Returns: this builder, for chaining
withFormatting(FormattingHelper... formattings): TextBuilderSince1.8.4#
Applies the supplied decorations to the current section, replacing its existing decorations. 
// a text helper can hand over the formattings its own style carries,
// which is how a decoration is copied from one piece of text to
// another rather than chosen
const bold = Chat.createTextBuilder()
  .append("x")
  .withFormatting(false, true, false, false, false)
  .build();
const builder = Chat.createTextBuilder()
  .append("copied ");
bold.visit(JavaWrapper.methodToJava(function (style: StyleHelper, part) {
  const f = style.getFormatting();
  if (f !== null) {
    builder.withFormatting(f);
  }
  return part;
}));
Chat.actionbar(builder.build());

Parameters:

  • formattings: the formattings to apply
Returns: self for chaining.

withShowEntityHover ​

withShowEntityHover(EntityHelper<Entity> entity): TextBuilderSince1.3.0#
Sets the current section's hover event to show the entity's name and type, captured when this method is called.

Parameters:

  • entity: the entity to show on hover
Returns: this builder, for chaining

withShowItemHover ​

withShowItemHover(ItemStackHelper item): TextBuilderSince1.3.0#
Sets the current section's hover event to show an item's tooltip. This is the hover that shows an item's own tooltip, name, enchants and all, so what appears is whatever that item would show on its own rather than text of the script's choosing. The stack is taken as it is, so its count, damage and custom name are all part of what is shown. 
// show an item's tooltip when this section is hovered
const diamond = Client.getRegistryManager().getItemStack("minecraft:diamond");
const text = Chat.createTextBuilder()
  .append("a diamond")
  .withShowItemHover(diamond)
  .build();
Chat.actionbar(text);

Parameters:

  • item: the item to show on hover
Returns: this builder, for chaining

withShowTextHover ​

withShowTextHover(TextHelper text): TextBuilderSince1.3.0#
Sets the current section's hover event to show text. This is the hover the game shows when the cursor is over the section, and the text it shows is a TextHelper rather than a plain string, so it can be styled in turn. The hover belongs to the section that was appended last and it replaces any hover that section already had. 
// a section that shows a second, styled line when hovered
const tip = Chat.createTextBuilder()
  .append("this is the tooltip")
  .withColor(0x6)
  .build();
const text = Chat.createTextBuilder()
  .append("hover me")
  .withShowTextHover(tip)
  .build();
Chat.actionbar(text);

Parameters:

  • text: the text to show on hover, which may itself be styled
Returns: this builder, for chaining

withStyle ​

withStyle(StyleHelper style): TextBuilderSince1.8.4#
Replaces the current section's entire style with the supplied style, including any existing color, formatting, hover, or click event. 
// this replaces the whole style, so a colour set earlier on the
// same section is gone afterwards. The visitor below hands over the
// style of a section that has both a colour and a decoration
const source = Chat.createTextBuilder()
  .append("x")
  .withColor(0xc)
  .withFormatting(false, true, false, false, false)
  .build();
const text = Chat.createTextBuilder()
  .append("copied style");
source.visit(JavaWrapper.methodToJava(function (style: StyleHelper, part) {
  text.withStyle(style);
  return part;
}));
Chat.actionbar(text);

Parameters:

  • style: the style to put on the current section, replacing whatever it had
Returns: this builder, for chaining