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