Class WidgetQuery

java.lang.Object
privbot.query.WidgetQuery

public final class WidgetQuery extends Object
Fluent query over Widget instances, similar to NPCQuery / ObjectQuery. Prefer Widgets.queryAt(int) for inspector ids (group.child packed): it seeds the subtree and expands one child layer (IF3 item rows). Use root(int) with expandDescendants(int) and withAction(String...) to locate a component by menu action inside a deep interface (e.g. ToA rewards Bank-all).
  • Constructor Summary

    Constructors
    Constructor
    Description
    WidgetQuery(List<net.runelite.api.widgets.Widget> raw, net.runelite.api.Client client)
    Wraps a copy of raw.
  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    True when no widget is left.
    expandDescendants(int maxRounds)
    Repeats expandImmediateChildren() maxRounds times, accumulating all widgets up to that many levels below the current set (deduplicated by identity).
    For each current widget, appends all immediate children (same child discovery as the dialogue hook's tree walks: dynamic, static, nested, and Widget.getChildren()), preserving order and deduplicating by identity.
    filter(Predicate<net.runelite.api.widgets.Widget> predicate)
    Narrows this query in place and returns it.
    net.runelite.api.widgets.Widget
    The first remaining widget, or null when the query is empty.
    net.runelite.api.widgets.Widget
    first(Predicate<net.runelite.api.widgets.Widget> predicate)
    Narrows by predicate (in place) and returns the first match, or null.
    fromPacked(net.runelite.api.Client client, int packedId)
    Single root via inspector-style lookup.
    List<net.runelite.api.widgets.Widget>
    An unmodifiable view of the remaining widgets.
    root(int packedId)
    Add a widget resolved from an inspector packed id (group.child).
    Adds all current top-level widget roots.
    int
    The number of widgets left.
    start(net.runelite.api.Client client)
    Empty query — add widgets with root(int), withWidget(Widget), or use Widgets.queryAt(int).
    Keeps widgets that are not hidden (Widget.isHidden()).
    where(Predicate<net.runelite.api.widgets.Widget> predicate)
    withAction(String... options)
    Keeps widgets whose Widget.getActions() list matches any of the given options (normalized text, same rules as component menu interaction: exact normalized match or substring contains).
    Keeps widgets whose normalized Widget.getText() or Widget.getName() exactly matches any requested value (case-insensitive, colour tags stripped).
    Inventory-style slot: withNonEmptyName() logic or positive Widget.getItemId() when the client omits the label but sets an item.
    Non-blank Widget.getName() or meaningful text after stripping colour tags (the same normalisation the dialogue hook uses).
    withText(String... texts)
    Keeps widgets whose Widget.getText() or Widget.getName() contains any of the given substrings (case-insensitive, colour tags stripped).
    withWidget(net.runelite.api.widgets.Widget w)
    Adds w to the working set; null is ignored.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • WidgetQuery

      public WidgetQuery(List<net.runelite.api.widgets.Widget> raw, net.runelite.api.Client client)
      Wraps a copy of raw. Widget reads in this class are not marshalled: build and run the chain on the client thread (the ctx.widgets hook does this for its own verbs).
  • Method Details

    • start

      public static WidgetQuery start(net.runelite.api.Client client)
      Empty query — add widgets with root(int), withWidget(Widget), or use Widgets.queryAt(int).
    • fromPacked

      public static WidgetQuery fromPacked(net.runelite.api.Client client, int packedId)
      Single root via inspector-style lookup.
    • root

      public WidgetQuery root(int packedId)
      Add a widget resolved from an inspector packed id (group.child).
    • roots

      public WidgetQuery roots()
      Adds all current top-level widget roots. Use with expandDescendants(int) when querying globally for visible text or actions.
    • withWidget

      public WidgetQuery withWidget(net.runelite.api.widgets.Widget w)
      Adds w to the working set; null is ignored.
    • visible

      public WidgetQuery visible()
      Keeps widgets that are not hidden (Widget.isHidden()).

      On Impact, Elorin and SpawnPK a closed interface's widgets can still report not-hidden, so "visible" here does not prove the interface is drawn; prefer the hook's open/drawn checks.

    • withText

      public WidgetQuery withText(String... texts)
      Keeps widgets whose Widget.getText() or Widget.getName() contains any of the given substrings (case-insensitive, colour tags stripped).

      Usage: widgets.queryAt(219_01).withText("Give me a task").first()

    • withExactText

      public WidgetQuery withExactText(String... texts)
      Keeps widgets whose normalized Widget.getText() or Widget.getName() exactly matches any requested value (case-insensitive, colour tags stripped).
    • withNonEmptyName

      public WidgetQuery withNonEmptyName()
      Non-blank Widget.getName() or meaningful text after stripping colour tags (the same normalisation the dialogue hook uses). Does not use Widget.getItemId() — empty name with a stale item id still fails (e.g. CoX reward line after the label clears).
    • withItemOrName

      public WidgetQuery withItemOrName()
      Inventory-style slot: withNonEmptyName() logic or positive Widget.getItemId() when the client omits the label but sets an item.
    • expandImmediateChildren

      public WidgetQuery expandImmediateChildren()
      For each current widget, appends all immediate children (same child discovery as the dialogue hook's tree walks: dynamic, static, nested, and Widget.getChildren()), preserving order and deduplicating by identity.
    • expandDescendants

      public WidgetQuery expandDescendants(int maxRounds)
      Repeats expandImmediateChildren() maxRounds times, accumulating all widgets up to that many levels below the current set (deduplicated by identity).
    • withAction

      public WidgetQuery withAction(String... options)
      Keeps widgets whose Widget.getActions() list matches any of the given options (normalized text, same rules as component menu interaction: exact normalized match or substring contains).
    • filter

      public WidgetQuery filter(Predicate<net.runelite.api.widgets.Widget> predicate)
      Narrows this query in place and returns it. Queries are mutable and single-use; the predicate runs on the calling thread. A null predicate is ignored.
    • where

      public WidgetQuery where(Predicate<net.runelite.api.widgets.Widget> predicate)
    • first

      public net.runelite.api.widgets.Widget first()
      The first remaining widget, or null when the query is empty.
    • first

      public net.runelite.api.widgets.Widget first(Predicate<net.runelite.api.widgets.Widget> predicate)
      Narrows by predicate (in place) and returns the first match, or null.
    • list

      public List<net.runelite.api.widgets.Widget> list()
      An unmodifiable view of the remaining widgets.
    • empty

      public boolean empty()
      True when no widget is left.
    • size

      public int size()
      The number of widgets left.