Editing XML GRC

=== Creating the XML Block Definition ===

The best way to learn how to create the xml file is to learn by example. Look at the .grc file of a few blocks packaged with GNU Radio as examples. Essentially, all block definitions are structured as follows:

<pre>
&lt;?xml version="1.0"?&gt;
&lt;block&gt;
  &lt;name&gt;My Block Name&lt;/name&gt;
  &lt;key&gt;my_package_my_block_ff&lt;/key&gt;
  &lt;category&gt;Filters&lt;/category&gt;
  &lt;import&gt;from gnuradio import my_package&lt;/import&gt;
  &lt;make&gt;my_package.my_block_ff($param1, $param2)&lt;/make&gt;
  &lt;callback&gt;set_param1($param1)&lt;/callback&gt;


  &lt;param&gt;
    &lt;name&gt;Parameter 1&lt;/name&gt;
    &lt;key&gt;param1&lt;/key&gt;
    &lt;type&gt;real&lt;/type&gt;
  &lt;param&gt;


  &lt;param&gt;
    &lt;name&gt;Parameter 2&lt;/name&gt;
    &lt;key&gt;param2&lt;/key&gt;
    &lt;value&gt;1&lt;/value&gt;
    &lt;type&gt;int&lt;/type&gt;
  &lt;param&gt;


  &lt;sink&gt;
    &lt;name&gt;in&lt;/name&gt;
    &lt;type&gt;float&lt;/name&gt;
  &lt;/sink&gt;

    
  &lt;source&gt;
    &lt;name&gt;out&lt;/name&gt;
    &lt;type&gt;float&lt;/type&gt;
  &lt;/source&gt;
    

  &lt;source&gt;
    &lt;name&gt;out&lt;/name&gt;
    &lt;type&gt;float&lt;/type&gt;
  &lt;/source&gt;
&lt;/block&gt;
</pre>

* The example above will make a block with 2 parameters, 1 input, and 2 outputs.
* The ordering of the tags is important, if tags are not ordered properly, the block will fail validation. For now just try to follow the ordering other blocks use (e.g. params then sources/sinks)
* The '''name''' tags dictate the label text for the block, parameters, and ports. 
* The '''key''' tags are unique identifiers, they may not contain spaces. The block key must be globally unique among all blocks in GRC. The parameter keys must be unique only within the block.
* The '''category''' tag is a unix-style path that represents the location of the block inside the block selection window. The path can be a new category (Custom), or represent a sub-category (Filters/Custom). To put a block into the root category, just use a single slash (/) for the root path.
* The '''import''' tag (there can be multiple) must be a valid python import statement to the module containing your block.
* The '''make''' tag contains the code necessary to construct your block. This code is essentially a cheetah template nested inside an xml tag. Upon code generation, the template performs a text substitution on the "$" parameters. For more advanced capabilities, see the [http://cheetahtemplate.org/users_guide/index.html cheetah template documentation.] 
* The '''callback''' tag registers a set-method from your custom block. Once the set-method is registered, the set-method can be called at runtime when a variable is changed. There can be any number of '''callback''' tags, one for each set-method of your block. Or no '''callback''' tags if this is not applicable. 
* For the '''param''' tags, the commonly used values for the '''type''' tags are: complex, real, int, complex_vector, real_vector, int_vector, string, and raw. The ''raw'' type allows any value to be used without performing type checking. The ''real'' type should be used for single and double precision floating point numbers. The ''int'' type should be used for longs, ints, shorts, and chars.
* The hide tag controls how the parameter is displayed in GRC. It's either none, part (show in the prop dialog, not in the block on the canvas) or all.
* The '''sink''' tag represents an input port, and the '''source''' tag represents an output port. The allowed values for the '''type''' tags are: complex, float, int, short, and byte. For ports with a vector length, specify a '''vlen''' tag after the '''type''' tag.
* In case you want to create a block definition as done for the FECAPI, the '''key''' tag has to start with '''variable_''' in order to work correctly in GRC.

=== Some Example Definitions ===

* Simple Example: "Complex to Real" source:[https://github.com/gnuradio/gnuradio/blob/maint-3.7/gr-blocks/grc/blocks_complex_to_real.xml gr-blocks/grc/blocks_complex_to_real.xml]
* Multiple Callbacks: "Costas Loop" source:[https://github.com/gnuradio/gnuradio/blob/maint-3.7/gr-digital/grc/digital_costas_loop_cc.xml gr-digital/grc/digital_costas_loop_cc.xml]
* Vlen Example: "Throttle" source:[https://github.com/gnuradio/gnuradio/blob/maint-3.7/gr-blocks/grc/blocks_throttle.xml gr-digital/grc/blocks_throttle.xml]
* Advanced Make: "FFT" source:[https://github.com/gnuradio/gnuradio/blob/maint-3.7/gr-fft/grc/fft_fft_vxx.xml gr-fft/grc/fft_fft_vxx.xml]