summaryrefslogtreecommitdiffstats
path: root/tdeui/kactionselector.h
diff options
context:
space:
mode:
Diffstat (limited to 'tdeui/kactionselector.h')
-rw-r--r--tdeui/kactionselector.h402
1 files changed, 402 insertions, 0 deletions
diff --git a/tdeui/kactionselector.h b/tdeui/kactionselector.h
new file mode 100644
index 000000000..03c5ab5da
--- /dev/null
+++ b/tdeui/kactionselector.h
@@ -0,0 +1,402 @@
+/* This file is part of the KDE project
+ Copyright (C) 2002 Anders Lund <anders.lund@lund.tdcadsl.dk>
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Library General Public
+ License version 2 as published by the Free Software Foundation.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Library General Public License for more details.
+
+ You should have received a copy of the GNU Library General Public License
+ along with this library; see the file COPYING.LIB. If not, write to
+ the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301, USA.
+*/
+
+#ifndef _KACTION_SELECTOR_H_
+#define _KACTION_SELECTOR_H_
+
+#include <tqwidget.h>
+
+#include <kdelibs_export.h>
+
+class TQListBox;
+class TQListBoxItem;
+class TQKeyEvent;
+class TQEvent;
+class TQIconSet;
+
+class KActionSelectorPrivate;
+
+/**
+ @short A widget for selecting and arranging actions/objects
+
+ This widget allows the user to select from a set of objects and arrange
+ the order of the selected ones using two list boxes labeled "Available"
+ and "Used" with horizontal arrows in between to move selected objects between
+ the two, and vertical arrows on the right to arrange the order of the selected
+ objects.
+
+ The widget moves objects to the other listbox when doubleclicked if
+ the property moveOnDoubleClick is set to true (default). See moveOnDoubleClick()
+ and setMoveOnDoubleClick().
+
+ The user control the widget using the keyboard if enabled (default),
+ see keyboardEnabled.
+
+ Note that this may conflist with keyboard selection in the selected list box,
+ if you set that to anything else than TQListBox::Single (which is the default).
+
+ To use it, simply construct an instance and then add items to the two listboxes,
+ available through lbAvailable() and lbSelected(). Whenever you want, you can retrieve
+ the selected options using TQListBox methods on lbSelected().
+
+ This way, you can use your own TQListBoxItem class, allowing you to easily
+ store object data in those.
+
+ When an item is moved to a listbox, it is placed below the current item
+ of that listbox.
+
+ Standard arrow icons are used, but you can use icons of your own choice if desired,
+ see setButtonIcon(). It is also possible to set tooltips and whatsthis help
+ for the buttons. See setButtonTooltip() and setButtonWhatsThis().
+
+ To set whatsthis or tooltips for the listboxes, access them through
+ availableListbox() and selectedListBox().
+
+ All the moving buttons are automatically set enabled as expected.
+
+ Signals are sent each time an item is moved, allowing you to follow the
+ users actions if you need to. See addedToSelection(), removedFromSelection(),
+ movedUp() and movedDown()
+
+ @author Anders Lund <anders@alweb.dk>
+*/
+
+class KDEUI_EXPORT KActionSelector : public TQWidget {
+ Q_OBJECT
+ Q_ENUMS( ButtonIconSize InsertionPolicy )
+ Q_PROPERTY( bool moveOnDoubleClick READ moveOnDoubleClick WRITE setMoveOnDoubleClick )
+ Q_PROPERTY( bool keyboardEnabled READ keyboardEnabled WRITE setKeyboardEnabled )
+ Q_PROPERTY( TQString availableLabel READ availableLabel WRITE setAvailableLabel )
+ Q_PROPERTY( TQString selectedLabel READ selectedLabel WRITE setSelectedLabel )
+ Q_PROPERTY( ButtonIconSize buttonIconSize READ buttonIconSize WRITE setButtonIconSize )
+ Q_PROPERTY( InsertionPolicy availableInsertionPolicy READ availableInsertionPolicy WRITE setAvailableInsertionPolicy )
+ Q_PROPERTY( InsertionPolicy selectedInsertionPolicy READ selectedInsertionPolicy WRITE setSelectedInsertionPolicy )
+ Q_PROPERTY( bool showUpDownButtons READ showUpDownButtons WRITE setShowUpDownButtons )
+
+public:
+ KActionSelector( TQWidget *parent=0, const char *name=0 );
+ ~KActionSelector();
+
+ /**
+ @return The TQListBox holding the available actions
+ */
+ TQListBox *availableListBox() const;
+
+ /**
+ @return The TQListBox holding the selected actions
+ */
+ TQListBox *selectedListBox() const;
+
+ /**
+ This enum indentifies the moving buttons
+ */
+ enum MoveButton {
+ ButtonAdd,
+ ButtonRemove,
+ ButtonUp,
+ ButtonDown
+ };
+
+ /**
+ This enum identifies the icon sizes, used for the move buttons.
+ The values correspond to the following pixel sizes:
+ @li SmallIcon - the return value of IconSize( KIcon::Small ), the user defined size
+ of a small icon in KDE. This is the default setting.
+ @li Small - 16px
+ @li Medium - 22px
+ @li Large - 32px
+ @li XLarge - 48px
+ */
+ enum ButtonIconSize {
+ SmallIcon,
+ Small,
+ Medium,
+ Large,
+ XLarge
+ };
+
+ /**
+ This enum defines policies for where to insert moved items in a listbox.
+ The following policies are currently defined:
+ @li BelowCurrent - The item is inserted below the listbox'
+ currentItem() or at the end if there is no curent item.
+ @li Sorted - The listbox is sort()ed after one or more items are inserted.
+ @li AtTop - The item is inserted at index 0 in the listbox.
+ @li AtBottom - The item is inserted at the end of the listbox.
+
+ @sa availableInsertionPolicy(), setAvailableInsertionPolicy(),
+ selectedInsertionPolicy(), setSelectedInsertionPolicy().
+ */
+ enum InsertionPolicy {
+ BelowCurrent,
+ Sorted,
+ AtTop,
+ AtBottom
+ };
+
+ /**
+ @return Wheather moveOnDoubleClcik is enabled.
+
+ If enabled, an item in any listbox will be moved to the other one whenever
+ doubleclicked.
+ @sa setMoveOnDoubleClick()
+ */
+ bool moveOnDoubleClick() const;
+
+ /**
+ Sets moveOnDoubleClick to @p enable
+ @sa moveOnDoubleClick()
+ */
+ void setMoveOnDoubleClick( bool enable );
+
+ /**
+ @return Weather keyboard control is enabled.
+
+ When Keyboard control is enabled, the widget will react to
+ the following keyboard actions:
+ @li CTRL + Right - simulate clicking the add button
+ @li CTRL + Left - simulate clicking the remove button
+ @li CTRL + Up - simulate clicking the up button
+ @li CTRL + Down - simulate clicking the down button
+
+ Additionally, pressing RETURN or ENTER on one of the list boxes
+ will cause the current item of that listbox to be moved to the other
+ listbox.
+
+ The keyboard actions are enabled by default.
+
+ @sa setKeyboardEnabled()
+ */
+ bool keyboardEnabled() const;
+
+ /**
+ Sets the keyboard enabled depending on @p enable.
+ @sa keyboardEnabled()
+ */
+ void setKeyboardEnabled( bool enable );
+
+ /**
+ @return The text of the label for the available items listbox.
+ */
+ TQString availableLabel() const;
+
+ /**
+ Sets the label for the available items listbox to @p text.
+ Note that this label has the listbox as its @e buddy, so that
+ if you have a single ampersand in the text, the following character
+ will become the accellerator to focus te listbox.
+ */
+ void setAvailableLabel( const TQString & text );
+
+ /**
+ @return the label of the selected items listbox.
+ */
+ TQString selectedLabel() const;
+
+ /**
+ Sets the label for the selected items listbox to @p text.
+ Note that this label has the listbox as its @e buddy, so that
+ if you have a single ampersand in the text, the following character
+ will become the accellerator to focus te listbox.
+ */
+ void setSelectedLabel( const TQString & text );
+
+ /**
+ @return the current ButtonIconSize.
+ */
+ ButtonIconSize buttonIconSize() const;
+
+ /**
+ Sets the button icon size.
+ See ButtonIconSize for the possible values and their pixel meaning.
+ */
+ void setButtonIconSize( ButtonIconSize size );
+
+ /**
+ @return The current insertion policy for the available listbox.
+ The default policy for the available listbox is Sorted.
+ See also InsertionPolicy, setAvailableInsertionPolicy().
+ */
+ InsertionPolicy availableInsertionPolicy() const;
+
+ /**
+ Sets the insertion policy for the available listbox.
+ See also InsertionPolicy, availableInsertionPolicy().
+ */
+ void setAvailableInsertionPolicy( InsertionPolicy policy );
+
+ /**
+ @return The current insertion policy for the selected listbox.
+ The default policy for the selected listbox is BelowCurrent.
+ See also InsertionPolicy, setSelectedInsertionPolicy().
+ */
+ InsertionPolicy selectedInsertionPolicy() const;
+
+ /**
+ Sets the insertion policy for the selected listbox.
+ See also InsertionPolicy, selectedInsertionPolicy().
+ */
+ void setSelectedInsertionPolicy( InsertionPolicy policy );
+
+ /**
+ @return wheather the Up and Down buttons should be displayed.
+ */
+ bool showUpDownButtons() const;
+
+ /**
+ Sets wheather the Up and Down buttons should be displayed
+ according to @p show
+ */
+ void setShowUpDownButtons( bool show );
+
+ /**
+ Sets the pixmap of the button @p button to @p icon.
+ It calls SmallIconSet(pm) to generate the icon set.
+ */
+ void setButtonIcon( const TQString &icon, MoveButton button );
+
+ /**
+ Sets the iconset for button @p button to @p iconset.
+ You can use this method to et a costum icon set. Either
+ created by TQIconSet, or use the application instance of
+ KIconLoader (recommended).
+ */
+ void setButtonIconSet( const TQIconSet &iconset, MoveButton button );
+
+ /**
+ Sets the tooltip for the button @p button to @p tip.
+ */
+ void setButtonTooltip( const TQString &tip, MoveButton button );
+
+ /**
+ Sets the whatsthis help for button @p button to @p text.
+ */
+ void setButtonWhatsThis( const TQString &text, MoveButton button );
+
+ /**
+ Sets the enabled state of all moving buttons to reflect the current
+ options.
+
+ Be sure to call this if you add or removes items to either listbox after the
+ widget is show()n
+ */
+ void setButtonsEnabled();
+
+signals:
+ /**
+ Emitted when an item is moved to the "selected" listbox.
+ */
+ void added( TQListBoxItem *item );
+
+ /**
+ Emitted when an item is moved out of the "selected" listbox.
+ */
+ void removed( TQListBoxItem *item );
+
+ /**
+ Emitted when an item is moved upwards in the "selected" listbox.
+ */
+ void movedUp( TQListBoxItem *item );
+
+ /**
+ Emitted when an item is moved downwards in the "selected" listbox.
+ */
+ void movedDown( TQListBoxItem *item );
+
+ /**
+ Emitted when an item is moved to the "selected" listbox.
+ */
+// void addedToSelection( TQListBoxItem *item );
+
+public slots:
+ /**
+ Reimplemented for internal reasons.
+ (calls setButtonsEnabled())
+ */
+ void polish();
+
+protected:
+ /**
+ Reimplamented for internal reasons.
+ */
+ void keyPressEvent( TQKeyEvent * );
+
+ /**
+ Reimplemented for internal reasons.
+ */
+ bool eventFilter( TQObject *, TQEvent * );
+
+private slots:
+ /**
+ Move selected item from available box to the selected box
+ */
+ void buttonAddClicked();
+
+ /**
+ Move selected item from selected box to available box
+ */
+ void buttonRemoveClicked();
+
+ /**
+ Move selected item in selected box upwards
+ */
+ void buttonUpClicked();
+
+ /**
+ Move seleted item in selected box downwards
+ */
+ void buttonDownClicked();
+
+ /**
+ Moves the item @p item to the other listbox if moveOnDoubleClick is enabled.
+ */
+ void itemDoubleClicked( TQListBoxItem *item );
+
+ /**
+ connected to both list boxes to set the buttons enabled
+ */
+ void slotCurrentChanged( TQListBoxItem * ) { setButtonsEnabled(); }
+
+private:
+
+ /**
+ Move item @p item to the other listbox
+ */
+ void moveItem( TQListBoxItem *item );
+
+ /**
+ loads the icons for the move buttons.
+ */
+ void loadIcons();
+
+ /**
+ @return the index to insert an item into listbox @p lb,
+ given InsertionPolicy @p policy.
+
+ Note that if policy is Sorted, this will return -1.
+ Sort the listbox after inserting the item in that case.
+ */
+ int insertionIndex( TQListBox *lb, InsertionPolicy policy );
+
+ /** @private
+ Private data storage
+ */
+ KActionSelectorPrivate *d;
+};
+
+#endif // _KACTION_SELECTOR_H_