interface/wx/ctrlsub.h

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