src/jalview/api/FinderI.java

   1 package jalview.api;
   2
   3 import jalview.datamodel.SearchResultsI;
   4 import jalview.datamodel.SequenceI;
   5
   6 import java.util.List;
   7
   8 /**
   9  * An interface for searching for a pattern in an aligment
  10  */
  11 public interface FinderI
  12 {
  13
  14   /**
  15    * Performs a find for the given search string (interpreted as a regular
  16    * expression). Search may optionally be case-sensitive, and may optionally
  17    * including match in sequence description (sequence id is always searched). If
  18    * the viewport has an active selection, then the find is restricted to the
  19    * selection region. Sequences matched by id or description can be retrieved by
  20    * getIdMatches(), and matched residue patterns by getSearchResults().
  21    * <p>
  22    * If {@code ignoreHidden} is true, then any residues in hidden columns are
  23    * ignored (skipped) when matching, so for example pattern {@code KRT} would
  24    * match sequence {@code KRqmT} (where {@code qm} are in hidden columns).
  25    * <p>
  26    * Matches of entirely hidden patterns are not returned. Matches that span
  27    * hidden regions on one or both sides may be returned.
  28    *
  29    * @param theSearchString
  30    * @param caseSensitive
  31    * @param searchDescription
  32    * @param ignoreHidden
  33    * @return
  34    */
  35   void findAll(String theSearchString, boolean caseSensitive,
  36           boolean searchDescription, boolean ignoreHidden);
  37
  38   /**
  39    * Finds the next match for the given search string (interpreted as a regular
  40    * expression), starting from the position after the last match found. Search
  41    * may optionally be case-sensitive, and may optionally including match in
  42    * sequence description (sequence id is always searched). If the viewport has an
  43    * active selection, then the find is restricted to the selection region.
  44    * Sequences matched by id or description can be retrieved by getIdMatches(),
  45    * and matched residue patterns by getSearchResults().
  46    * <p>
  47    * If {@code ignoreHidden} is true, any hidden residues are skipped (matches may
  48    * span them). If false, they are included for matching purposes. In either
  49    * cases, entirely hidden matches are not returned.
  50    *
  51    * @param theSearchString
  52    * @param caseSensitive
  53    * @param searchDescription
  54    * @param ignoreHidden
  55    * @return
  56    */
  57   void findNext(String theSearchString, boolean caseSensitive,
  58           boolean searchDescription, boolean ignoreHidden);
  59
  60   /**
  61    * Returns the (possibly empty) list of sequences matched on sequence name or
  62    * description
  63    *
  64    * @return
  65    */
  66   List<SequenceI> getIdMatches();
  67
  68   /**
  69    * Answers the search results (possibly empty) from the last search
  70    *
  71    * @return
  72    */
  73   SearchResultsI getSearchResults();
  74
  75 }