<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="reference.widgets">
<sect1info>
  <authorgroup>
    <author> &Thomas.Baumgart; &Thomas.Baumgart.mail; </author>
  </authorgroup>
  <date>2010-07-25</date>
  <releaseinfo>4.5</releaseinfo>
</sect1info>

<title>Widgets</title>

<para>
  &kappname; has some specific widgets not found in other applications. The
  usage of these widgets is explained in this chapter.
</para>

<sect2 id="reference.widgets.datepicker">
<title>Date entry widget</title>

<para>
  Whenever &kappname; needs information about a specific date, &eg;, the posting
  date of a transaction or the opening date of an account, it offers the user
  the <emphasis>date entry widget</emphasis>. This widget consists of three
  fields and a button. The fields present the <emphasis>day</emphasis>, the
  <emphasis>month</emphasis>, and the <emphasis>year</emphasis>, separated by
  the date separator characters specified by your locale settings. The button -
  if pressed - opens the <emphasis>datepicker</emphasis> widget.
</para>

<para>
<screenshot>
	<screeninfo>Tip of the Day</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="date_widget.png" format="PNG" />
	</imageobject>
	<textobject>
	<phrase>Date widget</phrase>
	</textobject>
	</mediaobject>
</screenshot>
</para>

<para>
  Within the date entry widget, the left/right cursor keys can be used to switch
  between the <emphasis>day</emphasis>, the <emphasis>month</emphasis>, and the
  <emphasis>year</emphasis> fields. Using the up/down cursor keys, the value of
  the selected field can be incremented/decremented.  The <keycap>+</keycap> and
  <keycap>-</keycap> keys can be used to increment/decrement a single day.
  Month and year boundaries are considered and incremented/decremented if
  necessary. Pressing <keycap>T</keycap> will set the date to today's date.
</para>

<para>
  The date can also be changed using the mouse. Clicking on the
  <emphasis>day</emphasis>, <emphasis>month</emphasis>, or
  <emphasis>year</emphasis> field selects the field. The value can then be
  incremented/decremented using the arrow buttons on the right of the
  widget. They act exactly the same as the up/down key.
</para>

<para>
  The datepicker opens when the button to the right of the arrow buttons is
  pressed. It shows four arrow buttons at the top, two on each side of the
  currently selected month name and year. The leftmost buttons are used to
  decrement the year and the month; the buttons to the right of the year are
  used to increment the month and the year. The button to the very right closes
  the datepicker.
</para>

<para>
  Beneath the buttons, the widget presents a calendar page for the selected 
  month. Clicking a day on the calendar selects that date, closes the
  datepicker, and transfers the selected date into the <emphasis>day</emphasis>,
  <emphasis>month</emphasis>, and <emphasis>year</emphasis> fields.
</para>

<para>
  At the bottom of the datepicker widget, there are a button, a text edit field,
  and a combo box. Pressing the button selects today's date in the
  datepicker. The text field can be used to enter a specific date. Pressing the
  <keycap>RETURN</keycap> key shows that date in the datepicker widget.  The
  combo box allows the user to select a specific week, and continue to pick a
  date from there.
</para>
</sect2>

<sect2 id="reference.widgets.value">
<title>Value entry</title>
<para>
  The value entry widget consists of a text field (that accepts digits,
  thousands separators, and decimal symbols) as well as a button to the
  right. Use the digits to enter the value. Separate the fractional part by
  entering the decimal separator for your locale. If you click on the button to
  the right or press a key representing a numeric operation (&eg;, +,-,/,* or %)
  a little calculator will pop up and allow you to calculate the final value.
</para>

<para>
  Negative values can be entered by preceding the value with a minus sign. In
  case your locale is set to display negative numbers with parentheses around
  the value, the value can also be enclosed in parenthesis in the value entry
  widget.
</para>

<para>
<screenshot>
	<screeninfo>Tip of the Day</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="value_widget.png" format="PNG" />
	</imageobject>
	<textobject>
	<phrase>Value widget</phrase>
	</textobject>
	</mediaobject>
</screenshot>
</para>

<para>
  Use the calculator widget just like a normal calculator and once done leave
  it by clicking on the '=' button or press the '=' key on your keyboard.
</para>
</sect2>

<sect2 id="reference.widgets.payee">
<title>Payee/Payer entry</title>

<para>
  When you are requested to enter a payee/payer for a transaction, you can start
  entering the name by pressing keys on your keyboard.  As long as matching
  entries exist in the list of payees/payers maintained by &kappname; they will
  be presented in a box beneath or above the text entry area. Using the mouse or
  the up/down keys one can select a name from that list. Using the keyboard
  additionally requires you to select the entry by pressing the RETURN key.
</para>

<para>
<screenshot>
	<screeninfo>Tip of the Day</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="payee_widget.png" format="PNG" />
	</imageobject>
	<textobject>
	<phrase>Payee widget</phrase>
	</textobject>
	</mediaobject>
</screenshot>
</para>

<para>
  If a name is entered that is not yet known to &kappname; you will be asked if
  you want to create a new payee/payer record.  If you do not wish to do so,
  then the field will be blanked. Otherwise, the record will be created and
  added to the list.
</para>

<para>
  Once the edit field contains characters, the list only shows those payees that
  match the character sequence entered. Double-click on the arrow of the combo
  box to show all payees in the list.
</para>

</sect2>

<sect2 id="reference.widgets.category">
<title>Category/account entry</title>

<para>
  When you are requested to enter the name of a category or account, you can
  start entering the name by pressing keys on your keyboard.  As long as
  matching entries exist in the list of categories/accounts known to &kappname;
  they will be presented in a box beneath or above the text entry area. Using
  the mouse or the up/down keys one can select a name from that list. Using the
  keyboard additionally requires you to select the entry by pressing the RETURN
  key.
</para>

<para>
<screenshot>
	<screeninfo>Tip of the Day</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="category_widget.png" format="PNG" />
	</imageobject>
	<textobject>
	<phrase>Category widget</phrase>
	</textobject>
	</mediaobject>
</screenshot>
</para>

<para>
  If a name is entered that is not yet known to &kappname; you will be asked if
  you want to create a new category record.  If you do not wish to do so, then
  the field will be blanked. Otherwise, the record will be created and added to
  the list.
</para>

<para>
  Once the edit field is filled with characters, the list only shows those
  categories/accounts that match the character sequence entered. Double-click on
  the arrow of the combo box to show the complete list.
</para>

</sect2>
</sect1>