← Back to branch summary

~ubuntu-branches/debian/sid/kdevelop/sid

« back to all changes in this revision

Viewing changes to parts/fileselector/kactionselector.h

  • Committer: Bazaar Package Importer
  • Author(s): Jeremy Lainé
  • Date: 2006-05-23 18:39:42 UTC
  • Revision ID: james.westby@ubuntu.com-20060523183942-hucifbvh68k2bwz7
Tags: upstream-3.3.2
Import upstream version 3.3.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
parts/fileselector/kactionselector.h
 
1
/* This file is part of the KDE project
 
2
   Copyright (C) 2002 Anders Lund <anders.lund@lund.tdcadsl.dk>
 
3
 
 
4
   This library is free software; you can redistribute it and/or
 
5
   modify it under the terms of the GNU Library General Public
 
6
   License version 2 as published by the Free Software Foundation.
 
7
 
 
8
   This library is distributed in the hope that it will be useful,
 
9
   but WITHOUT ANY WARRANTY; without even the implied warranty of
 
10
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 
11
   Library General Public License for more details.
 
12
 
 
13
   You should have received a copy of the GNU Library General Public License
 
14
   along with this library; see the file COPYING.LIB.  If not, write to
 
15
   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 
16
   Boston, MA 02111-1307, USA.
 
17
*/
 
18
 
 
19
#ifndef _KACTION_SELECTOR_H_
 
20
#define _KACTION_SELECTOR_H_
 
21
 
 
22
#include <qwidget.h>
 
23
 
 
24
class QListBox;
 
25
class QListBoxItem;
 
26
class QKeyEvent;
 
27
class QEvent;
 
28
class QIconSet;
 
29
 
 
30
class KActionSelectorPrivate;
 
31
 
 
32
/**
 
33
    @short A widget for selecting and arranging actions/objects
 
34
    This widget allows the user to select from a set of objects and arrange
 
35
    the order of the selected ones using two list boxes labeled "Available"
 
36
    and "Used" with horizontal arrows in between to move selected objects between 
 
37
    the two, and vertical arrows on the right to arrange the order of the selected 
 
38
    objects.
 
39
    
 
40
    The widget moves objects to the other listbox when doubleclicked if
 
41
    the property moveOnDoubleClick is set to true (default). See moveOnDoubleClick() 
 
42
    and setMoveOnDoubleClick().
 
43
 
 
44
    The user control the widget using the keyboard if enabled (default),
 
45
    see keyboardEnabled.
 
46
    
 
47
    Note that this may conflist with keyboard selection in the selected list box, 
 
48
    if you set that to anything else than QListBox::Single (which is the default).
 
49
    
 
50
    To use it, simply construct an instance and then add items to the two listboxes,
 
51
    available through lbAvailable() and lbSelected(). Whenever you want, you can retrieve
 
52
    the selected options using QListBox methods on lbSelected().
 
53
    
 
54
    This way, you can use your own QListBoxItem class, allowing you to easily
 
55
    store object data in those.
 
56
    
 
57
    When an item is moved to a listbox, it is placed below the current item
 
58
    of that listbox.
 
59
                
 
60
    Standard arrow icons are used, but you can use icons of your own choice if desired,
 
61
    see setButtonIcon(). It is also possible to set tooltips and whatsthis help
 
62
    for the buttons. See setButtonTooltip() and setButtonWhatsThis().
 
63
    
 
64
    To set whatsthis or tooltips for the listboxes, access them through
 
65
    availableListbox() and selectedListBox().
 
66
    
 
67
    All the moving buttons are automatically set enabled as expected.
 
68
    
 
69
    Signals are sent each time an item is moved, allowing you to follow the
 
70
    users actions if you need to. See addedToSelection(), removedFromSelection(),
 
71
    movedUp() and movedDown()
 
72
    
 
73
    @author Anders Lund <anders@alweb.dk>
 
74
*/
 
