Gst::Bin Class Reference

Gst::Bin — Base class and element that can contain other elements. More...

#include <bin.h>

Inheritance diagram for Gst::Bin:

Gst::Element Gst::ChildProxy Gst::Object Gst::Pipeline

List of all members.

Public Member Functions

virtual ~Bin ()
GstBin* gobj ()
 Provides access to the underlying C GObject.
const GstBin* gobj () const
 Provides access to the underlying C GObject.
GstBin* gobj_copy ()
 Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
Glib::RefPtr<Binadd (const Glib::RefPtr<Element>& element)
 Adds the given element to the bin.
Glib::RefPtr<Binremove (const Glib::RefPtr<Element>& element)
 Removes the element from the bin, unparenting it as well.
Glib::RefPtr<Elementget_element (const Glib::ustring& name)
 Gets the element with the given name from a bin.
Glib::RefPtr<const Elementget_element (const Glib::ustring& name) const
 Gets the element with the given name from a bin.
Glib::RefPtr<Elementget_element_recurse_up (const Glib::ustring& name)
 Gets the element with the given name from this bin.
Glib::RefPtr<const Elementget_element_recurse_up (const Glib::ustring& name) const
 Gets the element with the given name from this bin.
Glib::RefPtr<Elementget_element (GType interface)
 Looks for an element inside the bin that implements the given interface.
Glib::RefPtr<const Elementget_element (GType interface) const
 Looks for an element inside the bin that implements the given interface.
Glib::RefPtr<Padfind_unconnected_pad (PadDirection dir)
 Recursively looks for elements with an unlinked pad of the given direction within the specified bin and returns an unlinked pad if one is found, or 0 otherwise.
Glib::RefPtr<const Padfind_unconnected_pad (PadDirection dir) const
 Recursively looks for elements with an unlinked pad of the given direction within the specified bin and returns an unlinked pad if one is found, or 0 otherwise.
Glib::ListHandle< Glib::RefPtr
<Element >> 
get_children () const
 Gets the bin's list of children.
int get_num_children () const
 Gets the number of children in the bin.
Glib::SignalProxy1< void,
const Glib::RefPtr<Element >&> 
signal_element_added ()
 Will be emitted after the element was added to the bin.
Glib::SignalProxy1< void,
const Glib::RefPtr<Element >&> 
signal_element_removed ()
 Will be emitted after the element was removed from the bin.
Glib::PropertyProxy<bool> property_async_handling ()
 The bin will handle Asynchronous state changes.
Glib::PropertyProxy_ReadOnly
<bool> 
property_async_handling () const
 The bin will handle Asynchronous state changes.
virtual bool add_element_vfunc (const Glib::RefPtr<Element>& element)
 method to add an element to a bin
virtual bool remove_element_vfunc (const Glib::RefPtr<Element>& element)
 method to remove an element from a bin
virtual void handle_message_vfunc (const Glib::RefPtr<Message>& message)
 method to handle a message from the children

Static Public Member Functions

static Glib::RefPtr<Bincreate (const Glib::ustring& name)
 Creates a new bin with the given name.

Protected Member Functions

 Bin (const Glib::ustring& name)
virtual void on_element_added (const Glib::RefPtr<Element>& element)
virtual void on_element_removed (const Glib::RefPtr<Element>& element)

Related Functions

(Note that these are not member functions.)

Glib::RefPtr<Gst::Binwrap (GstBin* object, bool take_copy=false)
 A Glib::wrap() method for this object.


Detailed Description

Gst::Bin — Base class and element that can contain other elements.

Gst::Bin is an element that can contain other Gst::Element, allowing them to be managed as a group. Pads from the child elements can be ghosted to the bin, see Gst::GhostPad. This makes the bin look like any other elements and enables creation of higher-level abstraction elements.

A new Gst::Bin is created with create(). Use a Gst::Pipeline instead if you want to create a toplevel bin because a normal bin doesn't have a bus or handle clock distribution of its own.

After the bin has been created you will typically add elements to it with add(). You can remove elements with remove().

An element can be retrieved from a bin with get_element(), using the elements name. get_element_recurse_up() is mainly used for internal purposes and will query the parent bins when the element is not found in the current bin.

