An object that can be searched with a KLFSearchBar. More...

#include <klfsearchbar.h>

Inheritance diagram for KLFPosSearchable:

Collaboration diagram for KLFPosSearchable:

Classes
struct	Pos
	An abstract position in a searchable object. More...
Public Member Functions
virtual Pos	searchStartFrom (bool forward)
virtual Pos	searchFind (const QString &queryString, const Pos &fromPos, bool forward)=0
virtual void	searchMoveToPos (const Pos &pos)
virtual void	searchPerformed (const QString &queryString, bool found, const Pos &pos)
virtual void	searchAborted ()=0
virtual void	searchReinitialized ()
virtual QString	searchQueryString () const
	The current query string.
virtual void	setSearchQueryString (const QString &s)
virtual bool	searchHasInterruptRequested ()
virtual void	setSearchInterruptRequested (bool on)

Detailed Description

An object that can be searched with a KLFSearchBar.

This class is provides an interface for an object to be searched with a KLFSearchBar.

An abstract positioning scheme is introduced with the class Pos. This class handles Pos objects without asking to what they refer to or point to, they could contain an index in a list, or a QTextCursor in a document, or a pointer to some arbitrary data. A Pos is valid if it has non-NULL posdata. You should subclass PosData to store some relevant data, as well as provide an equality-test function.

This interface, in conjunction with KLFSearchBar, handles the different search states, searching forward/backwards, returning to previous results (e.g. with Emacs-style backspace key).

How the search is performed, which logic is used, which order of elements is used, case sensitivity, etc., is up to the subclass implementation. Pos objects do not have a sense of "order", the interface just queries the "next match" from a given position, which can then be described by another position object.

Minimal example:

Todo:: MINIMAL EXAMPLE

Note:: If you have data that is "linearly ordered", i.e. that you can describe the possible search results with a C++/STL-like iterator concept (for example a list of strings or values, etc.), then consider using KLFIteratorSearchable which takes this into account and requires you to write less code.

Definition at line 73 of file klfsearchbar.h.

Member Function Documentation

virtual void KLFPosSearchable::searchAborted ( ) [pure virtual]

Called by the search bar to inform the searched object that the search was aborted by the user.

Implemented in KLFSearchable, KLFPosSearchableProxy, KLFIteratorSearchable< Iter >, KLFIteratorSearchable< QModelIndex >, and KLFItemViewSearchTarget.

Referenced by KLFSearchBar::abortSearch(), and KLFPosSearchableProxy::searchAborted().

virtual Pos KLFPosSearchable::searchFind	(	const QString &	queryString,
		const Pos &	fromPos,
		bool	forward
	)		`[pure virtual]`

Search the content for queryString, from position fromPos, in direction forward. If found, return the position of the match, if not found, return an invalid position. Do not act upon the find (eg. select element in list), because the function searchMoveTo() and searchPerformed() will be called after a successful searchFind() automatically, while the function searchMoveTo() will be called with an invalid position and the function searchPerformed() will be called if the search failed.

Note:: The search is performed AFTER fromPos, ie. do not return fromPos itself if it matches.

The reimplementation should call from time to time

 qApp->processEvents()

to keep the GUI from freezing in long searches.

Note:: If the reimplementation implements the above suggestion, note that the slot searchAborted() may be called during that time! It is best to take that into account and provide a means to stop the search if that is the case.

Implemented in KLFSearchable, KLFPosSearchableProxy, KLFIteratorSearchable< Iter >, and KLFIteratorSearchable< QModelIndex >.

Referenced by KLFPosSearchableProxy::searchFind().

virtual bool KLFPosSearchable::searchHasInterruptRequested ( ) [inline, virtual]

Reimplemented in KLFPosSearchableProxy.

Definition at line 286 of file klfsearchbar.h.

Referenced by KLFPosSearchableProxy::searchHasInterruptRequested(), and KLFIteratorSearchable< QModelIndex >::searchIterFindNext().

virtual void KLFPosSearchable::searchMoveToPos ( const Pos & pos ) [inline, virtual]

Called by the search bar to inform the searched object that the current search position is pos.

Reimplemented in KLFSearchable, KLFPosSearchableProxy, KLFIteratorSearchable< Iter >, and KLFIteratorSearchable< QModelIndex >.

Definition at line 256 of file klfsearchbar.h.

Referenced by KLFSearchBar::eventFilter(), KLFSearchBar::promptEmptySearch(), and KLFPosSearchableProxy::searchMoveToPos().

virtual void KLFPosSearchable::searchPerformed	(	const QString &	queryString,
		bool	found,
		const Pos &	pos
	)		`[inline, virtual]`

Called by the search bar to inform that the queryString was reported either to be found (in which case found is TRUE), either not to be found (then found is FALSE), at position pos. This function call always immediately preceded by a searchMoveToPos(). pos is invalid if the query string was not found (found==FALSE).

Reimplemented in KLFSearchable, KLFPosSearchableProxy, KLFIteratorSearchable< Iter >, and KLFIteratorSearchable< QModelIndex >.

Definition at line 262 of file klfsearchbar.h.

Referenced by KLFSearchBar::eventFilter(), KLFIteratorSearchable< QModelIndex >::searchPerformed(), and KLFPosSearchableProxy::searchPerformed().

virtual QString KLFPosSearchable::searchQueryString ( ) const [inline, virtual]

The current query string.

This function can be used by subclasses to retrieve the current search string.

Reimplemented in KLFPosSearchableProxy.

Definition at line 279 of file klfsearchbar.h.

References klfDbg.

Referenced by KLFIteratorSearchable< QModelIndex >::searchFind(), KLFIteratorSearchable< QModelIndex >::searchIterFind(), KLFIteratorSearchable< QModelIndex >::searchIterFindNext(), and KLFPosSearchableProxy::searchQueryString().

virtual void KLFPosSearchable::searchReinitialized ( ) [inline, virtual]

Called when search bar has focus, but not text is typed. Typically if user hits backspace enough times to an empty string.

Reimplemented in KLFPosSearchableProxy, and KLFItemViewSearchTarget.

Definition at line 272 of file klfsearchbar.h.

Referenced by KLFSearchBar::promptEmptySearch(), and KLFPosSearchableProxy::searchReinitialized().

KLFPosSearchable::Pos KLFPosSearchable::searchStartFrom ( bool forward ) [virtual]

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 search is performed AFTER the returned pos, and an invalid Pos is regarded as being both before the beginning and after the end, ie. to search forward from the beginning, use an invalid position as well as to search backward from the end.

The default implementation returns an invalid position.

Reimplemented in KLFPosSearchableProxy, KLFIteratorSearchable< Iter >, and KLFIteratorSearchable< QModelIndex >.

Definition at line 149 of file klfsearchbar.cpp.

References klfDbg.

Referenced by KLFSearchBar::find(), and KLFPosSearchableProxy::searchStartFrom().

void KLFPosSearchable::setSearchInterruptRequested ( bool on ) [virtual]

Reimplemented in KLFPosSearchableProxy.

Definition at line 156 of file klfsearchbar.cpp.

References klfDbg.

Referenced by KLFSearchBar::abortSearch(), KLFSearchBar::eventFilter(), KLFSearchBar::find(), KLFSearchBar::promptEmptySearch(), KLFIteratorSearchable< QModelIndex >::searchAborted(), and KLFPosSearchableProxy::setSearchInterruptRequested().

virtual void KLFPosSearchable::setSearchQueryString ( const QString & s ) [inline, virtual]

Used internally to update the return value of searchQueryString().