#include <Plugin.h>

Inheritance diagram for Kwave::Plugin:

Collaboration diagram for Kwave::Plugin:

Public Slots
virtual void	setProgressDialogEnabled (bool enable)

virtual void	updateProgress (qreal progress)

virtual void	cancel ()

virtual void	close ()

void	release ()

Signals
void	sigRunning (Kwave::Plugin *plugin)

void	sigDone (Kwave::Plugin *plugin)

void	sigClosed (Kwave::Plugin *p)

void	sigCommand (const QString &command)

void	setProgressText (const QString &text)

Public Member Functions
	Plugin (QObject *parent, const QVariantList &args)

virtual	~Plugin () Q_DECL_OVERRIDE

virtual QString	name () const

virtual QString	description () const

virtual QString	progressText ()

virtual bool	canClose () const

bool	isRunning () const

bool	shouldStop () const

virtual void	load (QStringList &params)

virtual void	unload ()

virtual QStringList *	setup (QStringList &previous_params)

virtual int	start (QStringList &params)

virtual int	stop ()

virtual void	run (QStringList params)

Kwave::PluginManager &	manager () const

Kwave::SignalManager &	signalManager ()

QWidget *	parentWidget () const

QString	signalName ()

virtual sample_index_t	signalLength ()

virtual double	signalRate ()

virtual const QList< unsigned int >	selectedTracks ()

virtual sample_index_t	selection (QList< unsigned int > tracks=Q_NULLPTR, sample_index_t left=Q_NULLPTR, sample_index_t *right=Q_NULLPTR, bool expand_if_empty=false)

virtual void	selectRange (sample_index_t offset, sample_index_t length)

virtual void	migrateToActiveContext ()

Public Member Functions inherited from Kwave::Runnable
virtual	~Runnable ()

Protected Member Functions
int	execute (QStringList &params)

void	emitCommand (const QString &command)

void	use ()

void	setPluginManager (Kwave::PluginManager *new_plugin_manager)

virtual void	run_wrapper (const QVariant &params) Q_DECL_OVERRIDE

Private Slots
void	closeProgressDialog (Kwave::Plugin *)

void	updateProgressTick ()

Private Attributes
Kwave::PluginManager *	m_plugin_manager

QString	m_name

QString	m_description

Kwave::WorkerThread *	m_thread

QMutex	m_thread_lock

bool	m_progress_enabled

QAtomicInt	m_stop

QProgressDialog *	m_progress

Kwave::ConfirmCancelProxy *	m_confirm_cancel

unsigned int	m_usage_count

QMutex	m_usage_lock

QTimer	m_progress_timer

qreal	m_current_progress

QMutex	m_progress_lock

Friends
class	Kwave::PluginManager

class	Kwave::WorkerThread

Detailed Description

Generic class that should be used for all types of Kwave plugins. This interface is the only one that should be used, it provides all necessary functions to access the functionality of the main Kwave program.

Definition at line 75 of file Plugin.h.

Constructor & Destructor Documentation

◆ Plugin()

Kwave::Plugin::Plugin	(	QObject *	parent,
		const QVariantList &	args
	)

Constructor

Parameters

parent	pointer to our plugin manager
args	argument list for initializing the plugin

Definition at line 71 of file Plugin.cpp.

References Kwave::connect(), m_plugin_manager, m_progress_timer, and updateProgressTick().

     :QObject(Q_NULLPTR),
      Kwave::Runnable(),
      m_plugin_manager(qobject_cast<Kwave::PluginManager *>(parent)),
      m_name(args[0].toString()),
      m_description(args[1].toString()),
      m_thread(Q_NULLPTR),
      m_thread_lock(),
      m_progress_enabled(true),
      m_stop(0),
      m_progress(Q_NULLPTR),
      m_confirm_cancel(Q_NULLPTR),
      m_usage_count(1),
      m_usage_lock(),
      m_progress_timer(),
      m_current_progress(-1),
      m_progress_lock(QMutex::Recursive)
 {
     Q_ASSERT(m_plugin_manager);
     connect(&m_progress_timer, SIGNAL(timeout()),
             this, SLOT(updateProgressTick()),
             Qt::DirectConnection);
 }

Here is the call graph for this function:

◆ ~Plugin()

Kwave::Plugin::~Plugin ( )

virtual

Destructor.

Definition at line 96 of file Plugin.cpp.

References close(), closeProgressDialog(), m_thread, m_thread_lock, m_usage_lock, and Kwave::WorkerThread::stop().

 {
     // inform our owner that we close. This allows the plugin to
     // delete itself
     close();
 
     // lock usage
     QMutexLocker lock_usage(&m_usage_lock);
     {
         QMutexLocker lock_thread(&m_thread_lock);
         if (m_thread) {
             if (m_thread->isRunning()) m_thread->wait(5000);
             if (m_thread->isRunning()) m_thread->stop();
             if (m_thread->isRunning()) m_thread->wait(1000);
             if (m_thread->isRunning()) {
                 // unable to stop the thread
                 qWarning("Kwave::Plugin::stop(): stale thread !");
             }
             delete m_thread;
             m_thread = Q_NULLPTR;
         }
     }
 
     // finally get rid of the confirm/cancel proxy and the progress dialog
     closeProgressDialog(this);
 }

Here is the call graph for this function:

