*********************************************************************************
Widgets, sockets, and interactivity
*********************************************************************************

.. index:: sockets, widgets

A widget appears as an overlay on the terminal (like
*picture-in-picture* for TVs, or dashboard widgets on the Mac). This
is an experimental feature, enabled using the ``--widget-port=-1``
option, that allows programs running in the background to display
information overlaid on the terminal. The widget is accessed by
redirecting ``stdout`` to a Bash ``tcp`` socket device whose address
is stored in the environment variable ``GTERM_SOCKET``.  For example,
the following command will run a background job to open a new terminal
in an overlay *iframe*::

    gframe -f --opacity=0.2 http://localhost:8900/local/new > $GTERM_SOCKET &

You can use the overlay terminal just like a regular terminal,
including having recursive overlays within the overlay! To delete the
widget, just close the socket connection by killing the background
job. (You can use the ``fg`` command to bring the job to the
foreground and then kill it.)

A simple example of a live feed widget is to combine ``gfeed`` with
``tail -f``::

    tail -f output.log | gfeed > $GTERM_SOCKET &

The above feed will display the new lines appended to the file ``output.log``.

Another example of widget use is to display live audience feedback on
the screen during a presentation, sort of like a "twitter feed". The
widget background job should be started before using ``greveal`` to make
a presentation::

  gchat 2> $GTERM_SOCKET 0<&2 | gfeed > $GTERM_SOCKET &
  greveal $GTERM_DIR/bin/landslide/graphterm-talk1.md | gframe -f

The first command uses ``gchat`` to capture feedback from others
viewing the terminal session as a stream of lines from
$GTERM_SOCKET. The viewers use the overlaid *chat* button
to provide feedback. The ``stdout`` from ``gchat`` is piped to
``gfeed`` which displays its ``stdin`` stream as a  "live feed"
overlay, also via $GTERM_SOCKET.

To display a live twitter feed as an overlay on a presentation, you can use the
commands::

  gtweet -w -f -s topic > $GTERM_SOCKET &
  greveal $GTERM_DIR/bin/landslide/graphterm-talk1.md | gframe -f

