[Commit-gnuradio] [gnuradio] 15/21: qtgui: documenting message input support.

[git]

This is an automated email from the git hooks/post-receive script.

jcorgan pushed a commit to branch master
in repository gnuradio.

commit c46f60db17e369fe66a2fafca50319f479cd4a9b
Author: Tom Rondeau <address@hidden>
Date:   Thu Oct 29 16:16:01 2015 -0400

    qtgui: documenting message input support.
---
 gr-qtgui/doc/qtgui.dox                             | 52 ++++++++++++++++++++++
 gr-qtgui/include/gnuradio/qtgui/const_sink_c.h     | 13 +++++-
 gr-qtgui/include/gnuradio/qtgui/freq_sink_c.h      | 11 +++++
 gr-qtgui/include/gnuradio/qtgui/freq_sink_f.h      | 18 +++++---
 gr-qtgui/include/gnuradio/qtgui/histogram_sink_f.h | 13 +++++-
 .../include/gnuradio/qtgui/time_raster_sink_b.h    | 13 +++++-
 .../include/gnuradio/qtgui/time_raster_sink_f.h    | 12 ++++-
 gr-qtgui/include/gnuradio/qtgui/time_sink_c.h      | 13 +++++-
 gr-qtgui/include/gnuradio/qtgui/time_sink_f.h      | 13 +++++-
 gr-qtgui/include/gnuradio/qtgui/waterfall_sink_c.h | 20 +++++----
 gr-qtgui/include/gnuradio/qtgui/waterfall_sink_f.h | 21 +++++----
 11 files changed, 170 insertions(+), 29 deletions(-)

diff --git a/gr-qtgui/doc/qtgui.dox b/gr-qtgui/doc/qtgui.dox
index 3cce328..d95ab19 100644
--- a/gr-qtgui/doc/qtgui.dox
+++ b/gr-qtgui/doc/qtgui.dox
@@ -180,6 +180,58 @@ 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_messages Message Input Support
+
+All QTGUI sinks can accept and plot messages over their "in" message
+port. The message types must either be uniform vectors or PDUs. The
+data type held within the uniform vector or PDU must match the data
+type of the block itself. For example, a qtgui.time_sink_c will only
+handle vectors that pass the pmt::is_c32vector test while a
+qtgui.time_sink_f will only handle vectors that pass the
+pmt::is_f32vector test.
+
+The sinks must only be used with one type of input model: streaming or
+messages. You cannot use them both together or unknown behavior will
+occur.
+
+In the GNU Radio Companion, the QTGUI sink blocks can be set to
+message mode by changing the Type field. Most of the QTGUI sinks
+support multiple data types, even for messages, but GRC only displays
+the message type as the single gray color. Within the block's property
+box, you can set the type to handle the correct message data type
+(e.g., 'Complex Message' or 'Float Message'). When using a message
+type interface, GRC will hide certain parameters that are not usable
+or settable anymore. For example, when plotting a message in the time
+sink, the number of points shown in the time sink is determined by the
+length of the vector in the message. Presetting this in the GUI would
+have no effect.
+
+The behavior in GRC is for convenience and to try and reduce confusion
+about properties and settings in the message mode. However, all of the
+API hooks are still there, so it is possible to set all of this
+programmatically. The results would be harmless, however.
+
+Here is an example of setting up and using a message passing complex
+time sink block:
+
+\code
+from gnuradio import gr, qtgui
+
+tsnk = qtgui.time_sink_c(1024, samp_rate, "", 0)
+tsnk.set_update_time(0.05)
+tsnk.set_y_axis(-1.25, 1.25)
+tsnk.set_y_label("Amp (V)", "")
+tsnk.enable_autoscale(False)
+tsnk.enable_grid(False)
+tsnk.enable_control_panel(False)
+
+tb = gr.top_block()
+msg_block = ? # some PDU/message generating block
+tb.msg_connect((msg_block, 'msg'), (tsnk, 'in'))
+\endcode
+
+
 \section qtgui_configuration Configuration
 
 There is currently a single configuration option in the preferences
