interface/wx/ctrlsub.h

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