Unity Scopes API
unity::scopes::qt::QScopeBase Class Referenceabstract

Base class for a scope implementation. More...

#include <unity/scopes/qt/QScopeBase.h>

Inheritance diagram for unity::scopes::qt::QScopeBase:

Public Member Functions

virtual void start (QString const &)
 
virtual void stop ()
 
virtual QPreviewQueryBase::UPtr preview (const QResult &, const QActionMetadata &)=0
 
virtual QSearchQueryBase::UPtr search (unity::scopes::CannedQuery const &q, unity::scopes::SearchMetadata const &)=0
 

Detailed Description

Base class for a scope implementation.

Scopes are accessed by the scopes run time as a shared library (one library per scope). Each scope must implement a class that derives from ScopeBase, for example:

class MyScope : public unity::scopes::qt::QScopeBase
{
public:
MyScope();
virtual ~MyScope();
virtual void start(QString const& scope_id); // Optional
virtual void stop(); // Optional
virtual void run(); // Optional
// ...
};

In addition, the library must provide two functions with "C" linkage:

  • a create function that must return a pointer to the derived instance
  • a destroy function that is passed the pointer returned by the create function

Typically, the create and destroy functions will simply call new and delete, respectively. (However, there is no requirement that the derived class instance must be heap-allocated.) If the create function throws an exception, the destroy function will not be called. If the create function returns NULL, the destroy function will be called with NULL as its argument.

Rather than hard-coding the names of the functions, use the UNITY_SCOPE_CREATE_FUNCTION and UNITY_SCOPE_DESTROY_FUNCTION macros, for example:

// You must provide a function that creates your own scope
// That function must have no parameters and return a pointer to QScopeBase
{
return new MyScope();
}
{
// Initialize scope. This line is mandatory, you should pass your creation scope function to
// the class QScopeBaseAPI, which will instantiate your class in the correct Qt Thread.
return new QScopeBaseAPI(create_my_scope);
}
void
{
}

After the scopes run time has obtained a pointer to the class instance from the create function, it calls start(), which allows the scope to initialize itself. This is followed by a call to run(). All calls to the methods of this class will be done from the main QThread.

The scope implementation, if it does not return from run(), is expected to return from run() in response to a call to stop() in a timely manner.

Member Function Documentation

virtual QPreviewQueryBase::UPtr unity::scopes::qt::QScopeBase::preview ( const QResult ,
const QActionMetadata  
)
pure virtual

Called each time a new preview is requested

virtual QSearchQueryBase::UPtr unity::scopes::qt::QScopeBase::search ( unity::scopes::CannedQuery const &  q,
unity::scopes::SearchMetadata const &   
)
pure virtual

Called each time a new query is requested

void QScopeBase::start ( QString const &  start_string)
virtual

Called once at startup

void QScopeBase::stop ( )
virtual

Called at shutdown


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