Class SourceClip

Additionally, the children properties of the newly added element will be shared with the container, meaning they can also be read and set using ges_timeline_element_get_child_property() and ges_timeline_element_set_child_property() on the container.

pspec should be unique from other children properties that have been registered on self.

If the given child is already in another track, this will create a copy of the child, add it to the clip, and add this copy to the track.

You should only call this whilst a clip is part of a #GESTimeline, and for tracks that are in the same timeline.

This method is an alternative to using the #GESTimeline::select-tracks-for-object signal, but can be used to complement it when, say, you wish to copy a clip's children from one track into a new one.

When the child is a core child, it must be added to a track that does not already contain another core child of the same clip. If it is not a core child (an additional effect), then it must be added to a track that already contains one of the core children of the same clip.

This method can also fail if the adding the track element to the track would break a configuration rule of the corresponding #GESTimeline, such as causing three sources to overlap at a single time, or causing a source to completely overlap another in the same track.

Unlike using ges_container_add(), this allows you to set the index in advance. It will also check that no error occurred during the track selection for the effect.

Note, only subclasses of #GESClipClass that have #GES_CLIP_CLASS_CAN_ADD_EFFECTS set to %TRUE (such as #GESSourceClip and #GESBaseEffectClip) can have additional top effects added.

Note, if the effect is a time effect, this may be refused if the clip would not be able to adapt itself once the effect is added.

Whenever the source_property is changed the target_property is updated using the same value. For instance:

  g_object_bind_property (action, "active", widget, "sensitive", 0);

Will result in the "sensitive" property of the widget #GObject instance to be updated with the same value of the "active" property of the action #GObject instance.

If flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: if target_property on target changes then the source_property on source will be updated as well.

The binding will automatically be removed when either the source or the target instances are finalized. To remove the binding without affecting the source and the target you can just call g_object_unref() on the returned #GBinding instance.

Removing the binding by calling g_object_unref() on it must only be done if the binding, source and target are only used from a single thread and it is clear that both source and target outlive the binding. Especially it is not safe to rely on this if the binding, source or target can be finalized from different threads. Keep another reference to the binding and use g_binding_unbind() instead to be on the safe side.

A #GObject can have multiple bindings.

This function is the language bindings friendly version of g_object_bind_property_full(), using #GClosures instead of function pointers.

If deep is %TRUE, then the new element is prepared so that it can be used in ges_timeline_element_paste() or ges_timeline_paste_element(). In the case of copying a #GESContainer, this ensures that the children of self will also be pasted. The new element should not be used for anything else and can only be used once in a pasting operation. In particular, the new element itself is not an actual 'deep' copy of self, but should be thought of as an intermediate object used for a single paste operation.

Note that the layers argument is currently ignored, so you should just pass %NULL.

Note that if you act on a #GESTrackElement, this will edit its parent #GESClip instead. Moreover, for any #GESTimelineElement, if you select #GES_EDGE_NONE for #GES_EDIT_MODE_NORMAL or #GES_EDIT_MODE_RIPPLE, this will edit the toplevel instead, but still in such a way as to make the #GESTimelineElement:start of self reach the edit position.

Note that if the element's timeline has a #GESTimeline:snapping-distance set, then the edit position may be snapped to the edge of some element under the edited element.

new_layer_priority can be used to switch self, and other elements moved by the edit, to a new layer. New layers may be be created if the the corresponding layer priority/index does not yet exist for the timeline.

Note, if multiple track elements in the clip match the given criteria, this will return the element amongst them with the highest #GESTimelineElement:priority (numerically, the smallest). See ges_clip_find_track_elements() if you wish to find all such elements.

You may also give type to further restrict the search to track elements of the given type.

This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.

property_name can either be in the format "prop-name" or "TypeName::prop-name", where "prop-name" is the name of the property to get (as used in g_object_get()), and "TypeName" is the type name of the child (as returned by G_OBJECT_TYPE_NAME()). The latter format is useful when two children of different types share the same property name.

