Package io.github.jspinak.brobot.core.location

Interface ElementLocator

All Known Implementing Classes:
VisualElementLocator
public interface ElementLocator
Core interface for element location operations.

This interface defines the contract for locating GUI elements on screen, orchestrating pattern matching and screen capture operations. It sits at a higher level than PatternMatcher but lower than Find/Actions, providing element location services without any circular dependencies.

ElementLocator is the key abstraction that breaks the circular dependency between Find and other actions. Actions that need to find elements use ElementLocator directly instead of depending on Find.

Key design principles:

  • Depends ONLY on core services (PatternMatcher, ScreenCaptureService)
  • NO dependencies on Find or any Action classes
  • Provides element location without action semantics
  • Thread-safe and stateless
Since:
2.0.0

  • Method Details

    • locate

      List<ElementLocator.Element> locate(ElementLocator.LocateRequest request)
      Locates elements on screen based on the request parameters.

      This is the main method that orchestrates screen capture and pattern matching to locate GUI elements. The behavior is controlled by the FindStrategy in the request.

      Parameters:
      request - The location request containing patterns and parameters
      Returns:
      List of found elements, empty if none found

    • locateInRegion

      List<ElementLocator.Element> locateInRegion(ElementLocator.LocateRequest request, Region region)
      Locates elements within a specific region.

      This method optimizes the search by limiting it to a specific screen region, improving performance for targeted searches.

      Parameters:
      request - The location request containing patterns and parameters
      region - The screen region to search within
      Returns:
      List of found elements within the region, empty if none found

    • verifyElement

      boolean verifyElement(ElementLocator.Element element)
      Checks if an element is still present at its last known location.

      This method performs a quick verification to see if an element is still visible at the same location, useful for wait operations.

      Parameters:
      element - The element to verify
      Returns:
      true if the element is still present, false otherwise

    • waitForElement

      List<ElementLocator.Element> waitForElement(ElementLocator.LocateRequest request, double timeoutSeconds)
      Waits for an element to appear on screen.

      This method repeatedly searches for elements until found or timeout is reached.

      Parameters:
      request - The location request
      timeoutSeconds - Maximum time to wait
      Returns:
      List of found elements, empty if timeout reached

    • waitForVanish

      boolean waitForVanish(ElementLocator.Element element, double timeoutSeconds)
      Waits for an element to disappear from screen.

      This method repeatedly checks if elements are still present until they disappear or timeout is reached.

      Parameters:
      element - The element to wait for disappearance
      timeoutSeconds - Maximum time to wait
      Returns:
      true if element disappeared, false if timeout reached

    • getImplementationName

      String getImplementationName()
      Gets the name of this element locator implementation.
      Returns:
      Implementation name for logging/debugging