class KCompletionBase

An abstract class for using KCompletion in widgets. More...

Contains pure virtuals
Definition#include <kcompletion.h>
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

Public Methods

Protected Methods


Detailed Description

An abstract base class for adding completion feature into widgets.

This is a convienence class that tries to provide the common functions needed to add support for completion into widgets. Refer to KLineEdit or KComboBox to see how to such support can be added using this base class.

NOTE: Do not forget to provide an implementation for the protected pure virtual method connectSignals() if you do not want the class to be abstract.

 KCompletionBase ()

Default constructor.

KCompletionBase ()

[virtual]

Basic destructor.

KCompletion*  completionObject ( bool hsig = true )

Returns a pointer to the current completion object.

If the object does not exisit, it is automatically created. Note that the completion object created here is used by default to handle the signals internally. It is also deleted when this object's destructor is invoked. If you do not want these default settings, use setAutoDeleteCompletionObject and setHandleSignals to change the behavior. Alternatively, you can set the boolean parameter to false to disable the automatic handling of the signals by this object. Note that the boolean argument will be ignored if there already exists a completion object since no new object needs to be created. You need to use either setHandleSignals or setCompletionObject for such cases depending on your requirement.

Parameters:
hsigif true, handles signals internally.

Returns: a pointer the completion object.

void  setCompletionObject ( KCompletion* compObj, bool hsig = true )

[virtual]

Sets up the completion object to be used.

This method assigns the completion object and sets it up to automatically handle the completion and rotation signals internally. You should use this function if you want to share one completion object among you widgets or need to use a customized completion object.

The object assigned through this method is not deleted when this object's destructor is invoked unless you explicitly call setAutoDeleteCompletionObject after calling this method. Also if you do not want the signals to be handled by an internal implementation, be sure to set the bool argument to false.

Parameters:
compObja KCompletion or a derived child object.
hsigif true, handles signals internally.

void  setHandleSignals ( bool handle )

Enables this object to handle completion signals internally.

This function simply assigns the boolean value that indicates whether it should handle signals or not. All child objects must provide an implementation for connectSignals() which this method calls first.

Parameters:
completeif true, handle completion & roation internally.

bool  isCompletionObjectAutoDeleted ()

[const]

Returns true if the completion object is deleted upon this widget's destruction.

See setCompeltionObject and enableCompletion for details.

Returns: true if the completion object

void  setAutoDeleteCompletionObject ( bool autoDelete )

Sets the completion object for deletion upon this widget's destruction.

If the argument is set to true, the completion object is deleted when this widget's destructor is called.

Parameters:
autoDeleteif true, delete completion object on destruction.

void  disableSignals ()

Disables (temporarily) this widget's ability to emit the rotation and completion signals.

Invoking this function will cause the completion & rotation signals not to be emitted. Note that this also disbales any internal handling of these signals. However, unlike setCompletionObject object, disabling the emition of the signals through this method does not delete the comlpetion object.

void  enableSignals ()

Enables the widget's ability to emit completion signals.

Note that there is no need to invoke this function by default. When a completion object is created through completionObject() or setCompletionObject(), these signals are automatically actiavted. Only call this functions if you disbaled them manually.

bool  handleSignals ()

[const]

Returns true if the object handles the signals

Returns: true if this signals are handled internally.

bool  emitSignals ()

[const]

Returns true if the object emits the signals

Returns: true if signals are emitted

void  setCompletionMode ( KGlobalSettings::Completion mode )

[virtual]

Sets the type of completion to be used.

The completion modes supported are those defined in KGlobalSettings. See below.

Parameters:
modeCompletion type:

KGlobalSettings::Completion  completionMode ()

[const]

Retrieves the current completion mode.

The return values are of type KGlobalSettings::Completion. See setCompletionMode for details.

Returns: the completion mode.

bool  setRotateDownKey ( int rDnKey = 0 )

Sets the key-binding(s) to be used for rotating through a list to find the next match.

When this key is activated by the user a rotateDown signal will be emitted. If no value is supplied for rDnkey or it is set to 0, then the completion key will be defaulted to the global setting. This method returns false if rDnkey is negative or the supplied key-binding conflicts with either completion or rotateUp keys.

Parameters:
rDnkeykey-binding used to rotate up in a list.

Returns: true if key-binding can successfully be set.

bool  setRotateUpKey ( int rUpKey = 0 )

Sets the key-binding to be used for rotating through a list to find the previous match.

