gstreamermm 0.10.10.1
Public Types | Public Member Functions | Static Public Member Functions | Protected Attributes | Related Functions
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, You must not change or free this string.
static Glib::ustring get_description (const Glib::ustring& tag)
 Returns the human-readable description of this tag, You must not change or free this string.
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

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

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:
tagThe tag name.
dataA string to which the tag should be set to.
modeThe 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:
tagThe tag name.
dataA string to which the tag should be set to.
modeThe merge mode to use.
template <class DataType >
void Gst::TagList::add ( Tag  tag,
const DataType &  data,
TagMergeMode  mode = TAG_MERGE_PREPEND 
)

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

Parameters:
tagThe tag name.
dataA value which the tag should be set to (this can be any supported C++ type).
modeThe merge mode to use.
template <class DataType >
void Gst::TagList::add ( const Glib::ustring tag,
const DataType &  data,
TagMergeMode  mode = TAG_MERGE_PREPEND 
)

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

Parameters:
tagThe tag name.
dataA value which the tag should be set to (this can be any supported C++ type).
modeThe 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:
tagThe tag name.
modeThe mode to use.
valueThe 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:
tagThe tag name.
modeThe mode to use.
valueThe Glib::Value<> to use.
static bool Gst::TagList::exists ( const Glib::ustring tag) [static]

Checks if the given type is already registered.

Parameters:
tagName 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:
slotSlot to be called for each tag.
template <class DataType >
bool Gst::TagList::get ( Tag  tag,
guint  index,
DataType &  value 
) const

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

Parameters:
tagThe tag to read out.
indexNumber of entry to read out.
valueLocation 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,
guint  index,
DataType &  value 
) const

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

Parameters:
tagThe tag to read out.
indexNumber of entry to read out.
valueLocation 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

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

Parameters:
tagThe tag to read out.
valueLocation 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

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

Parameters:
tagThe tag to read out.
valueLocation 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, You must not change or free this string.

Parameters:
tagThe 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:
tagThe 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, You must not change or free this string.

Parameters:
tagThe 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:
tagThe tag.
Returns:
The Type of this tag.
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:
tagThe tag to read out.
indexNumber 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,
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:
destAn uninitialized Glib::ValueBase to copy into.
tagThe 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 ( 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:
destAn uninitialized Glib::ValueBase to copy into.
tagThe 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 ( const Glib::ustring tag,
guint  index,
Glib::ValueBase dest 
) const

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

Parameters:
tagThe tag to read out.
indexNumber 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.
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:
fromList to merge from.
modeThe 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.
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:
tagTag 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.

Free-function: gst_tag_list_free

Parameters:
list2Second list to merge.
modeThe 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:
tagTag to remove.
void Gst::TagList::remove_tag ( Tag  tag)

Removes the given tag from the taglist.

Parameters:
tagTag 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:
tagThe 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:
lhsThe left-hand side
rhsThe 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:
objectThe C instance.
take_copyFalse 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: