clip-widget.cpp File Reference

Go to the source code of this file.

Description

Implementation details of clip display within the Lumiera UI.

Note

a "clip" can be a media clip proper, or just some part of the former, a channel, or even an effect attached to a clip. Moreover, this clip display can be used both within the context of the timeline or as element in a media bin in the asset management section.

Managing Clip appearance and behaviour

Here we are looking at the actual implementation of the clip display, which is hidden behind two layers of abstraction. The interface for controlling the desired representation style can be found within the ClipPresenter, which in turn delegates through the ClipDelegate interface.

Organisation of representation mode

Due to the various clip appearance styles, the actual implementation needs to be flexible on several levels. Thus, the presentation mode is structured as follows:

• the the Mode of representation controls the basic implementation approach
  • in Mode::HIDDEN, there is no actual UI representation; rather, the ClipDelegate acts as data container to receive and hold the presentation relevant properties of the clip, so to be able to return to a visible representation later on.
  • in Mode::SUMMARY, we use the help of a mediator to create a summarised display of timeline contents; the clip is not mapped individually into the display.
  • only in Mode::INDIVIDUAL there is an actual GTK widget, attached into the display framework in some appropriate way – even in this mode there is still a lot of flexibility, since the implementing widget itself has several options for representation, and, moreover, the widget can still be hidden or out of view.
• the ClipDelegate::Appearance can be seen as an ordered scale of increasingly detailed representation. Some segments of this scale are mapped into the aforementioned three modes of representation. Especially within the Mode::INDIVIDUAL, the appearance can be distinguished into
  • ClipDelegate::Appearance::ABRIDGED : the clip acts as placeholder icon
  • ClipDelegate::Appearance::COMPACT : the clip has real extension
  • ClipDelegate::Appearance::EXPANDED : details within the clip are revealed

Choosing the appropriate representation

On construction, the ClipPresenter invokes ClipPresenter::establishAppearance(), which in turn invokes the generic function ClipDelegate::selectAppearance(), which in this case will always build a new ClipDelegate, since a CanvasHook ("view") is explicitly given. Generally speaking, this function ensures there is a delegate, and this delegate reflects the desired presentation style.

When especially the optional argument timing is provided by the population diff creating the clip, then we can use the given lib::time::TimeSpan data for actually allocating a screen rectangle, and thus only when this condition is met (which should be the default), a ClipWidget is constructed and mapped into presentation.

Later the appearance style can be switched, which might incur the necessity also to exchange the actual implementation of the clip delegate. The latter is the case whenever we detect a different Mode of representation. Beyond that, we always know there is an existing delegate, which can be used to retrieve the further detail presentation data. In some cases the clip needs to be "re-hooked", in which case the existing CanvasHook is used to establish a new display attachment. For this to work, even the modes not directly representing the clip need to hold onto some CanvasHook, so each delegate can implement the ClipDelegate::getCanvas()

Todo:

WIP-WIP-WIP as of 1/2021

Definition in file clip-widget.cpp.

#include "stage/gtk-base.hpp"
#include "stage/timeline/clip-widget.hpp"
#include "stage/widget/element-box-widget.hpp"
#include "lib/format-string.hpp"
#include "lib/util.hpp"
#include <utility>

Classes
class	ClipData
class	ClipWidget
class	DormantClip
	A Clip not directly mapped into presentation, yet present as entity within the timeline framework. More...

Typedefs
using	HookedWidget = model::CanvasHooked< widget::ElementBoxWidget, Gtk::Widget >
using	WidgetHook = model::CanvasHook< Gtk::Widget >

Enumerations
enum	Mode {   HIDDEN,   SUMMARY,   INDIVIDUAL }

Functions
ClipDelegate *	buildDelegateFor (Mode newMode, PDelegate &existingDelegate, WidgetHook *newView, optional< TimeSpan > const &timing)
bool	canRepresentAsClip (PDelegate &existing, optional< TimeSpan > const &timing)
bool	canShow (Time start)
	special convention to suppress a clip with start time == Time::NEVER
Mode	classifyAppearance (ClipDelegate::Appearance appearance)

Namespaces
	stage
	Lumiera GTK UI implementation root.
	stage::timeline
	The timeline display and editing operations.