/*! \page page_qtgui QT Graphical User Interface

\section qtgui_introduction Introduction

This is the gr-qtgui package. It contains various QT-based graphical
user interface blocks that add graphical sinks to a GNU Radio
flowgraph. The Python namespaces is in gnuradio.qtgui, which would be normally
imported as:

\code
    from gnuradio import qtgui
\endcode

See the Doxygen documentation for details about the blocks available
in this package. The relevant blocks are listed in the \ref
qtgui_blk group.

A quick listing of the details can be found in Python after importing
by using:

\code
    help(qtgui)
\endcode

\subsection qtgui_blocks Blocks

There are a number of available QTGUI blocks for different plotting
purposes. These include:

\li Time Domain (gr::qtgui::time_sink_c and gr::qtgui::time_sink_f):
x-axis is time, y-axis is amplitude.
\li Frequency Domain or PSD (gr::qtgui::freq_sink_c and
gr::qtgui::freq_sink_f): x-axis is frequency, y-axis is magnitude in
dB.
\li Waterfall or spectrogram (gr::qtgui::waterfall_sink_c and
gr::qtgui::waterfall_sink_f): x-axis is frequency, y-axis is
time,z-axis is intensity related to magnitude in dB.
\li Constellation (gr::qtgui::const_sink_c): polar plot of real vs. imaginary.
\li Time Raster (gr::qtgui::time_raster_sink_f and
gr::qtgui::time_raster_sink_b): time vs. time with the z-axis being
intensity basedon value of the sample.
\li Histogram (gr::qtgui::histogram_sink_f): Displays a histogram of
the data stream.
\li Combined Sink (gr::qtgui::sink_c and gr::qtgui::sink_f): combines
time, frequency, waterfall, and constellation plots into one widget.

The time domain, frequency domain, and waterfall have both a complex
and a floating point block. The constellation plot only makes sense
with complex inputs. The time raster plots accept bits and floats.

Because the time raster plots are designed to show structure over time
in a signal, frame, packet, etc., they never drop samples. This is a

fairly taxing job and performance can be an issue. Since it is
expected that this block will work on a frame or packet structure, we
tend to be at the lowest possible rate at this point, so that will
help. Expect performance issues at high data rates.

Note: There seem to be extra performance issue with the raster
plotters in QWT version 5 that were fixed with QWT version 6. As such,
the time raster plots have incredibly poor performance with QWT5 to
the point of almost being unusable. In the future, we may restrict
compilation and installation of these plots only if QWT6 or higher is
discovered. For now, just be aware of this limitation.


\section qtgui_menu Drop-Down Menu and Interacting with Plots

All QTGUI sinks have interactive capabilities.

\li Zooming is done simply by clicking the left mouse button and
dragging a rectangle around the area to zoom.
\li Zooming can be done in multiple steps.
\li A right mouse click will zoom out one step.
\li Ctrl+Right mouse click will zoom all the way out.
\li Ctrl+Middle mouse click and hold can drag the canvas around.
\li Mouse wheel up/down will zoom out/in on y axis (both axes in
constellation plot).
\li Middle mouse button brings up a context menu.

Each type of graph has a different set of menu items in the context
menu. Most have some way to change the appearance of the lines or
surfaces, such as changing the line width color, marker, and
transparency. Other common features can set the sampling rate, turn a
grid on an off, pause and unpause (stop/start) the display update, and
save the current figure. Specific feature are things like setting the
number of points to display, setting the FFT size, FFT window, and any
FFT averaging.

\subsection qtgui_menu_trigger Triggering Menu for Time Plots

The time plots have triggering capabilities. Triggering can happen
when the signal of a specific channel crosses (positive or negative
slope) a certain level threshold. Or triggering can be done off a
specific stream tag such that whenever a tag of a given key is found,
the scope will trigger.

In the signal level mode, the trigger can be either 'auto' or 'normal'
where the latter will only trigger when the even is seen. The 'auto'
mode will trigger on the event or every so often even if no trigger is
found. The 'free' mode ignores ignores triggering and continuously
plots.

By default, the triggers plot the triggering event at the x=0 (i.e.,
the left-most point in the plot). A delay can be set to delay the
signal along the x-axis to observe any signal before the triggering
event. The delay feature works the same for both level and tag
triggers. The delay is set according to time in seconds, not
samples. So the delay can be calculated as the number of samples
divided by the sample rate given to the block.

All trigger settings (mode, slope, level, delay, channel, and tag key)
are settable in the GRC properties boxes to easily set up a repeatable
environment.

A note on the trigger delay setting. This value is limited by the
buffer size and/or the number of points being display. It is capped by
the minimum of these two values. The buffer size issue is generally
only a problem when plotting a large number of samples. However, if
the delay is set large to begin with (in the GRC properties box or
before top_block.start() is called), then the buffers are resized
accordingly offering more freedom. This should be a problem in a
limited number of scenarios, but a log INFO level message is produced
when asking for the delay outside of the available range.

\section qtgui_dependencies Dependencies

The QT GUI blocks require the following dependencies.

\li QtCore (version >= 4.4)
\li QtGui (version >= 4.4)
\li QtOpenGL (version >= 4.4)
\li PyQt4 for Qt4 (version >= 4.4)
\li Qwt (version >= 5.2)
\li PyQwt5 for Qt4 (version >= 5.2)

\section qtgui_usage Usage

To use the qtgui interface, a bit of boiler-plate lines must be
included. First, the sink is defined, then it must be exposed from C++
into Python using the "sip.wrapinstance" command, and finally, the
"show" method is run on the new Python object. This sets up the QT
environment to show the widget, but the qApplication must also be
launched.

In the "main" function of the code, the qApp is retrieved. Then, after
the GNU Radio top block is started (remember that start() is a
non-blocking call to launch the main thread of the flowgraph), the
qapp's "exec_()" function is called. This function is a blocking call
while the GUI is alive.

\code
from PyQt4 import Qt
from gnuradio import qtgui
import sys, sip

class grclass(gr.top_block):
    ....

    self.snk = qtgui.sink_c(1024,           #fftsize
    	       		    samp_rate,      #bw
			    "QT GUI Plot")  #name

    self.snk_win = sip.wrapinstance(self.snk.pyqwidget(), Qt.QWidget)
    self.snk_win.show()

def main():
    qapp = Qt.QApplication(sys.argv)
    tb = grclass()
    tb.start()
    qapp.exec_()
    tb.stop()
\endcode

There are graphical controls in all but the combined plotting
tools. In the margins of the GUIs (that is, not on the canvas showing
the signal itself), right-clicking the mouse will pull up a drop-down
menu that will allow you to change difference parameters of the
plots. These include things like the look of the lines (width, color,
style, markers, etc.), the ability to start and stop the display, the
ability to save to a file, and other plot-specific controls (FFT size
for the frequency and waterfall plots, etc.).

\section qtgui_configuration Configuration

There is currently a single configuration option in the preferences
files to set the rendering engine of the QTGUI sinks. Located in
etc/gnuradio/conf.d/gr-qtgui.conf:

\verbatim
[qtgui]
style = raster
\endverbatim

The available styles are:

\li opengl: the fastest but not likely to always work
\li raster: fast and stable; terrible X forwarding performance
\li native: most compute intensive; very good over X

We default this setting to raster for the mix of performance and
usability. When using QTGUI sinks through an X-forwarding session over
SSH, switch to using 'native' for a significant speed boost on the
remote end.

We can also set a QT Style Sheet (QSS) file to adjust the look of our
plotting tools. Set the 'qss' option of the 'qtgui' section in our
configuration file to a QSS file. An example QSS file is distributed
with the QTGUI examples found in
share/gnuradio/examples/qt-gui/dark.qss.

*/