Gst::TagList Class Reference

A List of tags and values used to describe media metadata. More...

#include <taglist.h>

Inheritance diagram for Gst::TagList:

Gst::Structure

List of all members.

Public Types

typedef sigc::slot< void,
const Glib::ustring& > 
SlotForeach
 For example, void on_foreach(const Glib::ustring& tag);.

Public Member Functions

 TagList ()
 TagList (GstTagList* gobject, bool make_a_copy=true)
 TagList (const TagList& other)
TagListoperator= (const TagList& other)
 ~TagList ()
void swap (TagList& other)
GstTagList* gobj ()
 Provides access to the underlying C instance.
const GstTagList* gobj () const
 Provides access to the underlying C instance.
GstTagList* gobj_copy () const
 Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs.
bool is_empty () const
 Checks if the given taglist is empty.
void insert (const Gst::TagList& other, TagMergeMode mode=TAG_MERGE_PREPEND)
 Inserts the tags of the second list into the first list using the given mode.
Gst::TagList merge (const Gst::TagList& other, TagMergeMode mode=TAG_MERGE_PREPEND)
 Merges the two given lists into a new list.
guint size (const Glib::ustring& tag) const
 Checks how many value are stored in this tag list for the given tag.
void add (const Glib::ustring& tag, const Glib::ValueBase& value, TagMergeMode mode=TAG_MERGE_PREPEND)
 Sets a GValue for the given tag using the specified mode.
void add (const Glib::ustring& tag, const char* data, TagMergeMode mode=TAG_MERGE_PREPEND)
 Sets the value for the given tag to string data using the specified mode.
template<class DataType >
void add (const Glib::ustring& tag, const DataType& data, TagMergeMode mode=TAG_MERGE_PREPEND)
 Sets the value for the given tag using the specified mode.
void remove_tag (const Glib::ustring& tag)
 Removes the given tag from the taglist.
void foreach (const SlotForeach& slot)
 Calls the given slot for each tag inside the tag list.
bool get (const Glib::ustring& tag, Glib::ValueBase& dest)
 Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.
bool get (const Glib::ustring& tag, guint index, Glib::ValueBase& dest)
 Gets the value that is at the given index for the given tag.
template<class DataType >
bool get (const Glib::ustring& tag, DataType& value)
 Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.
template<class DataType >
bool get (const Glib::ustring& tag, guint index, DataType& value)
 Gets the value that is at the given index for the given tag.

Static Public Member Functions

static bool exists (const Glib::ustring& tag)
 Checks if the given type is already registered.
static GType get_type (const Glib::ustring& tag)
 Gets the Type used for this tag.
static Glib::ustring get_nick (const Glib::ustring& tag)
 Returns: the human-readable name of this tag.
static Glib::ustring get_description (const Glib::ustring& tag)
 Returns: the human-readable description of this tag.
static TagFlag get_flag (const Glib::ustring& tag)
 Gets the flag of tag.
static bool is_fixed (const Glib::ustring& tag)
 Checks if the given tag is fixed.

Protected Attributes

GstTagList* gobject_

Related Functions

(Note that these are not member functions.)

void swap (TagList& lhs, TagList& rhs)
Gst::TagList wrap (GstTagList* object, int dummy, bool take_copy=false)
 A Glib::wrap() method for this object.


Detailed Description

A List of tags and values used to describe media metadata.

Taglists form part of media streams and describe the content of a stream in a non-technical way. Examples include the author of a song, the title of that very same song or the album it is a part of. Tag reading is done through a Gst::Bus. You can listen for Gst::MESSAGE_TAG messages and handle them as you wish.

Note, however, that the Gst::MESSAGE_TAG message may be fired multiple times in the pipeline. It is the application's responsibility to put all those tags together and display them to the user in a nice, coherent way. Usually, using merge() is a good enough way of doing this; make sure to empty the cache when loading a new song, or after every few minutes when listening to internet radio. Also, make sure you use Gst::TAG_MERGE_PREPEND as merging mode, so that a new title (which came in later) has a preference over the old one for display.


Member Typedef Documentation

typedef sigc::slot<void, const Glib::ustring&> Gst::TagList::SlotForeach

For example, void on_foreach(const Glib::ustring& tag);.

Reimplemented from Gst::Structure.


Constructor & Destructor Documentation

Gst::TagList::TagList (  ) 

Gst::TagList::TagList ( GstTagList *  gobject,
bool  make_a_copy = true 
) [explicit]

Gst::TagList::TagList ( const TagList other  ) 

Gst::TagList::~TagList (  ) 


Member Function Documentation

template <class DataType >
void Gst::TagList::add ( const Glib::ustring &  tag,
const DataType &  data,
TagMergeMode  mode = TAG_MERGE_PREPEND 
) [inline]

Sets the value for the given tag using the specified mode.

Parameters:
tag The tag name.
data A value which the tag should be set to (this can be any supported C++ type).
mode The merge mode to use.

void Gst::TagList::add ( const Glib::ustring &  tag,
const char *  data,
TagMergeMode  mode = TAG_MERGE_PREPEND 
)

Sets the value for the given tag to string data using the specified mode.

Parameters:
tag The tag name.
data A string to which the tag should be set to.
mode The merge mode to use.

void Gst::TagList::add ( const Glib::ustring &  tag,
const Glib::ValueBase &  value,
TagMergeMode  mode = TAG_MERGE_PREPEND 
)

Sets a GValue for the given tag using the specified mode.

