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 Types

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.

enum KeyBindingType {TextCompletion, PrevCompletionMatch, NextCompletionMatch, RotateUp, RotateDown }

Constants that represent the items whose short-cut key-binding is programmable. The default key-bindings for these items are defined in KStdAccel.

 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  setKeyBinding ( KeyBindingType , int key = 0 )

Sets the key-binding to be used for manual text completion, text rotation in a history list as well as a completion list.

When the keys set by this function are pressed, a signal defined by the inherting widget will be activated. If the default value or 0 is specified by the second parameter, then the key-binding as defined in the global setting should be used. This method returns false value for key is negative or the supplied key-binding conflicts with the ones set for one of the other features.

NOTE: To use a modifier key (Shift, Ctrl, Alt) as part of the key-binding simply simply sum up the values of the modifier and the actual key. For example, to use CTRL+E as a key binding for one of the items, you would simply supply @p "Qt::CtrlButton + Qt::Key_E" as the second argument to this function.

Parameters:
itemthe feature whose key-binding needs to be set:
keykey-binding used to rotate down in a list.

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

int  getKeyBinding ( KeyBindingType item )

[const]

Returns the key-binding used for the specified item.

This methods returns the key-binding used to activate the feature feature given by item. If the binding contains modifier key(s), the SUM of the modifier key and the actual key code are returned.

Returns: the key-binding used for the feature given by item.

void  useGlobalKeyBindings ()

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.

NOTE: By default inheriting widgets should uses the global key-bindings so that there will be no need to call this method.

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 method is implemented here as a matter of convience and for the sake of consistency in the appearance of the completion mode changer items. It initially inerts four of the standard menu items labeled: "None", "Manual", "Automatic" and "Semi-Automatic". and puts a check mark beside the mode that is currently active. When the user changes this default mode, another item labeled "Default" is inserted so that the user can quickly revert back to the default mode.

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

Note that when this "Default" item, the clicked signal emitted has its integer argument set to 0. Thus, you need to make sure that you replace this value with the one returned by KGlobalSettings::completionMode().

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.

KeyBindingMap  getKeyBindings ()

[protected const]

Returns a key-binding maps

This method is the same as getKeyBinding except it returns the whole keymap containing the key-bindings.

Returns: the key-binding used for the feature given by item.