The first child found with the given "prop-name" property that was registered with ges_timeline_element_add_child_property() (and of the type "TypeName", if it was given) will have the corresponding property copied into value.

Note that ges_timeline_element_get_child_properties() may be more convenient for C programming.

When timeline_time is above the #GESTimelineElement:start of clip, this will return the internal time at which the content that appears at timeline_time in the output of the timeline is created in child. For example, if timeline_time corresponds to the current seek position, this would let you know which part of a media file is being read.

This will be done assuming the clip has an indefinite end, so the internal time may be beyond the current out-point of the child, or even its #GESTimelineElement:max-duration.

If, instead, timeline_time is below the current #GESTimelineElement:start of clip, this will return what you would need to set the #GESTimelineElement:in-point of child to if you set the #GESTimelineElement:start of clip to timeline_time and wanted to keep the content of child currently found at the current #GESTimelineElement:start of clip at the same timeline position. If this would be negative, the conversion fails. This is useful for determining what #GESTimelineElement:in-point would result from a #GES_EDIT_MODE_TRIM to timeline_time.

Note that whilst a clip has no time effects, this second return is equivalent to finding the internal time at which the content that appears at timeline_time in the timeline can be found in child if it had indefinite extent in both directions. However, with non-linear time effects this second return will be more distinct.

In either case, the returned time would be appropriate to use for the #GESTimelineElement:in-point or #GESTimelineElement:max-duration of the child.

See ges_clip_get_timeline_time_from_internal_time(), which performs the reverse.

Note that a #GESAudioSource may also have a natural framerate if it derives from the same #GESSourceClip asset as a #GESVideoSource, and its value will be that of the video source. For example, if the uri of a #GESUriClip points to a file that contains both a video and audio stream, then the corresponding #GESAudioUriSource will share the natural framerate of the corresponding #GESVideoUriSource.

The value can be:

• an empty #GValue initialized by %G_VALUE_INIT, which will be automatically initialized with the expected type of the property (since GLib 2.60)
• a #GValue initialized with the expected type of the property
• a #GValue initialized with a type to which the expected type of the property can be transformed

In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling g_value_unset().

Note that g_object_get_property() is really intended for language bindings, g_object_get() is much more convenient for C programming.

When internal_time is above the #GESTimelineElement:in-point of child, this will return the timeline time at which the internal content found at internal_time appears in the output of the timeline's track. For example, this would let you know where in the timeline a particular scene in a media file would appear.

This will be done assuming the clip has an indefinite end, so the timeline time may be beyond the end of the clip, or even breaking its #GESClip:duration-limit.

If, instead, internal_time is below the current #GESTimelineElement:in-point of child, this will return what you would need to set the #GESTimelineElement:start of clip to if you set the #GESTimelineElement:in-point of child to internal_time and wanted to keep the content of child currently found at the current #GESTimelineElement:start of clip at the same timeline position. If this would be negative, the conversion fails. This is useful for determining what position to use in a #GES_EDIT_MODE_TRIM if you wish to trim to a specific point in the internal content, such as a particular scene in a media file.

Note that whilst a clip has no time effects, this second return is equivalent to finding the timeline time at which the content of child at internal_time would be found in the timeline if it had indefinite extent in both directions. However, with non-linear time effects this second return will be more distinct.

In either case, the returned time would be appropriate to use in ges_timeline_element_edit() for #GES_EDIT_MODE_TRIM, and similar, if you wish to use a particular internal point as a reference. For example, you could choose to end a clip at a certain internal 'out-point', similar to the #GESTimelineElement:in-point, by translating the desired end time into the timeline coordinates, and using this position to trim the end of a clip.

See ges_clip_get_internal_time_from_timeline_time(), which performs the reverse, or ges_clip_get_timeline_time_from_source_frame() which does the same conversion, but using frame numbers.

The returned timeline time can be used to seek or edit to a specific frame.

