<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>KCompletion</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<link rel="stylesheet" type="text/css" href="../common/doxygen.css" />
<link rel="stylesheet" media="screen" type="text/css" title="KDE Colors" href="../common/kde.css" />
</head>
<body>
<div id="container">
<div id="header">
<div id="header_top">
<div>
<div>
<img alt ="" src="../common/top-kde.jpg"/>
KDE 4.9 PyKDE API Reference
</div>
</div>
</div>
<div id="header_bottom">
<div id="location">
<ul>
<li>KDE's Python API</li>
</ul>
</div>
<div id="menu">
<ul>
<li><a href="../modules.html">Overview</a></li>
<li><a href="http://techbase.kde.org/Development/Languages/Python">PyKDE Home</a></li>
<li><a href="http://kde.org/family/">Sitemap</a></li>
<li><a href="http://kde.org/contact/">Contact Us</a></li>
</ul>
</div>
</div>
</div>
<div id="body_wrapper">
<div id="body">
<div id="right">
<div class="content">
<div id="main">
<div class="clearer"> </div>
<h1>KCompletion Class Reference</h1>
<code>from PyKDE4.kdeui import *</code>
<p>
Inherits: QObject<br />
<h2>Detailed Description</h2>
<p>A generic class for completing QStrings
</p>
<p>
This class offers easy use of "auto-completion", "manual-completion" or
"shell completion" on QString objects. A common use is completing filenames
or URLs (see KUrlCompletion()).
But it is not limited to URL-completion -- everything should be completable!
The user should be able to complete email-addresses, telephone-numbers,
commands, SQL queries, ...
Every time your program knows what the user can type into an edit-field, you
should offer completion. With KCompletion, this is very easy, and if you are
using a line edit widget ( KLineEdit), it is even more easy.
Basically, you tell a KCompletion object what strings should be completable
and whenever completion should be invoked, you call makeCompletion().
KLineEdit and (an editable) KComboBox even do this automatically for you.
</p>
<p>
KCompletion offers the completed string via the signal match() and
all matching strings (when the result is ambiguous) via the method
allMatches().
</p>
<p>
Notice: auto-completion, shell completion and manual completion work
slightly differently:
</p>
<p>
<li> auto-completion always returns a complete item as match. </li>
When more than one matching items are available, it will deliver just
the first (depending on sorting order) item. Iterating over all matches
is possible via nextMatch() and previousMatch().
</p>
<p>
<li> popup-completion works in the same way, the only difference being that </li>
the completed items are not put into the edit-widget, but into a
separate popup-box.
</p>
<p>
<li> manual completion works the same way as auto-completion, the </li>
subtle difference is, that it isn't invoked automatically while the user
is typing, but only when the user presses a special key. The difference
of manual and auto-completion is therefore only visible in UI classes,
KCompletion needs to know whether to deliver partial matches
(shell completion) or whole matches (auto/manual completion), therefore
KGlobalSettings.CompletionMan and
KGlobalSettings.CompletionAuto have the exact same effect in
KCompletion.
</p>
<p>
<li> shell completion works like how shells complete filenames: </li>
when multiple matches are available, the longest possible string of all
matches is returned (i.e. only a partial item).
Iterating over all matching items (complete, not partial) is possible
via nextMatch() and previousMatch().
</p>
<p>
You don't have to worry much about that though, KCompletion handles
that for you, according to the setting setCompletionMode().
The default setting is globally configured by the user and read
from KGlobalSettings.completionMode().
</p>
<p>
A short example:
<pre class="fragment">
KCompletion completion;
completion.setOrder( KCompletion.Sorted );
completion.addItem( "pfeiffer@kde.org" );
completion.addItem( "coolo@kde.org" );
completion.addItem( "carpdjih@sp.zrz.tu-berlin.de" );
completion.addItem( "carp@cs.tu-berlin.de" );
cout << completion.makeCompletion( "ca" ).latin1() << endl;
</pre>
</p>
<p>
In shell-completion-mode, this will be "carp"; in auto-completion-
mode it will be "carp\@cs.tu-berlin.de", as that is alphabetically
smaller.
If setOrder was set to Insertion, "carpdjih\@sp.zrz.tu-berlin.de"
would be completed in auto-completion-mode, as that was inserted before
"carp\@cs.tu-berlin.de".
</p>
<p>
You can dynamically update the completable items by removing and adding them
whenever you want.
For advanced usage, you could even use multiple KCompletion objects. E.g.
imagine an editor like kwrite with multiple open files. You could store
items of each file in a different KCompletion object, so that you know (and
tell the user) where a completion comes from.
</p>
<p>
Note: KCompletion does not work with strings that contain 0x0 characters
(unicode nul), as this is used internally as a delimiter.
</p>
<p>
You may inherit from KCompletion and override makeCompletion() in
special cases (like reading directories/urls and then supplying the
contents to KCompletion, as KUrlCompletion does), but generally, this is
not necessary.
</p>
<p>
<dl class="author" compact><dt><b>Author:</b></dt><dd> Carsten Pfeiffer <pfeiffer@kde.org> </dd></dl>
</p>
<table border="0" cellpadding="0" cellspacing="0"><tr><td colspan="2"><br><h2>Enumerations</h2></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="#CompOrder">CompOrder</a> </td><td class="memItemRight" valign="bottom">{ Sorted, Insertion, Weighted }</td></tr>
<tr><td colspan="2"><br><h2>Signals</h2></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#match">match</a> (QString item)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#matches">matches</a> (QStringList matchlist)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#multipleMatches">multipleMatches</a> ()</td></tr>
<tr><td colspan="2"><br><h2>Methods</h2></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#KCompletion">__init__</a> (self)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#KCompletion">__init__</a> (self, <a href="../kdeui/KCompletion.html">KCompletion</a> a0)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#addItem">addItem</a> (self, QString item)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#addItem">addItem</a> (self, QString item, long weight)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">QStringList </td><td class="memItemRight" valign="bottom"><a class="el" href="#allMatches">allMatches</a> (self)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">QStringList </td><td class="memItemRight" valign="bottom"><a class="el" href="#allMatches">allMatches</a> (self, QString string)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#clear">clear</a> (self)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a href="../kdeui/KGlobalSettings.html#Completion">KGlobalSettings.Completion</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="#completionMode">completionMode</a> (self)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="#hasMultipleMatches">hasMultipleMatches</a> (self)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="#ignoreCase">ignoreCase</a> (self)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#insertItems">insertItems</a> (self, QStringList items)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="#isEmpty">isEmpty</a> (self)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">QStringList </td><td class="memItemRight" valign="bottom"><a class="el" href="#items">items</a> (self)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">QString </td><td class="memItemRight" valign="bottom"><a class="el" href="#lastMatch">lastMatch</a> (self)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">QString </td><td class="memItemRight" valign="bottom"><a class="el" href="#makeCompletion">makeCompletion</a> (self, QString string)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">QString </td><td class="memItemRight" valign="bottom"><a class="el" href="#nextMatch">nextMatch</a> (self)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a href="../kdeui/KCompletion.html#CompOrder">KCompletion.CompOrder</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="#order">order</a> (self)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#postProcessMatch">postProcessMatch</a> (self, QString pMatch)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#postProcessMatches">postProcessMatches</a> (self, QStringList pMatches)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">QString </td><td class="memItemRight" valign="bottom"><a class="el" href="#previousMatch">previousMatch</a> (self)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#removeItem">removeItem</a> (self, QString item)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#setCompletionMode">setCompletionMode</a> (self, <a href="../kdeui/KGlobalSettings.html#Completion">KGlobalSettings.Completion</a> mode)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#setIgnoreCase">setIgnoreCase</a> (self, bool ignoreCase)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#setItems">setItems</a> (self, QStringList list)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#setOrder">setOrder</a> (self, <a href="../kdeui/KCompletion.html#CompOrder">KCompletion.CompOrder</a> order)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#setSoundsEnabled">setSoundsEnabled</a> (self, bool enable)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#slotMakeCompletion">slotMakeCompletion</a> (self, QString string)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#slotNextMatch">slotNextMatch</a> (self)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="#slotPreviousMatch">slotPreviousMatch</a> (self)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="#soundsEnabled">soundsEnabled</a> (self)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">QStringList </td><td class="memItemRight" valign="bottom"><a class="el" href="#substringCompletion">substringCompletion</a> (self, QString string)</td></tr>
</table>
<hr><h2>Signal Documentation</h2><a class="anchor" name="match"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> match</td>
<td>(</td>
<td class="paramtype">QString </td>
<td class="paramname"><em>item</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>The matching item. Will be emitted by makeCompletion(),
previousMatch() or nextMatch(). May be QString() if there
is no matching item.
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>item</em> </td><td> the match, or QString() if there is none
</td></tr>
</table></dl>
<p>
</p><dl compact><dt><b>Signal syntax:</b></dt><dd><code>QObject.connect(source, SIGNAL("match(const QString&)"), target_slot)</code></dd></dl></div></div><a class="anchor" name="matches"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> matches</td>
<td>(</td>
<td class="paramtype">QStringList </td>
<td class="paramname"><em>matchlist</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>All matching items. Will be emitted by makeCompletion() in shell-
completion-mode, when the same string is passed to makeCompletion twice
or more often.
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>matchlist</em> </td><td> the list of matches
</td></tr>
</table></dl>
<p>
</p><dl compact><dt><b>Signal syntax:</b></dt><dd><code>QObject.connect(source, SIGNAL("matches(const QStringList&)"), target_slot)</code></dd></dl></div></div><a class="anchor" name="multipleMatches"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> multipleMatches</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname">)</td>
<td width="100%"> </td>
</tr>
</table>
</div>
<div class="memdoc"><p>This signal is emitted, when calling makeCompletion() and more than
one matching item is found.
<dl class="see" compact><dt><b>See also:</b></dt><dd> hasMultipleMatches
</dd></dl>
</p><dl compact><dt><b>Signal syntax:</b></dt><dd><code>QObject.connect(source, SIGNAL("multipleMatches()"), target_slot)</code></dd></dl></div></div><hr><h2>Method Documentation</h2><a class="anchor" name="KCompletion"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname">__init__</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname"><em>self</em> )</td>
<td width="100%"> </td>
</tr>
</table>
</div>
<div class="memdoc"><p>Constructor, nothing special here :)
</p></div></div><a class="anchor" name="KCompletion"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname">__init__</td>
<td>(</td>
<td class="paramtype"> <em>self</em>, </td>
<td class="paramname"></td>
</tr><tr>
<td class="memname"></td>
<td></td>
<td class="paramtype"><a href="../kdeui/KCompletion.html">KCompletion</a> </td>
<td class="paramname"><em>a0</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>Constructor, nothing special here :)
</p></div></div><a class="anchor" name="addItem"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> addItem</td>
<td>(</td>
<td class="paramtype"> <em>self</em>, </td>
<td class="paramname"></td>
</tr><tr>
<td class="memname"></td>
<td></td>
<td class="paramtype">QString </td>
<td class="paramname"><em>item</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>Adds an item to the list of available completions.
Resets the current item-state ( previousMatch() and nextMatch()
won't work anymore).
</p>
<p>
Sets the weighting of the item to <b>weight</b> or adds it to the current
weighting if the item is already available. The weight has to be greater
than 1 to take effect (default weight is 1).
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>item</em> </td><td> the item to add
<tr><td></td><td valign="top"><em>weight</em> </td><td> the weight of the item, default is 1
</td></tr>
</table></dl>
<p>
</p></div></div><a class="anchor" name="addItem"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> addItem</td>
<td>(</td>
<td class="paramtype"> <em>self</em>, </td>
<td class="paramname"></td>
</tr><tr>
<td class="memname"></td>
<td></td>
<td class="paramtype">QString </td>
<td class="paramname"><em>item</em>, </td>
</tr>
<tr>
<td class="memname"></td>
<td></td>
<td class="paramtype">long </td>
<td class="paramname"><em>weight</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>Adds an item to the list of available completions.
Resets the current item-state ( previousMatch() and nextMatch()
won't work anymore).
</p>
<p>
Sets the weighting of the item to <b>weight</b> or adds it to the current
weighting if the item is already available. The weight has to be greater
than 1 to take effect (default weight is 1).
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>item</em> </td><td> the item to add
<tr><td></td><td valign="top"><em>weight</em> </td><td> the weight of the item, default is 1
</td></tr>
</table></dl>
<p>
</p></div></div><a class="anchor" name="allMatches"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname">QStringList allMatches</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname"><em>self</em> )</td>
<td width="100%"> </td>
</tr>
</table>
</div>
<div class="memdoc"><p>Returns a list of all items matching <b>string.</b>
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>string</em> </td><td> the string to match
</td></tr> </table></dl>
<p> <dl class="return" compact><dt><b>Returns:</b></dt><dd> the list of all matches
</dd></dl>
</p></div></div><a class="anchor" name="allMatches"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname">QStringList allMatches</td>
<td>(</td>
<td class="paramtype"> <em>self</em>, </td>
<td class="paramname"></td>
</tr><tr>
<td class="memname"></td>
<td></td>
<td class="paramtype">QString </td>
<td class="paramname"><em>string</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>Returns a list of all items matching <b>string.</b>
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>string</em> </td><td> the string to match
</td></tr> </table></dl>
<p> <dl class="return" compact><dt><b>Returns:</b></dt><dd> the list of all matches
</dd></dl>
</p></div></div><a class="anchor" name="clear"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> clear</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname"><em>self</em> )</td>
<td width="100%"> </td>
</tr>
</table>
</div>
<div class="memdoc"><p>Removes all inserted items.
</p></div></div><a class="anchor" name="completionMode"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"><a href="../kdeui/KGlobalSettings.html#Completion">KGlobalSettings.Completion</a> completionMode</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname"><em>self</em> )</td>
<td width="100%"> </td>
</tr>
</table>
</div>
<div class="memdoc"><p>Return the current completion mode.
May be different from KGlobalSettings.completionMode(), if you
explicitly called setCompletionMode().
<dl class="return" compact><dt><b>Returns:</b></dt><dd> the current completion mode
</dd></dl> <dl class="see" compact><dt><b>See also:</b></dt><dd> setCompletionMode
</dd></dl>
</p></div></div><a class="anchor" name="hasMultipleMatches"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname">bool hasMultipleMatches</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname"><em>self</em> )</td>
<td width="100%"> </td>
</tr>
</table>
</div>
<div class="memdoc"><p>Returns true when more than one match is found.
<dl class="return" compact><dt><b>Returns:</b></dt><dd> true if there are more than one match
</dd></dl> <dl class="see" compact><dt><b>See also:</b></dt><dd> multipleMatches
</dd></dl>
</p></div></div><a class="anchor" name="ignoreCase"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname">bool ignoreCase</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname"><em>self</em> )</td>
<td width="100%"> </td>
</tr>
</table>
</div>
<div class="memdoc"><p>Return whether KCompletion acts case insensitively or not.
Default is false (case sensitive).
<dl class="return" compact><dt><b>Returns:</b></dt><dd> true if the case will be ignored
</dd></dl> <dl class="see" compact><dt><b>See also:</b></dt><dd> setIgnoreCase
</dd></dl>
</p></div></div><a class="anchor" name="insertItems"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> insertItems</td>
<td>(</td>
<td class="paramtype"> <em>self</em>, </td>
<td class="paramname"></td>
</tr><tr>
<td class="memname"></td>
<td></td>
<td class="paramtype">QStringList </td>
<td class="paramname"><em>items</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>Inserts <b>items</b> into the list of possible completions.
Does the same as setItems(), but does not call clear() before.
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>items</em> </td><td> the items to insert
</td></tr>
</table></dl>
<p>
</p></div></div><a class="anchor" name="isEmpty"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname">bool isEmpty</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname"><em>self</em> )</td>
<td width="100%"> </td>
</tr>
</table>
</div>
<div class="memdoc"><p>Returns true when the completion object contains no entries.
</p></div></div><a class="anchor" name="items"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname">QStringList items</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname"><em>self</em> )</td>
<td width="100%"> </td>
</tr>
</table>
</div>
<div class="memdoc"><p>Returns a list of all items inserted into KCompletion. This is useful
if you need to save the state of a KCompletion object and restore it
later.
</p>
<p>
Important note: when order() == Weighted, then every item in the
stringlist has its weight appended, delimited by a colon. E.g. an item
"www.kde.org" might look like "www.kde.org:4", where 4 is the weight.
</p>
<p>
This is necessary so that you can save the items along with its
weighting on disk and load them back with setItems(), restoring its
weight as well. If you really don't want the appended weightings, call
setOrder( KCompletion.Insertion )
before calling items().
</p>
<p>
<dl class="return" compact><dt><b>Returns:</b></dt><dd> a list of all items
</dd></dl> <dl class="see" compact><dt><b>See also:</b></dt><dd> setItems
</dd></dl>
</p></div></div><a class="anchor" name="lastMatch"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname">QString lastMatch</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname"><em>self</em> )</td>
<td width="100%"> </td>
</tr>
</table>
</div>
<div class="memdoc"><p>Returns the last match. Might be useful if you need to check whether
a completion is different from the last one.
<dl class="return" compact><dt><b>Returns:</b></dt><dd> the last match. QString() is returned when there is no
last match.
</dd></dl>
</p></div></div><a class="anchor" name="makeCompletion"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname">QString makeCompletion</td>
<td>(</td>
<td class="paramtype"> <em>self</em>, </td>
<td class="paramname"></td>
</tr><tr>
<td class="memname"></td>
<td></td>
<td class="paramtype">QString </td>
<td class="paramname"><em>string</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>Attempts to find an item in the list of available completions,
that begins with <b>string.</b> Will either return the first matching item
(if there is more than one match) or QString(), if no match was
found.
</p>
<p>
In the latter case, a sound will be issued, depending on
soundsEnabled().
If a match was found, it will also be emitted via the signal
match().
</p>
<p>
If this is called twice or more often with the same string while no
items were added or removed in the meantime, all available completions
will be emitted via the signal #matches().
This happens only in shell-completion-mode.
</p>
<p>
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>string</em> </td><td> the string to complete
</td></tr> </table></dl>
<p> <dl class="return" compact><dt><b>Returns:</b></dt><dd> the matching item, or QString() if there is no matching
item.
</dd></dl> <dl class="see" compact><dt><b>See also:</b></dt><dd> slotMakeCompletion
</dd></dl> <dl class="see" compact><dt><b>See also:</b></dt><dd> substringCompletion
</dd></dl>
</p></div></div><a class="anchor" name="nextMatch"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname">QString nextMatch</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname"><em>self</em> )</td>
<td width="100%"> </td>
</tr>
</table>
</div>
<div class="memdoc"><p>Returns the next item from the matching-items-list.
When reaching the last item, the list is rotated, so it will return
the first match and a sound is issued (depending on
soundsEnabled()).
<dl class="return" compact><dt><b>Returns:</b></dt><dd> the next item from the matching-items-list. When there is no
match, QString() is returned and a sound is issued
</dd></dl> <dl class="see" compact><dt><b>See also:</b></dt><dd> slotNextMatch
</dd></dl>
</p></div></div><a class="anchor" name="order"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"><a href="../kdeui/KCompletion.html#CompOrder">KCompletion.CompOrder</a> order</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname"><em>self</em> )</td>
<td width="100%"> </td>
</tr>
</table>
</div>
<div class="memdoc"><p>Returns the completion order.
<dl class="return" compact><dt><b>Returns:</b></dt><dd> the current completion order.
</dd></dl> <dl class="see" compact><dt><b>See also:</b></dt><dd> setOrder
</dd></dl>
</p></div></div><a class="anchor" name="postProcessMatch"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> postProcessMatch</td>
<td>(</td>
<td class="paramtype"> <em>self</em>, </td>
<td class="paramname"></td>
</tr><tr>
<td class="memname"></td>
<td></td>
<td class="paramtype">QString </td>
<td class="paramname"><em>pMatch</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>This method is called after a completion is found and before the
matching string is emitted. You can override this method to modify the
string that will be emitted.
This is necessary e.g. in KUrlCompletion(), where files with spaces
in their names are shown escaped ("filename\ with\ spaces"), but stored
unescaped inside KCompletion.
Never delete that pointer!
</p>
<p>
Default implementation does nothing.
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>pMatch</em> </td><td> the match to process
</td></tr> </table></dl>
<p> <dl class="see" compact><dt><b>See also:</b></dt><dd> postProcessMatches
</dd></dl>
</p></div></div><a class="anchor" name="postProcessMatches"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> postProcessMatches</td>
<td>(</td>
<td class="paramtype"> <em>self</em>, </td>
<td class="paramname"></td>
</tr><tr>
<td class="memname"></td>
<td></td>
<td class="paramtype">QStringList </td>
<td class="paramname"><em>pMatches</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>This method is called before a list of all available completions is
emitted via #matches. You can override this method to modify the
found items before #match() or #matches() are emitted.
Never delete that pointer!
</p>
<p>
Default implementation does nothing.
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>pMatches</em> </td><td> the matches to process
</td></tr> </table></dl>
<p> <dl class="see" compact><dt><b>See also:</b></dt><dd> postProcessMatch
</dd></dl>
</p></div></div><a class="anchor" name="previousMatch"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname">QString previousMatch</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname"><em>self</em> )</td>
<td width="100%"> </td>
</tr>
</table>
</div>
<div class="memdoc"><p>Returns the next item from the matching-items-list.
When reaching the beginning, the list is rotated so it will return the
last match and a sound is issued (depending on soundsEnabled()).
<dl class="return" compact><dt><b>Returns:</b></dt><dd> the next item from the matching-items-list.
When there is no match, QString() is returned and
a sound is be issued.
</dd></dl> <dl class="see" compact><dt><b>See also:</b></dt><dd> slotPreviousMatch
</dd></dl>
</p></div></div><a class="anchor" name="removeItem"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> removeItem</td>
<td>(</td>
<td class="paramtype"> <em>self</em>, </td>
<td class="paramname"></td>
</tr><tr>
<td class="memname"></td>
<td></td>
<td class="paramtype">QString </td>
<td class="paramname"><em>item</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>Removes an item from the list of available completions.
Resets the current item-state ( previousMatch() and nextMatch()
won't work anymore).
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>item</em> </td><td> the item to remove
</td></tr>
</table></dl>
<p>
</p></div></div><a class="anchor" name="setCompletionMode"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> setCompletionMode</td>
<td>(</td>
<td class="paramtype"> <em>self</em>, </td>
<td class="paramname"></td>
</tr><tr>
<td class="memname"></td>
<td></td>
<td class="paramtype"><a href="../kdeui/KGlobalSettings.html#Completion">KGlobalSettings.Completion</a> </td>
<td class="paramname"><em>mode</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>Sets the completion mode to Auto/Manual, Shell or None.
If you don't set the mode explicitly, the global default value
KGlobalSettings.completionMode() is used.
KGlobalSettings.CompletionNone disables completion.
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>mode</em> </td><td> the completion mode
</td></tr> </table></dl>
<p> <dl class="see" compact><dt><b>See also:</b></dt><dd> completionMode
</dd></dl> <dl class="see" compact><dt><b>See also:</b></dt><dd> KGlobalSettings.completionMode
</dd></dl>
</p></div></div><a class="anchor" name="setIgnoreCase"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> setIgnoreCase</td>
<td>(</td>
<td class="paramtype"> <em>self</em>, </td>
<td class="paramname"></td>
</tr><tr>
<td class="memname"></td>
<td></td>
<td class="paramtype">bool </td>
<td class="paramname"><em>ignoreCase</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>Setting this to true makes KCompletion behave case insensitively.
E.g. makeCompletion( "CA" ); might return "carp\@cs.tu-berlin.de".
Default is false (case sensitive).
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>ignoreCase</em> </td><td> true to ignore the case
</td></tr> </table></dl>
<p> <dl class="see" compact><dt><b>See also:</b></dt><dd> ignoreCase
</dd></dl>
</p></div></div><a class="anchor" name="setItems"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> setItems</td>
<td>(</td>
<td class="paramtype"> <em>self</em>, </td>
<td class="paramname"></td>
</tr><tr>
<td class="memname"></td>
<td></td>
<td class="paramtype">QStringList </td>
<td class="paramname"><em>list</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>Sets the list of items available for completion. Removes all previous
items.
</p>
<p>
Notice: when order() == Weighted, then the weighting is looked up for
every item in the stringlist. Every item should have ":number" appended,
where number is an unsigned integer, specifying the weighting.
</p>
<p>
If you don't like this, call
setOrder( KCompletion.Insertion )
before calling setItems().
</p>
<p>
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>list</em> </td><td> the list of items that are available for completion
</td></tr> </table></dl>
<p> <dl class="see" compact><dt><b>See also:</b></dt><dd> items
</dd></dl>
</p></div></div><a class="anchor" name="setOrder"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> setOrder</td>
<td>(</td>
<td class="paramtype"> <em>self</em>, </td>
<td class="paramname"></td>
</tr><tr>
<td class="memname"></td>
<td></td>
<td class="paramtype"><a href="../kdeui/KCompletion.html#CompOrder">KCompletion.CompOrder</a> </td>
<td class="paramname"><em>order</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>KCompletion offers three different ways in which it offers its items:
<li> in the order of insertion </li>
<li> sorted alphabetically </li>
<li> weighted </li>
</p>
<p>
Choosing weighted makes KCompletion perform an implicit weighting based
on how often an item is inserted. Imagine a web browser with a location
bar, where the user enters URLs. The more often a URL is entered, the
higher priority it gets.
</p>
<p>
Note: Setting the order to sorted only affects new inserted items,
already existing items will stay in the current order. So you probably
want to call setOrder( Sorted ) before inserting items, when you want
everything sorted.
</p>
<p>
Default is insertion order.
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>order</em> </td><td> the new order
</td></tr> </table></dl>
<p> <dl class="see" compact><dt><b>See also:</b></dt><dd> order
</dd></dl>
</p></div></div><a class="anchor" name="setSoundsEnabled"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> setSoundsEnabled</td>
<td>(</td>
<td class="paramtype"> <em>self</em>, </td>
<td class="paramname"></td>
</tr><tr>
<td class="memname"></td>
<td></td>
<td class="paramtype">bool </td>
<td class="paramname"><em>enable</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>Enables/disables playing a sound when
<li> makeCompletion() can't find a match </li>
<li> there is a partial completion (= multiple matches in </li>
Shell-completion mode)
<li> nextMatch() or previousMatch() hit the last possible </li>
match -> rotation
</p>
<p>
For playing the sounds, KNotifyClient() is used.
</p>
<p>
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>enable</em> </td><td> true to enable sounds
</td></tr> </table></dl>
<p> <dl class="see" compact><dt><b>See also:</b></dt><dd> soundsEnabled
</dd></dl>
</p></div></div><a class="anchor" name="slotMakeCompletion"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> slotMakeCompletion</td>
<td>(</td>
<td class="paramtype"> <em>self</em>, </td>
<td class="paramname"></td>
</tr><tr>
<td class="memname"></td>
<td></td>
<td class="paramtype">QString </td>
<td class="paramname"><em>string</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>Attempts to complete "string" and emits the completion via match().
Same as makeCompletion() (just as a slot).
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>string</em> </td><td> the string to complete
</td></tr> </table></dl>
<p> <dl class="see" compact><dt><b>See also:</b></dt><dd> makeCompletion
</dd></dl>
</p></div></div><a class="anchor" name="slotNextMatch"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> slotNextMatch</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname"><em>self</em> )</td>
<td width="100%"> </td>
</tr>
</table>
</div>
<div class="memdoc"><p>Searches the next matching item and emits it via match().
Same as nextMatch() (just as a slot).
<dl class="see" compact><dt><b>See also:</b></dt><dd> nextMatch
</dd></dl>
</p></div></div><a class="anchor" name="slotPreviousMatch"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname"> slotPreviousMatch</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname"><em>self</em> )</td>
<td width="100%"> </td>
</tr>
</table>
</div>
<div class="memdoc"><p>Searches the previous matching item and emits it via match().
Same as previousMatch() (just as a slot).
<dl class="see" compact><dt><b>See also:</b></dt><dd> previousMatch
</dd></dl>
</p></div></div><a class="anchor" name="soundsEnabled"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname">bool soundsEnabled</td>
<td>(</td>
<td class="paramtype"> </td>
<td class="paramname"><em>self</em> )</td>
<td width="100%"> </td>
</tr>
</table>
</div>
<div class="memdoc"><p>Tells you whether KCompletion will play sounds on certain occasions.
Default is enabled.
<dl class="return" compact><dt><b>Returns:</b></dt><dd> true if sounds are enabled
</dd></dl> <dl class="see" compact><dt><b>See also:</b></dt><dd> setSoundsEnabled
</dd></dl>
</p></div></div><a class="anchor" name="substringCompletion"></a>
<div class="memitem">
<div class="memproto">
<table class="memname"><tr>
<td class="memname">QStringList substringCompletion</td>
<td>(</td>
<td class="paramtype"> <em>self</em>, </td>
<td class="paramname"></td>
</tr><tr>
<td class="memname"></td>
<td></td>
<td class="paramtype">QString </td>
<td class="paramname"><em>string</em></td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td>
<td></td>
<td width="100%"> </td>
</tr></table>
</div>
<div class="memdoc"><p>Returns a list of all completion items that contain the given <b>string.</b>
</p><dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td></td><td valign="top"><em>string</em> </td><td> the string to complete
</td></tr> </table></dl>
<p> <dl class="return" compact><dt><b>Returns:</b></dt><dd> a list of items which all contain <b>text</b> as a substring,
i.e. not necessarily at the beginning.
</dd></dl> </p>
<p>
<dl class="see" compact><dt><b>See also:</b></dt><dd> makeCompletion
</dd></dl>
</p></div></div><hr><h2>Enumeration Documentation</h2><a class="anchor" name="CompOrder"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr><td class="memname">CompOrder</td>
</tr>
</table>
</div>
<div class="memdoc"><p>Constants that represent the order in which KCompletion performs
completion-lookups.
</p><dl compact><dt><b>Enumerator: </b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0"><tr><td valign="top"><em>Sorted</em> </td><td><tr><td valign="top"><em>Insertion</em> </td><td><tr><td valign="top"><em>Weighted</em> </td><td></table>
</dl>
</div></div><p>
</div>
</div>
</div>
<div id="left">
<div class="menu_box">
<div class="nav_list">
<ul>
<li><a href="../allclasses.html">Full Index</a></li>
</ul>
</div>
<a name="cp-menu" /><div class="menutitle"><div>
<h2 id="cp-menu-project">Modules</h2>
</div></div>
<div class="nav_list">
<ul><li><a href="../akonadi/index.html">akonadi</a></li>
<li><a href="../dnssd/index.html">dnssd</a></li>
<li><a href="../kdecore/index.html">kdecore</a></li>
<li><a href="../kdeui/index.html">kdeui</a></li>
<li><a href="../khtml/index.html">khtml</a></li>
<li><a href="../kio/index.html">kio</a></li>
<li><a href="../knewstuff/index.html">knewstuff</a></li>
<li><a href="../kparts/index.html">kparts</a></li>
<li><a href="../kutils/index.html">kutils</a></li>
<li><a href="../nepomuk/index.html">nepomuk</a></li>
<li><a href="../phonon/index.html">phonon</a></li>
<li><a href="../plasma/index.html">plasma</a></li>
<li><a href="../polkitqt/index.html">polkitqt</a></li>
<li><a href="../solid/index.html">solid</a></li>
<li><a href="../soprano/index.html">soprano</a></li>
</ul></div></div>
</div>
</div>
<div class="clearer"/>
</div>
<div id="end_body"></div>
</div>
<div id="footer"><div id="footer_text">
This documentation is maintained by <a href="mailto:simon@simonzone.com">Simon Edwards</a>.<br />
KDE<sup>®</sup> and <a href="../images/kde_gear_black.png">the K Desktop Environment<sup>®</sup> logo</a> are registered trademarks of <a href="http://ev.kde.org/" title="Homepage of the KDE non-profit Organization">KDE e.V.</a> |
<a href="http://www.kde.org/contact/impressum.php">Legal</a>
</div></div>
</body>
</html>
