interface/wx/rearrangectrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/rearrangectrl.h
   3 // Purpose:     interface of wxRearrangeList
   4 // Author:      Vadim Zeitlin
   5 // Created:     2008-12-15
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2008 Vadim Zeitlin <vadim@wxwidgets.org>
   8 // Licence:     wxWindows license
   9 /////////////////////////////////////////////////////////////////////////////
  10
  11 /**
  12     @class wxRearrangeList
  13
  14     A listbox-like control allowing the user to rearrange the items and to
  15     enable or disable them.
  16
  17     This class allows to change the order of the items shown in it as well as
  18     to check or uncheck them individually. The data structure used to allow
  19     this is the order array which contains the items indices indexed by their
  20     position with an added twist that the unchecked items are represented by
  21     the bitwise complement of the corresponding index (for any architecture
  22     using two's complement for negative numbers representation (i.e. just about
  23     any at all) this means that a checked item N is represented by -N-1 in
  24     unchecked state). In practice this means that you must apply the C bitwise
  25     complement operator when constructing the order array, e.g.
  26     @code
  27         wxArrayInt order;
  28         order.push_back(0); // checked item #0
  29         order.push_back(~1); // unchecked item #1
  30     @endcode
  31
  32     So, for example, the array order [1 -3 0] used in conjunction with the
  33     items array ["first", "second", "third"] means that the items order is
  34     "second", "third", "first" and the "third" item is unchecked while the
  35     other two are checked.
  36
  37     This convention is used both for the order argument of the control ctor or
  38     Create() and for the array returned from GetCurrentOrder().
  39
  40     Usually this control will be used together with other controls allowing to
  41     move the items around in it interactively. The simplest possible solution
  42     is to use wxRearrangeCtrl which combines it with two standard buttons to
  43     move the current item up or down.
  44
  45     @library{wxcore}
  46     @category{ctrl}
  47 */
  48 class wxRearrangeList : public wxCheckListBox
  49 {
  50 public:
  51     /**
  52         Default constructor.
  53
  54         Create() must be called later to effectively create the control.
  55      */
  56     wxRearrangeList();
  57
  58     /**
  59         Constructor really creating the control.
  60
  61         Please see Create() for the parameters description.
  62      */
  63     wxRearrangeList(wxWindow *parent,
  64                     wxWindowID id,
  65                     const wxPoint& pos,
  66                     const wxSize& size,
  67                     const wxArrayInt& order,
  68                     const wxArrayString& items,
  69                     long style = 0,
  70                     const wxValidator& validator = wxDefaultValidator,
  71                     const wxString& name = wxRearrangeListNameStr);
  72
  73     /**
  74         Effectively creates the window for an object created using the default
  75         constructor.
  76
  77         This function is very similar to wxCheckListBox::Create() except that
  78         it has an additional parameter specifying the initial order of the
  79         items. Please see the class documentation for the explanation of the
  80         conventions used by the @a order argument.
  81
  82         @param parent
  83             The parent window, must be non-@NULL.
  84         @param id
  85             The window identifier.
  86         @param pos
  87             The initial window position.
  88         @param size
  89             The initial window size.
  90         @param order
  91             Array specifying the initial order of the items in @a items array.
  92         @param items
  93             The items to display in the list.
  94         @param style
  95             The control style, there are no special styles for this class but
  96             the base class styles can be used here.
  97         @param validator
  98             Optional window validator.
  99         @param name
 100             Optional window name.
 101      */
 102     bool Create(wxWindow *parent,
 103                 wxWindowID id,
 104                 const wxPoint& pos,
 105                 const wxSize& size,
 106                 const wxArrayInt& order,
 107                 const wxArrayString& items,
 108                 long style = 0,
 109                 const wxValidator& validator = wxDefaultValidator,
 110                 const wxString& name = wxRearrangeListNameStr);
 111
 112
 113     /**
 114         Return the current order of the items.
 115
 116         The order may be different from the one passed to the constructor if
 117         MoveCurrentUp() or MoveCurrentDown() were called.
 118      */
 119     const wxArrayInt& GetCurrentOrder() const;
 120
 121     /**
 122         Return @true if the currently selected item can be moved up.
 123
 124         This function is useful for EVT_UPDATE_UI handler for the standard "Up"
 125         button often used together with this control and wxRearrangeCtrl uses
 126         it in this way.
 127
 128         @return
 129             @true if the currently selected item can be moved up in the
 130             listbox, @false if there is no selection or the current item is the
 131             first one.
 132
 133         @see CanMoveCurrentDown()
 134      */
 135     bool CanMoveCurrentUp() const;
 136
 137     /**
 138         Return @true if the currently selected item can be moved down.
 139
 140         @see CanMoveCurrentUp()
 141      */
 142     bool CanMoveCurrentDown() const;
 143
 144     /**
 145         Move the currently selected item one position above.
 146
 147         This method is useful to implement the standard "Up" button behaviour
 148         and wxRearrangeCtrl uses it for this.
 149
 150         @return
 151             @true if the item was moved or @false if this couldn't be done.
 152
 153         @see MoveCurrentDown()
 154      */
 155     bool MoveCurrentUp();
 156
 157     /**
 158         Move the currently selected item one position below.
 159
 160         @see MoveCurrentUp()
 161      */
 162     bool MoveCurrentDown();
 163 };
 164
 165
 166 /**
 167     @class wxRearrangeCtrl
 168
 169     A composite control containing a wxRearrangeList and the buttons allowing
 170     to move the items in it.
 171
 172     This control is in fact a panel containing the wxRearrangeList control and
 173     the "Up" and "Down" buttons to move the currently selected item up or down.
 174     It is used as the main part of a wxRearrangeDialog.
 175
 176     @library{wxcore}
 177     @category{ctrl}
 178  */
 179 class wxRearrangeCtrl
 180 {
 181 public:
 182     /**
 183         Default constructor.
 184
 185         Create() must be called later to effectively create the control.
 186      */
 187     wxRearrangeCtrl();
 188
 189     /**
 190         Constructor really creating the control.
 191
 192         Please see Create() for the parameters description.
 193      */
 194     wxRearrangeCtrl(wxWindow *parent,
 195                     wxWindowID id,
 196                     const wxPoint& pos,
 197                     const wxSize& size,
 198                     const wxArrayInt& order,
 199                     const wxArrayString& items,
 200                     long style = 0,
 201                     const wxValidator& validator = wxDefaultValidator,
 202                     const wxString& name = wxRearrangeListNameStr);
 203
 204     /**
 205         Effectively creates the window for an object created using the default
 206         constructor.
 207
 208         The parameters of this method are the same as for
 209         wxRearrangeList::Create().
 210      */
 211     bool Create(wxWindow *parent,
 212                 wxWindowID id,
 213                 const wxPoint& pos,
 214                 const wxSize& size,
 215                 const wxArrayInt& order,
 216                 const wxArrayString& items,
 217                 long style = 0,
 218                 const wxValidator& validator = wxDefaultValidator,
 219                 const wxString& name = wxRearrangeListNameStr);
 220
 221     /**
 222         Return the listbox which is the main part of this control.
 223      */
 224     wxRearrangeList *GetList() const;
 225 };
 226
 227 /**
 228     @class wxRearrangeDialog
 229
 230     A dialog allowing the user to rearrange the specified items.
 231
 232     This dialog can be used to allow the user to modify the order of the items
 233     and to enable or disable them individually. For example:
 234     @code
 235         wxArrayString items;
 236         items.push_back("meat");
 237         items.push_back("fish");
 238         items.push_back("fruits");
 239         items.push_back("beer");
 240         wxArrayInt order;
 241         order.push_back(3);
 242         order.push_back(0);
 243         order.push_back(1);
 244         order.push_back(2);
 245
 246         wxRearrangeDialog dlg(NULL,
 247                               "You can also uncheck the items you don't like "
 248                               "at all.",
 249                               "Sort the items in order of preference",
 250                               order, items);
 251         if ( dlg.ShowModal() == wxID_OK ) {
 252             order = dlg.GetOrder();
 253             for ( size_t n = 0; n < order.size(); n++ ) {
 254                 if ( order[n] >= 0 ) {
 255                     wxLogMessage("Your most preferred item is \"%s\"",
 256                                  items[order[n]]);
 257                     break;
 258                 }
 259             }
 260         }
 261     @endcode
 262
 263     @library{wxcore}
 264     @category{cmndlg}
 265  */
 266 class wxRearrangeDialog
 267 {
 268 public:
 269     /**
 270         Constructor creating the dialog.
 271
 272         @param parent
 273             The dialog parent, possibly @NULL.
 274         @param message
 275             The message shown inside the dialog itself, above the items list.
 276         @param title
 277             The title of the dialog.
 278         @param order
 279             The initial order of the items in the convention used by
 280             wxRearrangeList.
 281         @param items
 282             The items to show in the dialog.
 283         @param pos
 284             Optional dialog position.
 285         @param name
 286             Optional dialog name.
 287      */
 288     wxRearrangeDialog(wxWindow *parent,
 289                       const wxString& message,
 290                       const wxString& title,
 291                       const wxArrayInt& order,
 292                       const wxArrayString& items,
 293                       const wxPoint& pos = wxDefaultPosition,
 294                       const wxString& name = wxRearrangeDialogNameStr);
 295
 296     /**
 297         Return the array describing the order of items after it was modified by
 298         the user.
 299
 300         Please notice that the array will contain negative items if any items
 301         were unchecked. See wxRearrangeList for more information about the
 302         convention used for this array.
 303      */
 304     wxArrayInt GetOrder() const;
 305 };