A Searchable object interface based on iterative searching. More...
#include <klfiteratorsearchable.h>
Public Types | |
typedef Iter | SearchIterator |
Public Member Functions | |
KLFIteratorSearchable () | |
virtual | ~KLFIteratorSearchable () |
virtual SearchIterator | searchIterBegin ()=0 |
virtual SearchIterator | searchIterEnd ()=0 |
virtual SearchIterator | searchIterAdvance (const SearchIterator &pos, bool forward) |
SearchIterator | searchIterNext (const SearchIterator &pos) |
SearchIterator | searchIterPrev (const SearchIterator &pos) |
virtual SearchIterator | searchIterStartFrom (bool forward) |
virtual bool | searchIterMatches (const SearchIterator &pos, const QString &queryString)=0 |
virtual void | searchPerformed (const SearchIterator &resultMatchPosition) |
virtual SearchIterator | searchIterFind (const SearchIterator &startPos, const QString &queryString, bool forward) |
Find occurence of a search string. More... | |
virtual SearchIterator | searchIterFindNext (bool forward) |
Find the next occurence of previous search string. More... | |
virtual bool | searchFind (const QString &queryString, bool forward) |
virtual bool | searchFindNext (bool forward) |
virtual void | searchAbort () |
SearchIterator | searchAdvanceIteratorSafe (const SearchIterator &it, int n=1) |
![]() | |
KLFSearchable () | |
virtual | ~KLFSearchable () |
bool | searchFind (const QString &queryString) |
Find the first occurence of a query string. More... | |
Protected Member Functions | |
QString | searchQueryString () const |
SearchIterator | searchCurrentIterPos () const |
A Searchable object interface based on iterative searching.
Most searchable displays work with iterators, or objects that behave as such. This can be, for example, an integer position in a displayed list. When searchFind() is called, then usually the search iteratively looks at all items in the list, until a match is found.
This class implements an interface of such iterator-based searchable displays for use as a KLFSearchable, to be searched with a KLFSearchBar for example.
The iterator may be any object that:
int
, QModelIndex
, ...)The functions searchIterBegin() and searchIterEnd() have to be implemented, to return respectively an iterator position for the first valid displayed element, and an iterator for the one-after-last-valid displayed item.
The function searchIterAdvance(), by default uses operator-(Iter, int) and operator+(Iter, int) to increment or decrement the iterator by one. If this is not the correct way to increment/decrement an iterator, reimplement this function to perform the job correctly. (for example to walk with QModelIndex'es in a tree view).
The search functions defined in this class guarantee never to increment an iterator that is already equal to searchIterEnd(), and never to decrement an operator that is equal to searchIterBegin().
The searchIterMatches() has to be reimplemented to say whether the data displayed at the given position matches with the query string.
This class provides implementations for KLFSearchable's searchFind(), searchFindNext() and searchAbort(). Additionally, it provides searchIterFind(), searchIterFindNext() which are a bit more flexible than KLFSearchable's base functions (for example by returning the match position!).
Definition at line 69 of file klfiteratorsearchable.h.
typedef Iter KLFIteratorSearchable< Iter >::SearchIterator |
Definition at line 75 of file klfiteratorsearchable.h.
|
inline |
Definition at line 72 of file klfiteratorsearchable.h.
|
inlinevirtual |
Definition at line 73 of file klfiteratorsearchable.h.
|
inlinevirtual |
Implements KLFSearchable.
Definition at line 238 of file klfiteratorsearchable.h.
|
inline |
Advances iterator it
safely, that means it incremenets or decrements the iterator while always making sure not to perform illegal operations like incremenet an iterator that has arrived at searchIterEnd() and making sure not to decrement an iterator that has arrived at searchIterBegin().
Iterators that have arrived to searchIterEnd() or searchIterBegin(), when again incremented (resp. decremented), wrap around and start again from the other end. Namely decrementing an iterator equal to searchIterBegin() will give you searchIterEnd() and incrementing searchIterEnd() will yield searchIterBegin().
Definition at line 252 of file klfiteratorsearchable.h.
|
inlineprotected |
Definition at line 270 of file klfiteratorsearchable.h.
|
inlinevirtual |
Implements KLFSearchable.
Definition at line 214 of file klfiteratorsearchable.h.
References KLF_DEBUG_BLOCK, KLF_DEBUG_TEE, and KLF_FUNC_NAME.
|
inlinevirtual |
Implements KLFSearchable.
Definition at line 224 of file klfiteratorsearchable.h.
References KLF_DEBUG_BLOCK, KLF_DEBUG_TEE, and KLF_FUNC_NAME.
|
inlinevirtual |
Increment or decrement iterator. The default implementation does pos+1
or pos-1
; you can re-implement this function if your iterator cannot be incremented/decremented this way.
Definition at line 91 of file klfiteratorsearchable.h.
|
pure virtual |
Returns the first valid SearchIterator
object. This should point to the element at top of the display, or be equal to searchIterEnd() if the display is empty.
|
pure virtual |
Returns the one-after-last-valid SearchIterator
object. This should NOT point to a valid object, however it should either be equal to searchIterBegin() if the display is empty, or if searchIterPrev() is called on it it should validly point on the last object in display.
|
inlinevirtual |
Find occurence of a search string.
Extension of searchFind(). Looks for queryString
starting at position startPos
.
This function returns the position to the first match, or searchIterEnd() if no match was found.
This function starts searching from startPos
inclusive, in forward direction, if forward
is TRUE, and searches from startPos
not inclusive [see reason below], in reverse direction, if forward
is FALSE.
Reason: iterators have an asymmetry, namely that 'begin' points on the first item while 'end' points to one-past-end. We want to be able to search forward naturally from 'begin' and search reverse from 'end', see also searchIterStartFrom().
This function need not be reimplemented, the default implementation should suffice for most cases.
Definition at line 145 of file klfiteratorsearchable.h.
References klfDbg.
|
inlinevirtual |
Find the next occurence of previous search string.
Extension of searchFindNext(), in that this function returns the position of the next match.
Returns searchIterEnd() if no match was found.
This function need not be reimplemented, the default implementation should suffice for most cases.
Definition at line 165 of file klfiteratorsearchable.h.
References QTime::elapsed(), KLF_DEBUG_TIME_BLOCK, KLF_FUNC_NAME, klfDbg, and QTime::restart().
|
pure virtual |
See if the data pointed at by pos
matches the query string queryString
. Return TRUE if it does match, or FALSE if it does not match.
pos
is garanteed to point on a valid object (this function will never be called with pos
equal to searchIterEnd()).
|
inline |
Increment iterator. Shortcut for searchIterAdvance() with forward
= TRUE.
Definition at line 94 of file klfiteratorsearchable.h.
|
inline |
Decrement iterator. Shortcut for searchIterAdvance() with forward
= FALSE.
Definition at line 97 of file klfiteratorsearchable.h.
|
inlinevirtual |
Returns the position from where we should start the search, given the current view situation. This can be reimplemented to start the search for example from the current scroll position in the display.
If forward
is TRUE, then the search is about to be performed forward, otherwise it is about to be performed in reverse direction.
The default implementation returns searchIterBegin() to search from beginning if forward
is TRUE, or searchIterEnd() if forward
is FALSE.
Definition at line 107 of file klfiteratorsearchable.h.
|
inlinevirtual |
Virtual handler for the subclass to act upon the result of a search. A subclass may for example want to select the matched item in a list to make it conspicuous to the user.
resultMatchPosition
is the position of the item that matched the search. If resultMatchPosition
is equal to searchIterEnd(), then the search failed (no match was found). (Note in this case calling searchFindNext() again will wrap the search).
The base implementation does nothing.
Definition at line 126 of file klfiteratorsearchable.h.
|
inlineprotected |
Definition at line 269 of file klfiteratorsearchable.h.