Note that you can get the frame timestamp of a particular clip asset with ges_clip_asset_get_frame_time().

prop_name can either be in the format "prop-name" or "TypeName::prop-name", where "prop-name" is the name of the property to look up (as used in g_object_get()), and "TypeName" is the type name of the child (as returned by G_OBJECT_TYPE_NAME()). The latter format is useful when two children of different types share the same property name.

The first child found with the given "prop-name" property that was registered with ges_timeline_element_add_child_property() (and of the type "TypeName", if it was given) will be passed to child, and the registered specification of this property will be passed to pspec.

When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.

Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.

This function omits the property name lookup, hence it is faster than g_object_notify().

One way to avoid using g_object_notify() from within the class that registered the properties, and using g_object_notify_by_pspec() instead, is to store the GParamSpec used with g_object_class_install_property() inside a static array, e.g.:

  enum
  {
    PROP_0,
    PROP_FOO,
    PROP_LAST
  };

  static GParamSpec *properties[PROP_LAST];

  static void
  my_object_class_init (MyObjectClass *klass)
  {
    properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo",
                                             0, 100,
                                             50,
                                             G_PARAM_READWRITE);
    g_object_class_install_property (gobject_class,
                                     PROP_FOO,
                                     properties[PROP_FOO]);
  }

and then notify a change on the "foo" property with:

  g_object_notify_by_pspec (self, properties[PROP_FOO]);

Pasting may fail if it would place the timeline in an unsupported configuration.

After calling this function element should not be used. In particular, element can not be pasted again. Instead, you can copy the returned element and paste that copy (although, this is only possible if the paste was successful).

See also ges_timeline_paste_element().

Since GLib 2.56, if GLIB_VERSION_MAX_ALLOWED is 2.56 or greater, the type of object will be propagated to the return type (using the GCC typeof() extension), so any casting the caller needs to do on the return type must be explicit.

In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.

Since GLib 2.56, the type of object will be propagated to the return type under the same conditions as for g_object_ref().

Unlike ges_meta_container_register_meta(), no (initial) value is set for this field, which means you can use this method to reserve the space to be optionally set later.

Note that if a value has already been set for the field being registered, then its type must match the registering type, and its value will be left in place. If the field has no set value, then you will likely want to include #GES_META_WRITABLE in flags to allow the value to be set later.

Note, if the effect is a time effect, this may be refused if the clip would not be able to adapt itself once the effect is removed.

This function should only be called from object system implementations.

When an object is extracted from an asset using ges_asset_extract() its asset will be automatically set. Note that many classes that implement #GESExtractable will automatically create their objects using assets when you call their new methods. However, you can use this method to associate an object with a compatible asset if it was created by other means and does not yet have an asset. Or, for some implementations of #GESExtractable, you can use this to change the asset of the given extractable object, which will lead to a change in its state to match the new asset #GESAsset:id.

Note that ges_timeline_element_set_child_properties() may be more convenient for C programming.

property_name can either be in the format "prop-name" or "TypeName::prop-name", where "prop-name" is the name of the property to set (as used in g_object_set()), and "TypeName" is the type name of the child (as returned by G_OBJECT_TYPE_NAME()). The latter format is useful when two children of different types share the same property name.

The first child found with the given "prop-name" property that was registered with ges_timeline_element_add_child_property() (and of the type "TypeName", if it was given) will have the corresponding property set to value. Other children that may have also matched the property name (and type name) are left unchanged!

If the object already had an association with that name, the old association will be destroyed.

Internally, the key is converted to a #GQuark using g_quark_from_string(). This means a copy of key is kept permanently (even after object has been finalized) — so it is recommended to only use a small, bounded set of values for key in your program, to avoid the #GQuark storage growing unbounded.

