<?xml version="1.0" encoding="UTF-8"?>
<chapter id="details.search">
<chapterinfo>
  <authorgroup>
    <author> &Darin.Strait; &Darin.Strait.mail; </author>
    <author> &Jack.H.Ostroff; &Jack.H.Ostroff.mail; </author>
  </authorgroup>
  <date>2024-12-01</date>
  <releaseinfo>5.2.0</releaseinfo>
</chapterinfo>
<title>Search Transactions</title>

<para>
  You can use the <guilabel>Search transactions</guilabel> dialog to search your data
  for transactions based on criteria that you specify.  You can access the dialog by
  selecting the <menuchoice> <guimenu>Edit</guimenu> <guimenuitem>Find
  transaction...</guimenuitem></menuchoice> menu item, or typing <keycombo
  action="simul">&Ctrl; &Shift;<keycap>F</keycap></keycombo>.
</para>

<para>
  There are two main tabs in this dialog. The <guilabel>Criteria</guilabel> tab
  displays a number of subtabs for specifying the search criteria.  When the
  <guibutton>Find</guibutton> button is pressed, the search is initiated and all
  criteria that have been entered on any of the Criteria subtabs will be taken into
  account.
</para>

<para>
  After the search has completed, the results will be displayed under the
  <guilabel>Result</guilabel> tab.  Below the list of results, &kmymoney; shows the
  number of transactions that met the search criteria.  Double-clicking an individual
  transaction in the result list will bring up the appropriate ledger with that
  transaction selected.
</para>

<para>
 The <guibutton>Reset</guibutton> button resets all of the fields on all of the
 criteria subtabs back to the defaults. This allows you to specify new search
 criteria.
</para>

<para>
  The <guibutton>Close</guibutton> button closes the <guilabel>Search
  Transactions</guilabel> dialog box.
</para>

<sect1 id="details.search.criteria"><title>Search Criteria</title>
<para>
  There are several subtabs under the main Criteria tab, each of which allows you to
  specify a different type of search criteria.  Below the area for specifying the
  criteria, &kmymoney; lists each of the different types of criteria that are
  currently specified for the search.
</para>

<sect2 id="details.search.text"><title>Text</title>
<screenshot>
  <screeninfo>search transactions, criteria tab, text subtab</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="find-text.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>search transactions, criteria tab, text subtab</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<para>
  This tab allows you to specify text to search for.  There are also a dropdown
  field and two check boxes that control how the text is used in the search.
</para>

<para>
  By default, the search will match on simple substrings. For example:
</para>

<para>
<itemizedlist>
  <listitem>
    <para><quote>Best</quote> will find <quote>Best Cakes, Inc.</quote></para>
  </listitem>
  <listitem>
    <para>
      <quote>est</quote> will also find <quote>Best Cakes, Inc.</quote>
    </para>
  </listitem>
</itemizedlist>
</para>

<para>
  In the dropdown field next to the text field, select <guilabel>Contains</guilabel>
  if you want to find transactions that contain the text, or select <guilabel>Does
  not contain</guilabel> if you want to find transactions that do not contain the
  specified text.
</para>

<para>
  If you check the <guilabel>Case Sensitive</guilabel> box, the search will be
  case sensitive.  For example, <quote>best</quote> would not find <quote>Best
  Cakes, Inc.</quote> if this option is set.
</para>

<para>
  If you check the <guilabel>Treat Text as regular expression</guilabel> box, the
  text will be treated as a regular expression.  For details on how to craft a
  regular expression, visit the &Qt; documentation about the <ulink
  url="https://doc.qt.io/qt-5/qregularexpression.html">QRegularExpression
  class</ulink>.
</para>
</sect2>

<sect2 id="details.search.account"><title>Account</title>
<screenshot>
  <screeninfo>search transactions, criteria tab, account subtab</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="find-account.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>search transactions, criteria tab, account subtab</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<para>
  This tab allows you to specify the accounts that should be searched.
</para>

<para>
  Accounts are displayed in a tree format.  Accounts that are marked for search are
  indicated with a checkbox.  If you click <guibutton>All</guibutton>, all accounts
  are marked for searching.  If you click <guibutton>None</guibutton>.  no accounts
  will be marked for searching.  Individual accounts can be marked or unmarked by
  clicking the box next to the account name using the &LMB;.  A complete hierarchy
  of accounts can be marked or unmarked by clicking the box using the &RMB;.
</para>
</sect2>

<sect2 id="details.search.date"><title>Date</title>
<screenshot>
  <screeninfo>search transactions, criteria tab, date subtab</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="find-date.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>search transactions, criteria tab, date subtab</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<para>
  This tab allows you to specify which dates should be searched.  The date refers to
  the post date of the transaction.
</para>

<para>
  The <quote>Range</quote> dropdown provides a convenient way to set the From and To
  date controls.  The From and To controls can be manipulated individually.  Dates
  can be entered manually, and clicking the down arrow at the right of the field will
  bring up a typical calendar widget to select the date.  The controls will prevent
  you from entering non-existing dates.  Date values can also be changed by clicking
  the up and down arrows while the cursor in within a particular part of a date.