Member Function Documentation

◆ cancel

void Kwave::Plugin::cancel ( )

virtualslot

called when the user has pressed "Cancel" in the progress dialog and also has confirmed the cancel confirmation message box.

Definition at line 325 of file Plugin.cpp.

References m_stop.

Referenced by start(), stop(), Kwave::PlayBackPlugin::testPlayBack(), and Kwave::SonagramPlugin::windowDestroyed().

 {
     m_stop = true;
 }

Here is the caller graph for this function:

◆ canClose()

bool Kwave::Plugin::canClose ( ) const

virtual

Returns true if the plugin can be closed. The default implementation returns "!isRunning()"

Definition at line 351 of file Plugin.cpp.

References isRunning().

 {
     return !isRunning();
 }

Here is the call graph for this function:

◆ close

void Kwave::Plugin::close ( )

virtualslot

Called to close the plugin. This will be called from the plugin manager and can as well be used from inside the plugin if it wishes to close itself.

Definition at line 394 of file Plugin.cpp.

References closeProgressDialog(), m_thread, and stop().

Referenced by Kwave::SonagramPlugin::start(), Kwave::PlayBackPlugin::testPlayBack(), and ~Plugin().

 {
     // only call stop() if we are NOT in the worker thread / run function !
     if (m_thread && m_thread->isRunning() &&
         (QThread::currentThread() != m_thread) )
     {
         // check: this must be called from the GUI thread only!
         Q_ASSERT(this->thread() == QThread::currentThread());
         Q_ASSERT(this->thread() == qApp->thread());
 
         closeProgressDialog(this);
         stop();
     } else if ((QThread::currentThread() == m_thread)) {
         qWarning("Kwave::Plugin::close -> called from worker thread?");
     }
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ closeProgressDialog

void Kwave::Plugin::closeProgressDialog ( Kwave::Plugin * )

privateslot

closes the progress dialog and the confirm/cancel proxy

Definition at line 293 of file Plugin.cpp.

References m_confirm_cancel, m_progress, m_progress_lock, and m_progress_timer.

Referenced by close(), start(), and ~Plugin().

 {
     // check: this must be called from the GUI thread only!
     Q_ASSERT(this->thread() == QThread::currentThread());
     Q_ASSERT(this->thread() == qApp->thread());
 
     QMutexLocker lock(&m_progress_lock);
 
     // stop the progress timer
     m_progress_timer.stop();
     m_progress_timer.disconnect();
 
     if (m_confirm_cancel) m_confirm_cancel->disconnect();
     if (m_progress)       m_progress->disconnect();
 
     // NOTE: as the progress dialog is *modal*, it is higly probable
     //       that this function is called from the context of the event
     //       loop that is provided by the progress dialog
     //       => deleting this object should be done somewhere later...
     if (m_confirm_cancel) {
         m_confirm_cancel->deleteLater();
         m_confirm_cancel = Q_NULLPTR;
     }
 
     if (m_progress) {
         m_progress->done(0);
         m_progress->deleteLater();
         m_progress = Q_NULLPTR;
     }
 }

Here is the caller graph for this function:

◆ description()

QString Kwave::Plugin::description ( ) const

virtual

Returns the description of the plugin (already translated).

Definition at line 202 of file Plugin.cpp.

References m_description.

Referenced by Kwave::SaveBlocksPlugin::setup(), and Kwave::K3BExportPlugin::setup().

 {
     return m_description;
 }

Here is the caller graph for this function:

◆ emitCommand()

void Kwave::Plugin::emitCommand ( const QString & command )

protected

emits a sigCommand()

Definition at line 510 of file Plugin.cpp.

References Kwave::PluginManager::enqueueCommand(), and manager().

Referenced by Kwave::FileInfoPlugin::apply(), Kwave::MP3CodecPlugin::load(), Kwave::StringEnterPlugin::load(), Kwave::K3BExportPlugin::load(), Kwave::RecordPlugin::resetRecording(), Kwave::NewSignalPlugin::setup(), Kwave::SaveBlocksPlugin::setup(), Kwave::AmplifyFreePlugin::setup(), Kwave::SelectRangePlugin::setup(), Kwave::GotoPluginBase::setup(), Kwave::StringEnterPlugin::setup(), Kwave::K3BExportPlugin::setup(), Kwave::GotoPluginBase::start(), and Kwave::RecordPlugin::startRecording().

 {
     manager().enqueueCommand(command);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ execute()

int Kwave::Plugin::execute ( QStringList & params )

protected

Gets called to execute the plugin's run function in a separate thread.

Parameters

params list of strings with parameters

Bug:: the return value is never evaluated

Definition at line 331 of file Plugin.cpp.

References m_stop, m_thread, m_thread_lock, Kwave::WorkerThread::start(), and use().

Referenced by Kwave::FilterPlugin::startPreListen(), and Kwave::PlayBackPlugin::testPlayBack().

 {
     QMutexLocker lock(&m_thread_lock);
     m_stop = false;
 
     m_thread = new(std::nothrow) Kwave::WorkerThread(this, QVariant(params));
     Q_ASSERT(m_thread);
     if (!m_thread) return -ENOMEM;
 
     // increment the use count, it is decremented at the end of
     // the run_wrapper when the thread is finished
     use();
 
     // start the thread, this executes run()
     m_thread->start();
 
     return 0;
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isRunning()

bool Kwave::Plugin::isRunning ( ) const

Returns true if the plugin has a running thread.

Definition at line 357 of file Plugin.cpp.

References m_thread.

Referenced by canClose(), and Kwave::PlayBackPlugin::testPlayBack().

 {
     return (m_thread) && m_thread->isRunning();
 }

Here is the caller graph for this function:

◆ load()

void Kwave::Plugin::load ( QStringList & params )

virtual

Called after the plugin has been loaded into memory. This is useful for plugins that don't use start() and execute(), maybe for some persistent plugins like playback and record. The default implementation does nothing.

Reimplemented in Kwave::K3BExportPlugin, Kwave::PlayBackPlugin, Kwave::CodecPlugin, Kwave::MemoryPlugin, Kwave::DebugPlugin, Kwave::StringEnterPlugin, and Kwave::MP3CodecPlugin.

Definition at line 124 of file Plugin.cpp.

125 {

126 }

◆ manager()

Kwave::PluginManager & Kwave::Plugin::manager ( ) const

Returns a reference to the manager of this plugin.

Definition at line 437 of file Plugin.cpp.

References m_plugin_manager.

Referenced by Kwave::NoisePlugin::createDialog(), emitCommand(), migrateToActiveContext(), parentWidget(), Kwave::RecordPlugin::resetRecording(), Kwave::ReversePlugin::run(), Kwave::K3BExportPlugin::saveBlocks(), selection(), selectRange(), Kwave::VolumePlugin::setup(), Kwave::SelectRangePlugin::setup(), Kwave::RecordPlugin::setup(), Kwave::PlayBackPlugin::setup(), signalLength(), signalManager(), signalRate(), Kwave::AboutPlugin::start(), Kwave::SonagramPlugin::start(), Kwave::FilterPlugin::startPreListen(), and Kwave::PlayBackPlugin::testPlayBack().

 {
     Q_ASSERT(m_plugin_manager);
     return *m_plugin_manager;
 }

Here is the caller graph for this function:

◆ migrateToActiveContext()

void Kwave::Plugin::migrateToActiveContext ( )

virtual

Migrates this plugin instance to the currently active file context. This might be necessary for plugins that create a new file context and then expect that all operations are executed in the context of that new file context. Example: the record plugin creates a new context and does recording into that new created file context.

Definition at line 516 of file Plugin.cpp.

References manager(), and Kwave::PluginManager::migratePluginToActiveContext().

Referenced by Kwave::RecordPlugin::resetRecording(), and Kwave::RecordPlugin::startRecording().

 {
     manager().migratePluginToActiveContext(this);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ name()

QString Kwave::Plugin::name ( ) const

virtual

Returns the name of the plugin.

Reimplemented in Kwave::AboutPlugin.

Definition at line 196 of file Plugin.cpp.

References m_name.

Referenced by Kwave::RecordPlugin::changeCompression(), Kwave::K3BExportPlugin::createFileName(), Kwave::SaveBlocksPlugin::findBase(), Kwave::SaveBlocksPlugin::firstIndex(), progressText(), run_wrapper(), Kwave::RecordPlugin::setDevice(), Kwave::RecordPlugin::setMethod(), Kwave::SaveBlocksPlugin::setup(), Kwave::RecordPlugin::setup(), Kwave::K3BExportPlugin::setup(), Kwave::SaveBlocksPlugin::start(), Kwave::K3BExportPlugin::start(), stop(), and Kwave::UndoTransactionGuard::UndoTransactionGuard().

 {
     return m_name;
 }

Here is the caller graph for this function:

◆ parentWidget()

QWidget * Kwave::Plugin::parentWidget ( ) const

Returns the parent widget of the plugin. This normally should be a TopWidget of the Kwave main program.

Definition at line 450 of file Plugin.cpp.

References manager(), and Kwave::PluginManager::parentWidget().

 {
     return manager().parentWidget();
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ progressText()

QString Kwave::Plugin::progressText ( )

virtual

Returns a text for the progress dialog if enabled. (already be localized)

Reimplemented in Kwave::FilterPlugin, and Kwave::AmplifyFreePlugin.

Definition at line 208 of file Plugin.cpp.

References name().

Referenced by start().

 {
     return i18n("Running plugin '%1'...", name());
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ release

void Kwave::Plugin::release ( )

slot

decrements the usage counter

Definition at line 420 of file Plugin.cpp.

References m_usage_count, m_usage_lock, and sigClosed().

Referenced by Kwave::PluginManager::pluginDone(), run_wrapper(), Kwave::PluginManager::setupPlugin(), Kwave::PlayBackPlugin::unload(), Kwave::CodecPlugin::unload(), and Kwave::SonagramPlugin::windowDestroyed().

 {
     bool finished = false;
 
     {
         QMutexLocker lock(&m_usage_lock);
         Q_ASSERT(m_usage_count);
         if (m_usage_count) {
             m_usage_count--;
             if (!m_usage_count) finished = true;
         }
     }
 
     if (finished) emit sigClosed(this);
 }

Here is the caller graph for this function:

◆ run()

void Kwave::Plugin::run ( QStringList params )

virtual

Gets called from the plugin's execute function and should be overwritten to perform some action. This function runs in a separate thread!

Parameters

params list of strings with parameters

See also: sigDone

Reimplemented in Kwave::SonagramPlugin, Kwave::FilterPlugin, Kwave::PlayBackPlugin, Kwave::DebugPlugin, Kwave::NormalizePlugin, Kwave::AmplifyFreePlugin, Kwave::VolumePlugin, Kwave::ReversePlugin, Kwave::ZeroPlugin, and Kwave::SampleRatePlugin.

Definition at line 363 of file Plugin.cpp.

Referenced by run_wrapper().

 {
     Q_UNUSED(params);
 }

Here is the caller graph for this function:

◆ run_wrapper()

void Kwave::Plugin::run_wrapper ( const QVariant & params )

protectedvirtual

Wrapper for run() that contains a call to release()

Implements Kwave::Runnable.

Definition at line 369 of file Plugin.cpp.

References DBG, m_stop, name(), release(), run(), sigDone(), and sigRunning().

 {
     // signal that we are running
     emit sigRunning(this);
 
     // start time measurement
     QTime t;
     t.start();
 
     // call the plugin's run function in this worker thread context
     run(params.toStringList());
 
     // evaluate the elapsed time
     double seconds = static_cast<double>(t.elapsed()) * 1E-3;
     qDebug("plugin %s done, running for %0.03g seconds",
            DBG(name()), seconds);
 
     // emit the "done" signal
     emit sigDone(this);
 
     m_stop = false;
     release();
 }

Here is the call graph for this function:

◆ selectedTracks()

const QList< unsigned int > Kwave::Plugin::selectedTracks ( )

virtual

Returns an array of indices of currently selected channels.

Definition at line 474 of file Plugin.cpp.

References Kwave::SignalManager::selectedTracks(), and signalManager().

Referenced by Kwave::VolumePlugin::run(), Kwave::AmplifyFreePlugin::run(), and Kwave::FilterPlugin::startPreListen().

 {
     return signalManager().selectedTracks();
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ selection()

sample_index_t Kwave::Plugin::selection	(	QList< unsigned int > *	tracks = `Q_NULLPTR`,
		sample_index_t *	left = `Q_NULLPTR`,
		sample_index_t *	right = `Q_NULLPTR`,
		bool	expand_if_empty = `false`
	)

virtual

Returns the left and right sample index of the current selection in samples from 1 to (size-1). The left and right samples are included in the selection and might be equal. The left is always less or equal than the right. Note that there is always at least one sample selected!

Parameters

tracks	received a list of selected tracks (optional or null-pointer)
left	receives the first selected sample (optional or null-pointer)
right	receives the last selected sample (optional or null-pointer)
expand_if_empty	if set to true, the selection will be made equal to the whole signal if left==right

Returns: the number of selected samples (right-left+1) [1..length]

Definition at line 480 of file Plugin.cpp.

References manager(), Kwave::SignalManager::selectedTracks(), Kwave::PluginManager::selectionEnd(), Kwave::PluginManager::selectionStart(), Kwave::PluginManager::signalLength(), and signalManager().

Referenced by Kwave::NoisePlugin::createDialog(), Kwave::SampleRatePlugin::run(), Kwave::ReversePlugin::run(), Kwave::ZeroPlugin::run(), Kwave::VolumePlugin::run(), Kwave::AmplifyFreePlugin::run(), Kwave::NormalizePlugin::run(), Kwave::FilterPlugin::run(), Kwave::SaveBlocksPlugin::scanBlocksToSave(), Kwave::VolumePlugin::setup(), Kwave::SaveBlocksPlugin::setup(), Kwave::K3BExportPlugin::setup(), Kwave::SaveBlocksPlugin::start(), Kwave::K3BExportPlugin::start(), Kwave::SonagramPlugin::start(), and start().

 {
     sample_index_t l = manager().selectionStart();
     sample_index_t r = manager().selectionEnd();
 
     // expand to the whole signal if left==right and expand_if_empty is set
     if ((l == r) && (expand_if_empty)) {
         l = 0;
         r = manager().signalLength();
         if (r) r--;
     }
 
     // get the list of selected tracks
     if (tracks) *tracks = signalManager().selectedTracks();
 
     if (left)  *left  = l;
     if (right) *right = r;
     return (r != l) ? (r - l + 1) : 0;
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ selectRange()

void Kwave::Plugin::selectRange	(	sample_index_t	offset,
		sample_index_t	length
	)

virtual

Sets the current start and length of the selection to new values.

Parameters

offset	index of the first sample
length	number of samples

Definition at line 504 of file Plugin.cpp.

References manager(), and Kwave::PluginManager::selectRange().

Referenced by Kwave::SaveBlocksPlugin::start(), and Kwave::SelectRangePlugin::start().

 {
     manager().selectRange(offset, length);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setPluginManager()

void Kwave::Plugin::setPluginManager ( Kwave::PluginManager * new_plugin_manager )

protected

assign this plugin to a new plugin manager (when migrating)

Definition at line 522 of file Plugin.cpp.

References m_confirm_cancel, m_plugin_manager, m_progress, and Kwave::PluginManager::parentWidget().

Referenced by Kwave::PluginManager::migratePluginToActiveContext().

 {
     Q_ASSERT(new_plugin_manager);
     if (!new_plugin_manager) return;
     m_plugin_manager = new_plugin_manager;
 
     if (m_progress)
         m_progress->setParent(m_plugin_manager->parentWidget());
     if (m_confirm_cancel)
         m_confirm_cancel->setParent(m_plugin_manager->parentWidget());
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setProgressDialogEnabled

void Kwave::Plugin::setProgressDialogEnabled ( bool enable )

virtualslot

Switches the support for a progress dialog on [default] or off

Definition at line 254 of file Plugin.cpp.

References m_progress_enabled.

Referenced by Kwave::FilterPlugin::startPreListen(), and Kwave::FilterPlugin::stopPreListen().

 {
     m_progress_enabled = enable;
 }

Here is the caller graph for this function:

◆ setProgressText

void Kwave::Plugin::setProgressText ( const QString & text )

signal

Sets the text of the progress dialog

Parameters

text	new progress bar text, already be localized

Referenced by Kwave::SampleRatePlugin::run(), Kwave::NormalizePlugin::run(), and start().

Here is the caller graph for this function:

◆ setup()

QStringList * Kwave::Plugin::setup ( QStringList & previous_params )

virtual

Sets up all necessary parameters for executing the plugin. Could be overwritten and show a dialog box. This only will be called if currently no parameters are given from the function that loads the plugin (the normal case) but not in the context of replaying a previously recorded macro.

Parameters

previous_params the parameters of a previous call, could be used to initialize the controls of a setup dialog

Returns: a string list with all parameters, an empty list (if nothing has to be set up) or null if the setup (dialog) has been aborted and the plugin should not get executed

Reimplemented in Kwave::SonagramPlugin, Kwave::FilterPlugin, Kwave::K3BExportPlugin, Kwave::PlayBackPlugin, Kwave::RecordPlugin, Kwave::DebugPlugin, Kwave::MemoryPlugin, Kwave::StringEnterPlugin, Kwave::AmplifyFreePlugin, Kwave::GotoPluginBase, Kwave::SelectRangePlugin, Kwave::MP3CodecPlugin, Kwave::SaveBlocksPlugin, Kwave::VolumePlugin, Kwave::NewSignalPlugin, and Kwave::FileInfoPlugin.

Definition at line 134 of file Plugin.cpp.

Referenced by Kwave::PluginManager::setupPlugin().

 {
     QStringList *result = new QStringList();
     Q_ASSERT(result);
     return result;
 }

Here is the caller graph for this function:

◆ shouldStop()

bool Kwave::Plugin::shouldStop ( ) const

inline

Returns true if the plugin should stop, e.g. when the user has pressed "cancel"

Definition at line 120 of file Plugin.h.

Referenced by Kwave::NormalizePlugin::getMaxPower(), Kwave::SonagramPlugin::makeAllValid(), Kwave::SampleRatePlugin::run(), Kwave::ZeroPlugin::run(), Kwave::ReversePlugin::run(), Kwave::VolumePlugin::run(), Kwave::AmplifyFreePlugin::run(), Kwave::NormalizePlugin::run(), Kwave::DebugPlugin::run(), Kwave::PlayBackPlugin::run(), and Kwave::FilterPlugin::run().

120 { return m_stop; }

Kwave::Plugin::m_stop

QAtomicInt m_stop

Definition: Plugin.h:367

Here is the caller graph for this function:

◆ sigClosed

void Kwave::Plugin::sigClosed ( Kwave::Plugin * p )

signal

will be emitted in the plugin's destructor

Referenced by release(), and Kwave::SonagramPlugin::start().

Here is the caller graph for this function:

◆ sigCommand

void Kwave::Plugin::sigCommand ( const QString & command )

signal

can be used by plugins to execute toplevel commands

◆ sigDone

void Kwave::Plugin::sigDone ( Kwave::Plugin * plugin )

signal

will be emitted when the "run" function has finished

See also: run

Referenced by run_wrapper(), Kwave::FilterPlugin::setup(), start(), and Kwave::PlayBackPlugin::testPlayBack().

Here is the caller graph for this function:

◆ signalLength()

sample_index_t Kwave::Plugin::signalLength ( )

virtual

Returns the length of the current signal in samples. If no signal is present the return value will be zero.

Definition at line 462 of file Plugin.cpp.

References manager(), and Kwave::PluginManager::signalLength().

Referenced by Kwave::RecordPlugin::recordStopped(), Kwave::SampleRatePlugin::run(), Kwave::ZeroPlugin::run(), Kwave::DebugPlugin::run(), Kwave::SaveBlocksPlugin::scanBlocksToSave(), Kwave::K3BExportPlugin::scanBlocksToSave(), Kwave::SaveBlocksPlugin::setup(), Kwave::GotoPluginBase::setup(), Kwave::SelectRangePlugin::setup(), Kwave::K3BExportPlugin::setup(), Kwave::SaveBlocksPlugin::start(), Kwave::GotoPluginBase::start(), Kwave::SelectRangePlugin::start(), and Kwave::K3BExportPlugin::start().

 {
     return manager().signalLength();
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ signalManager()

Kwave::SignalManager & Kwave::Plugin::signalManager ( )

Returns a reference to the current signal manager

Definition at line 444 of file Plugin.cpp.

References manager(), and Kwave::PluginManager::signalManager().

Referenced by Kwave::FileInfoPlugin::apply(), Kwave::PlayBackPlugin::createDevice(), Kwave::SaveBlocksPlugin::createFileName(), Kwave::NormalizePlugin::getMaxPower(), Kwave::SonagramPlugin::makeAllValid(), Kwave::RecordPlugin::recordStopped(), Kwave::ReversePlugin::reverseSlice(), Kwave::SampleRatePlugin::run(), Kwave::ReversePlugin::run(), Kwave::ZeroPlugin::run(), Kwave::VolumePlugin::run(), Kwave::AmplifyFreePlugin::run(), Kwave::NormalizePlugin::run(), Kwave::DebugPlugin::run(), Kwave::FilterPlugin::run(), Kwave::K3BExportPlugin::saveBlocks(), Kwave::K3BExportPlugin::saveDocumentData(), Kwave::SaveBlocksPlugin::scanBlocksToSave(), Kwave::K3BExportPlugin::scanBlocksToSave(), selectedTracks(), selection(), Kwave::FileInfoPlugin::setup(), Kwave::RecordPlugin::setup(), Kwave::PlayBackPlugin::setup(), signalName(), Kwave::SaveBlocksPlugin::start(), Kwave::SonagramPlugin::start(), and Kwave::RecordPlugin::startRecording().

 {
     return manager().signalManager();
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ signalName()

QString Kwave::Plugin::signalName ( )

Returns the name of the current signal. This can be used to set the caption of a plugin's main window. If no signal is currently loaded the returned string is empty.

Definition at line 456 of file Plugin.cpp.

References signalManager(), and Kwave::SignalManager::signalName().

Referenced by Kwave::SaveBlocksPlugin::setup(), Kwave::K3BExportPlugin::setup(), and Kwave::SonagramPlugin::start().

 {
     return signalManager().signalName();
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ signalRate()

double Kwave::Plugin::signalRate ( )

virtual

Returns the sample rate of the current signal. If no signal is present the return value will be zero.

Definition at line 468 of file Plugin.cpp.

References manager(), and Kwave::PluginManager::signalRate().

Referenced by Kwave::BandPassPlugin::createDialog(), Kwave::NotchFilterPlugin::createDialog(), Kwave::LowPassPlugin::createDialog(), Kwave::ZeroPlugin::run(), Kwave::DebugPlugin::run(), Kwave::GotoPluginBase::setup(), Kwave::SelectRangePlugin::setup(), Kwave::GotoPluginBase::start(), Kwave::SelectRangePlugin::start(), Kwave::SonagramPlugin::start(), Kwave::BandPassPlugin::updateFilter(), Kwave::NotchFilterPlugin::updateFilter(), Kwave::PitchShiftPlugin::updateFilter(), and Kwave::LowPassPlugin::updateFilter().

 {
     return manager().signalRate();
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sigRunning

void Kwave::Plugin::sigRunning ( Kwave::Plugin * plugin )

signal

will be emitted when the "run" function starts

See also: run

Referenced by run_wrapper().

Here is the caller graph for this function:

◆ start()

int Kwave::Plugin::start ( QStringList & params )

virtual

Is called from the main program before the run() function and can be overwritten to show a window or initialize some things before the run() function gets called.

Parameters

params list of strings with parameters

Returns: an error code if the execution failed or zero if everything was ok.

Reimplemented in Kwave::SonagramPlugin, Kwave::K3BExportPlugin, Kwave::AmplifyFreePlugin, Kwave::SelectRangePlugin, Kwave::GotoPluginBase, Kwave::SaveBlocksPlugin, and Kwave::AboutPlugin.

Definition at line 142 of file Plugin.cpp.

References cancel(), closeProgressDialog(), Kwave::connect(), m_confirm_cancel, m_progress, m_progress_enabled, m_stop, m_thread_lock, parentWidget(), PROGRESS_MAXIMUM, progressText(), selection(), setProgressText(), and sigDone().

Referenced by Kwave::AmplifyFreePlugin::start().

 {
     QMutexLocker lock(&m_thread_lock);
     m_stop = false;
 
     // check: start() must be called from the GUI thread only!
     Q_ASSERT(this->thread() == QThread::currentThread());
     Q_ASSERT(this->thread() == qApp->thread());
 
     // create a progress dialog for processing mode (not used for pre-listen)
     if (m_progress_enabled && !m_progress) {
         m_progress = new QProgressDialog(parentWidget());
         Q_ASSERT(m_progress);
     }
 
     // set up the progress dialog when in processing (not pre-listen) mode
     if (m_progress_enabled && m_progress) {
         sample_index_t first, last;
         QList<unsigned int> tracks;
 
         selection(&tracks, &first, &last, true);
         m_progress->setModal(true);
         m_progress->setVisible(false);
         m_progress->setMinimumDuration(2000);
         m_progress->setAutoClose(false);
         m_progress->setMaximum(PROGRESS_MAXIMUM);
         m_progress->setValue(0);
         m_progress->setLabelText(progressText());
         int h = m_progress->sizeHint().height();
         int w = m_progress->sizeHint().height();
         if (w < 4 * h) w = 4 * h;
         m_progress->setFixedSize(w, h);
 
         // use a "proxy" that asks for confirmation of cancel
         if (!m_confirm_cancel) {
             m_confirm_cancel = new Kwave::ConfirmCancelProxy(m_progress,
                 Q_NULLPTR, Q_NULLPTR, this, SLOT(cancel()));
             Q_ASSERT(m_confirm_cancel);
         }
         connect(m_progress,       SIGNAL(canceled()),
                 m_confirm_cancel, SLOT(cancel()));
         connect(this,             SIGNAL(setProgressText(QString)),
                 m_progress,       SLOT(setLabelText(QString)),
                 Qt::QueuedConnection);
         connect(this, SIGNAL(sigDone(Kwave::Plugin*)),
                 this, SLOT(closeProgressDialog(Kwave::Plugin*)),
                 Qt::QueuedConnection);
         m_progress->setVisible(true);
     }
 
     return 0;
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ stop()

int Kwave::Plugin::stop ( )

virtual

Stops any threads and is called from the close() function and the plugin's destructor.

Definition at line 214 of file Plugin.cpp.

References cancel(), DBG, m_thread, m_thread_lock, name(), and Kwave::WorkerThread::stop().

Referenced by close(), Kwave::FilterPlugin::stopPreListen(), and Kwave::PlayBackPlugin::testPlayBack().

 {
     cancel();
 
     if (m_thread && m_thread->isRunning() &&
         (QThread::currentThread() == m_thread)) {
         qWarning("Kwave::Plugin::stop(): plugin '%s' called stop() from "
                  "within it's own worker thread (from run() ?). "
                  "This would produce a deadlock, PLEASE FIX THIS !",
                  DBG(name()));
 
 #ifdef DEBUG
         qDebug("pthread_self()=%p, tid=%p",
                reinterpret_cast<void *>(QThread::currentThread()),
                reinterpret_cast<void *>(m_thread));
         void *buf[256];
         int n = backtrace(buf, 256);
         backtrace_symbols_fd(buf, n, 2);
 #endif
         return -EBUSY;
     }
 
     {
         QMutexLocker lock(&m_thread_lock);
         if (m_thread) {
             if (m_thread->isRunning()) m_thread->wait(5000);
             if (m_thread->isRunning()) m_thread->stop();
             if (m_thread->isRunning()) m_thread->wait(1000);
             if (m_thread->isRunning()) {
                 // unable to stop the thread
                 qWarning("Kwave::Plugin::stop(): stale thread !");
             }
             delete m_thread;
             m_thread = Q_NULLPTR;
         }
     }
     return 0;
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unload()

void Kwave::Plugin::unload ( )

virtual

Called before the plugin gets unloaded. Can be used by a plugin to do some cleanup tasks before it gets unloaded from memory.

Reimplemented in Kwave::CodecPlugin, and Kwave::PlayBackPlugin.

Definition at line 129 of file Plugin.cpp.

130 {

131 }

◆ updateProgress

void Kwave::Plugin::updateProgress ( qreal progress )

virtualslot

update the progress dialog

Parameters

progress the current progress in percent [0...100]

Definition at line 260 of file Plugin.cpp.

References m_current_progress, m_progress, m_progress_lock, m_progress_timer, PROGRESS_MAXIMUM, and PROGRESS_UPDATES_PER_SECOND.

Referenced by Kwave::SampleRatePlugin::run(), Kwave::ZeroPlugin::run(), Kwave::VolumePlugin::run(), Kwave::AmplifyFreePlugin::run(), Kwave::NormalizePlugin::run(), Kwave::DebugPlugin::run(), Kwave::FilterPlugin::run(), and Kwave::ReversePlugin::updateProgress().

 {
     // check: this must be called from the GUI thread only!
     Q_ASSERT(this->thread() == QThread::currentThread());
     Q_ASSERT(this->thread() == qApp->thread());
 
 //     qDebug("Kwave::Plugin::updateProgress(%0.1f)", progress);
     QMutexLocker lock(&m_progress_lock);
 
     // take over the current progress
     // note: no lock needed, this is called in the GUI thread context!
     m_current_progress = qreal(PROGRESS_MAXIMUM / 100.0) * progress;
 
     // start the timer for updating the progress bar if it is not active
     if (!m_progress_timer.isActive() && m_progress) {
         m_progress_timer.setSingleShot(true);
         m_progress_timer.start(1000 / PROGRESS_UPDATES_PER_SECOND);
     }
 }

Here is the caller graph for this function:

◆ updateProgressTick

void Kwave::Plugin::updateProgressTick ( )

privateslot

updates the progress bar, triggered by timer

Definition at line 281 of file Plugin.cpp.

References m_current_progress, m_progress, m_progress_lock, PROGRESS_MAXIMUM, and Kwave::toInt().

Referenced by Plugin().

 {
     // check: this must be called from the GUI thread only!
     Q_ASSERT(this->thread() == QThread::currentThread());
     Q_ASSERT(this->thread() == qApp->thread());
 
     QMutexLocker lock(&m_progress_lock);
     if (m_progress) m_progress->setValue(
         Kwave::toInt(qBound<double>(0.0, m_current_progress, PROGRESS_MAXIMUM)));
 }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ use()

void Kwave::Plugin::use ( )

protected

increments the usage counter

Definition at line 412 of file Plugin.cpp.

References m_usage_count, and m_usage_lock.

Referenced by execute(), Kwave::CodecPlugin::load(), Kwave::PlayBackPlugin::load(), Kwave::PluginManager::pluginStarted(), and Kwave::SonagramPlugin::start().

 {
     QMutexLocker lock(&m_usage_lock);
     Q_ASSERT(m_usage_count); // should be at least 1 (from constructor)
     m_usage_count++;
 }

Here is the caller graph for this function:

Friends And Related Function Documentation

◆ Kwave::PluginManager

friend class Kwave::PluginManager

friend

Definition at line 254 of file Plugin.h.

◆ Kwave::WorkerThread

friend class Kwave::WorkerThread

friend

Definition at line 339 of file Plugin.h.

Member Data Documentation

◆ m_confirm_cancel

Kwave::ConfirmCancelProxy* Kwave::Plugin::m_confirm_cancel

private

proxy dialog that asks for confirmation if the user pressed cancel in the progress dialog

Definition at line 376 of file Plugin.h.

Referenced by closeProgressDialog(), setPluginManager(), and start().

◆ m_current_progress

qreal Kwave::Plugin::m_current_progress

private

latest progress value [percent]

Definition at line 388 of file Plugin.h.

Referenced by updateProgress(), and updateProgressTick().

◆ m_description

QString Kwave::Plugin::m_description

private

description of the plugin, for GUI purposes, captions etc

Definition at line 353 of file Plugin.h.

Referenced by description().

◆ m_name

QString Kwave::Plugin::m_name

private

name of the plugin, for undo/redo

Definition at line 350 of file Plugin.h.

Referenced by name().

◆ m_plugin_manager

Kwave::PluginManager* Kwave::Plugin::m_plugin_manager

private

reference to the plugin manager

Definition at line 347 of file Plugin.h.

Referenced by manager(), Plugin(), and setPluginManager().

◆ m_progress

QProgressDialog* Kwave::Plugin::m_progress

private

a progress dialog, if the audio processing takes longer...

Definition at line 370 of file Plugin.h.

Referenced by closeProgressDialog(), setPluginManager(), start(), updateProgress(), and updateProgressTick().

◆ m_progress_enabled

bool Kwave::Plugin::m_progress_enabled

private

determines whether a progress dialog should be used in run()

Definition at line 364 of file Plugin.h.

Referenced by setProgressDialogEnabled(), and start().

◆ m_progress_lock

QMutex Kwave::Plugin::m_progress_lock

private

Mutex for locking the progress bar

Definition at line 391 of file Plugin.h.

Referenced by closeProgressDialog(), updateProgress(), and updateProgressTick().

◆ m_progress_timer

QTimer Kwave::Plugin::m_progress_timer

private

timer for updating the progress dialog

Definition at line 385 of file Plugin.h.

Referenced by closeProgressDialog(), Plugin(), and updateProgress().

◆ m_stop

QAtomicInt Kwave::Plugin::m_stop

private

flag for stopping the process (stop if set to non-zero)

Definition at line 367 of file Plugin.h.

Referenced by cancel(), execute(), run_wrapper(), and start().

◆ m_thread

Kwave::WorkerThread* Kwave::Plugin::m_thread

private

Thread that executes the run() member function.

Definition at line 358 of file Plugin.h.

Referenced by close(), execute(), isRunning(), stop(), and ~Plugin().

◆ m_thread_lock

QMutex Kwave::Plugin::m_thread_lock

private

Mutex for control over the thread

Definition at line 361 of file Plugin.h.

Referenced by execute(), start(), stop(), and ~Plugin().

◆ m_usage_count

unsigned int Kwave::Plugin::m_usage_count

private

Usage counter

Definition at line 379 of file Plugin.h.

Referenced by release(), and use().

◆ m_usage_lock

QMutex Kwave::Plugin::m_usage_lock

private

Mutex for locking the usage counter

Definition at line 382 of file Plugin.h.

Referenced by release(), use(), and ~Plugin().

The documentation for this class was generated from the following files:

libkwave/Plugin.h
libkwave/Plugin.cpp

Public Slots

Signals

Public Member Functions

Protected Member Functions

Private Slots

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Plugin()

◆ ~Plugin()

Member Function Documentation

◆ cancel

◆ canClose()

◆ close

◆ closeProgressDialog

◆ description()

◆ emitCommand()

◆ execute()

◆ isRunning()

◆ load()

◆ manager()

◆ migrateToActiveContext()

◆ name()

◆ parentWidget()

◆ progressText()

◆ release

◆ run()

◆ run_wrapper()

◆ selectedTracks()

◆ selection()

◆ selectRange()

◆ setPluginManager()

◆ setProgressDialogEnabled

◆ setProgressText

◆ setup()

◆ shouldStop()

◆ sigClosed

◆ sigCommand

◆ sigDone

◆ signalLength()

◆ signalManager()

◆ signalName()

◆ signalRate()

◆ sigRunning

◆ start()

◆ stop()

◆ unload()

◆ updateProgress

◆ updateProgressTick

◆ use()

Friends And Related Function Documentation

◆ Kwave::PluginManager

◆ Kwave::WorkerThread

Member Data Documentation

◆ m_confirm_cancel

◆ m_current_progress

◆ m_description

◆ m_name

◆ m_plugin_manager

◆ m_progress

◆ m_progress_enabled

◆ m_progress_lock

◆ m_progress_timer

◆ m_stop

◆ m_thread

◆ m_thread_lock

◆ m_usage_count

◆ m_usage_lock