When this key is activated by the user a rotateUp signal will be emitted. If no value is supplied for rUpkey or it is set to 0, then the completion key will be defaulted to the global setting. This method returns false if rUpkey is negative or the supplied key-binding conflicts with either completion or rotateDown keys.

Parameters:
rUpkeykey-binding used to rotate down in a list.

Returns: true if key-binding can successfully be set.

bool  setCompletionKey ( int ckey = 0 )

Sets the key-binding to be used for the two manual completion types: CompletionMan and CompletionShell.

This function expects the value of the modifier keys (Shift, Ctrl, Alt), if present, to be @bf summed up with actual key, ex: Qt::CTRL+Qt::Key_E. If no value is supplied for ckey or it is set to 0, then the completion key will be defaulted to the global setting. This function returns true if the supplied key-binding can be successfully assigned.

Note that if ckey is negative or the key-binding conflicts with either completion or rotateDown keys, this function will return false. This method will also always returns false if the widget is not editable.

Parameters:
ckeyKey binding to use for completion

Returns: true if key-binding is successfully set.

int  completionKey ()

[const]

Returns the key-binding used for completion.

If the key binding contains modifier key(s), the @bf sum of the key and the modifier will be returned. See also setCompletionKey. Note that this method is only useful when this widget is editable. Otherwise this method has no meaning.

Returns: the key-binding used for rotating through a list.

int  rotateUpKey ()

[const]

Returns the key-binding used for rotating up in a list.

This methods returns the key used to iterate through a list in the "UP" direction. This is opposite to what the rotateDown key does.

If the key binding contains modifier key(s), the SUM of their values is returned. See also setRotateUpKey.

Returns: the key-binding used for rotating up in a list.

int  rotateDownKey ()

[const]

Returns the key-binding used for rotating down in a list.

This methods returns the key used to match the previous item in a list. Everytime this key is pressed most widgets that inherit from it emit a signal that indicates this action.

If the key binding contains modifier key(s), the SUM of their values is returned. See also setRotateDownKey.

Returns: the key-binding used for rotating down in a list.

void  useGlobalSettings ()

Sets this object to use global values for key-bindings.

This method changes the values of the key bindings for rotation and completion features to the default values provided in KGlobalSettings.

By default this object uses the global key-bindings. There is no need to call this method unless you have locally modified the key bindings and want to revert back.

void  showModeChanger ()

Makes the completion mode changer visible in the context menu.

Note that the mode changer item is a sub menu, that allows the user to select from one of the standard completion modes described at setCompletionMode. Additionally, if the user changes the completion mode to something other than the global setting, a "Default" entry is added at the bottom to allow the user to revert his/her changes back to the global setting.

void  hideModeChanger ()

Hides the completion mode changer in the context menu.

bool  isModeChangerVisible ()

[const]

Returns true if the mode changer item is visible in the context menu.

Returns: true if the mode changer is visible in context menu.

void  connectSignals ( bool handle )

[protected const pure virtual]

A pure virtual function.

This function must provide an implementation for how signals are connected when they are handled internally. Since this is implementation dependent it is left upto each inheriting object to decide.

void  insertCompletionItems ( QObject* receiver, const char* member )

[protected]

Inserts completion mode changers items.

This is method is implemented as a matter of convience and for the sake of consistency of in the appearance of the completion mode changer items.

Simply invoke this function from your implementation of the slot supplied to insertCompletionMenu. See KLineEdit::showCompletionItems or KComboBox::showCompletionItems for an example of implementation.

Parameters:
receiverobject that receives the activation of completion items.
membermethod invoked when completion items are clicked.

void  insertCompletionMenu ( QObject* receiver, const char* member, QPopupMenu* parent, int index = -1 )

[protected]

Adds a completion menu item to the given popup menu.

This function adds/removes a completion menu item at the specified index position in the popup menu. If index is a negative value, the menu item is inserted at the end of the parent popup menu. Since this function manages the addition and removal of the completion menu item by itself, it is intended/designed to be invoked just before you display your popup menu.

See KLineEdit::aboutToShow or KComboBox::aboutToShow for an example implementation.

Parameters:
receiverobject that receives the activation of completion items.
membermethod invoked when completion sub-menu is about to be shown.
parentif not NULL, add the completion option as its sub-menu.
indexif non-negative, add the compleiton option at the specified position.

bool  hasBeenInserted ()

[protected]

Returns true if completion menu item has been inserted into the popup menu.

Returns: true if completion menu is inserted into popup menu.