.. _ui:

User Interface
==============

The **lnav** TUI displays the content of the current "view" in the middle,
with status bars above and below, and the interactive prompt as the last line.

.. figure:: lnav-ui.png
   :align: center
   :alt: Screenshot of lnav showing a mix of syslog and web access_log messages.

   Screenshot of **lnav** viewing syslog messages.

The default view shows the log messages from the log files that have been
loaded.  There are other views for displaying content like plaintext files
and SQL results.  The :ref:`ui_views` section describes the characteristics of
each view in more detail.  You can switch to the different views using the
hotkeys described in the :ref:`hotkeys_display` section or by pressing
:kbd:`ENTER` to activate the breadcrumb bar, moving to the first crumb, and
then selecting the desired view.  You can switch back to the previous view by
pressing :kbd:`q`.  You can switch forward to the new view by pressing
:kbd:`a`.  If the views are time-based (e.g. log and histogram), pressing
:kbd:`Shift` + :kbd:`q` and :kbd:`Shift` + :kbd:`a` will synchronize the top
times in the views.

The right side of the display has a proportionally sized 'scrollbar' that
shows:

* the current position in the file;
* the locations of errors/warnings in the log files by using red or yellow
  coloring;
* the locations of search hits by using a tick-mark pointing to the left;
* the locations of bookmarks by using a tick-mark pointing to the right.

Top Status Bar
--------------

The top status bar shows the current time and messages stored in the
:code:`lnav_user_notifications` table.

Below the top status bar is the breadcrumb bar that displays the semantic
location of the top line in the main view.  For example, within a
pretty-printed JSON document, it will show the path to property at the top
of the view.  The actual content of the bar depends on the current view and
will be updated as you navigate around the main view.  The bar can also be
used to navigate around the document by focusing on it.

Breadcrumb Bar
--------------

.. figure:: lnav-breadcrumbs-help.png
   :align: center
   :figwidth: 90%

   Screenshot of the breadcrumb bar focused and navigating the help text

To focus on the breadcrumb bar, press :kbd:`ENTER`.  The :kbd:`←`/:kbd:`→`
cursor keys can be used to select a crumb and the :kbd:`↑`/:kbd:`↓` keys can
be used select a value of that crumb.  To accept a value and drop focus on the
bar, press :kbd:`ENTER`.  To accept a value and move to the next crumb, press
:kbd:`→`.  Using :kbd:`→` makes it quicker to drill down into a document
without having to constantly switch focus.  To drop focus on the bar without
accepting anything, press :kbd:`Escape`.

There are three types of crumbs:

* a dropdown where one of a limited set of values can be selected;
* a combobox where a value can be entered directly or selected;
* a numeric input for entering array indexes.

When a dropdown or combobox is selected, you can type part of the desired value
to filter the list of values.  For example, the first crumb is always the
current view, typing in "hi" will filter the list down to the "HIST" value.

Configuration Panels
--------------------

After the main view content, there is a header bar for two configuration
panels: Files and Filters.  These panels provide visual access to parts of
lnav's configuration.

The Files panel is open initially to display progress in loading files.
The following information can be displayed for each file:

* the "unique" portion of the path relative to the other files;
* the amount of data that has been indexed;
* the date range of log messages contained in the file;
* the errors that were encountered while trying to index the file;
* the notes recorded for files where some automatic action was taken,
  like hiding the file if it was seen as a duplicate of another file.

If the view supports filtering, there will be a status line showing the
following:

* the number of enabled filters and the total number of filters;
* the number of lines that are **not** displayed because of filtering.

To edit the filters, you can press TAB to change the focus from the main
view to the filter editor.  The editor allows you to create, enable/disable,
and delete filters easily.

Finally, the last line on the display is where you can enter search
patterns and execute internal commands, such as converting a
unix-timestamp into a human-readable date.  The command-line is by
the readline library, so the usual set of keyboard shortcuts can
be used.

The body of the display is also used to display other content, such
as: the help file, histograms of the log messages over time, and
SQL results.  The views are organized into a stack so that any time
you activate a new view with a key press or command, the new view
is pushed onto the stack.  Pressing the same key again will pop the
view off of the stack and return you to the previous view.  Note
that you can always use 'q' to pop the top view off of the stack.

.. _ui_views:

Views
-----

LOG
^^^

The log view displays the log messages from any loaded log files in time
order.

On color displays, the log messages will be highlighted as follows:

* Errors will be colored in red;
* warnings will be yellow;
* search hits are reverse video;
* various color highlights will be applied to: IP addresses, SQL keywords,
  XML tags, file and line numbers in Java backtraces, and quoted strings;
* "identifiers" in the messages will be randomly assigned colors based on their
  content (works best on "xterm-256color" terminals).

.. note::

  If the coloring is too much for your tastes, you can change to the
  "grayscale" theme by entering the following command:

  .. code-block::  lnav

    :config /ui/theme grayscale

The breadcrumb bar will show:

* the timestamp
* the log format for the top line;
* the name of the file the top line was pulled from;
* the line number for the top line in the display;
* the current search hit, the total number of hits, and the search term;

DB
^^

HELP
^^^^

HIST
^^^^