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