Gst::TagList Class Reference

A class tha represents a list of tags and values used to describe media metadata. More...

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.
 operator bool () const
 Use this to discover if the TagList is a valid object.
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 from 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_value (Tag tag, const Glib::ValueBase& value, TagMergeMode mode=TAG_MERGE_PREPEND)
 Sets a GValue for the given tag using the specified mode.
void add_value (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 (Tag tag, const char* data, TagMergeMode mode=TAG_MERGE_PREPEND)
 Sets the value for the given tag to string data 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 (Tag tag, const DataType& data, TagMergeMode mode=TAG_MERGE_PREPEND)
 Sets the value for the given tag 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 (Tag tag)
 Removes the given tag from the taglist.
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_value (Tag tag, Glib::ValueBase& dest) const
 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_value (const Glib::ustring& tag, Glib::ValueBase& dest) const
 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_value (Tag tag, guint index, Glib::ValueBase& dest) const
 Gets the value that is at the given index for the given tag.
bool get_value (const Glib::ustring& tag, guint index, Glib::ValueBase& dest) const
 Gets the value that is at the given index for the given tag.
template<class DataType >
bool get (Tag tag, DataType& value) const
 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, DataType& value) const
 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 (Tag tag, guint index, DataType& value) const
 Gets the value that is at the given index for the given tag.
template<class DataType >
bool get (const Glib::ustring& tag, guint index, DataType& value) const
 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_taglist (GstTagList* object, bool take_copy=false)
 A Glib::wrap() method for this object.

Detailed Description

A class tha represents 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);.


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.
template <class DataType >
void Gst::TagList::add ( Tag  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 ( Tag  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_value ( 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 Glib::Value<> to use.
void Gst::TagList::add_value ( Tag  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 Glib::Value<> to use.
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 
) const [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 ( Tag  tag,
guint  index,
DataType &  value 
) const [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 
) const [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.
template <class DataType >
bool Gst::TagList::get ( Tag  tag,
DataType &  value 
) const [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.
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.
bool Gst::TagList::get_value ( const Glib::ustring &  tag,
guint  index,
Glib::ValueBase &  dest 
) const

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_value ( Tag  tag,
guint  index,
Glib::ValueBase &  dest 
) const

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_value ( const Glib::ustring &  tag,
Glib::ValueBase &  dest 
) const

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.
bool Gst::TagList::get_value ( Tag  tag,
Glib::ValueBase &  dest 
) const

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.
const GstTagList* Gst::TagList::gobj (  )  const [inline]

Provides access to the underlying C instance.

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

Provides access to the underlying C instance.

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.

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

Inserts the tags of the from 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 gstreamermm 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.
Gst::TagList::operator bool (  )  const

Use this to discover if the TagList is a valid object.

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.
void Gst::TagList::remove_tag ( Tag  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  ) 

Friends And Related Function Documentation

void swap ( TagList lhs,
TagList rhs 
) [related]
Parameters:
lhs The left-hand side
rhs The right-hand side
Gst::TagList wrap_taglist ( GstTagList *  object,
bool  take_copy = false 
) [related]

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

The method has a non-standard name because otherwise it would collide with the wrap method for Gst::Structure because both Gst::TagList and Gst::Structure wrap the same underlying C type.

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.

Member Data Documentation

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

The documentation for this class was generated from the following file:
Generated on Mon May 24 15:28:38 2010 for gstreamermm by  doxygen 1.6.3