docs/pwg/other-manager.xml

<chapter id="chapter-other-manager" xreflabel="Writing a Manager">
  <title>Writing a Manager</title>
  <para>
    Managers are elements that add a function or unify the function of
    another (series of) element(s). Managers are generally a
    <classname>GstBin</classname> with one or more ghostpads. Inside them
    is/are the actual element(s) that matters. There is several cases where
    this is useful. For example:
  </para>
  <itemizedlist>
    <listitem>
      <para>
        To add support for private events with custom event handling to
        another element.
      </para>
    </listitem>
    <listitem>
      <para>
        To add support for custom pad <function>_query ()</function>
        or <function>_convert ()</function> handling to another element.
      </para>
    </listitem>
    <listitem>
      <para>
        To add custom data handling before or after another element's data
        handler function (generally its <function>_chain ()</function>
        function).
      </para>
    </listitem>
    <listitem>
      <para>
        To embed an element, or a series of elements, into something that
        looks and works like a simple element to the outside world. This
        is particular handy for implementing sources and sink elements with
        multiple pads.
      </para>
    </listitem>
  </itemizedlist>
  <para>
    Making a manager is about as simple as it gets. You can derive from a
    <classname>GstBin</classname>, and in most cases, you can embed the
    required elements in the <function>_init ()</function> already, including
    setup of ghostpads. If you need any custom data handlers, you can connect
    signals or embed a second element which you control.
  </para>
</chapter>