An iterator of elements in a bin can be retrieved with iterate_elements(). Various other iterators exist to retrieve the elements in a bin.

The element-added signal is fired whenever a new element is added to the bin. Likewise the element-removed signal is fired whenever an element is removed from the bin.

Notes:

A Gst::Bin internally intercepts every Gst::Message posted by its children and implements the following default behaviour for each of them:

A Gst::Bin implements the following default behaviour for answering to a Gst::Query:

A Gst::Bin will by default forward any event sent to it to all sink elements. If all the sinks return true, the bin will also return true, else false is returned. If no sinks are in the bin, the event handler will return true.

Last reviewed on 2006-04-28 (0.10.6)


Constructor & Destructor Documentation

virtual Gst::Bin::~Bin (  )  [virtual]

Gst::Bin::Bin ( const Glib::ustring &  name  )  [explicit, protected]


Member Function Documentation

GstBin* Gst::Bin::gobj (  )  [inline]

Provides access to the underlying C GObject.

Reimplemented from Gst::ChildProxy.

Reimplemented in Gst::Pipeline.

const GstBin* Gst::Bin::gobj (  )  const [inline]

Provides access to the underlying C GObject.

Reimplemented from Gst::ChildProxy.

Reimplemented in Gst::Pipeline.

GstBin* Gst::Bin::gobj_copy (  ) 

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

Reimplemented from Gst::Element.

Reimplemented in Gst::Pipeline.

static Glib::RefPtr<Bin> Gst::Bin::create ( const Glib::ustring &  name  )  [static]

Creates a new bin with the given name.

Parameters:
name The name of the new bin.
Returns:
A new Gst::Bin.

Reimplemented in Gst::Pipeline.

Glib::RefPtr<Bin> Gst::Bin::add ( const Glib::RefPtr<Element>&  element  ) 

Adds the given element to the bin.

This sets the element's parent, and thus takes ownership of the element. An element can only be added to one bin.

If the element's pads are linked to other pads then the pads will be unlinked before the element is added to the bin.

MT safe.

Parameters:
element The Gst::Element to add.
Returns:
This Gst::Bin if successful, for chained calls to add().
Exceptions:
std::runtime_error if the Bin does not want to accept the Element.

Glib::RefPtr<Bin> Gst::Bin::remove ( const Glib::RefPtr<Element>&  element  ) 

Removes the element from the bin, unparenting it as well.

Unparenting the element means that the element will be dereferenced, so if the bin holds the only reference to the element, the element will be freed in the process of removing it from the bin.

If the element's pads are linked to other pads, the pads will be unlinked before the element is removed from the bin.

MT safe.

element the Gst::Element to remove Returns this Gst::Bin if successful (for further removing if wanted), NULL otherwise

Glib::RefPtr<Element> Gst::Bin::get_element ( const Glib::ustring &  name  ) 

Gets the element with the given name from a bin.

This function recurses into child bins.

Returns: the Gst::Element with the given name, or 0

Parameters:
name The element name to search for.
Returns:
The Gst::Element with the given name, or 0.

Glib::RefPtr<const Element> Gst::Bin::get_element ( const Glib::ustring &  name  )  const

Gets the element with the given name from a bin.

This function recurses into child bins.

Returns: the Gst::Element with the given name, or 0

Parameters:
name The element name to search for.
Returns:
The Gst::Element with the given name, or 0.

Glib::RefPtr<Element> Gst::Bin::get_element_recurse_up ( const Glib::ustring &  name  ) 

Gets the element with the given name from this bin.

If the element is not found, a recursion is performed on the parent bin.

Returns: the Gst::Element with the given name, or 0

Parameters:
name The element name to search for.
Returns:
The Gst::Element with the given name, or 0.

Glib::RefPtr<const Element> Gst::Bin::get_element_recurse_up ( const Glib::ustring &  name  )  const

Gets the element with the given name from this bin.

If the element is not found, a recursion is performed on the parent bin.

Returns: the Gst::Element with the given name, or 0

Parameters:
name The element name to search for.
Returns:
The Gst::Element with the given name, or 0.