75
 
 
76
class KActionSelector : public QWidget {
 
77
  Q_OBJECT
 
78
  Q_ENUMS( ButtonIconSize InsertionPolicy )
 
79
  Q_PROPERTY( bool moveOnDoubleClick READ moveOnDoubleClick WRITE setMoveOnDoubleClick )
 
80
  Q_PROPERTY( bool keyboardEnabled READ keyboardEnabled WRITE setKeyboardEnabled )
 
81
  Q_PROPERTY( QString availableLabel READ availableLabel WRITE setAvailableLabel )
 
82
  Q_PROPERTY( QString selectedLabel READ selectedLabel WRITE setSelectedLabel )
 
83
  Q_PROPERTY( ButtonIconSize buttonIconSize READ buttonIconSize WRITE setButtonIconSize )
 
84
  Q_PROPERTY( InsertionPolicy availableInsertionPolicy READ availableInsertionPolicy WRITE setAvailableInsertionPolicy )
 
85
  Q_PROPERTY( InsertionPolicy selectedInsertionPolicy READ selectedInsertionPolicy WRITE setSelectedInsertionPolicy )
 
86
  Q_PROPERTY( bool showUpDownButtons READ showUpDownButtons WRITE setShowUpDownButtons )
 
87
 
 
88
public:
 
89
  KActionSelector( QWidget *parent=0, const char *name=0 );
 
90
  ~KActionSelector();
 
91
    
 
92
  /**
 
93
     @return The QListBox holding the available actions
 
94
  */
 
95
  QListBox *availableListBox(); 
 
96
  
 
97
  /**
 
98
     @return The QListBox holding the selected actions
 
99
  */
 
100
  QListBox *selectedListBox();
 
101
 
 
102
  /**
 
103
    This enum indentifies the moving buttons
 
104
  */
 
105
  enum MoveButton {
 
106
    ButtonAdd,
 
107
    ButtonRemove,
 
108
    ButtonUp,
 
109
    ButtonDown
 
110
  };
 
111
      
 
112
  /**
 
113
    This enum identifies the icon sizes, used for the move buttons.
 
114
    The values correspond to the following pixel sizes:
 
115
    @li SmallIcon - the return value of IconSize( KIcon::Small ), the user defined size
 
116
                of a small icon in KDE. This is the default setting.
 
117
    @li Small - 16px
 
118
    @li Medium - 22px
 
119
    @li Large - 32px
 
120
    @li XLarge - 48px
 
121
  */
 
122
  enum ButtonIconSize {
 
123
    SmallIcon,
 
124
    Small,
 
125
    Medium,
 
126
    Large,
 
127
    XLarge
 
128
  };
 
129
  
 
130
  /**
 
131
    This enum defines policies for where to insert moved items in a listbox.
 
132
    The following policies are currently defined:
 
133
    @li BelowCurrent - The item is inserted below the listbox'
 
134
        currentItem() or at the end if there is no curent item.
 
135
    @li Sorted - The listbox is sort()ed after one or more items are inserted.
 
136
    @li AtTop - The item is inserted at index 0 in the listbox.
 
137
    @li AtBottom - The item is inserted at the end of the listbox.
 
138
    
 
139
    @sa availableInsertionPolicy(), setAvailableInsertionPolicy(),
 
140
    selectedInsertionPolicy(), setSelectedInsertionPolicy(). 
 
141
  */
 
142
  enum InsertionPolicy {
 
143
    BelowCurrent,
 
144
    Sorted,
 
145
    AtTop,
 
146
    AtBottom
 
147
  };
 
148
  
 
149
  /**
 
150
    @return Wheather moveOnDoubleClcik is enabled.
 
151
    
 
152
    If enabled, an item in any listbox will be moved to the other one whenever
 
153
    doubleclicked.
 
154
    @sa setMoveOnDoubleClick()
 
155
  */ 
 
156
  bool moveOnDoubleClick() const;
 
157
  
 
158
  /**
 
159
    Sets moveOnDoubleClick to @p enable
 
160
    @sa moveOnDoubleClick()
 
161
  */
 
162
  void setMoveOnDoubleClick( bool enable );
 
163
  
 
164
  /**
 
165
    @return Weather keyboard control is enabled.
 
166
    
 
167
    When Keyboard control is enabled, the widget will react to
 
168
    the following keyboard actions:
 
169
    @li CTRL + Right - simulate clicking the add button
 
170
    @li CTRL + Left - simulate clicking the remove button
 
171
    @li CTRL + Up - simulate clicking the up button
 
172
    @li CTRL + Down - simulate clicking the down button
 
173
    
 
174
    Additionally, pressing RETURN or ENTER on one of the list boxes
 
175
    will cause the current item of that listbox to be moved to the other
 
176
    listbox.
 
177
    
 
178
    The keyboard actions are enabled by default.
 
179
    
 
180
    @sa setKeyboardEnabled()
 
181
  */
 
182
  bool keyboardEnabled() const;
 
183
  
 
184
  /**
 
185
    Sets the keyboard enabled depending on @p enable.
 
186
    @sa keyboardEnabled()
 
187
  */
 
188
  void setKeyboardEnabled( bool enable );
 
189
  
 
190
  /**
 
191
    @return The text of the label for the available items listbox.
 
192
  */
 
193
  QString availableLabel() const;
 
194
  
 
195
  /**
 
196
    Sets the label for the available items listbox to @p text.
 
197
    Note that this label has the listbox as its @e buddy, so that
 
198
    if you have a single ampersand in the text, the following character
 
199
    will become the accellerator to focus te listbox.
 
200
  */
 
201
  void setAvailableLabel( const QString & text );
 
202
  
 
203
  /**
 
204
    @return the label of the selected items listbox.
 
205
  */
 
206
  QString selectedLabel() const;
 
207
  
 
208
  /**
 
209
    Sets the label for the selected items listbox to @p text.
 
210
    Note that this label has the listbox as its @e buddy, so that
 
211
    if you have a single ampersand in the text, the following character
 
212
    will become the accellerator to focus te listbox.
 
213
  */
 
214
  void setSelectedLabel( const QString & text );
 
215
    
 
216
  /**
 
217
    @return the current ButtonIconSize.
 
218
  */
 
219
  ButtonIconSize buttonIconSize() const;
 
220
  
 
221
  /**
 
222
    Sets the button icon size.
 
223
    See ButtonIconSize for the possible values and their pixel meaning.
 
224
  */
 
225
  void setButtonIconSize( ButtonIconSize size );
 
226
 
 
227
  /**
 
228
    @return The current insertion policy for the available listbox.
 
229
    The default policy for the available listbox is Sorted.
 
230
    See also InsertionPolicy, setAvailableInsertionPolicy().
 
231
  */
 
232
  InsertionPolicy availableInsertionPolicy() const;
 
233
  
 
234
  /**
 
235
    Sets the insertion policy for the available listbox.
 
236
    See also InsertionPolicy, availableInsertionPolicy().
 
237
  */
 
238
  void setAvailableInsertionPolicy( InsertionPolicy policy );
 
239
 
 
240
  /**
 
241
    @return The current insertion policy for the selected listbox.
 
242
    The default policy for the selected listbox is BelowCurrent.
 
243
    See also InsertionPolicy, setSelectedInsertionPolicy().
 
244
  */
 
245
  InsertionPolicy selectedInsertionPolicy() const;
 
246
  
 
247
  /**
 
248
    Sets the insertion policy for the selected listbox.
 
249
    See also InsertionPolicy, selectedInsertionPolicy().
 
250
  */
 
251
  void setSelectedInsertionPolicy( InsertionPolicy policy );
 
252
  
 
253
  /**
 
254
    @return wheather the Up and Down buttons should be displayed.
 
255
  */
 
256
  bool showUpDownButtons() const;
 
257
  
 
258
  /**
 
259
    Sets wheather the Up and Down buttons should be displayed
 
260
    according to @p show
 
261
  */
 
262
  void setShowUpDownButtons( bool show );
 
263
      
 
264
  /**
 
265
    Sets the pixmap of the button @p button to @p icon.
 
266
    It calls SmallIconSet(pm) to generate the icon set.
 
267
  */
 
268
  void setButtonIcon( const QString &icon, MoveButton button );
 
269
  
 
270
  /**
 
271
    Sets the iconset for button @p button to @p iconset.
 
272
    You can use this method to et a costum icon set. Either
 
273
    created by @ref QIconSet, or use the application instance of
 
274
    @ref KIconLoader (recommended).
 
275
  */
 
276
  void setButtonIconSet( const QIconSet &iconset, MoveButton button );
 
277
  
 
278
  /**
 
279
    Sets the tooltip for the button @p button to @p tip.
 
280
  */
 
281
  void setButtonTooltip( const QString &tip, MoveButton button );
 
282
  
 
283
  /**
 
284
    Sets the whatsthis help for button @p button to @p text.
 
285
  */
 
286
  void setButtonWhatsThis( const QString &text, MoveButton button );
 
287
 
 
288
  /**
 
289
     Sets the enabled state of all moving buttons to reflect the current
 
290
     options.
 
291
     
 
292
     Be sure to call this if you add or removes items to either listbox after the
 
293
     widget is show()n
 
294
  */
 
295
  void setButtonsEnabled();
 
296
    
 
297
signals:
 
298
  /**
 
299
    Emitted when an item is moved to the "selected" listbox.
 
300
  */
 
301
  void added( QListBoxItem *item );
 
302
 
 
303
  /**
 
304
    Emitted when an item is moved out of the "selected" listbox.
 
305
  */
 
306
  void removed( QListBoxItem *item );
 
307
 
 
308
  /**
 
309
    Emitted when an item is moved upwards in the "selected" listbox.
 
310
  */
 
311
  void movedUp( QListBoxItem *item );
 
312
 
 
313
  /**
 
314
    Emitted when an item is moved downwards in the "selected" listbox.
 
315
  */
 
316
  void movedDown( QListBoxItem *item );
 
317
 
 
318
  /**
 
319
    Emitted when an item is moved to the "selected" listbox.
 
320
  */
 
321
//  void addedToSelection( QListBoxItem *item );
 
322
 
 
323
public slots:
 
324
  /**
 
325
    Reimplemented for internal reasons.
 
326
    (calls setButtonsEnabled())
 
327
  */
 
328
  void polish();
 
329
  
 
330
protected:
 
331
  /**
 
332
    Reimplamented for internal reasons.
 
333
  */
 
334
  void keyPressEvent( QKeyEvent * );
 
335
  
 
336
  /**
 
337
    Reimplemented for internal reasons.
 
338
  */
 
339
  bool eventFilter( QObject *, QEvent * );
 
340
  
 
341
private slots:
 
342
  /** 
 
343
    Move selected item from available box to the selected box 
 
344
  */  
 
345
  void buttonAddClicked();
 
346
  
 
347
  /** 
 
348
    Move selected item from selected box to available box 
 
349
  */
 
350
  void buttonRemoveClicked();
 
351
  
 
352
  /**
 
353
    Move selected item in selected box upwards 
 
354
  */
 
355
  void buttonUpClicked();
 
356
  
 
357
  /**
 
358
    Move seleted item in selected box downwards 
 
359
  */
 
360
  void buttonDownClicked();
 
361
  
 
362
  /**
 
363
    Moves the item @p item to the other listbox if moveOnDoubleClick is enabled.
 
364
  */
 
365
  void  itemDoubleClicked( QListBoxItem *item );
 
366
  
 
367
  /**
 
368
    connected to both list boxes to set the buttons enabled
 
369
  */
 
370
  void slotCurrentChanged( QListBoxItem * ) { setButtonsEnabled(); };
 
371
  
 
372
private:
 
373
  
 
374
  /**
 
375
    Move item @p item to the other listbox
 
376
  */
 
377
  void moveItem( QListBoxItem *item );
 
378
  
 
379
  /**
 
380
    loads the icons for the move buttons.
 
381
  */
 
382
  void loadIcons();
 
383
  
 
384
  /**
 
385
    @return the index to insert an item into listbox @p lb,
 
386
    given InsertionPolicy @p policy.
 
387
    
 
388
    Note that if policy is Sorted, this will return -1.
 
389
    Sort the listbox after inserting the item in that case.
 
390
  */
 
391
  int insertionIndex( QListBox *lb, InsertionPolicy policy );
 
392
  
 
393
  /**
 
394
    Private data storage 
 
395
  */
 
396
  KActionSelectorPrivate *d;
 
397
};
 
398
 
 
399
#endif // _KACTION_SELECTOR_H_