Menu
▾
▴
[Kdenlive-svn] [kdenlive/refactoring] src: Add API documentation.
|
From: Till T. <ro...@tt...> - 2012-08-16 14:40:26
|
Git commit 34f38ea16af2ad51811919d0812ae69abe0c4914 by Till Theato. Committed on 29/06/2012 at 11:16. Pushed by theato into branch 'refactoring'. Add API documentation. M +1 -7 src/core/bin/bin.cpp M +6 -2 src/core/bin/bin.h M +4 -0 src/core/bin/projectitemmodel.h M +20 -1 src/core/core.h M +5 -0 src/core/fraction.h M +1 -1 src/core/mainwindow.cpp M +24 -2 src/core/mainwindow.h M +2 -0 src/core/monitor/monitorgraphicsscene.cpp M +36 -0 src/core/monitor/monitorgraphicsscene.h M +19 -3 src/core/monitor/monitormanager.h M +63 -0 src/core/monitor/monitormodel.h M +17 -2 src/core/monitor/monitorview.h M +11 -0 src/core/monitor/positionbar.h M +7 -0 src/core/pluginmanager.h M +22 -0 src/core/project/abstractclipplugin.h M +31 -0 src/core/project/abstractprojectclip.h M +1 -1 src/core/project/abstractprojectitem.cpp M +56 -0 src/core/project/abstractprojectitem.h M +24 -0 src/core/project/abstractprojectpart.h M +72 -0 src/core/project/abstracttimelineclip.h M +34 -0 src/core/project/binmodel.h M +4 -2 src/core/project/clippluginmanager.cpp M +31 -0 src/core/project/clippluginmanager.h M +15 -2 src/core/project/commands/addclipcommand.h M +16 -0 src/core/project/commands/configuretrackcommand.h M +14 -0 src/core/project/commands/moveclipcommand.h M +23 -0 src/core/project/commands/resizeclipcommand.h M +32 -0 src/core/project/producerwrapper.h M +5 -3 src/core/project/project.cpp M +34 -1 src/core/project/project.h M +2 -2 src/core/project/projectfolder.cpp M +25 -2 src/core/project/projectfolder.h M +1 -1 src/core/project/projectmanager.cpp M +19 -0 src/core/project/projectmanager.h M +1 -0 src/core/project/timeline.cpp M +33 -0 src/core/project/timeline.h M +2 -0 src/core/project/timelinebackground.cpp M +6 -0 src/core/project/timelinebackground.h M +4 -4 src/core/project/timelinetrack.cpp M +73 -1 src/core/project/timelinetrack.h M +35 -0 src/core/timecode.h M +39 -0 src/core/timecodeformatter.h M +4 -0 src/core/undoview.h M +2 -0 src/plugins/kdenliveplugin.desktop http://commits.kde.org/kdenlive/34f38ea16af2ad51811919d0812ae69abe0c4914 diff --git a/src/core/bin/bin.cpp b/src/core/bin/bin.cpp index dc2e52e..b621063 100644 --- a/src/core/bin/bin.cpp +++ b/src/core/bin/bin.cpp @@ -31,12 +31,6 @@ Bin::Bin(QWidget* parent) : Bin::~Bin() { - if (m_itemView) { - delete m_itemView; - } - if (m_itemModel) { - delete m_itemModel; - } } void Bin::setProject(Project* project) @@ -50,7 +44,7 @@ void Bin::setProject(Project* project) m_itemModel = new ProjectItemModel(project->bin(), this); - m_itemView = new QTreeView(); + m_itemView = new QTreeView(this); layout()->addWidget(m_itemView); m_itemView->setModel(m_itemModel); m_itemView->setSelectionModel(m_itemModel->selectionModel()); diff --git a/src/core/bin/bin.h b/src/core/bin/bin.h index b33a143..c8509c6 100644 --- a/src/core/bin/bin.h +++ b/src/core/bin/bin.h @@ -18,6 +18,11 @@ class Project; class QAbstractItemView; class ProjectItemModel; +/** + * @class Bin + * @brief The bin widget takes care of both item model and view upon project opening. + */ + class KDE_EXPORT Bin : public QWidget { @@ -27,10 +32,9 @@ public: Bin(QWidget* parent = 0); ~Bin(); -public slots: +private slots: void setProject(Project *project); - private: ProjectItemModel *m_itemModel; QAbstractItemView *m_itemView; diff --git a/src/core/bin/projectitemmodel.h b/src/core/bin/projectitemmodel.h index be97aed..67bab5e 100644 --- a/src/core/bin/projectitemmodel.h +++ b/src/core/bin/projectitemmodel.h @@ -17,6 +17,10 @@ class BinModel; class AbstractProjectItem; class QItemSelectionModel; +/** + * @class ProjectItemModel + * @brief Acts as an adaptor to be able to use BinModel with item views. + */ class ProjectItemModel : public QAbstractItemModel { diff --git a/src/core/core.h b/src/core/core.h index 4e8ab60..91d8f2b 100644 --- a/src/core/core.h +++ b/src/core/core.h @@ -23,10 +23,17 @@ class PluginManager; class MonitorManager; class KUrl; - #define pCore Core::self() +/** + * @class Core + * @brief Singleton that provides access to the different parts of Kdenlive + * + * Needs to be initialize before any widgets are created in MainWindow. + * Plugins should be loaded after the widget setup. + */ + class KDE_EXPORT Core : public QObject { Q_OBJECT @@ -34,17 +41,29 @@ class KDE_EXPORT Core : public QObject public: virtual ~Core(); + /** + * @brief Constructs the singleton object and the managers. + * @param mainWindow pointer to MainWindow + */ static void initialize(MainWindow *mainWindow); + /** @brief Returns a pointer to the singleton object. */ static Core *self(); + /** @brief Makes the plugin manager load all auto load plugins. */ void loadPlugins(); + /** @brief Returns a pointer to the main window. */ MainWindow *window(); + /** @brief Returns a pointer to the project manager. */ ProjectManager *projectManager(); + /** @brief Returns a pointer to the effect repository. */ EffectRepository *effectRepository(); + /** @brief Returns a pointer to the clip plugin manager. */ ClipPluginManager *clipPluginManager(); + /** @brief Returns a pointer to the monitor manager. */ MonitorManager *monitorManager(); + /** @brief Returns a pointer to the plugin manager. */ PluginManager *pluginManager(); private: diff --git a/src/core/fraction.h b/src/core/fraction.h index 1e56067..d9bb142 100644 --- a/src/core/fraction.h +++ b/src/core/fraction.h @@ -12,6 +12,11 @@ the Free Software Foundation, either version 3 of the License, or #define FRACTION_H +/** + * @class Fraction + * @brief Describes a fraction with numerator and denominator. + */ + class Fraction { public: diff --git a/src/core/mainwindow.cpp b/src/core/mainwindow.cpp index 5d464b2..d154acd 100644 --- a/src/core/mainwindow.cpp +++ b/src/core/mainwindow.cpp @@ -28,7 +28,7 @@ the Free Software Foundation, either version 3 of the License, or #include <KDebug> -MainWindow::MainWindow(const QString &MltPath, const KUrl &url, const QString & clipsToLoad, QWidget* parent) : +MainWindow::MainWindow(const QString &mltPath, const KUrl &url, const QString & clipsToLoad, QWidget* parent) : KXmlGuiWindow(parent) { initLocale(); diff --git a/src/core/mainwindow.h b/src/core/mainwindow.h index 79b127d..7e38b75 100644 --- a/src/core/mainwindow.h +++ b/src/core/mainwindow.h @@ -21,18 +21,40 @@ class MonitorView; class QUndoView; +/** + * @class MainWindow + * @brief Kdenlive's main window. + */ + class KDE_EXPORT MainWindow : public KXmlGuiWindow { Q_OBJECT public: - explicit MainWindow(const QString &MltPath = QString(), - const KUrl &Url = KUrl(), const QString & clipsToLoad = QString(), QWidget* parent = 0); + /** + * @brief Initializes Core and creates some core widgets. + * @param mltPath tbd + * @param url url of project to load + * @param clipsToLoad list of clips to add to project + */ + explicit MainWindow(const QString &mltPath = QString(), + const KUrl &url = KUrl(), const QString & clipsToLoad = QString(), QWidget* parent = 0); virtual ~MainWindow(); + /** @brief Returns a pointer to the bin widget. */ Bin *bin(); + + /** @brief Returns a pointer to the timeline widget. */ TimelineWidget *timelineWidget(); + /** + * @brief Adds a new dock widget to this window. + * @param title title of the dock widget + * @param objectName objectName of the dock widget (required for storing layouts) + * @param widget widget to use in the dock + * @param area area to which the dock should be added to + * @returns the created dock widget + */ QDockWidget *addDock(const QString &title, const QString &objectName, QWidget *widget, Qt::DockWidgetArea area = Qt::TopDockWidgetArea); private: diff --git a/src/core/monitor/monitorgraphicsscene.cpp b/src/core/monitor/monitorgraphicsscene.cpp index fbf55c5..f14690c 100644 --- a/src/core/monitor/monitorgraphicsscene.cpp +++ b/src/core/monitor/monitorgraphicsscene.cpp @@ -124,6 +124,8 @@ void MonitorGraphicsScene::drawBackground(QPainter* painter, const QRectF& rect) int size = width * height * 4; if (KDE_ISUNLIKELY(size != m_imageRect->rect().width() * m_imageRect->rect().height() * 4)) { + // The frame dimensions have changed. We need to update the gl buffer sizes. + m_imageRect->setRect(0, 0, width, height); #ifdef USE_PBO diff --git a/src/core/monitor/monitorgraphicsscene.h b/src/core/monitor/monitorgraphicsscene.h index e0a583f..93f98d8 100644 --- a/src/core/monitor/monitorgraphicsscene.h +++ b/src/core/monitor/monitorgraphicsscene.h @@ -26,23 +26,59 @@ namespace Mlt typedef QAtomicPointer<Mlt::Frame> AtomicFramePointer; +/** + * @class MonitorGraphicsScene + * @brief Draws Mlt::Frame using OpenGL in a zoomable scene. + * + * Upon consumer setup a pointer to an atomic pointer is provided. + * When a new frame should be shown it needs to stored in the atomic pointer + * and then update() should be called. + */ + + class MonitorGraphicsScene : public QGraphicsScene { Q_OBJECT public: + /** @brief Constructor. */ MonitorGraphicsScene(QObject* parent = 0); virtual ~MonitorGraphicsScene(); + /** @brief Returns the current zoom level. */ qreal zoom() const; + /** + * @brief Performs OpenGL setup. + * @param glWidget pointer to the OpenGL widget which is used as viewport for this scene's view + */ void initializeGL(QGLWidget *glWidget); + + /** + * @brief Sets a new frame pointer. + * @param frame pointer to atomic pointer which should be updated to always point to the curent frame. + * + * The atomic pointer is set to 0 when receiving the frame. + */ void setFramePointer(AtomicFramePointer *frame); public slots: + /** + * @brief Sets the current zoom level. + * @param level level of zoom. 1 means a 100% on the image + */ void setZoom(qreal level = 1); + /** @brief Sets the zoom to fit the dimensions of the viewport. */ void zoomFit(); + /** + * @brief Zooms in. + * @param by amount to zoom in by + */ void zoomIn(qreal by = .05); + /** + * @brief Zooms out. + * @param by amount to zoom out by + */ void zoomOut(qreal by = .05); signals: diff --git a/src/core/monitor/monitormanager.h b/src/core/monitor/monitormanager.h index a0b7ec2..4a00905 100644 --- a/src/core/monitor/monitormanager.h +++ b/src/core/monitor/monitormanager.h @@ -20,19 +20,35 @@ class Project; class QSignalMapper; +/** + * @class MonitorManager + * @brief Takes care of assigning the monitor models to views. + */ + + class MonitorManager : public QObject { Q_OBJECT public: + /** @brief Creates a "auto" monitor view. */ explicit MonitorManager(QObject* parent = 0); + /** + * @brief Registers a model and creates a view for it is necessary. + * @param id indentifier for model and view + * @param model pointer to model + * @param needsOwnView @c false if a view with id @param id exists it is used, otherwise on activation + * the model is assigned to the auto view + * @c true if no view with id @param id exists one is created. + * + * The two default project models (bin, timeline) do not need to be added manually, they are registerd + * internally once a project is openend. + */ void registerModel(const QString &id, MonitorModel *model, bool needsOwnView = false); -public slots: - void setProject(Project *project); - private slots: + void setProject(Project *project); void onModelActivated(const QString &id); private: diff --git a/src/core/monitor/monitormodel.h b/src/core/monitor/monitormodel.h index 2523c5f..34c49a1 100644 --- a/src/core/monitor/monitormodel.h +++ b/src/core/monitor/monitormodel.h @@ -28,37 +28,100 @@ class QImage; typedef QAtomicPointer<Mlt::Frame> AtomicFramePointer; +/** + * @class MonitorModel + * @brief Wrapper around Mlt::Consumer + */ + class KDE_EXPORT MonitorModel : public QObject { Q_OBJECT public: + /** + * @brief Creates a new consumer according to the parameters and some global settings. + * @param profile profile to use + * @param name Displayable (translated) name used as dock widget title by MonitorManager + */ explicit MonitorModel(Mlt::Profile *profile, const QString &name, QObject *parent = 0); virtual ~MonitorModel(); + /** @brief Returns the displayable translated name. */ QString name() const; + /** + * @brief Connects the provided producer to the handled consumer. + * @param producer new producer to use + * + * emits activated + * emits producerChanged + */ void setProducer(ProducerWrapper *producer); + /** @brief Returns the current position. */ int position() const; + /** @brief Returns the current playback speed. */ double speed() const; + /** @brief Returns the producer's duration (playtime). */ int duration() const; + + /** + * @brief Returns the frame pointer. + * + * The frame pointer either points to the current frame or is 0 if it was already used. + */ AtomicFramePointer *framePointer(); + /** + * @brief Updates the frame pointer. + * + * emits frameUpdated + * emits positionChanged if necessary + * + * Should only be used internally by consumer_frame_show! + */ void updateFrame(mlt_frame frame); + /** @brief Emits durationChanged and makes sure the current position is still valid. */ void emitDurationChanged(); + /** @brief Callback for the consumer-frame-show consumer event. Calls updateFrame. */ static void consumer_frame_show(mlt_consumer, MonitorModel *self, mlt_frame frame_ptr); + + /** @brief Callback for the producer-changed producer event. Calls emitDurationChanged. */ static void producer_change(mlt_producer producer, MonitorModel *self); public slots: + /** @brief Starts playback. */ void play(); + /** @brief Pauses playback. */ void pause(); + /** @brief Toggles between play and pause. */ void togglePlaybackState(); + /** + * @brief Sets the position. + * @param position new position + * + * A range change for position is performed. + * + * emits positionChanged and triggers a frame update if necessary + */ void setPosition(int position); + /** + * @brief Sets the speed. + * @param speed new speed + * + * Does not trigger a monitor refresh! + * emits speedChanged + */ void setSpeed(double speed); + /** + * @brief Emits activated. + */ void activate(); + /** + * @brief Tells the consumer to refresh/get a new frame. + */ void refresh(); signals: diff --git a/src/core/monitor/monitorview.h b/src/core/monitor/monitorview.h index 85cdc6a..2efcfbe 100644 --- a/src/core/monitor/monitorview.h +++ b/src/core/monitor/monitorview.h @@ -23,22 +23,37 @@ class KDualAction; class QGraphicsView; +/** + * @class MonitorView + * @brief Widget contains the actual monitor and the related controls. + */ + + class KDE_EXPORT MonitorView : public QWidget { Q_OBJECT public: + /** + * @brief Sets up the GUI elements. + */ explicit MonitorView(QWidget* parent = 0); virtual ~MonitorView(); + /** + * @brief Assigns a new model to the view and connects the controls to it. + * @param model new monitor model + */ void setModel(MonitorModel *model); + /** @brief Returns the current model */ MonitorModel *model(); -public slots: +private slots: + /** @brief Toggles between play and pause. */ void togglePlaybackState(); + /** @brief Updates the shown position of the controls (position bar, timecode widget). */ void setPosition(int position); -private slots: void onPlaybackStateChange(bool plays); void onProducerChanged(); diff --git a/src/core/monitor/positionbar.h b/src/core/monitor/positionbar.h index 9c7535d..0153e19 100644 --- a/src/core/monitor/positionbar.h +++ b/src/core/monitor/positionbar.h @@ -24,6 +24,11 @@ #include <QWidget> +/** + * @class PositionBar + * @brief Small bar with time ticks and a movable position indicator/cursor. + */ + class PositionBar : public QWidget { Q_OBJECT @@ -32,10 +37,16 @@ public: explicit PositionBar(QWidget* parent = 0); virtual ~PositionBar(); + /** @brief Returns the currently displayed position. */ int position() const; public slots: + /** @brief Updates the length in frames to show. */ void setDuration(int duration); + /** @brief Updates the displayed position. + * + * positionChanged is not emitted + */ void setPosition(int position); signals: diff --git a/src/core/pluginmanager.h b/src/core/pluginmanager.h index 3e285e7..13342a1 100644 --- a/src/core/pluginmanager.h +++ b/src/core/pluginmanager.h @@ -17,14 +17,21 @@ the Free Software Foundation, either version 3 of the License, or class KPluginFactory; +/** + * @class PluginManager + * @brief Locates the plugins and allows to load them. + */ class PluginManager : public QObject { Q_OBJECT public: + /** @brief Locates the plugins. */ explicit PluginManager(QObject* parent = 0); + /** @brief Creates all plugins with should be auto loaded. + * @see kdenliveplugin.desktop */ void load(); private: diff --git a/src/core/project/abstractclipplugin.h b/src/core/project/abstractclipplugin.h index 99b368f..eaa17df 100644 --- a/src/core/project/abstractclipplugin.h +++ b/src/core/project/abstractclipplugin.h @@ -24,17 +24,39 @@ class QDomElement; class QGraphicsItem; +/** + * @class AbstractClipPlugin + * @brief Abstract base class for clip plugins. + * + * A clip plugin has to exist for every clip type. It should be created by the plugins factory (which + * will be loaded on startup) and is responsible for providing means to open a clip of the implemented + * type (for example by registering a mimetype to the add file dialog). + * The plugin object is also responsible for creating project clip objects. + */ + + class KDE_EXPORT AbstractClipPlugin : public QObject { Q_OBJECT public: + /** @brief Should do basic setup and registering the different ways of creating a clip. */ explicit AbstractClipPlugin(ClipPluginManager* parent); virtual ~AbstractClipPlugin(); + /** @brief Should return a clip created from @param url. */ virtual AbstractProjectClip *createClip(const KUrl &url, ProjectFolder *parent) const = 0; + /** + * @brief Should return a clip created from @paramd description. + * + * This function is only used when opening a project. + */ virtual AbstractProjectClip *loadClip(const QDomElement &description, ProjectFolder *parent) const = 0; + /** + * @brief Returns a timelineView clip item for the provided timeline clip. + * @param clip timeline clip to create view for. + */ // change to QObject *timelineClipView(TimelineViewType type, AbstractTimelineClip *clip, QObject *parent) once we have different timeline views virtual TimelineClipItem *timelineClipView(AbstractTimelineClip *clip, QGraphicsItem* parent) const; diff --git a/src/core/project/abstractprojectclip.h b/src/core/project/abstractprojectclip.h index c69d9c0..8d09ff1 100644 --- a/src/core/project/abstractprojectclip.h +++ b/src/core/project/abstractprojectclip.h @@ -22,28 +22,59 @@ class AbstractClipPlugin; class QDomElement; +/** + * @class AbstractProjectClip + * @brief Represents a clip in the project (not timeline). + * + * Has to be the base class for every clip type implementation. + * It is created by it's plugin object and is in return responsible for creating timeline instances. + */ + + class KDE_EXPORT AbstractProjectClip : public AbstractProjectItem { Q_OBJECT public: + /** @brief Constructor. + * @param url url of the file this clip is describing; the filename is used as the item's name + * @param parent parent item/folder + * @param plugin plugin ... + */ AbstractProjectClip(const KUrl &url, ProjectFolder *parent, AbstractClipPlugin const *plugin); + /** + * @brief Constructor; tries to get url and name from the producer's resource. + */ AbstractProjectClip(ProducerWrapper *producer, ProjectFolder *parent, AbstractClipPlugin const *plugin); + /** + * @brief Constructor used when opening a project. + * @param description element describing the clip; the attributes "id" and "url" are used + */ AbstractProjectClip(const QDomElement &description, ProjectFolder *parent, AbstractClipPlugin const *plugin); virtual ~AbstractProjectClip(); + /** @brief Returns a pointer to the clip's plugin. */ AbstractClipPlugin const *plugin() const; + /** @brief Should return a timeline clip/instance of this clip. */ virtual AbstractTimelineClip *addInstance(ProducerWrapper *producer, TimelineTrack *parent) = 0; + /** @brief Returns this if @param id matches the clip's id or NULL otherwise. */ AbstractProjectClip *clip(int id); + /** @brief Returns the clip's id. */ int id() const; + /** @brief Returns whether this clip has a url (=describes a file) or not. */ bool hasUrl() const; + /** @brief Returns the clip's url. */ KUrl url() const; + + /** @brief Returns whether this clip has a limited duration or whether it is resizable ad infinitum. */ virtual bool hasLimitedDuration() const; + /** @brief Returns the clip's duration. */ virtual int duration() const; + /** @brief Calls AbstractProjectItem::setCurrent and sets the bin monitor to use the clip's producer. */ virtual void setCurrent(bool current); protected: diff --git a/src/core/project/abstractprojectitem.cpp b/src/core/project/abstractprojectitem.cpp index da5b128..07fcb3d 100644 --- a/src/core/project/abstractprojectitem.cpp +++ b/src/core/project/abstractprojectitem.cpp @@ -73,7 +73,7 @@ void AbstractProjectItem::setParent(AbstractProjectItem* parent) void AbstractProjectItem::addChild(AbstractProjectItem* child) { - if (child) { + if (child && !contains(child)) { bin()->emitAboutToAddItem(child); append(child); bin()->emitItemAdded(child); diff --git a/src/core/project/abstractprojectitem.h b/src/core/project/abstractprojectitem.h index 284922f..d79c438 100644 --- a/src/core/project/abstractprojectitem.h +++ b/src/core/project/abstractprojectitem.h @@ -19,26 +19,64 @@ class BinModel; class QDomElement; +/** + * @class AbstractProjectItem + * @brief Base class for all project items (clips, folders, ...). + * + * Project items are stored in a tree like structure ... + */ + + class KDE_EXPORT AbstractProjectItem : public QObject, public QList<AbstractProjectItem *> { Q_OBJECT public: + /** + * @brief Constructor. + * @param parent parent this item should be added to + */ AbstractProjectItem(AbstractProjectItem *parent = 0); + /** + * @brief Creates a project item upon project load. + * @param description element for this item. + * @param parent parent this item should be added to + * + * We try to read the attributes "name" and "description" + */ AbstractProjectItem(const QDomElement &description, AbstractProjectItem* parent = 0); virtual ~AbstractProjectItem(); bool operator==(const AbstractProjectItem *projectItem) const; + /** @brief Returns a pointer to the parent item (or NULL). */ AbstractProjectItem *parent() const; + /** @brief Removes the item from its current parent and adds it as a child to @param parent. */ virtual void setParent(AbstractProjectItem *parent); + /** + * @brief Adds a new child item and notifies the bin model about it (before and after). + * @param child project item which should be added as a child + * + * This function is called by setParent. + */ virtual void addChild(AbstractProjectItem *child); + + /** + * @brief Removes a child item and notifies the bin model about it (before and after). + * @param child project which sould be removed from the child list + * + * This function is called when a child's parent is changed through setParent + */ virtual void removeChild(AbstractProjectItem *child); + /** @brief Returns a pointer to the bin model this item is child of (through its parent item). */ virtual BinModel *bin(); + + /** @brief Returns the index this item has in its parent's child list. */ int index() const; + /** @brief Used to search for a clip with a specific id. */ virtual AbstractProjectClip *clip(int id) = 0; enum DataType { @@ -47,14 +85,32 @@ public: DataDate }; + /** @brief Returns the data that describes this item. + * @param type type of data to return + * + * This function is necessary for interaction with ProjectItemModel. + */ virtual QVariant data(DataType type) const; + + /** + * @brief Returns the amount of different types of data this item supports. + * + * This base class supports only DataName and DataDescription, so the return value is always 2. + * This function is necessary for interaction with ProjectItemModel. + */ virtual int supportedDataCount() const; + /** @brief Returns the (displayable) name of this item. */ QString name() const; + /** @brief Sets a new (displayable) name. */ virtual void setName(const QString &name); + + /** @brief Returns the (displayable) description of this item. */ QString description() const; + /** @brief Sets a new description. */ virtual void setDescription(const QString &description); + /** @brief Flags this item as being current (or not) and notifies the bin model about it. */ virtual void setCurrent(bool current); // virtual bool isSelected(); diff --git a/src/core/project/abstractprojectpart.h b/src/core/project/abstractprojectpart.h index 94dbb60..2fe63fe 100644 --- a/src/core/project/abstractprojectpart.h +++ b/src/core/project/abstractprojectpart.h @@ -16,18 +16,42 @@ the Free Software Foundation, either version 3 of the License, or #include <kdemacros.h> +/** + * @class AbstractProjectPart + * @brief Subclassing AbstractProjectPart allows to store extra information in the project. + * + * For very simple information that does not need a complete separation the project's setting + * functionality should be used instead. + * + * Objects are registered to the project manager and the individual projects only call load and + * save but don't instantiate the objects themself. + */ + + class KDE_EXPORT AbstractProjectPart : public QObject { Q_OBJECT public: + /** + * @brief Registers the part to the project manager. + * @param name name of the element this part stores its information in + */ explicit AbstractProjectPart(const QString &name, QObject *parent = 0); + /** @brief Returns the (tag) name of the element this part stores its information in. */ QString name() const; + /** @brief Called by the project to request the current data. */ virtual QDomElement save() const = 0; + /** @brief Called upon project creation. */ virtual void load(const QDomElement &element) = 0; + /** + * @brief Should be called when the data of this part has changed. + * + * emits modified to notify the project. + */ void setModified(); signals: diff --git a/src/core/project/abstracttimelineclip.h b/src/core/project/abstracttimelineclip.h index b045ee5..2ab6033 100644 --- a/src/core/project/abstracttimelineclip.h +++ b/src/core/project/abstracttimelineclip.h @@ -20,38 +20,110 @@ class TimelineTrack; class QUndoCommand; +/** + * @class AbstractTimelineClip + * @brief Base class for timeline clips (layer on top of cut producers). + * + * + */ + + class KDE_EXPORT AbstractTimelineClip : public QObject { Q_OBJECT public: + /** + * @brief Creates a new timeline clip. + * @param producer producer this timeline clip should handle (the cut producer/playlist entry, not the parent) + * @param projectClip project clip this instance belongs to + * @param parent track this clip is inside of; the constructor does not add the clip to the track, you have to do this manually + */ AbstractTimelineClip(ProducerWrapper *producer, AbstractProjectClip *projectClip, TimelineTrack *parent); virtual ~AbstractTimelineClip(); + /** @brief Returns a pointer to the clip's producer. */ ProducerWrapper *producer(); + /** @brief Sets a new producer. + * + * emits producerChanged + */ virtual void setProducer(ProducerWrapper *producer); + /** @brief Returns the project clip this instance belongs to. */ AbstractProjectClip *projectClip(); + /** @brief Returns the parent track. */ TimelineTrack *track(); + /** @brief Returns the clips index in the parent mlt_playlist (blanks are counted too!). */ int index() const; + /** @brief Returns a pointer to the previous clip (timewise, per track) or NULL. */ AbstractTimelineClip *before(); + /** @brief Returns a pointer to the next clip (timewise, per track) or NULL. */ AbstractTimelineClip *after(); + /** @brief Returns the position of the clip (in frames). */ int position() const; + /** @brief Returns the duration of the clip (in frames). */ int duration() const; + /** @brief Returns the in point of the clip (in frames). */ int in() const; + /** @brief Returns the out point of the clip (in frames). */ int out() const; + /** @brief Returns the (displayable) name of the clip (same as AbstractProjectClip::name). */ QString name() const; + /** @brief Emits resized. */ void emitResized(); + /** @brief Emits moved. */ void emitMoved(); public slots: + /** + * @brief Moves the clip. + * @param position new position + * @param parentCommand command the MoveClipCommand should be parented to + * + * If parentCommand is not supplied, the created command is pushed to the undo stack. + * This function does not perform any safety checks! Make sure there is sufficient blank space + * at @param position. + * + * @see MoveClipCommand + */ void setPosition(int position, QUndoCommand *parentCommand = 0); + + /** + * @brief Sets a new in point. + * @param in new in point in frames + * @param parentCommand command the ResizeClipCommand should be parented to + * + * The clips postion will not be changed, but the absolute out point (position + duration). + * + * @see setInOut + */ virtual void setIn(int in, QUndoCommand *parentCommand = 0); + /** + * @brief Sets a new out point. + * @param out new out point in frames + * @param parentCommand command the ResizeClipCommand should be parented to + * + * @see setInOut + */ virtual void setOut(int out, QUndoCommand *parentCommand = 0); + /** + * @brief Sets new in and out points. + * @param in new in point in frames + * @param out new out point in frames + * @param parentCommand command the ResizeClipCommand should be parented to + * + * If parentCommand is not supplied, the created command is pushed to the undo stack. + * This function does not perform any safety checks! Make sure the supplied in and out points are + * valid for this clip and that there is sufficient blank space. + * The clips postion will not be changed, but the absolute out point (position + duration). + * + * @see ResizeClipCommand + */ virtual void setInOut(int in, int out, QUndoCommand *parentCommand = 0); signals: diff --git a/src/core/project/binmodel.h b/src/core/project/binmodel.h index 1192820..a753afe 100644 --- a/src/core/project/binmodel.h +++ b/src/core/project/binmodel.h @@ -22,26 +22,60 @@ class AbstractProjectItem; class QDomElement; +/** + * @class BinModel + * @brief Provides some functionality on top of the root folder for easy access from both the project and the item model. + */ + + class KDE_EXPORT BinModel : public QObject { Q_OBJECT public: + /** + * @brief Creates an empty root folder and a monitor model. + * @param parent project this bin belongs to + */ BinModel(Project *parent = 0); + /** + * @brief Creates monitor model and root folder and passes the supplied information on to it. + * @param rootItem element describing the bin contents (handled by the root folder) + * @param parent project this bin belongs to + * + */ BinModel(const QDomElement &rootItem, Project* parent = 0); + /** @brief Returns a pointer to the project this bin belongs to. */ Project *project(); + /** @brief Returns a pointer to the bin's monitor model. */ MonitorModel *monitor(); + /** @brief Returns a pointer to the root folder. */ ProjectFolder *rootFolder(); + /** + * @brief Returns a pointer to the clip or NULL if not found. + * @param id id of the clip which should be searched for + */ AbstractProjectClip *clip(int id); + /** @brief Returns a pointer to the current item or NULL if there is no current item. */ AbstractProjectItem *currentItem(); + /** + * @brief Sets a new current item and tells the old one about it. + * @param item new current item + * + * emits currentItemChanged + */ void setCurrentItem(AbstractProjectItem *item); public slots: + /** @brief emits aboutToAddItem. */ void emitAboutToAddItem(AbstractProjectItem *item); + /** @brief emits itemAdded. */ void emitItemAdded(AbstractProjectItem *item); + /** @brief emits aboutToRemoveItem. */ void emitAboutToRemoveItem(AbstractProjectItem *item); + /** @brief emits itemRemoved. */ void emitItemRemoved(AbstractProjectItem *item); signals: diff --git a/src/core/project/clippluginmanager.cpp b/src/core/project/clippluginmanager.cpp index 87843ab..99cd603 100644 --- a/src/core/project/clippluginmanager.cpp +++ b/src/core/project/clippluginmanager.cpp @@ -67,14 +67,16 @@ void ClipPluginManager::createClip(const KUrl& url, ProjectFolder *folder, QUndo if (producer->is_valid()) { AbstractClipPlugin *plugin = clipPlugin(producer->get("mlt_service")); if (plugin) { - new AddClipCommand(url, plugin, folder, parentCommand); + AddClipCommand *command = new AddClipCommand(url, plugin, folder, parentCommand); + if (!parentCommand) { + pCore->projectManager()->current()->undoStack()->push(command); + } } else { kWarning() << "no clip plugin available for mlt service " << producer->get("mlt_service"); } } delete producer; } else { - // TODO: proper warning kWarning() << url.path() << " does not exist"; } } diff --git a/src/core/project/clippluginmanager.h b/src/core/project/clippluginmanager.h index ca4a2cf..1215143 100644 --- a/src/core/project/clippluginmanager.h +++ b/src/core/project/clippluginmanager.h @@ -25,22 +25,53 @@ class QDomElement; class QUndoCommand; +/** + * @class ClipPluginManager + * @brief Loads the clip plugins and provides ways to open clips. + */ + + class KDE_EXPORT ClipPluginManager : public QObject { Q_OBJECT public: + /** @brief Loads the clip plugins and creates the "add clip" action. */ explicit ClipPluginManager(QObject* parent = 0); ~ClipPluginManager(); + /** + * @brief Finds out the clip plugin needed for the file provided and creates a AddClipCommand. + * @param url url of the file which should be opened + * @param folder folder the created clip should be parented to + * @param parentCommand parent commmand + * + * If no parent command is provided the created command will be pushed to the undo stack. + */ void createClip(const KUrl &url, ProjectFolder *folder, QUndoCommand *parentCommand = 0) const; + + /** + * @brief Loads the clip described (only used when opening a project). + * @param clipDescription element describing the clip + * @param folder folder the created clip should be parented to + * + */ AbstractProjectClip *loadClip(const QDomElement &clipDescription, ProjectFolder *folder) const; + /** + * @brief Adds support for the supplied mimetypes to the add clip file dialog. + * @param mimetypes list of mimetype names + */ void addSupportedMimetypes(const QStringList &mimetypes); + /** @brief Returns the clip plugin that is associated with the supplied producer type or NULL is no such plugin exists. */ AbstractClipPlugin *clipPlugin(const QString &producerType) const; public slots: + /** + * @brief Allows to add clips through the add clip dialog. + * @param folder folder the created clips should be parented to + */ void execAddClipDialog(ProjectFolder *folder = 0) const; private: diff --git a/src/core/project/commands/addclipcommand.h b/src/core/project/commands/addclipcommand.h index f194cf2..c9d5884 100644 --- a/src/core/project/commands/addclipcommand.h +++ b/src/core/project/commands/addclipcommand.h @@ -18,11 +18,24 @@ class AbstractClipPlugin; class ProjectFolder; class AbstractProjectClip; -// WARNING: when the parentItem is recreated between redo and undo calls we will crash -// -> instead of a pointer store a "index"-Tree which allows us to get the current pointer to the parentItem + +/** + * @class AddClipCommand + * @brief Handles creating and adding a clip to the project. + * + * WARNING: when the parentItem is recreated between redo and undo calls we will crash + * -> instead of a pointer store a "index"-Tree which allows us to get the current pointer to the parentItem + */ + class AddClipCommand : public QUndoCommand { public: + /** + * @brief Constructor. + * @param url url to the file which should be added + * @param plugin plugin handling the clip type of the file + * @param parentItem folder to which the clip should be added to + */ explicit AddClipCommand(const KUrl &url, AbstractClipPlugin *plugin, ProjectFolder *parentItem, QUndoCommand* parent = 0); void undo(); diff --git a/src/core/project/commands/configuretrackcommand.h b/src/core/project/commands/configuretrackcommand.h index 1a141bc..7308979 100644 --- a/src/core/project/commands/configuretrackcommand.h +++ b/src/core/project/commands/configuretrackcommand.h @@ -14,12 +14,28 @@ the Free Software Foundation, either version 3 of the License, or #include <QUndoCommand> #include "project/timelinetrack.h" +/** Pointer to a member function of TimelineTrack with no arguments. */ typedef void (TimelineTrack::*TrackNotifier)(); +/** + * @class ConfigureTrackCommand + * @brief Handles the modification of track settings. + */ + + class ConfigureTrackCommand : public QUndoCommand { public: + /** + * @brief Constructor. + * @param text untranslated text describing the command (@see QUndoCommand::setText) + * @param trackIndex index of the track + * @param setting producer property name of the setting to be modified + * @param value new value + * @param oldValue current/old value + * @param notifier notifier which should be called upon setting change + */ explicit ConfigureTrackCommand(const char *text, int trackIndex, const QString &setting, const QString &value, const QString &oldValue, TrackNotifier notifier, QUndoCommand* parent = 0); void undo(); diff --git a/src/core/project/commands/moveclipcommand.h b/src/core/project/commands/moveclipcommand.h index 2964b6c..171bf4c 100644 --- a/src/core/project/commands/moveclipcommand.h +++ b/src/core/project/commands/moveclipcommand.h @@ -14,9 +14,23 @@ the Free Software Foundation, either version 3 of the License, or #include <QUndoCommand> +/** + * @class MoveClipCommand + * @brief Handles changing a clips position inside a track. + * + * WARNING: No safety checks are performed. Make sure there is sufficient white space at the new position. + */ + + class MoveClipCommand : public QUndoCommand { public: + /** + * @brief Constructor; if no parent command is supplied redo is called (it won't be called again when pushing to the stack). + * @param track index of the track containing the clip + * @param position new position + * @param oldPosition current/old position + */ explicit MoveClipCommand(int track, int position, int oldPosition, QUndoCommand* parent = 0); void redo(); diff --git a/src/core/project/commands/resizeclipcommand.h b/src/core/project/commands/resizeclipcommand.h index acea943..8917a89 100644 --- a/src/core/project/commands/resizeclipcommand.h +++ b/src/core/project/commands/resizeclipcommand.h @@ -14,9 +14,32 @@ the Free Software Foundation, either version 3 of the License, or #include <QUndoCommand> +/** + * @class ResizeClipCommand + * @brief Handles resizing a clip. + * + * The clips position will not be changed. Modifying the in point will cause the absolute out point + * to change (=position + duration). + * + * WARNING: No safety checks are perfomed! + * Make sure that the in and out points are valid for the clip and that there is sufficient white + * space following the clip. + */ + + class ResizeClipCommand : public QUndoCommand { public: + /** + * @brief Constructor; if no parent command is supplied redo is called (it won't be called again when pushing to the stack). + * @param track index of the track containing the clip + * @param position position of the clip + * @param in new in point (in frames); negative values are allowed for clips without a duration + * limit and will cause "out" to be increased + * @param out new out point + * @param oldIn current in point + * @param oldOut current out point + */ explicit ResizeClipCommand(int track, int position, int in, int out, int oldIn, int oldOut, QUndoCommand* parent = 0); void redo(); diff --git a/src/core/project/producerwrapper.h b/src/core/project/producerwrapper.h index 2908c35..27d7fa4 100644 --- a/src/core/project/producerwrapper.h +++ b/src/core/project/producerwrapper.h @@ -18,16 +18,48 @@ the Free Software Foundation, either version 3 of the License, or class QPixmap; +/** + * @class ProducerWrapper + * @brief Provides a thin convenience wrapper around Mlt::Producer + */ + + class KDE_EXPORT ProducerWrapper : public Mlt::Producer { public: + /** + * @brief Constructor. + * @param producer producer to create reference to + */ ProducerWrapper(Mlt::Producer *producer); + /** + * @brief Constructs a new producer. + * @param profile profile to use + * @param input construction argument for the producer (for example the resource) + * @param service type of producer to create + * @see mlt_factory_producer + */ ProducerWrapper(Mlt::Profile &profile, const QString &input, const QString &service = QString()); virtual ~ProducerWrapper(); + /** + * @brief Sets a property. + * @param name name of the property + * @param value the new value + */ void setProperty(const QString &name, const QString &value); + /** + * @brief Returns the value of a property. + * @param name name o the property + */ QString property(const QString &name); + /** + * @brief Returns a pixmap created from a frame of the producer. + * @param position frame position + * @param width width of the pixmap (only a guidance) + * @param height height of the pixmap (only a guidance) + */ QPixmap pixmap(int position = 0, int width = 0, int height = 0); }; diff --git a/src/core/project/project.cpp b/src/core/project/project.cpp index b495ae4..2df41eb 100644 --- a/src/core/project/project.cpp +++ b/src/core/project/project.cpp @@ -29,8 +29,7 @@ the Free Software Foundation, either version 3 of the License, or Project::Project(const KUrl& url, QObject* parent) : QObject(parent), - m_url(url), - m_timeline(0) + m_url(url) { if (url.isEmpty()) { openNew(); @@ -44,6 +43,9 @@ Project::Project(const KUrl& url, QObject* parent) : Project::Project(QObject* parent) : QObject(parent) { + openNew(); + + m_undoStack = new QUndoStack(this); } Project::~Project() @@ -55,7 +57,7 @@ KUrl Project::url() const return m_url; } -QString Project::description() +QString Project::caption() { if (m_url.isEmpty()) return i18n("Untitled") + " / " + profile()->description(); diff --git a/src/core/project/project.h b/src/core/project/project.h index 14c044e..d7ee3ec 100644 --- a/src/core/project/project.h +++ b/src/core/project/project.h @@ -26,28 +26,61 @@ namespace Mlt } +/** + * @class Project + * @brief ... + */ + + class KDE_EXPORT Project : public QObject { Q_OBJECT public: + /** + * @brief Loads the project from the supplied url. + * @param url url of file to open/load + */ Project(const KUrl &url, QObject* parent = 0); + /** @brief Creates a new project. */ Project(QObject *parent = 0); virtual ~Project(); + /** @brief Returns the url of the project file. */ KUrl url() const; - QString description(); + /** @brief Returns a short displayable caption describing the project in the format: filename / profile name. */ + QString caption(); + /** @brief Returns a pointer to the timeline. */ Timeline *timeline(); + /** @brief Returns a pointer to the bin model. */ BinModel *bin(); + /** @brief Returns a pointer to the bin monitor model. */ MonitorModel *binMonitor(); + /** @brief Returns a pointer to the timeline monitor model. */ MonitorModel *timelineMonitor(); + /** @brief Returns a pointer to the used profile. */ Mlt::Profile *profile(); + /** @brief Returns a pointer to the used timecode formatter. */ TimecodeFormatter *timecodeFormatter(); + /** @brief Returns a pointer to the project's undo stack. */ QUndoStack *undoStack(); + /** @brief Retrieves a setting. + * @param name name of the setting to get + * + * Settings can be used to store simple data in the project. For more complex data or something + * that requires better separation subclass AbstractProjectPart. + */ QString setting(const QString &name) const; + /** + * @brief Sets a new settings value. + * @param name name of value (does not have to exist already) + * @param value new value + * + * @see setting + */ void setSetting(const QString &name, const QString &value); private: diff --git a/src/core/project/projectfolder.cpp b/src/core/project/projectfolder.cpp index 0909ac5..2953d5d 100644 --- a/src/core/project/projectfolder.cpp +++ b/src/core/project/projectfolder.cpp @@ -16,7 +16,7 @@ the Free Software Foundation, either version 3 of the License, or #include <QDomElement> -ProjectFolder::ProjectFolder(const QDomElement& description, AbstractProjectItem* parent) : +ProjectFolder::ProjectFolder(const QDomElement& description, ProjectFolder* parent) : AbstractProjectItem(description, parent), m_bin(NULL) { @@ -30,7 +30,7 @@ ProjectFolder::ProjectFolder(const QDomElement& description, BinModel* bin) : loadChildren(description); } -ProjectFolder::ProjectFolder(AbstractProjectItem* parent) : +ProjectFolder::ProjectFolder(ProjectFolder* parent) : AbstractProjectItem(parent) { } diff --git a/src/core/project/projectfolder.h b/src/core/project/projectfolder.h index 55373b1..00dd76a 100644 --- a/src/core/project/projectfolder.h +++ b/src/core/project/projectfolder.h @@ -16,18 +16,41 @@ the Free Software Foundation, either version 3 of the License, or class BinModel; +/** + * @class ProjectFolder + * @brief A folder in the bin. + */ + + class ProjectFolder : public AbstractProjectItem { Q_OBJECT public: - ProjectFolder(const QDomElement &description, AbstractProjectItem* parent); + /** + * @brief Creates the supplied folder and loads its children. + * @param description element describing the folder and its children + * @param parent parent folder + */ + ProjectFolder(const QDomElement &description, ProjectFolder* parent); + /** + * @brief Creates the supplied folder and loads its children. This constructor is used for the root folder. + * @param description element describing the folder and its children + * @param bin bin model + */ ProjectFolder(const QDomElement &description, BinModel *bin); - ProjectFolder(AbstractProjectItem *parent); + /** @brief Creates an empty folder. */ + ProjectFolder(ProjectFolder *parent); + /** @brief Creates an empty root folder. */ ProjectFolder(BinModel *bin); ~ProjectFolder(); + /** + * @brief Returns the clip if it is a child (also indirect). + * @param id id of the child which should be returned + */ AbstractProjectClip *clip(int id); + /** @brief Returns a pointer to the bin model this folder belongs to. */ BinModel *bin(); private: diff --git a/src/core/project/projectmanager.cpp b/src/core/project/projectmanager.cpp index c92ea52..5bddfd4 100644 --- a/src/core/project/projectmanager.cpp +++ b/src/core/project/projectmanager.cpp @@ -62,7 +62,7 @@ void ProjectManager::openProject(const KUrl& url) } m_project = new Project(url, this); - pCore->window()->setCaption(m_project->description()); + pCore->window()->setCaption(m_project->caption()); emit projectOpened(m_project); diff --git a/src/core/project/projectmanager.h b/src/core/project/projectmanager.h index c8f21b6..f32d677 100644 --- a/src/core/project/projectmanager.h +++ b/src/core/project/projectmanager.h @@ -20,24 +20,43 @@ class KAction; class KUrl; +/** + * @class ProjectManager + * @brief Takes care of interaction with projects. + */ + + class KDE_EXPORT ProjectManager : public QObject { Q_OBJECT public: + /** @brief Sets up actions to interact for project interaction (undo, redo, open, save, ...) and creates an empty project. */ explicit ProjectManager(QObject* parent = 0); virtual ~ProjectManager(); + /** @brief Returns a pointer to the currently opened project. At any time a project should be open. */ Project *current(); + /** + * @brief Opens a project file. + * @param url url of the project file + * + * emits projectOpened + */ void openProject(const KUrl &url); + /** @brief Adds a project part to the parts list which is used by projects. */ void registerPart(AbstractProjectPart *part); + /** @brief Returns the registered project parts. */ QList<AbstractProjectPart*> parts(); public slots: + /** @brief Allows to open a project through the open file dialog. */ void execOpenFileDialog(); + /** @brief Calls undo on the command stack of the current project. */ void undoCommand(); + /** @brief Calls redo on the command stack of the current project. */ void redoCommand(); signals: diff --git a/src/core/project/timeline.cpp b/src/core/project/timeline.cpp index ab06e12..103ed4b 100644 --- a/src/core/project/timeline.cpp +++ b/src/core/project/timeline.cpp @@ -27,6 +27,7 @@ Timeline::Timeline(const QString& document, Project* parent) : m_profile = new Mlt::Profile(KdenliveSettings::default_profile().toUtf8().constData()); m_producer = new ProducerWrapper(*m_profile, document, "xml-string"); + // this shouldn't be an assert Q_ASSERT(m_producer && m_producer->is_valid()); Mlt::Service service(m_producer->parent().get_service()); diff --git a/src/core/project/timeline.h b/src/core/project/timeline.h index bed50c0..959ef61 100644 --- a/src/core/project/timeline.h +++ b/src/core/project/timeline.h @@ -27,29 +27,62 @@ namespace Mlt } +/** + * @class Timeline + * @brief Entry point for anything timeline related. Manages a Mlt::Tractor. + */ + + class KDE_EXPORT Timeline : public QObject { Q_OBJECT public: + /** + * @brief Creates a new timeline using the "xml-string" producer. + * @param document mlt xml containing the tractor + * @param parent project this timeline belongs to + */ Timeline(const QString &document, Project* parent); + /** @brief Creates an empty timeline */ Timeline(Project *parent); virtual ~Timeline(); + /** @brief Returns the duration of the timeline. */ int duration() const; + /** @brief Returns a pointer to the project this timeline belongs to. */ Project *project(); + /** + * @brief Returns a list of pointers to the tracks this timeline consists of. + * + * Please note that the track order in Kdenlive is reversed. + */ QList<TimelineTrack *> tracks(); + /** @brief Returns a pointer to the profile used. */ Mlt::Profile *profile(); + /** @brief Returns a pointer to the main producer used. */ ProducerWrapper *producer(); + /** @brief Returns a pointer to the monitor model used for this timeline. */ MonitorModel *monitor(); + /** @brief Returns a pointer to the track with the given index. */ TimelineTrack *track(int index); + /** + * @brief Creates Track objects based on the MLT track producers. + * + * This separate step (from the constructor) is necessary since the project clips need to be + * loaded before their timeline instances however for loading the project clips we need to know + * the project's profile which is determined when loading the tractor. Do not use this function + * anywhere else! + */ void loadTracks(); + /** @brief Emits durationChanged. */ void emitDurationChanged(); + /** @brief Callback for the "producer-changed" event of the main producer to find out about timeline duration changes. */ static void producer_change(mlt_producer producer, Timeline *self); signals: diff --git a/src/core/project/timelinebackground.cpp b/src/core/project/timelinebackground.cpp index d883ecf..8772b92 100644 --- a/src/core/project/timelinebackground.cpp +++ b/src/core/project/timelinebackground.cpp @@ -30,6 +30,8 @@ void TimelineBackground::onTimelineDurationChange() { int duration = m_playlist->get_playtime(); + // if the other tracks were shortened this track prevents us from seing the real timeline duration + // so hide it to find out the real timeline duration m_parent->producer()->block(); m_playlist->set_in_and_out(0, 0); int timelineDuration = m_parent->duration(); diff --git a/src/core/project/timelinebackground.h b/src/core/project/timelinebackground.h index 56da0b5..c82f62a 100644 --- a/src/core/project/timelinebackground.h +++ b/src/core/project/timelinebackground.h @@ -22,6 +22,12 @@ namespace Mlt } +/** + * @class TimelineBackground + * @brief Handles the background track (containing a black clip) and takes care of adjusting its length. + */ + + class TimelineBackground : public QObject { Q_OBJECT diff --git a/src/core/project/timelinetrack.cpp b/src/core/project/timelinetrack.cpp index 3ed035a..e689834 100644 --- a/src/core/project/timelinetrack.cpp +++ b/src/core/project/timelinetrack.cpp @@ -75,10 +75,10 @@ int TimelineTrack::index() const return m_parent->tracks().indexOf(const_cast<TimelineTrack*>(this)); } -int TimelineTrack::mltIndex() const -{ - return 0; -} +// int TimelineTrack::mltIndex() const +// { +// return 0; +// } QList< AbstractTimelineClip* > TimelineTrack::clips() { diff --git a/src/core/project/timelinetrack.h b/src/core/project/timelinetrack.h index bd3280b..2029f79 100644 --- a/src/core/project/timelinetrack.h +++ b/src/core/project/timelinetrack.h @@ -27,57 +27,129 @@ namespace Mlt } +/** + * @class TimelineTrack + * @brief Layer on top of Mlt::Playlist. + */ + + class KDE_EXPORT TimelineTrack : public QObject { Q_OBJECT public: + /** @brief Loads the track and the clips it contains. */ TimelineTrack(ProducerWrapper *producer, Timeline* parent = 0); virtual ~TimelineTrack(); + /** @brief Returns a pointer to the timeline this track is a part of. */ Timeline *timeline(); + /** @brief Returns a pointer to the track producer. */ ProducerWrapper *producer(); + /** @brief Returns a pointer to the track playlist. */ Mlt::Playlist *playlist(); + /** + * @brief Returns the index this track has inside the timeline. + * + * Please note that this does not equal the index of its playlist since the track order in + * Kdenlive is reversed. + */ int index() const; - int mltIndex() const; +// int mltIndex() const; + /** @brief Returns a list of pointers to the clips of this track in the order of their position. */ QList<AbstractTimelineClip*> clips(); + /** + * @brief Returns a pointer to the clip. + * @param index index of the clip to return + * + * The index is the one also used in the playlist so the counting includes blanks. + */ AbstractTimelineClip *clip(int index); + /** + * @brief Returns the index for a clip. + * @param clip pointer to clip for which the index should be returned + * + * @see function clip + */ int clipIndex(AbstractTimelineClip *clip) const; + /** @brief Returns the position in frames of the supplied clip. */ int clipPosition(const AbstractTimelineClip *clip) const; + /** @brief Returns a pointer to the clip in front of the given one (timewise). */ AbstractTimelineClip *before(AbstractTimelineClip *clip); + /** @brief Returns a pointer to the clip following the given one (timewise). */ AbstractTimelineClip *after(AbstractTimelineClip *clip); + /** + * @brief Adjusts the stored clip indices so that they match the ones used in the playlist again. + * @param after if supplied only the indices for the clips following the given clip are adjusted + * @param by amount to move indices by; if 0 the clips are automatically aligned with the entries in the playlist + * + * Does not consider changes to the order! Only useful when blanks were inserted or removed. + * @see adjustIndices + */ void adjustIndices(AbstractTimelineClip *after = 0, int by = 0); + /** + * @brief Assigns a new index to the clip + * @param clip clip whose index should be changed + * @param index new index for the clip + * + * Indices of other clips are also adjusted in the process (but no changes to the order are + * considered there). + */ void setClipIndex(AbstractTimelineClip *clip, int index); + /** @brief Returns the (displayable) name. */ QString name() const; + /** @brief Sets the displayable name. */ void setName(const QString &name); + /** @brief Returns whether this track is hidden (=shows no video content). */ bool isHidden() const; + /** @brief Returns whether this track is muted. */ bool isMute() const; + /** + * @brief Returns whether this track is locked. + * + * Does this really belong here? It's mainly GUI related... + */ bool isLocked() const; enum Types { VideoTrack, AudioTrack }; + /** @brief Returns the type of this track. */ Types type() const; + /** + * @brief Sets the track type. + * + * WARNING: not yet implemented + */ void setType(Types type); + /** @brief Emits nameChanged. */ void emitNameC... [truncated message content] |