</para>
</sect2>


<sect2 id="details.search.amount"><title>Amount</title>
<screenshot>
  <screeninfo>search transactions, criteria tab, amount subtab</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="find-amount.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>search transactions, criteria tab, amount subtab</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<para>
  This tab allows you to specify what amounts should be searched for.
</para>

<para>
  You can search for an exact amount or for a range of amounts.  If you click the
  calculator icon, a small on-screen calculator will pop up to assist you in entering
  a value.
</para>
</sect2>

<sect2 id="details.search.category"><title>Category</title>
<screenshot>
  <screeninfo>search transactions, criteria tab, category subtab</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="find-category.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>search transactions, criteria tab, category subtab</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<para>
  This tab allows you to specify which categories should be searched.
</para>

<para>
  Categories are displayed in a tree format, similar to Accounts.  Categories that
  are marked for search are indicated with a checkbox. If you click
  <guibutton>All</guibutton>, all categories are marked for searching.  If you click
  <guibutton>Income</guibutton>, all income categories will be marked and all expense
  categories will be unmarked.  If you click <guibutton>Expense</guibutton>, all
  income categories will be unmarked and all expense categories will be marked.  If
  you click <guibutton>None</guibutton>, no categories will be marked for searching.
</para>

<para>
  Individual categories can be marked or unmarked by clicking the checkbox next to
  the category name using the &LMB;.  A complete hierarchy of categories can be
  marked or unmarked by clicking the box using the &RMB;.
</para>
</sect2>

<sect2 id="details.search.tag"><title>Tag</title>
<screenshot>
  <screeninfo>search transactions, criteria tab, tag subtab</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="find-tag.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>search transactions, criteria tab, tag subtab</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<para>
  This tab allows you to specify which tags should be searched.
</para>

<para>
  Tags that are marked for search are indicated with a checked box.  If you click
  <guibutton>Select all</guibutton>, all tags are marked for searching. If you click
  <guibutton>Select none</guibutton>, no tags will be marked for searching.
  Individual tags can be marked or unmarked by clicking the checkbox next to the
  payee name.
</para>

<para>
  If you check the <guilabel>Select transactions without tags</guilabel> box, only
  transactions with no tag will be selected.
</para>
</sect2>

<sect2 id="details.search.payee"><title>Payee</title>
<screenshot>
  <screeninfo>search transactions, criteria tab, payee subtab</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="find-payee.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>search transactions, criteria tab, payee subtab</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<para>
  This tab allows you to specify which payees should be searched.
</para>

<para>
  Payees that are marked for search are indicated with a box.  If you click
  <guibutton>Select all</guibutton>, all payees are marked for searching.  If you
  click <guibutton>Select none</guibutton>, no payees will be marked for searching.
  Individual payees can be marked or unmarked by clicking the box next to the payee
  name.
</para>

<para>
  If you check the <guilabel>Select transactions without payees</guilabel> box,
  only transactions with no payee will be selected.
</para>
</sect2>

<sect2 id="details.search.details"><title>Details</title>
<screenshot>
  <screeninfo>search transactions, criteria tab, details subtab</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="find-details.png" format="PNG" />
    </imageobject>
    <textobject>
      <phrase>Search transactions Dialog, Details tab</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<para>
  This tab allows you to specify various additional search criteria.
</para>

<para>
  <itemizedlist>
    <title>Type can be one of the following:</title>
    <listitem><para>All Types</para></listitem>
    <listitem><para>Payments</para></listitem>
    <listitem><para>Deposits</para></listitem>
    <listitem><para>Transfers</para></listitem>
  </itemizedlist>

  <itemizedlist>
    <title>State can be one of the following:</title>
    <listitem><para>All states</para></listitem>
    <listitem><para>Not reconciled</para></listitem>
    <listitem><para>Cleared</para></listitem>
    <listitem><para>Reconciled</para></listitem>
  </itemizedlist>

  <itemizedlist>
    <title>Validity can be one of the following:</title>
    <listitem><para>Any transaction</para></listitem>
    <listitem><para>Valid transaction</para></listitem>
    <listitem><para>Invalid transaction</para></listitem>
  </itemizedlist>
</para>

<para>
  You can search for a particular transaction number or search for a range of
  transaction numbers.
</para>
</sect2>
</sect1>

<sect1 id="details.search.results"><title>Search results</title>
<para>
  The <guilabel>Result</guilabel> tab displays the Entry (entry date, optional,) Date
  (posting date,) Account, Payee, Details (memo,) C (reconciliation status,)
  Decrease, and Increase for each transaction that matches the search criteria you
  have entered.  Clicking the &RMB; on the header row of the results list allows you
  to toggle the display of the optional columns.
</para>

<para>
  Double-clicking a transaction will display the corresponding account ledger with
  that transaction selected.
</para>
</sect1>
</chapter>