Glib::RefPtr<Element> Gst::Bin::get_element ( GType  interface  ) 

Looks for an element inside the bin that implements the given interface.

If such an element is found, it returns the element. You can cast this element to the given interface afterwards. If you want all elements that implement the interface, use iterate_all_by_interface(). This function recurses into child bins.

MT safe. Caller owns returned reference.

Parameters:
iface The Type of an interface.
Returns:
A Gst::Element inside the bin implementing the interface.

Glib::RefPtr<const Element> Gst::Bin::get_element ( GType  interface  )  const

Looks for an element inside the bin that implements the given interface.

If such an element is found, it returns the element. You can cast this element to the given interface afterwards. If you want all elements that implement the interface, use iterate_all_by_interface(). This function recurses into child bins.

MT safe. Caller owns returned reference.

Parameters:
iface The Type of an interface.
Returns:
A Gst::Element inside the bin implementing the interface.

Glib::RefPtr<Pad> Gst::Bin::find_unconnected_pad ( PadDirection  dir  ) 

Recursively looks for elements with an unlinked pad of the given direction within the specified bin and returns an unlinked pad if one is found, or 0 otherwise.

If a pad is found, the caller owns a reference to it and should use Gst::Object::unref() on the pad when it is not needed any longer.

Parameters:
direction Whether to look for an unlinked source or sink pad.
Returns:
Unlinked pad of the given direction, or 0.
Since: 0.10.3

Deprecated: use find_unlinked_pad() instead.

Glib::RefPtr<const Pad> Gst::Bin::find_unconnected_pad ( PadDirection  dir  )  const

Recursively looks for elements with an unlinked pad of the given direction within the specified bin and returns an unlinked pad if one is found, or 0 otherwise.

If a pad is found, the caller owns a reference to it and should use Gst::Object::unref() on the pad when it is not needed any longer.

Parameters:
direction Whether to look for an unlinked source or sink pad.
Returns:
Unlinked pad of the given direction, or 0.
Since: 0.10.3

Deprecated: use find_unlinked_pad() instead.

Glib::ListHandle<Glib::RefPtr<Element>> Gst::Bin::get_children (  )  const

Gets the bin's list of children.

int Gst::Bin::get_num_children (  )  const

Gets the number of children in the bin.

Glib::SignalProxy1<void,const Glib::RefPtr<Element>&> Gst::Bin::signal_element_added (  ) 

Will be emitted after the element was added to the bin.

Prototype:
void on_my_element_added(const Glib::RefPtr<Element>& element)

Glib::SignalProxy1<void,const Glib::RefPtr<Element>&> Gst::Bin::signal_element_removed (  ) 

Will be emitted after the element was removed from the bin.

Prototype:
void on_my_element_removed(const Glib::RefPtr<Element>& element)

Glib::PropertyProxy<bool> Gst::Bin::property_async_handling (  ) 

The bin will handle Asynchronous state changes.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<bool> Gst::Bin::property_async_handling (  )  const

The bin will handle Asynchronous state changes.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

virtual bool Gst::Bin::add_element_vfunc ( const Glib::RefPtr<Element>&  element  )  [virtual]

method to add an element to a bin

virtual bool Gst::Bin::remove_element_vfunc ( const Glib::RefPtr<Element>&  element  )  [virtual]

method to remove an element from a bin

virtual void Gst::Bin::handle_message_vfunc ( const Glib::RefPtr<Message>&  message  )  [virtual]

method to handle a message from the children

virtual void Gst::Bin::on_element_added ( const Glib::RefPtr<Element>&  element  )  [protected, virtual]

virtual void Gst::Bin::on_element_removed ( const Glib::RefPtr<Element>&  element  )  [protected, virtual]


Friends And Related Function Documentation

Glib::RefPtr<Gst::Bin> wrap ( GstBin *  object,
bool  take_copy = false 
) [related]

A Glib::wrap() method for this object.

Parameters:
object The C instance.
take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns:
A C++ instance that wraps this C instance.


The documentation for this class was generated from the following file:

Generated on Sat Jul 26 11:56:13 2008 for gstreamermm by  doxygen 1.5.5