unity.scopes.qt.QScopeBase

Base class for a scope implementation. More...

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

Inheritance diagram for unity::scopes::qt::QScopeBase: src="https://assets.ubuntu.com/v1/ce4e3fa1-classunity_1_1scopes_1_1qt_1_1_q_scope_base__inherit__graph.png" border="0" alt="Inheritance graph"/>

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 QScopeBase, for example:

<span class="preprocessor">#include &lt;unity/scopes/qt/QScopeBase.h&gt;</span>
<span class="keyword">class </span>MyScope : <span class="keyword">public</span> <a class="code" href="index.html">unity::scopes::qt::QScopeBase</a>
{
<span class="keyword">public</span>:
MyScope();
<span class="keyword">virtual</span> ~MyScope();
<span class="keyword">virtual</span> <span class="keywordtype">void</span> <a class="code" href="#a948bd6ed6f465292db9ffb0eff11f1de">start</a>(QString <span class="keyword">const</span>&amp; scope_id);       <span class="comment">// Optional</span>
<span class="keyword">virtual</span> <span class="keywordtype">void</span> <a class="code" href="#a4cd139ca1b5cb8a1943b39d0729d8ca5">stop</a>();                               <span class="comment">// Optional</span>
<span class="comment">// ...</span>
};

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

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:

<span class="comment">// You must provide a function that creates your scope on the heap and</span>
<span class="comment">// pass this function to the QScopeBaseAPI constructor.</span>
<a class="code" href="index.html">unity::scopes::qt::QScopeBase</a> *create_my_scope()
{
<span class="keywordflow">return</span> <span class="keyword">new</span> MyScope();
}
<a class="code" href="unity.scopes.ScopeBase.md">unity::scopes::ScopeBase</a>*
UNITY_SCOPE_CREATE_FUNCTION()
{
<span class="comment">// You must return a dynamically allocated QScopeBaseAPI instance here.</span>
<span class="comment">// In turn, that instance calls your creation function to instantiate</span>
<span class="comment">// your scope in the correct Qt thread.</span>
<span class="keywordflow">return</span> <span class="keyword">new</span> QScopeBaseAPI(create_my_scope);
}
<span class="comment">// The runtime, once it has stopped your scope, calls the destroy function.</span>
<span class="keywordtype">void</span>
UNITY_SCOPE_DESTROY_FUNCTION(unity::scopes::ScopeBase* scope)
{
<span class="keyword">delete</span> scope;
}

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.

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