interface/ctrlsub.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        ctrlsub.h
   3 // Purpose:     interface of wxControlWithItems
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @class wxItemContainerImmutable
  12     @wxheader{ctrlsub.h}
  13
  14     wxItemContainer defines an interface which is implemented by all controls
  15     which have string subitems each of which may be selected.
  16
  17     It is decomposed in wxItemContainerImmutable which omits all methods
  18     adding/removing items and is used by wxRadioBox and wxItemContainer itself.
  19
  20     Note that this is not a control, it's a mixin interface that classes
  21     have to derive from in addition to wxControl or wxWindow.
  22
  23     Examples: wxListBox, wxCheckListBox, wxChoice and wxComboBox (which
  24     implements an extended interface deriving from this one)
  25
  26     @library{wxcore}
  27     @category{ctrl}
  28
  29     @see wxControlWithItems, wxItemContainer
  30 */
  31 class wxItemContainerImmutable
  32 {
  33 public:
  34     /// Constructor
  35     wxItemContainerImmutable();
  36
  37     //@{
  38
  39     /**
  40         Returns the number of items in the control.
  41
  42         @see IsEmpty()
  43     */
  44     virtual unsigned int GetCount() const;
  45
  46     /**
  47         Returns @true if the control is empty or @false if it has some items.
  48
  49         @see GetCount()
  50     */
  51     bool IsEmpty() const;
  52
  53     /**
  54         Returns the label of the item with the given index.
  55
  56         @param n
  57             The zero-based index.
  58
  59         @return The label of the item or an empty string if the position was
  60                 invalid.
  61     */
  62     virtual wxString GetString(unsigned int n) const;
  63
  64     /**
  65         Returns the array of the labels of all items in the control.
  66     */
  67     wxArrayString GetStrings() const;
  68
  69     /**
  70         Sets the label for the given item.
  71
  72         @param n
  73             The zero-based item index.
  74         @param string
  75             The label to set.
  76     */
  77     virtual void SetString(unsigned int n, const wxString& s);
  78
  79     /**
  80         Finds an item whose label matches the given string.
  81
  82         @param string
  83             String to find.
  84         @param caseSensitive
  85             Whether search is case sensitive (default is not).
  86
  87         @return The zero-based position of the item, or wxNOT_FOUND if the
  88                 string was not found.
  89     */
  90     virtual int FindString(const wxString& s, bool bCase = false) const;
  91
  92     //@}
  93
  94     /// @name Selection
  95     //@{
  96
  97     /**
  98         Sets the selection to the given item @a n or removes the selection
  99         entirely if @a n == @c wxNOT_FOUND.
 100
 101         Note that this does not cause any command events to be emitted nor does
 102         it deselect any other items in the controls which support multiple
 103         selections.
 104
 105         @param n
 106             The string position to select, starting from zero.
 107
 108         @see SetString(), SetStringSelection()
 109     */
 110     virtual void SetSelection(int n);
 111
 112     /**
 113         Returns the index of the selected item or @c wxNOT_FOUND if no item is
 114         selected.
 115
 116         @return The position of the current selection.
 117
 118         @remarks This method can be used with single selection list boxes only,
 119                  you should use wxListBox::GetSelections() for the list
 120                  boxes with wxLB_MULTIPLE style.
 121
 122         @see SetSelection(), GetStringSelection()
 123     */
 124     virtual int GetSelection() const;
 125
 126     /**
 127         Selects the item with the specified string in the control. This doesn't
 128         cause any command events to be emitted.
 129
 130         @param string
 131             The string to select.
 132
 133         @return @true if the specified string has been selected, @false if it
 134                 wasn't found in the control.
 135     */
 136     bool SetStringSelection(const wxString& string);
 137
 138     /**
 139         Returns the label of the selected item or an empty string if no item is
 140         selected.
 141
 142         @see GetSelection()
 143     */
 144     virtual wxString GetStringSelection() const;
 145
 146     /**
 147         This is the same as SetSelection() and exists only because it is
 148         slightly more natural for controls which support multiple selection.
 149     */
 150     void Select(int n);
 151
 152     //@}
 153 };
 154
 155
 156 /**
 157     @class wxItemContainer
 158     @wxheader{ctrlsub.h}
 159
 160     This class is an abstract base class for some wxWidgets controls which
 161     contain several items such as wxListBox, wxCheckListBox, wxComboBox or
 162     wxChoice. It defines an interface which is implemented by all controls
 163     which have string subitems each of which may be selected.
 164
 165     wxItemContainer extends wxItemContainerImmutable interface with methods
 166     for adding/removing items.
 167
 168     It defines the methods for accessing the controls items and although each
 169     of the derived classes implements them differently, they still all conform
 170     to the same interface.
 171
 172     The items in a wxItemContainer have (non-empty) string labels and,
 173     optionally, client data associated with them. Client data may be of two
 174     different kinds: either simple untyped (@c void *) pointers which are
 175     simply stored by the control but not used in any way by it, or typed
 176     pointers (wxClientData*) which are owned by the control meaning that the
 177     typed client data (and only it) will be deleted when an item is deleted
 178     using Delete() or the entire control is cleared using Clear(), which also
 179     happens when it is destroyed.
 180
 181     Finally note that in the same control all items must have client data of
 182     the same type (typed or untyped), if any. This type is determined by the
 183     first call to Append() (the version with client data pointer) or
 184     SetClientData().
 185
 186     Note that this is not a control, it's a mixin interface that classes
 187     have to derive from in addition to wxControl or wxWindow. Convenience
 188     class wxControlWithItems is provided for this purpose.
 189
 190     @library{wxcore}
 191     @category{ctrl}
 192
 193     @see wxControlWithItems, wxItemContainerImmutable
 194 */
 195 class wxItemContainer : public wxItemContainerImmutable
 196 {
 197 public:
 198     //@{
 199
 200     /**
 201         Appends item into the control.
 202
 203         @param item
 204             String to add.
 205
 206         @return The return value is the index of the newly inserted item.
 207                 Note that this may be different from the last one if the
 208                 control is sorted (e.g. has @c wxLB_SORT or @c wxCB_SORT
 209                 style).
 210     */
 211     int Append(const wxString& item);
 212
 213     /**
 214         Appends item into the control.
 215
 216         @param item
 217             String to add.
 218         @param clientData
 219             Pointer to client data to associate with the new item.
 220
 221         @return The return value is the index of the newly inserted item.
 222                 Note that this may be different from the last one if the
 223                 control is sorted (e.g. has @c wxLB_SORT or @c wxCB_SORT
 224                 style).
 225     */
 226     int Append(const wxString& item, void* clientData);
 227
 228     /**
 229         Appends item into the control.
 230
 231         @param item
 232             String to add.
 233         @param clientData
 234             Pointer to client data to associate with the new item.
 235
 236         @return The return value is the index of the newly inserted item.
 237                 Note that this may be different from the last one if the
 238                 control is sorted (e.g. has @c wxLB_SORT or @c wxCB_SORT
 239                 style).
 240     */
 241     int Append(const wxString& item, wxClientData* clientData);
 242
 243     /**
 244         Appends several items at once into the control.
 245
 246         Notice that calling this method is usually much faster than appending
 247         them one by one if you need to add a lot of items.
 248
 249         @param items
 250             Array of strings to insert.
 251     */
 252     void Append(const wxArrayString& items);
 253
 254     /**
 255         Appends several items at once into the control.
 256
 257         Notice that calling this method is usually much faster than appending
 258         them one by one if you need to add a lot of items.
 259
 260         @param items
 261             Array of strings to insert.
 262         @param clientData
 263             Array of client data pointers of the same size as @a items to
 264             associate with the new items.
 265     */
 266     void Append(const wxArrayString& items, void **clientData);
 267
 268     /**
 269         Appends several items at once into the control.
 270
 271         Notice that calling this method is usually much faster than appending
 272         them one by one if you need to add a lot of items.
 273
 274         @param items
 275             Array of strings to insert.
 276         @param clientData
 277             Array of client data pointers of the same size as @a items to
 278             associate with the new items.
 279     */
 280     void Append(const wxArrayString& items, wxClientData **clientData);
 281
 282     /**
 283         Appends several items at once into the control.
 284
 285         Notice that calling this method is usually much faster than appending
 286         them one by one if you need to add a lot of items.
 287
 288         @param n
 289             Number of items in the @a items array.
 290         @param items
 291             Array of strings of size @a n.
 292     */
 293     void Append(unsigned int n, const wxString* items);
 294
 295     /**
 296         Appends several items at once into the control.
 297
 298         Notice that calling this method is usually much faster than appending
 299         them one by one if you need to add a lot of items.
 300
 301         @param n
 302             Number of items in the @a items array.
 303         @param items
 304             Array of strings of size @a n.
 305         @param clientData
 306             Array of client data pointers of size @a n to associate with the
 307             new items.
 308     */
 309     void Append(unsigned int n, const wxString* items,
 310                 void** clientData);
 311
 312     /**
 313         Appends several items at once into the control.
 314
 315         Notice that calling this method is usually much faster than appending
 316         them one by one if you need to add a lot of items.
 317
 318         @param n
 319             Number of items in the @a items array.
 320         @param items
 321             Array of strings of size @a n.
 322         @param clientData
 323             Array of client data pointers of size @a n to associate with the
 324             new items.
 325     */
 326     void Append(unsigned int n, const wxString* items,
 327                 wxClientData** clientData);
 328     //@}
 329
 330     /**
 331         Removes all items from the control.
 332         Clear() also deletes the client data of the existing items if it is
 333         owned by the control.
 334     */
 335     void Clear();
 336
 337     /**
 338         Deletes an item from the control.
 339
 340         The client data associated with the item will be also deleted if it is
 341         owned by the control.  Note that it is an error (signalled by an assert
 342         failure in debug builds) to remove an item with the index negative or
 343         greater or equal than the number of items in the control.
 344
 345         @param n
 346             The zero-based item index.
 347
 348         @see Clear()
 349     */
 350     void Delete(unsigned int n);
 351
 352     //@{
 353
 354     /**
 355         Returns a pointer to the client data associated with the given item (if
 356         any).  It is an error to call this function for a control which doesn't
 357         have untyped client data at all although it is OK to call it even if
 358         the given item doesn't have any client data associated with it (but
 359         other items do).
 360
 361         @param n
 362             The zero-based position of the item.
 363
 364         @return A pointer to the client data, or @NULL if not present.
 365     */
 366     void* GetClientData(unsigned int n) const;
 367
 368     /**
 369         Returns a pointer to the client data associated with the given item (if
 370         any).  It is an error to call this function for a control which doesn't
 371         have typed client data at all although it is OK to call it even if the
 372         given item doesn't have any client data associated with it (but other
 373         items do).
 374
 375         @param n
 376             The zero-based position of the item.
 377
 378         @return A pointer to the client data, or @NULL if not present.
 379     */
 380     wxClientData* GetClientObject(unsigned int n) const;
 381
 382     /**
 383         Associates the given untyped client data pointer with the given item.
 384         Note that it is an error to call this function if any typed client data
 385         pointers had been associated with the control items before.
 386
 387         @param n
 388             The zero-based item index.
 389         @param data
 390             The client data to associate with the item.
 391     */
 392     void SetClientData(unsigned int n, void* data);
 393
 394     /**
 395         Associates the given typed client data pointer with the given item: the
 396         @a data object will be deleted when the item is deleted (either
 397         explicitly by using Delete() or implicitly when the control itself is
 398         destroyed).  Note that it is an error to call this function if any
 399         untyped client data pointers had been associated with the control items
 400         before.
 401
 402         @param n
 403             The zero-based item index.
 404         @param data
 405             The client data to associate with the item.
 406     */
 407     void SetClientObject(unsigned int n, wxClientData* data);
 408
 409     //@}
 410
 411     //@{
 412
 413     /**
 414         Inserts item into the control.
 415
 416         @param item
 417             String to add.
 418         @param pos
 419             Position to insert item before, zero based.
 420
 421         @return The return value is the index of the newly inserted item.
 422                 If the insertion failed for some reason, -1 is returned.
 423     */
 424     int Insert(const wxString& item, unsigned int pos);
 425
 426     /**
 427         Inserts item into the control.
 428
 429         @param item
 430             String to add.
 431         @param pos
 432             Position to insert item before, zero based.
 433         @param clientData
 434             Pointer to client data to associate with the new item.
 435
 436         @return The return value is the index of the newly inserted item.
 437                 If the insertion failed for some reason, -1 is returned.
 438     */
 439     int Insert(const wxString& item, unsigned int pos, void* clientData);
 440
 441     /**
 442         Inserts item into the control.
 443
 444         @param item
 445             String to add.
 446         @param pos
 447             Position to insert item before, zero based.
 448         @param clientData
 449             Pointer to client data to associate with the new item.
 450
 451         @return The return value is the index of the newly inserted item.
 452                 If the insertion failed for some reason, -1 is returned.
 453     */
 454     int Insert(const wxString& item, unsigned int pos,
 455                wxClientData* clientData);
 456
 457     /**
 458         Inserts several items at once into the control.
 459
 460         Notice that calling this method is usually much faster than inserting
 461         them one by one if you need to insert a lot of items.
 462
 463         @param items
 464             Array of strings to insert.
 465         @param pos
 466             Position to insert the items before, zero based.
 467     */
 468     void Insert(const wxArrayString& items, unsigned int pos);
 469
 470     /**
 471         Inserts several items at once into the control.
 472
 473         Notice that calling this method is usually much faster than inserting
 474         them one by one if you need to insert a lot of items.
 475
 476         @param items
 477             Array of strings to insert.
 478         @param pos
 479             Position to insert the items before, zero based.
 480         @param clientData
 481             Array of client data pointers of the same size as @a items to
 482             associate with the new items.
 483     */
 484     void Insert(const wxArrayString& items, unsigned int pos,
 485                 void **clientData);
 486
 487     /**
 488         Inserts several items at once into the control.
 489
 490         Notice that calling this method is usually much faster than inserting
 491         them one by one if you need to insert a lot of items.
 492
 493         @param items
 494             Array of strings to insert.
 495         @param pos
 496             Position to insert the items before, zero based.
 497         @param clientData
 498             Array of client data pointers of the same size as @a items to
 499             associate with the new items.
 500     */
 501     void Insert(const wxArrayString& items, unsigned int pos,
 502                 wxClientData **clientData);
 503
 504     /**
 505         Inserts several items at once into the control.
 506
 507         Notice that calling this method is usually much faster than inserting
 508         them one by one if you need to insert a lot of items.
 509
 510         @param n
 511             Number of items in the @a items array.
 512         @param items
 513             Array of strings of size @a n.
 514         @param pos
 515             Position to insert the items before, zero based.
 516     */
 517     void Insert(unsigned int n, const wxString* items,
 518                 unsigned int pos);
 519
 520     /**
 521         Inserts several items at once into the control.
 522
 523         Notice that calling this method is usually much faster than inserting
 524         them one by one if you need to insert a lot of items.
 525
 526         @param n
 527             Number of items in the @a items array.
 528         @param items
 529             Array of strings of size @a n.
 530         @param pos
 531             Position to insert the new items before, zero based.
 532         @param clientData
 533             Array of client data pointers of size @a n to associate with the
 534             new items.
 535     */
 536     void Insert(unsigned int n, const wxString* items,
 537                 unsigned int pos,
 538                 void** clientData);
 539
 540     /**
 541         Inserts several items at once into the control.
 542
 543         Notice that calling this method is usually much faster than inserting
 544         them one by one if you need to insert a lot of items.
 545
 546         @param n
 547             Number of items in the @a items array.
 548         @param items
 549             Array of strings of size @a n.
 550         @param pos
 551             Position to insert the new items before, zero based.
 552         @param clientData
 553             Array of client data pointers of size @a n to associate with the
 554             new items.
 555     */
 556     void Insert(unsigned int n, const wxString* items,
 557                 unsigned int pos,
 558                 wxClientData** clientData);
 559     //@}
 560
 561     //@{
 562     /**
 563         Replaces the current control contents with the given items.
 564
 565         Notice that calling this method is usually much faster than appending
 566         them one by one if you need to add a lot of items.
 567
 568         @param items
 569             Array of strings to insert.
 570     */
 571     void Set(const wxArrayString& items);
 572
 573     /**
 574         Replaces the current control contents with the given items.
 575
 576         Notice that calling this method is usually much faster than appending
 577         them one by one if you need to add a lot of items.
 578
 579         @param items
 580             Array of strings to insert.
 581         @param clientData
 582             Array of client data pointers of the same size as @a items to
 583             associate with the new items.
 584     */
 585     void Set(const wxArrayString& items, void **clientData);
 586
 587     /**
 588         Replaces the current control contents with the given items.
 589
 590         Notice that calling this method is usually much faster than appending
 591         them one by one if you need to add a lot of items.
 592
 593         @param items
 594             Array of strings to insert.
 595         @param clientData
 596             Array of client data pointers of the same size as @a items to
 597             associate with the new items.
 598     */
 599     void Set(const wxArrayString& items, wxClientData **clientData);
 600
 601     /**
 602         Replaces the current control contents with the given items.
 603
 604         Notice that calling this method is usually much faster than appending
 605         them one by one if you need to add a lot of items.
 606
 607         @param n
 608             Number of items in the @a items array.
 609         @param items
 610             Array of strings of size @a n.
 611     */
 612     void Set(unsigned int n, const wxString* items);
 613
 614     /**
 615         Replaces the current control contents with the given items.
 616
 617         Notice that calling this method is usually much faster than appending
 618         them one by one if you need to add a lot of items.
 619
 620         @param n
 621             Number of items in the @a items array.
 622         @param items
 623             Array of strings of size @a n.
 624         @param clientData
 625             Array of client data pointers of size @a n to associate with the
 626             new items.
 627     */
 628     void Set(unsigned int n, const wxString* items, void** clientData);
 629
 630     /**
 631         Replaces the current control contents with the given items.
 632
 633         Notice that calling this method is usually much faster than appending
 634         them one by one if you need to add a lot of items.
 635
 636         @param n
 637             Number of items in the @a items array.
 638         @param items
 639             Array of strings of size @a n.
 640         @param clientData
 641             Array of client data pointers of size @a n to associate with the
 642             new items.
 643     */
 644     void Set(unsigned int n, const wxString* items, wxClientData** clientData);
 645     //@}
 646 };
 647
 648
 649 /**
 650     @class wxControlWithItems
 651     @wxheader{ctrlsub.h}
 652
 653     This is convenience class that derives from both wxControl and
 654     wxItemContainer. It is used as basis for some wxWidgets controls
 655     (wxChoice and wxListBox).
 656
 657     @library{wxcore}
 658     @category{ctrl}
 659
 660     @see wxItemContainer, wxItemContainerImmutable
 661 */
 662 class wxControlWithItems : public wxControl, public wxItemContainer
 663 {
 664 };
 665