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         Default constructor.
 271
 272         Create() must be called later to effectively create the control.
 273      */
 274     wxRearrangeDialog();
 275
 276     /**
 277         Constructor creating the dialog.
 278
 279         Please see Create() for the parameters description.
 280      */
 281     wxRearrangeDialog(wxWindow *parent,
 282                       const wxString& message,
 283                       const wxString& title,
 284                       const wxArrayInt& order,
 285                       const wxArrayString& items,
 286                       const wxPoint& pos = wxDefaultPosition,
 287                       const wxString& name = wxRearrangeDialogNameStr);
 288
 289     /**
 290         Effectively creates the dialog for an object created using the default
 291         constructor.
 292
 293         @param parent
 294             The dialog parent, possibly @NULL.
 295         @param message
 296             The message shown inside the dialog itself, above the items list.
 297         @param title
 298             The title of the dialog.
 299         @param order
 300             The initial order of the items in the convention used by
 301             wxRearrangeList.
 302         @param items
 303             The items to show in the dialog.
 304         @param pos
 305             Optional dialog position.
 306         @param name
 307             Optional dialog name.
 308         @return
 309             @true if the dialog was successfully created or @false if creation
 310             failed.
 311      */
 312     bool Create(wxWindow *parent,
 313                 const wxString& message,
 314                 const wxString& title,
 315                 const wxArrayInt& order,
 316                 const wxArrayString& items,
 317                 const wxPoint& pos = wxDefaultPosition,
 318                 const wxString& name = wxRearrangeDialogNameStr);
 319
 320     /**
 321         Customize the dialog by adding extra controls to it.
 322
 323         This function adds the given @a win to the dialog, putting it just
 324         below the part occupied by wxRearrangeCtrl. It must be called after
 325         creating the dialog and you will typically need to process the events
 326         generated by the extra controls for them to do something useful.
 327
 328         For example:
 329         @code
 330             class MyRearrangeDialog : public wxRearrangeDialog
 331             {
 332             public:
 333                 MyRearrangeDialog(wxWindow *parent, ...)
 334                     : wxRearrangeDialog(parent, ...)
 335                 {
 336                     wxPanel *panel = new wxPanel(this);
 337                     wxSizer *sizer = new wxBoxSizer(wxHORIZONTAL);
 338                     sizer->Add(new wxStaticText(panel, wxID_ANY,
 339                                                 "Column width in pixels:"));
 340                     sizer->Add(new wxTextCtrl(panel, wxID_ANY, ""));
 341                     panel->SetSizer(sizer);
 342                     AddExtraControls(panel);
 343                 }
 344
 345                 ... code to update the text control with the currently selected
 346                     item width and to react to its changes omitted ...
 347             };
 348         @endcode
 349
 350         See also the complete example of a custom rearrange dialog in the
 351         dialogs sample.
 352
 353         @param win
 354             The window containing the extra controls. It must have this dialog
 355             as its parent.
 356      */
 357     void AddExtraControls(wxWindow *win);
 358
 359     /**
 360         Return the list control used by the dialog.
 361
 362         @see wxRearrangeCtrl::GetList()
 363      */
 364     wxRearrangeList *GetList() const;
 365
 366     /**
 367         Return the array describing the order of items after it was modified by
 368         the user.
 369
 370         Please notice that the array will contain negative items if any items
 371         were unchecked. See wxRearrangeList for more information about the
 372         convention used for this array.
 373      */
 374     wxArrayInt GetOrder() const;
 375 };