Class DrawCaptionBuilder

java.lang.Object
com.botwithus.bot.api.draw.DrawCaptionBuilder
public final class DrawCaptionBuilder extends Object
Fluent chain for the two commands that draw words — a text command and a captioned component highlight. 
draw.component(1473, 5).color(Colors.CYAN).label("Inventory").submit();
draw.text("state", 40, 140, "banking").font(DrawFont.SMALL).submit();
draw.value("dps", 40, 160, 1234, 2).font(DrawFont.LARGE).submit();   // "12.34"

Why this is a separate type from DrawBuilder. A caption and a font are legal only on these two kinds; the producer rejects both on a rect, ellipse, line or poly. Splitting the chain means draw.rect(...).font(...) does not compile, rather than compiling and being refused at run time on a round-trip the script has already paid for. The producer's spec warns callers who build commands from a shared style object to strip font for the shapes — there is nothing to strip here, because a shape's builder never had one.

The styling half is delegated to a DrawBuilder rather than copied, so there is one implementation of what color or ttl mean. Only the return types differ, which is what keeps the chain typed.

  • Method Details

    • label

      public DrawCaptionBuilder label(String text)
      Draw this text. Replaces any caption already set — the wire allows exactly one caption per command, so these are alternatives rather than additions.

    • value

      public DrawCaptionBuilder value(long value, int decimals)
      Draw this scaled number: value(1234, 2) renders "12.34". Replaces any caption already set.

      There is no float on this wire, deliberately. Send a scaled integer and say what you scaled it by.

    • value

      public DrawCaptionBuilder value(long value)
      Draw this whole number.

    • font

      public DrawCaptionBuilder font(DrawFont font)
      Draw the caption in a named style. A style name, not a size.

      Order-independent: the style is remembered and applied to whatever caption the chain ends up with, as well as to one already set. font(...) before label(...) and after it mean the same thing — which they would not if the style lived only on the caption value, because DrawCaption.NONE has nowhere to keep it.

      A font on a command that never gains a caption draws nothing and sends nothing: a highlight with no label has no words to style. That is deliberately not an error, because setting the style up front and the caption conditionally is a reasonable thing to write:

      DrawCaptionBuilder box = draw.component(iface, comp).font(DrawFont.HEADING);
if (showName) {
    box.label(npcName);
}
box.submit();
      Throws:
      IllegalArgumentException - if font is null. Rejected here rather than carried, because a null survives the DrawCaption.NONE path — None.withFont ignores its argument — and would otherwise surface from inside a later label() or value(), naming the wrong call.

    • caption

      public DrawCaption caption()
      The caption as configured.

    • color

      public DrawCaptionBuilder color(int argb)
      Packed 0xAARRGGBB. See Colors.

    • alpha

      public DrawCaptionBuilder alpha(int alpha)
      The current colour at a different 0..255 alpha.

    • thickness

      public DrawCaptionBuilder thickness(int pixels)
      Stroke width, for the box a component highlight draws around its rect.

    • filled

      public DrawCaptionBuilder filled()
      Fill rather than stroke. Meaningful for a component highlight's box.

    • filled

      public DrawCaptionBuilder filled(boolean fill)
      Fill or stroke explicitly.

    • z

      public DrawCaptionBuilder z(int order)
      Draw order; higher is drawn in front. The only way to control which of several overlapping highlights is visible where they cross.

    • ttl

      public DrawCaptionBuilder ttl(long milliseconds)
      Lifetime in milliseconds. Defaults to DrawLimits.DEFAULT_TTL_MS.

    • ttl

      public DrawCaptionBuilder ttl(Duration duration)
      Lifetime as a Duration, truncated to whole milliseconds.

    • untilCleared

      public DrawCaptionBuilder untilCleared()
      Keep until replaced, cleared, or the script's connection closes.

    • screen

      public DrawCaptionBuilder screen()
      Client-area pixels, origin top-left. The default.

    • world

      public DrawCaptionBuilder world()
      Game-world coordinates, projected by the producer. See DrawSpace.WORLD.

    • build

      public DrawCommand.Primitive build()
      The command as configured, without sending it.

      The return type narrowed from DrawCommand to DrawCommand.Primitive, for the same reason and with the same consequences as DrawBuilder.build(): source-compatible, not binary compatible, so a script compiled against an older bot-api needs a rebuild.

    • submit

      public String submit()
      Send the command, and answer the key it is stored under.