Parameters:
tag The tag name.
mode The mode to use.
value The GValue to set.

static bool Gst::TagList::exists ( const Glib::ustring &  tag  )  [static]

Checks if the given type is already registered.

Parameters:
tag Name of the tag.
Returns:
true if the type is already registered.

void Gst::TagList::foreach ( const SlotForeach slot  ) 

Calls the given slot for each tag inside the tag list.

Note that if there is no tag, the slot won't be called at all.

Parameters:
slot Slot to be called for each tag.

template <class DataType >
bool Gst::TagList::get ( const Glib::ustring &  tag,
guint  index,
DataType &  value 
) [inline]

Gets the value that is at the given index for the given tag.

Parameters:
tag The tag to read out.
index Number of entry to read out.
value Location for the result (this can be any supported C++ type).
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

template <class DataType >
bool Gst::TagList::get ( const Glib::ustring &  tag,
DataType &  value 
) [inline]

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

Parameters:
tag The tag to read out.
value Location for the result (this can be any supported C++ type).
Returns:
true, if a value was copied, false if the tag didn't exist in the given list.

bool Gst::TagList::get ( const Glib::ustring &  tag,
guint  index,
Glib::ValueBase &  dest 
)

Gets the value that is at the given index for the given tag.

Parameters:
tag The tag to read out.
index Number of entry to read out. @param The Glib::ValueBase to store the value in.
Returns:
true if tag was available and had right number of entries, false otherwise.

bool Gst::TagList::get ( const Glib::ustring &  tag,
Glib::ValueBase &  dest 
)

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

Parameters:
dest An uninitialized Glib::ValueBase to copy into.
tag The tag to read out.
Returns:
true, if a value was copied, false if the tag didn't exist in the list.

static Glib::ustring Gst::TagList::get_description ( const Glib::ustring &  tag  )  [static]

Returns: the human-readable description of this tag.

Parameters:
tag The tag.
Returns:
The human-readable description of this tag.

static TagFlag Gst::TagList::get_flag ( const Glib::ustring &  tag  )  [static]

Gets the flag of tag.

Parameters:
tag The tag.
Returns:
The flag of this tag.

static Glib::ustring Gst::TagList::get_nick ( const Glib::ustring &  tag  )  [static]

Returns: the human-readable name of this tag.

Parameters:
tag The tag.
Returns:
The human-readable name of this tag.

static GType Gst::TagList::get_type ( const Glib::ustring &  tag  )  [static]

Gets the Type used for this tag.

Parameters:
tag The tag.
Returns:
The Type of this tag.

const GstTagList* Gst::TagList::gobj (  )  const [inline]

Provides access to the underlying C instance.

Reimplemented from Gst::Structure.

References gobject_.

GstTagList* Gst::TagList::gobj (  )  [inline]

Provides access to the underlying C instance.

Reimplemented from Gst::Structure.

References gobject_.

GstTagList* Gst::TagList::gobj_copy (  )  const

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

Reimplemented from Gst::Structure.

void Gst::TagList::insert ( const Gst::TagList other,
TagMergeMode  mode = TAG_MERGE_PREPEND 
)

Inserts the tags of the second list into the first list using the given mode.

Parameters:
from List to merge from.
mode The mode to use.

bool Gst::TagList::is_empty (  )  const

Checks if the given taglist is empty.

Returns:
true if the taglist is empty, otherwise false.
Since: 0.10.11.

static bool Gst::TagList::is_fixed ( const Glib::ustring &  tag  )  [static]

Checks if the given tag is fixed.

A fixed tag can only contain one value. Unfixed tags can contain lists of values.

Parameters:
tag Tag to check.
Returns:
true, if the given tag is fixed.

Gst::TagList Gst::TagList::merge ( const Gst::TagList other,
TagMergeMode  mode = TAG_MERGE_PREPEND 
)

Merges the two given lists into a new list.

If one of the lists is 0, a copy of the other is returned. If both lists are 0, 0 is returned.

Parameters:
list2 Second list to merge.
mode The mode to use.
Returns:
The new list.

TagList& Gst::TagList::operator= ( const TagList other  ) 

void Gst::TagList::remove_tag ( const Glib::ustring &  tag  ) 

Removes the given tag from the taglist.

Parameters:
tag Tag to remove.

guint Gst::TagList::size ( const Glib::ustring &  tag  )  const

Checks how many value are stored in this tag list for the given tag.

Parameters:
tag The tag to query.
Returns:
The number of tags stored.

void Gst::TagList::swap ( TagList other  ) 

Referenced by swap().


Friends And Related Function Documentation

void swap ( TagList lhs,
TagList rhs 
) [related]

Parameters:
lhs The left-hand side
rhs The right-hand side

References swap().

Gst::TagList wrap ( GstTagList *  object,
int  dummy,
bool  take_copy = false 
) [related]

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

The dummy int parameter is added to disambiguate Gst::TagList::wrap() from Gst::Structure::wrap() (GstTagList is in fact a GstStructure so wrap method becomes ambiguous).

Parameters:
object The C instance.
dummy An unused parameter to disambiguate Gst::TagList::wrap() from Gst::Structure::wrap(). The value of this parameter is irrelevant.
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.


Member Data Documentation

GstTagList* Gst::TagList::gobject_ [protected]

Reimplemented from Gst::Structure.

Referenced by gobj().


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

Generated on Thu Jan 15 09:33:13 2009 for gstreamermm by  doxygen 1.5.7.1