# 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)
TagList& | operator= (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:

- gstreamermm/taglist.h