Whilst the element is part of a #GESTimeline, this is the same as editing the element with ges_timeline_element_edit() under #GES_EDIT_MODE_TRIM with #GES_EDGE_END. In particular, the #GESTimelineElement:duration of the element may be snapped to a different timeline time difference from the one given. In addition, setting may fail if it would place the timeline in an unsupported configuration, or the element does not have enough internal content to last the desired duration.

If self already has a #GESTimelineElement:timeline, you should not call this function with name set to %NULL.

You should ensure that, within each #GESTimeline, every element has a unique name. If you call this function with name as %NULL, then the library should ensure that the set generated name is unique from previously generated names. However, if you choose a name that interferes with the naming conventions of the library, the library will attempt to ensure that the generated names will not conflict with the chosen name, which may lead to a different name being set instead, but the uniqueness between generated and user-chosen names is not guaranteed.

This is used internally and you should normally not call this. A #GESContainer will set the #GESTimelineElement:parent of its children in ges_container_add() and ges_container_remove().

Note, if parent is not %NULL, self must not already have a parent set. Therefore, if you wish to switch parents, you will need to call this function twice: first to set the parent to %NULL, and then to the new parent.

If parent is not %NULL, you must ensure it already has a (non-floating) reference to self before calling this.

Whilst the element is part of a #GESTimeline, this is the same as editing the element with ges_timeline_element_edit() under #GES_EDIT_MODE_NORMAL with #GES_EDGE_NONE. In particular, the #GESTimelineElement:start of the element may be snapped to a different timeline time from the one given. In addition, setting may fail if it would place the timeline in an unsupported configuration.

This is used internally and you should normally not call this. A #GESClip will have its #GESTimelineElement:timeline set through its #GESLayer. A #GESTrack will similarly take care of setting the #GESTimelineElement:timeline of its #GESTrackElement-s. A #GESGroup will adopt the same #GESTimelineElement:timeline as its children.

If timeline is %NULL, this will stop its current #GESTimelineElement:timeline from tracking it, otherwise timeline will start tracking self. Note, in the latter case, self must not already have a timeline set. Therefore, if you wish to switch timelines, you will need to call this function twice: first to set the timeline to %NULL, and then to the new timeline.

The original clip's #GESTimelineElement:duration is reduced such that its end point matches the split position. Then a new clip is created in the same layer, whose #GESTimelineElement:start matches the split position and #GESTimelineElement:duration will be set such that its end point matches the old end point of the original clip. Thus, the two clips together will occupy the same positions in the timeline as the original clip did.

The children of the new clip will be new copies of the original clip's children, so it will share the same sources and use the same operations.

The new clip will also have its #GESTimelineElement:in-point set so that any internal data will appear in the timeline at the same time. Thus, when the timeline is played, the playback of data should appear the same. This may be complicated by any additional #GESEffect-s that have been placed on the original clip that depend on the playback time or change the data consumption rate of sources. This method will attempt to translate these effects such that the playback appears the same. In such complex situations, you may get a better result if you place the clip in a separate sub #GESProject, which only contains this clip (and its effects), and in the original layer create two neighbouring #GESUriClip-s that reference this sub-project, but at a different #GESTimelineElement:in-point.

void
object_add_to_user_list (GObject     *object,
                         const gchar *new_string)
{
  // the quark, naming the object data
  GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
  // retrieve the old string list
  GList *list = g_object_steal_qdata (object, quark_string_list);

  // prepend new string
  list = g_list_prepend (list, g_strdup (new_string));
  // this changed 'list', so we need to set it again
  g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
}
static void
free_string_list (gpointer data)
{
  GList *node, *list = data;

  for (node = list; node; node = node->next)
    g_free (node->data);
  g_list_free (list);
}

Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata() would have left the destroy function set, and thus the partial string list would have been freed upon g_object_set_qdata_full().

Duplicate notifications for each property are squashed so that at most one #GObject::notify signal is emitted for each property, in the reverse order in which they have been queued.

It is an error to call this function when the freeze count is zero.

If recursive is %TRUE, and the container contains other containers as children, then they will also be ungrouped, and so on.