<!DOCTYPE doctype PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<HTML>
  <HEAD>
    <META name="generator" content=
    "HTML Tidy for Java (vers. 2009-12-01), see jtidy.sourceforge.net">

    <TITLE>Ghidra Tree Filters</TITLE>
    <META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    <LINK rel="stylesheet" type="text/css" href="../../shared/Frontpage.css">
  </HEAD>

  <BODY>
    <H1><A name="Filters" id="Filters"></A>Ghidra Tree and Table Filters</H1>

    <BLOCKQUOTE>
      <P>Most trees and tables in Ghidra support filtering and have a text filter located at the
      bottom of the tree or table.   Tables also support the concept of 
      <A HREF="#Column_Filters">Column Filters</A> described below. 
      </P>
      
      <P>Below is an example from the Data Type Manager. The filter is
      currently set to "Starts With", but you can select a different filter strategy.</P>

      <CENTER>
        <IMG alt="" src="images/Filter.png" border="0">
      </CENTER>

      <P>The button to the right of the filter will bring up the <A href="#Filter_Options">Filter
      Options Dialog</A>. Its icon indicates the current <A href="#Filter_Strategy">Filter
      Strategy</A>.</P>

      <P>Ghidra will remember the filter state for each tree or table. So, when you re-launch
      Ghidra, all your trees and tables will have the filter state set as it was when you last
      exited Ghidra.</P>

      <BLOCKQUOTE>
        <P><IMG alt="" src="../../shared/note.png"> Some trees use more than the node's name for
        filter purposes. So, it may appear that the filter is matching more than it should, when
        actually it is also using some other related text for the match, such as a node
        description.</P>
      </BLOCKQUOTE>
    </BLOCKQUOTE><BR>
     <BR>
     

    <H2>Clear Filter</H2>

    <BLOCKQUOTE>
      <!--
            This HTML is a bit odd.  We are manually aligning the text with the image because the
            image contains extra whitespace that makes it appear off-center.
      -->

      <CENTER>
        <TABLE width="80%" border="0">
          <TR>
            <TD>
              <CENTER>
                <IMG alt="" src="images/FilterClearButton.png" border="0">
              </CENTER>
            </TD>
          </TR>

          <TR>
            <TD align="center"><FONT size="3"><I>The clear filter button will reset the filter when
            clicked.</I></FONT></TD>
          </TR>
        </TABLE>
      </CENTER>
    </BLOCKQUOTE><BR>
     <BR>
     

    <H2>The Filter Options Dialog<A name="Filter_Options" id="Filter_Options"></A></H2>

    <BLOCKQUOTE>
      <P>The Filter Options Dialog is used to control how the text in the filter text field is used
      to perform filtering on the tree or table.</P>

      <CENTER>
        <IMG alt="" src="images/FilterOptions.png" border="0">
      </CENTER>

      <H3>Filter Strategy<A name="Filter_Strategy" id="Filter_Strategy"></A></H3>

      <BLOCKQUOTE>
        <P>The filter strategy specifies how the text in the filter text field will be used to
        match against the nodes in a tree or the rows in a table.</P>

        <TABLE>
          <TR>
            <TD valign="top"><IMG alt="" src="images/page_code.png" border="0"></TD>

            <TD valign="top">Contains</TD>

            <TD>
              Tree nodes will match if its name contains the text in the filter text field. Table
              rows will match if any of the columns contains the filter text. 

              <BLOCKQUOTE>
                <BR>
                 <IMG alt="" src="../../shared/note.yellow.png"> Multiple words in the text field
                are treated as separate patterns and <B>ALL</B> patterns must match for the node or
                row to be accepted. For example, if the text field contained "foo bar", then the
                table will match if at least one column contains a "foo" and at least one column
                contains a "bar".
              </BLOCKQUOTE>
            </TD>
          </TR>

          <TR>
            <TD valign="top"><IMG alt="" src="images/page_go.png" border="0"></TD>

            <TD nowrap valign="top">Starts With</TD>

            <TD>Tree nodes will match if its name starts with the text in the filter text field.
            Table rows will match if any of the columns starts with the filter text.</TD>
          </TR>

          <TR>
            <TD valign="top"><IMG alt="" src="images/page_green.png" border="0"></TD>

            <TD nowrap valign="top">Matches Exactly</TD>

            <TD>Tree nodes will match if its name exactly matches the text in the filter text
            field.Table rows will match if any of the columns exactly match the filter text.</TD>
          </TR>

          <TR>
            <TD valign="top"><IMG alt="" src="images/page_excel.png" border="0"></TD>

            <TD nowrap valign="top">Regular Expression</TD>

            <TD>Tree nodes will match if the regular expression in the filter matches the name of
            the node. Table rows will match if any of the columns matches the regular expression.
            See <A href="help/topics/Search/Regular_Expressions.htm#Regex_Syntax">regular
            expression</A> for help. Note that the regular expression will match if the pattern it
            represents is <B>contained</B> in the tree node name or table column. If you want to
            match the beginning or end (i.e starts with or ends with), you must include the special
            "starts with" (^) or "ends with" ($) regular expression character syntax. For example,
            the regular expression "bob" will match "bobby", "hey bobby", and "bob", but the
            regular expression "^bob" will match "bobby" and "bob", and "^bob$" will only match
            "bob".</TD>
          </TR>
        </TABLE>
      </BLOCKQUOTE>

      <H3>Case Sensitive</H3>

      <BLOCKQUOTE>
        <P>Selecting the case sensitive checkbox will cause the filter to be case sensitive when
        matching the text in the filter text field against the nodes or table rows. NOTE: This
        option has no effect when the "Regular Expression" strategy is selected.</P>
      </BLOCKQUOTE>

      <H3>Allow Globbing</H3>

      <BLOCKQUOTE>
        <P>Selecting the allow globbing checkbox will cause the filter to interpret the globbing
        chars "*" and "?" as wildcards. The "*" char will match any number of characters while the
        "?" character will match a single character. For example "ab*g" will match "abxg" and
        "abxxg" and so on. The text "ab?g" will match "abxg" but not "abxxg". NOTE: This option has
        no effect when the "Regular Expression" strategy is selected.</P>
      </BLOCKQUOTE>

      <H3>Invert Filter</H3>

      <BLOCKQUOTE>
        <P>Selecting the inverted checkbox will cause the filter to only include those tree nodes
        or table rows that <B>DO NOT</B> meet the filter text criteria. In other words, "contains"
        becomes "does not contain". This negation happens after all other filtering tests have been
        performed, including multi-term matching.</P>
      </BLOCKQUOTE>

      <H3>Enable Multi-Term Filtering<A name="Multiple_Terms" id="Multiple_Terms"></A></H3>

      <BLOCKQUOTE>
        <P>Often it is useful to filter the contents of a tree or table according to multiple
        terms. The options here specify how a more complex filter expression is interpreted and
        evaluated. If the text is split, the Filter Strategy and associated options -- case
        sensitivity, globbing, and inversion -- are applied to each term.</P>

        <P><IMG alt="" src="../../shared/note.png"> When 'Regular Expression' is selected as the
        filter strategy, these options are disabled. Regular expressions are flexible enough to
        match multiple terms and may contain many of the characters otherwise used for convenient
        text splitting.</P>
      </BLOCKQUOTE>

      <H3>Delimiter<A name="Spliting_Strategy" id="Spliting_Strategy"></A></H3>

      <BLOCKQUOTE>
        <P>How terms are split apart is governed by two significant factors -- user preference, and
        the data being processed. If the data in the tree or table contains spaces and commas,
        these could make poor choices for separating filter terms -- the semicolon or pipe would
        likely be more appropriate choices.</P>

        <P>Ghidra defaults to a comma separator for multiple terms; you may select a different
        delimiter character from the following:<BR>
        </P>

        <P style="border:1px; border-style:solid; border-color:#CCCCCC; background-color:#EEEEEE">
        [space] ~ ` ! @ # $ % ^ &amp; * - _ + = | : ; , .</P>

        <P>Whitespace preceding and trailing the delimiter is automatically removed.</P>

        <P>In situations were the delimiter appears in your filter term, wrap the term in
        double-quotes to protect the expression. For example, '<CODE>bob | "cat | dog" |
        jane</CODE>' will be split (assume the '<CODE>|</CODE>' delimiter) into three terms --
        <CODE>bob</CODE>, <CODE>cat | dog</CODE>, and <CODE>jane</CODE>. (Note that both the
        delimiter character and the spaces in the '<CODE>cat | dog</CODE>' term persists; the
        entire quoted string was parsed as a string literal.) Typically, this situation can be
        avoided by selecting a more appropriate delimiter that doesn't collide with values in the
        tree or table row.</P>
      </BLOCKQUOTE>

      <H3>Evaluation Mode<A name="Evaluation_Mode" id="Evaluation_Mode"></A></H3>

      <BLOCKQUOTE>
        <P>When filtering multiple terms, it may be useful to specify a higher-level acceptance
        model. The Filter Evaluation Mode specification allows a user to specify how the multiple
        filters are combined into a more robust expression. Most frequently, you'll likely be
        looking for data that matches "X or Y" -- select '<CODE>OR</CODE>' in this case, and enter
        values X and Y according to the current splitting strategy ("X Y", "X;Y", "X|Y", etc.).
        Again, the evaluation for whether a piece of data matches X or Y is determined by the <A
        href="#Filter_Strategy">Filter Strategy</A>.<BR>
         However, if you're looking for data that matches all the terms of your filter, select the
        '<CODE>AND</CODE>' evaluation mode. Each filter for values X and Y must accept the data for
        overall acceptance by the filter.</P>

        <BLOCKQUOTE>
          <P><IMG alt="" src="../../shared/note.yellow.png"> Using delimiters that otherwise have a
          logical definition -- '<CODE>+</CODE>', or '<CODE>|</CODE>', for example -- have
          <I>no</I> semantic value in this application; they are simply tokens for input string
          processing.</P>
        </BLOCKQUOTE>
      </BLOCKQUOTE>

      <H3>Multi-Term Filter Examples</H3>

      <BLOCKQUOTE>
        <P>Consider the view where the files in the current project are presented in your choice of
        a tree or a table. Suppose there are minimally these two files:</P>

        <UL>
          <LI>'foo.dll', compiled by GCC on January 21st, and 'foo_new.dll',</LI>

          <LI>compiled by Visual Studio on January 21st.</LI>
        </UL>

        <P>The filter</P>

        <BLOCKQUOTE>
          <P><CODE>dll, january, gcc</CODE> (split on comma using the '<CODE>OR</CODE>' evaluation
          mode),</P>
        </BLOCKQUOTE>

        <P>will select both files. (In actuality, it will accept <I>any</I> file with 'dll',
        'january', or 'gcc' in it's set of filter-aware data.)</P>

        <P>Switching the evaluation mode to '<CODE>AND</CODE>' will select only 'foo.dll', as it is
        the only record that satisfies all three conditions (similar to the '<CODE>OR</CODE>'
        discussion, only files satisfying all three properties will be selected).</P>
      </BLOCKQUOTE>
    </BLOCKQUOTE>

    <P><BR>
    <BR>
    </P>
    <A name="Column_Filters"></A> 

    <H2>Ghidra Table Column Filters</H2>

    <BLOCKQUOTE>
      <P>Most filterable tables in Ghidra support advanced filtering based on column values. This
      allows for complex filtering where you can logically combine column specific clauses.</P>
      
      
      <BLOCKQUOTE>
	      <P><IMG src="../../shared/warning.png">
	      Some columns in tables are not filterable via the filter text field below the table.
	      For example, many numeric columns are ignored by the text filter because they can be 
	      slow to calculate and they are better filtered by using a range filter, as is available
	      using column filters.
	      </p>
       </BLOCKQUOTE>
      
      <BR>
       

      <CENTER>
        <IMG alt="" src="images/TableColumnFilter.png" border="0">
      </CENTER><BR>
       

      <P>The <IMG alt="" src="images/view-filter.png"> button in lower right corner will bring up
      the Column Filter Dialog.</P>
      <BR>
      <BR>
       

      <CENTER>
        <IMG alt="" src="images/TableColumnFilterDialog.png" border="1">
      </CENTER><BR>
       

      <BLOCKQUOTE>
        <P style="margin-left: 30%; margin-right: 30%;">This dialog describes a filter that will
        narrow the list of functions to those whose <I>name starts with "FUN_00" or contains
        "401"</I> <B>and</B> <I>the Function Size is at least 80</I>.</P>
      </BLOCKQUOTE><BR>
       

      <H3>Filters Panel</H3>

      <BLOCKQUOTE>
        <P>The main panel of the dialog consists of a series of column filters (each in its own
        row). Each column filter consists of a series of constraints for that column. Within a
        column, only one of the constraints for that column must pass (i.e., they are or'd
        together), but each column filter must pass (i.e. they are and'ed together) for the table
        row to pass the filter.</P>

        <P>The sections of each filter row are as follows:</P>

        <UL>
          <LI><B>Table Column</B> - Combo box for choosing the column to filter (they are listed in
          the order of the table). For additional OR conditions on the same column, this column
          will just have a "&lt;OR&gt;" label.</LI>

          <LI><B>Filter</B> - Combo box for choosing the constraint condition. For string types,
          this would include such items as "starts with", "ends with" and "contains".</LI>

          <LI><B>Filter Value</B> - Editor component for entering the condition value to compare
          against. This component will change depending on the column type.</LI>
        </UL>
      </BLOCKQUOTE>

      <H3>Actions</H3>

      <BLOCKQUOTE>
        <P>Panel Actions:</P>

        <UL>
          <LI><B>Add a new AND column filter</B> - The "<IMG alt="" src="images/Plus.png"> Add AND
          condition" button in the bottom right will add a new column filter that will be "ANDed"
          to any previous conditions. It will default to the first column with a default constraint
          applicable for that columns type.</LI>

          <LI><B>Add a new OR column filter</B> - The "<IMG alt="" src="images/Plus.png"> Add OR
          condition" button in the bottom right will add a new column filter that will be "ORed"
          with any previous conditions. It will default to the first column with a default
          constraint applicable for that columns type. Note that AND conditions have higher
          precedence than OR conditions.</LI>

          <LI><B>Add an additional constraint to a column filter</B> - The <IMG alt="" src=
          "images/Plus.png"> button all the way on the right of the column filter will add an
          additional constraint condition.</LI>

          <LI><B>Delete a column condition</B> - The <IMG alt="" src="Icons.DELETE_ICON">
          button at the end of a condition will delete that condition. If that condition was the
          last condition in a column filter, the column filter will be deleted.</LI>
        </UL>

        <P>Toolbar actions</P>

        <UL>

          <LI><A name="Save_Filter"></A><B>Save Filter <IMG alt="" src="images/disk.png"></B> - Saves the current dialog
          configuration to the tool. A dialog will appear that will allow you to name the
          filter</LI>

  
          <LI><A name="Load_Filter"></A><B>Load Filter <IMG alt="" src="Icons.OPEN_FOLDER_ICON"></B> - Pops up a dialog with
          a list of saved filters. Selecting one will load that filter into the dialog.</LI>
        </UL>

        <P>Dialog actions</P>

        <UL>
  
          <LI><A name="Apply_Button"></A><B>Apply</B> - Applies the dialog's filter to the table. Only enabled if all the
          conditions in the dialog are valid.</LI>

          <LI><A name="Dismiss_Button"></A><B>Dismiss</B> - Closes the filter dialog. Any currently applied filter remains in
          effect.</LI>

          <LI><A name="Clear_Filter_Button"></A><B>Clear Filter</B> - Removes any currently applied column filter from the table and
          resets the dialog to its initial state.</LI>
        </UL>
      </BLOCKQUOTE>

      <H3>Constraint Types</H3>

      <BLOCKQUOTE>
        <P>The column constraints (conditions) for a given column depend on the type of the data in
        that column. If the type of the column data is one that has at least one constraint
        defined, then that column is filterable; otherwise it will not appear in the column combo
        box. Some of the supported column types and their associated constraints are:</P>

        <H4>String</H4>

        <UL>
          <LI><B>Starts With</B> - Matches if the column value starts with a given string.</LI>

          <LI><B>Ends With</B> - Matches if the column value ends with a given string.</LI>

          <LI><B>Contains</B> - Matches if the column value contains a given string.</LI>

          <LI><B>Matches RegEx</B> - Matches if the column value matches a given regular
          expression.</LI>
        </UL>

        <H4>Byte, Short, Integer, Long, Float, Double</H4>

        <UL>
          <LI><B>At Most</B> - Matches if the column value is less than or equal to a given
          value.</LI>

          <LI><B>At Least</B> - Matches if the column value is greater than or equal to a given
          value.</LI>

          <LI><B>In Range</B> - Matches if the column value is in a given range.</LI>

          <LI><B>Not In Range</B> - Matches if the column value is not in a given range.</LI>
        </UL>

        <H4>Date</H4>

        <UL>
          <LI><B>On or After</B> - Matches if the column value date is newer than a given
          date.</LI>

          <LI><B>On or Before</B> - Matches if the column value date is older than a given
          date.</LI>

          <LI><B>Between Dates</B> - Matches if the column value date is in the given date
          range.</LI>

          <LI><B>Not Between Dates</B> - Matches if the column value date is not in the given date
          range.</LI>
        </UL>

        <H4>Boolean</H4>

        <UL>
          <LI><B>Matches</B> - Matches if the column boolean value is the same as the given boolean
          value.</LI>
        </UL>

        <H4>Enum (any enum type)</H4>

        <UL>
          <LI><B>Is One Of</B> - Matches if the column enum value is one of a given set of enum
          values.</LI>
        </UL>
      </BLOCKQUOTE>

      <H3>Filter Results</H3>

      <BLOCKQUOTE>
        <P>After applying the the filter show above, the table would appear as follows:</P>
        <BR>
         

        <CENTER>
          <IMG alt="" src="images/TableColumnFilterAfterFilterApplied.png" border="0">
        </CENTER><BR>
         

        <P>Notice that the headers for both the <B>Label</B> and <B>Function Size</B> columns have
        the <IMG alt="" src="images/view-filter.png"> icon. This indicates that there is an applied
        column based filter and those columns are the ones whose values are affected by the
        filter.</P>
      </BLOCKQUOTE>
    </BLOCKQUOTE>
    
    
      <!-- extra space at the bottom of the page (for readability) -->
  <br>
  <br>
  <br>
  <br>
  
      <P class="relatedtopic">Related Topics</P>

    <UL>
      <LI><A href="help/topics/Tables/GhidraTableHeaders.html">Table Sorting</A></LI>
    </UL>
  
    
  </BODY>
</HTML>