diff --git a/gr-qtgui/include/gnuradio/qtgui/const_sink_c.h 
b/gr-qtgui/include/gnuradio/qtgui/const_sink_c.h
index 14f9319..851f3be 100644
--- a/gr-qtgui/include/gnuradio/qtgui/const_sink_c.h
+++ b/gr-qtgui/include/gnuradio/qtgui/const_sink_c.h
@@ -1,6 +1,6 @@
 /* -*- c++ -*- */
 /*
- * Copyright 2012,2014 Free Software Foundation, Inc.
+ * Copyright 2012,2014-2015 Free Software Foundation, Inc.
  *
  * This file is part of GNU Radio
  *
@@ -44,6 +44,17 @@ namespace gr {
      * \details
      * This is a QT-based graphical sink the takes set of a complex
      * streams and plots them on an IQ constellation plot.
+     *
+     * The sink supports plotting streaming complex data or
+     * messages. The message port is named "in". The two modes cannot
+     * be used simultaneously, and \p nconnections should be set to 0
+     * when using the message mode. GRC handles this issue by
+     * providing the "Complex Message" type that removes the streaming
+     * port(s).
+     *
+     * This sink can plot messages that contain either uniform vectors
+     * of complex 32 values (pmt::is_c32vector) or PDUs where the data
+     * is a uniform vector of complex 32 values.
      */
     class QTGUI_API const_sink_c : virtual public sync_block
     {
diff --git a/gr-qtgui/include/gnuradio/qtgui/freq_sink_c.h 
b/gr-qtgui/include/gnuradio/qtgui/freq_sink_c.h
index c3c7de0..bf5a91f 100644
--- a/gr-qtgui/include/gnuradio/qtgui/freq_sink_c.h
+++ b/gr-qtgui/include/gnuradio/qtgui/freq_sink_c.h
@@ -48,6 +48,17 @@ namespace gr {
      * functions can be used to change the lable and color for a given
      * input number.
      *
+     * The sink supports plotting streaming complex data or
+     * messages. The message port is named "in". The two modes cannot
+     * be used simultaneously, and \p nconnections should be set to 0
+     * when using the message mode. GRC handles this issue by
+     * providing the "Complex Message" type that removes the streaming
+     * port(s).
+     *
+     * This sink can plot messages that contain either uniform vectors
+     * of complex 32 values (pmt::is_c32vector) or PDUs where the data
+     * is a uniform vector of complex 32 values.
+     *
      * Message Ports:
      *
      * - freq (input):
diff --git a/gr-qtgui/include/gnuradio/qtgui/freq_sink_f.h 
b/gr-qtgui/include/gnuradio/qtgui/freq_sink_f.h
index ff08f81..f13d5c6 100644
--- a/gr-qtgui/include/gnuradio/qtgui/freq_sink_f.h
+++ b/gr-qtgui/include/gnuradio/qtgui/freq_sink_f.h
@@ -48,14 +48,18 @@ namespace gr {
      * functions can be used to change the lable and color for a given
      * input number.
      *
-     * Message Ports:
+     * The sink supports plotting streaming float data or
+     * messages. The message port is named "in". The two modes cannot
+     * be used simultaneously, and \p nconnections should be set to 0
+     * when using the message mode. GRC handles this issue by
+     * providing the "Float Message" type that removes the streaming
+     * port(s).
+     *
+     * This sink can plot messages that contain either uniform vectors
+     * of float 32 values (pmt::is_f32vector) or PDUs where the data
+     * is a uniform vector of float 32 values.
      *
-     * - pdus (input):
-     *        Receives and plots a PDU. Each PDU must have a length
-     *        that is an integer multiple of the FFT size. The PDU
-     *        must be formatted as a PDU with float/double
-     *        samples. The block will throw a runtime error if either
-     *        of these conditions is not met.
+     * Message Ports:
      *
      * - freq (input):
      *        Receives a PMT pair: (intern("freq"), double(frequency).
diff --git a/gr-qtgui/include/gnuradio/qtgui/histogram_sink_f.h 
b/gr-qtgui/include/gnuradio/qtgui/histogram_sink_f.h
index 926b9ac..431941a 100644
--- a/gr-qtgui/include/gnuradio/qtgui/histogram_sink_f.h
+++ b/gr-qtgui/include/gnuradio/qtgui/histogram_sink_f.h
@@ -1,6 +1,6 @@
 /* -*- c++ -*- */
 /*
- * Copyright 2013 Free Software Foundation, Inc.
+ * Copyright 2013,2015 Free Software Foundation, Inc.
  *
  * This file is part of GNU Radio
  *
@@ -60,6 +60,17 @@ namespace gr {
      * accumulates the data between calls to work. When accumulate is
      * activated, the y-axis autoscaling is turned on by default as
      * the values will quickly grow in the this direction.
+     *
+     * The sink supports plotting streaming float data or
+     * messages. The message port is named "in". The two modes cannot
+     * be used simultaneously, and \p nconnections should be set to 0
+     * when using the message mode. GRC handles this issue by
+     * providing the "Float Message" type that removes the streaming
+     * port(s).
+     *
+     * This sink can plot messages that contain either uniform vectors
+     * of float 32 values (pmt::is_f32vector) or PDUs where the data
+     * is a uniform vector of float 32 values.
      */
     class QTGUI_API histogram_sink_f : virtual public sync_block
     {
diff --git a/gr-qtgui/include/gnuradio/qtgui/time_raster_sink_b.h 
b/gr-qtgui/include/gnuradio/qtgui/time_raster_sink_b.h
index 586007b..ed55e2e 100644
--- a/gr-qtgui/include/gnuradio/qtgui/time_raster_sink_b.h
+++ b/gr-qtgui/include/gnuradio/qtgui/time_raster_sink_b.h
@@ -1,6 +1,6 @@
 /* -*- c++ -*- */
 /*
- * Copyright 2012,2013 Free Software Foundation, Inc.
+ * Copyright 2012,2013,2015 Free Software Foundation, Inc.
  *
  * This file is part of GNU Radio
  *
@@ -48,6 +48,17 @@ namespace gr {
      * Input stream: This expects a bit stream (0, 1 in the LSB of a
      * byte). It will display packed bytes but the display will have
      * to be autoscaled.
+     *
+     * The sink supports plotting streaming byte/char data or
+     * messages. The message port is named "in". The two modes cannot
+     * be used simultaneously, and \p nconnections should be set to 0
+     * when using the message mode. GRC handles this issue by
+     * providing the "Float Message" type that removes the streaming
+     * port(s).
+     *
+     * This sink can plot messages that contain either uniform vectors
+     * of byte/char values (pmt::is_{u,s}32vector) or PDUs where the
+     * data is a uniform vector of byte/char values.
      */
     class QTGUI_API time_raster_sink_b : virtual public sync_block
     {
diff --git a/gr-qtgui/include/gnuradio/qtgui/time_raster_sink_f.h 
b/gr-qtgui/include/gnuradio/qtgui/time_raster_sink_f.h
index 2c7699d..5610dab 100644
--- a/gr-qtgui/include/gnuradio/qtgui/time_raster_sink_f.h
+++ b/gr-qtgui/include/gnuradio/qtgui/time_raster_sink_f.h
@@ -1,6 +1,6 @@
 /* -*- c++ -*- */
 /*
- * Copyright 2012,2013 Free Software Foundation, Inc.
+ * Copyright 2012,2013,2015 Free Software Foundation, Inc.
  *
  * This file is part of GNU Radio
  *
@@ -45,6 +45,16 @@ namespace gr {
      * This is a QT-based graphical sink that takes set of a floating
      * point streams and plots a time_raster (spectrogram) plot.
      *
+     * The sink supports plotting streaming float data or
+     * messages. The message port is named "in". The two modes cannot
+     * be used simultaneously, and \p nconnections should be set to 0
+     * when using the message mode. GRC handles this issue by
+     * providing the "Float Message" type that removes the streaming
+     * port(s).
+     *
+     * This sink can plot messages that contain either uniform vectors
+     * of float 32 values (pmt::is_f32vector) or PDUs where the data
+     * is a uniform vector of float 32 values.
      */
     class QTGUI_API time_raster_sink_f : virtual public sync_block
     {
diff --git a/gr-qtgui/include/gnuradio/qtgui/time_sink_c.h 
b/gr-qtgui/include/gnuradio/qtgui/time_sink_c.h
index 53e3d2a..10c87c8 100644
--- a/gr-qtgui/include/gnuradio/qtgui/time_sink_c.h
+++ b/gr-qtgui/include/gnuradio/qtgui/time_sink_c.h
@@ -1,6 +1,6 @@
 /* -*- c++ -*- */
 /*
- * Copyright 2011-2013 Free Software Foundation, Inc.
+ * Copyright 2011-2013,2015 Free Software Foundation, Inc.
  *
  * This file is part of GNU Radio
  *
@@ -47,6 +47,17 @@ namespace gr {
      * with a different color, and the \a set_title and \a set_color
      * functions can be used to change the lable and color for a given
      * input number.
+     *
+     * The sink supports plotting streaming complex data or
+     * messages. The message port is named "in". The two modes cannot
+     * be used simultaneously, and \p nconnections should be set to 0
+     * when using the message mode. GRC handles this issue by
+     * providing the "Complex Message" type that removes the streaming
+     * port(s).
+     *
+     * This sink can plot messages that contain either uniform vectors
+     * of complex 32 values (pmt::is_c32vector) or PDUs where the data
+     * is a uniform vector of complex 32 values.
      */
     class QTGUI_API time_sink_c : virtual public sync_block
     {
diff --git a/gr-qtgui/include/gnuradio/qtgui/time_sink_f.h 
b/gr-qtgui/include/gnuradio/qtgui/time_sink_f.h
index a47261b..d96383c 100644
--- a/gr-qtgui/include/gnuradio/qtgui/time_sink_f.h
+++ b/gr-qtgui/include/gnuradio/qtgui/time_sink_f.h
@@ -1,6 +1,6 @@
 /* -*- c++ -*- */
 /*
- * Copyright 2011-2013 Free Software Foundation, Inc.
+ * Copyright 2011-2013,2015 Free Software Foundation, Inc.
  *
  * This file is part of GNU Radio
  *
@@ -45,6 +45,17 @@ namespace gr {
      * and plots them in the time domain. Each signal is plotted with a
      * different color, and the \a set_title and \a set_color functions
      * can be used to change the lable and color for a given input number.
+     *
+     * The sink supports plotting streaming float data or
+     * messages. The message port is named "in". The two modes cannot
+     * be used simultaneously, and \p nconnections should be set to 0
+     * when using the message mode. GRC handles this issue by
+     * providing the "Float Message" type that removes the streaming
+     * port(s).
+     *
+     * This sink can plot messages that contain either uniform vectors
+     * of float 32 values (pmt::is_f32vector) or PDUs where the data
+     * is a uniform vector of float 32 values.
      */
     class QTGUI_API time_sink_f : virtual public sync_block
     {
diff --git a/gr-qtgui/include/gnuradio/qtgui/waterfall_sink_c.h 
b/gr-qtgui/include/gnuradio/qtgui/waterfall_sink_c.h
index cc72246..71a8b92 100644
--- a/gr-qtgui/include/gnuradio/qtgui/waterfall_sink_c.h
+++ b/gr-qtgui/include/gnuradio/qtgui/waterfall_sink_c.h
@@ -1,6 +1,6 @@
 /* -*- c++ -*- */
 /*
- * Copyright 2012,2014 Free Software Foundation, Inc.
+ * Copyright 2012,2014-2015 Free Software Foundation, Inc.
  *
  * This file is part of GNU Radio
  *
@@ -53,14 +53,18 @@ namespace gr {
      * here, it's probably best to sum the signals together and
      * connect that here.
      *
-     * Message Ports:
+     * The sink supports plotting streaming complex data or
+     * messages. The message port is named "in". The two modes cannot
+     * be used simultaneously, and \p nconnections should be set to 0
+     * when using the message mode. GRC handles this issue by
+     * providing the "Complex Message" type that removes the streaming
+     * port(s).
+     *
+     * This sink can plot messages that contain either uniform vectors
+     * of complex 32 values (pmt::is_c32vector) or PDUs where the data
+     * is a uniform vector of complex 32 values.
      *
-     * - pdus (input):
-     *        Receives and plots a PDU. Each PDU must have a length
-     *        that is an integer multiple of the FFT size. The PDU
-     *        must be formatted as a PDU with complex samples. The
-     *        block will throw a runtime error if either of these
-     *        conditions is not met.
+     * Message Ports:
      *
      * - freq (input):
      *        Receives a PMT pair: (intern("freq"), double(frequency)).
diff --git a/gr-qtgui/include/gnuradio/qtgui/waterfall_sink_f.h 
b/gr-qtgui/include/gnuradio/qtgui/waterfall_sink_f.h
index 0d5d8e5..2a51fba 100644
--- a/gr-qtgui/include/gnuradio/qtgui/waterfall_sink_f.h
+++ b/gr-qtgui/include/gnuradio/qtgui/waterfall_sink_f.h
@@ -1,6 +1,6 @@
 /* -*- c++ -*- */
 /*
- * Copyright 2012,2014 Free Software Foundation, Inc.
+ * Copyright 2012,2014-2015 Free Software Foundation, Inc.
  *
  * This file is part of GNU Radio
  *
@@ -53,14 +53,19 @@ namespace gr {
      * here, it's probably best to sum the signals together and
      * connect that here.
      *
-     * Message Ports:
+     * The sink supports plotting streaming float data or
+     * messages. The message port is named "in". The two modes cannot
+     * be used simultaneously, and \p nconnections should be set to 0
+     * when using the message mode. GRC handles this issue by
+     * providing the "Float Message" type that removes the streaming
+     * port(s).
+     *
+     * This sink can plot messages that contain either uniform vectors
+     * of float 32 values (pmt::is_f32vector) or PDUs where the data
+     * is a uniform vector of float 32 values.
      *
-     * - pdus (input):
-     *        Receives and plots a PDU. Each PDU must have a length
-     *        that is an integer multiple of the FFT size. The PDU
-     *        must be formatted as a PDU with float/double
-     *        samples. The block will throw a runtime error if either
-     *        of these conditions is not met.
+     *
+     * Message Ports:
      *
      * - freq (input):
      *        Receives a PMT pair: (intern("freq"), double(frequency).