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 licence
   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     @since 2.9.0
  46
  47     @library{wxcore}
  48     @category{ctrl}
  49 */
  50 class wxRearrangeList : public wxCheckListBox
  51 {
  52 public:
  53     /**
  54         Default constructor.
  55
  56         Create() must be called later to effectively create the control.
  57      */
  58     wxRearrangeList();
  59
  60     /**
  61         Constructor really creating the control.
  62
  63         Please see Create() for the parameters description.
  64      */
  65     wxRearrangeList(wxWindow *parent,
  66                     wxWindowID id,
  67                     const wxPoint& pos,
  68                     const wxSize& size,
  69                     const wxArrayInt& order,
  70                     const wxArrayString& items,
  71                     long style = 0,
  72                     const wxValidator& validator = wxDefaultValidator,
  73                     const wxString& name = wxRearrangeListNameStr);
  74
  75     /**
  76         Effectively creates the window for an object created using the default
  77         constructor.
  78
  79         This function is very similar to wxCheckListBox::Create() except that
  80         it has an additional parameter specifying the initial order of the
  81         items. Please see the class documentation for the explanation of the
  82         conventions used by the @a order argument.
  83
  84         @param parent
  85             The parent window, must be non-@NULL.
  86         @param id
  87             The window identifier.
  88         @param pos
  89             The initial window position.
  90         @param size
  91             The initial window size.
  92         @param order
  93             Array specifying the initial order of the items in @a items array.
  94         @param items
  95             The items to display in the list.
  96         @param style
  97             The control style, there are no special styles for this class but
  98             the base class styles can be used here.
  99         @param validator
 100             Optional window validator.
 101         @param name
 102             Optional window name.
 103      */
 104     bool Create(wxWindow *parent,
 105                 wxWindowID id,
 106                 const wxPoint& pos,
 107                 const wxSize& size,
 108                 const wxArrayInt& order,
 109                 const wxArrayString& items,
 110                 long style = 0,
 111                 const wxValidator& validator = wxDefaultValidator,
 112                 const wxString& name = wxRearrangeListNameStr);
 113
 114
 115     /**
 116         Return the current order of the items.
 117
 118         The order may be different from the one passed to the constructor if
 119         MoveCurrentUp() or MoveCurrentDown() were called.
 120      */
 121     const wxArrayInt& GetCurrentOrder() const;
 122
 123     /**
 124         Return @true if the currently selected item can be moved up.
 125
 126         This function is useful for EVT_UPDATE_UI handler for the standard "Up"
 127         button often used together with this control and wxRearrangeCtrl uses
 128         it in this way.
 129
 130         @return
 131             @true if the currently selected item can be moved up in the
 132             listbox, @false if there is no selection or the current item is the
 133             first one.
 134
 135         @see CanMoveCurrentDown()
 136      */
 137     bool CanMoveCurrentUp() const;
 138
 139     /**
 140         Return @true if the currently selected item can be moved down.
 141
 142         @see CanMoveCurrentUp()
 143      */
 144     bool CanMoveCurrentDown() const;
 145
 146     /**
 147         Move the currently selected item one position above.
 148
 149         This method is useful to implement the standard "Up" button behaviour
 150         and wxRearrangeCtrl uses it for this.
 151
 152         @return
 153             @true if the item was moved or @false if this couldn't be done.
 154
 155         @see MoveCurrentDown()
 156      */
 157     bool MoveCurrentUp();
 158
 159     /**
 160         Move the currently selected item one position below.
 161
 162         @see MoveCurrentUp()
 163      */
 164     bool MoveCurrentDown();
 165 };
 166
 167
 168 /**
 169     @class wxRearrangeCtrl
 170
 171     A composite control containing a wxRearrangeList and the buttons allowing
 172     to move the items in it.
 173
 174     This control is in fact a panel containing the wxRearrangeList control and
 175     the "Up" and "Down" buttons to move the currently selected item up or down.
 176     It is used as the main part of a wxRearrangeDialog.
 177
 178     @since 2.9.0
 179
 180     @library{wxcore}
 181     @category{ctrl}
 182  */
 183 class wxRearrangeCtrl : public wxPanel
 184 {
 185 public:
 186     /**
 187         Default constructor.
 188
 189         Create() must be called later to effectively create the control.
 190      */
 191     wxRearrangeCtrl();
 192
 193     /**
 194         Constructor really creating the control.
 195
 196         Please see Create() for the parameters description.
 197      */
 198     wxRearrangeCtrl(wxWindow *parent,
 199                     wxWindowID id,
 200                     const wxPoint& pos,
 201                     const wxSize& size,
 202                     const wxArrayInt& order,
 203                     const wxArrayString& items,
 204                     long style = 0,
 205                     const wxValidator& validator = wxDefaultValidator,
 206                     const wxString& name = wxRearrangeListNameStr);
 207
 208     /**
 209         Effectively creates the window for an object created using the default
 210         constructor.
 211
 212         The parameters of this method are the same as for
 213         wxRearrangeList::Create().
 214      */
 215     bool Create(wxWindow *parent,
 216                 wxWindowID id,
 217                 const wxPoint& pos,
 218                 const wxSize& size,
 219                 const wxArrayInt& order,
 220                 const wxArrayString& items,
 221                 long style = 0,
 222                 const wxValidator& validator = wxDefaultValidator,
 223                 const wxString& name = wxRearrangeListNameStr);
 224
 225     /**
 226         Return the listbox which is the main part of this control.
 227      */
 228     wxRearrangeList *GetList() const;
 229 };
 230
 231 /**
 232     @class wxRearrangeDialog
 233
 234     A dialog allowing the user to rearrange the specified items.
 235
 236     This dialog can be used to allow the user to modify the order of the items
 237     and to enable or disable them individually. For example:
 238     @code
 239         wxArrayString items;
 240         items.push_back("meat");
 241         items.push_back("fish");
 242         items.push_back("fruits");
 243         items.push_back("beer");
 244         wxArrayInt order;
 245         order.push_back(3);
 246         order.push_back(0);
 247         order.push_back(1);
 248         order.push_back(2);
 249
 250         wxRearrangeDialog dlg(NULL,
 251                               "You can also uncheck the items you don't like "
 252                               "at all.",
 253                               "Sort the items in order of preference",
 254                               order, items);
 255         if ( dlg.ShowModal() == wxID_OK ) {
 256             order = dlg.GetOrder();
 257             for ( size_t n = 0; n < order.size(); n++ ) {
 258                 if ( order[n] >= 0 ) {
 259                     wxLogMessage("Your most preferred item is \"%s\"",
 260                                  items[order[n]]);
 261                     break;
 262                 }
 263             }
 264         }
 265     @endcode
 266
 267     @since 2.9.0
 268
 269     @library{wxcore}
 270     @category{cmndlg}
 271  */
 272 class wxRearrangeDialog : public wxDialog
 273 {
 274 public:
 275     /**
 276         Default constructor.
 277
 278         Create() must be called later to effectively create the control.
 279      */
 280     wxRearrangeDialog();
 281
 282     /**
 283         Constructor creating the dialog.
 284
 285         Please see Create() for the parameters description.
 286      */
 287     wxRearrangeDialog(wxWindow *parent,
 288                       const wxString& message,
 289                       const wxString& title,
 290                       const wxArrayInt& order,
 291                       const wxArrayString& items,
 292                       const wxPoint& pos = wxDefaultPosition,
 293                       const wxString& name = wxRearrangeDialogNameStr);
 294
 295     /**
 296         Effectively creates the dialog for an object created using the default
 297         constructor.
 298
 299         @param parent
 300             The dialog parent, possibly @NULL.
 301         @param message
 302             The message shown inside the dialog itself, above the items list.
 303         @param title
 304             The title of the dialog.
 305         @param order
 306             The initial order of the items in the convention used by
 307             wxRearrangeList.
 308         @param items
 309             The items to show in the dialog.
 310         @param pos
 311             Optional dialog position.
 312         @param name
 313             Optional dialog name.
 314         @return
 315             @true if the dialog was successfully created or @false if creation
 316             failed.
 317      */
 318     bool Create(wxWindow *parent,
 319                 const wxString& message,
 320                 const wxString& title,
 321                 const wxArrayInt& order,
 322                 const wxArrayString& items,
 323                 const wxPoint& pos = wxDefaultPosition,
 324                 const wxString& name = wxRearrangeDialogNameStr);
 325
 326     /**
 327         Customize the dialog by adding extra controls to it.
 328
 329         This function adds the given @a win to the dialog, putting it just
 330         below the part occupied by wxRearrangeCtrl. It must be called after
 331         creating the dialog and you will typically need to process the events
 332         generated by the extra controls for them to do something useful.
 333
 334         For example:
 335         @code
 336             class MyRearrangeDialog : public wxRearrangeDialog
 337             {
 338             public:
 339                 MyRearrangeDialog(wxWindow *parent, ...)
 340                     : wxRearrangeDialog(parent, ...)
 341                 {
 342                     wxPanel *panel = new wxPanel(this);
 343                     wxSizer *sizer = new wxBoxSizer(wxHORIZONTAL);
 344                     sizer->Add(new wxStaticText(panel, wxID_ANY,
 345                                                 "Column width in pixels:"));
 346                     sizer->Add(new wxTextCtrl(panel, wxID_ANY, ""));
 347                     panel->SetSizer(sizer);
 348                     AddExtraControls(panel);
 349                 }
 350
 351                 ... code to update the text control with the currently selected
 352                     item width and to react to its changes omitted ...
 353             };
 354         @endcode
 355
 356         See also the complete example of a custom rearrange dialog in the
 357         dialogs sample.
 358
 359         @param win
 360             The window containing the extra controls. It must have this dialog
 361             as its parent.
 362      */
 363     void AddExtraControls(wxWindow *win);
 364
 365     /**
 366         Return the list control used by the dialog.
 367
 368         @see wxRearrangeCtrl::GetList()
 369      */
 370     wxRearrangeList *GetList() const;
 371
 372     /**
 373         Return the array describing the order of items after it was modified by
 374         the user.
 375
 376         Please notice that the array will contain negative items if any items
 377         were unchecked. See wxRearrangeList for more information about the
 378         convention used for this array.
 379      */
 380     wxArrayInt GetOrder() const;
 381 };