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     */
 515     int Insert(const wxArrayString& items, unsigned int pos);
 516
 517     /**
 518         Inserts several items at once into the control.
 519
 520         Notice that calling this method is usually much faster than inserting
 521         them one by one if you need to insert a lot of items.
 522
 523         @param items
 524             Array of strings to insert.
 525         @param pos
 526             Position to insert the items before, zero based.
 527         @param clientData
 528             Array of client data pointers of the same size as @a items to
 529             associate with the new items.
 530     */
 531     int Insert(const wxArrayString& items, unsigned int pos,
 532                 void **clientData);
 533
 534     /**
 535         Inserts several items at once into the control.
 536
 537         Notice that calling this method is usually much faster than inserting
 538         them one by one if you need to insert a lot of items.
 539
 540         @param items
 541             Array of strings to insert.
 542         @param pos
 543             Position to insert the items before, zero based.
 544         @param clientData
 545             Array of client data pointers of the same size as @a items to
 546             associate with the new items.
 547     */
 548     int Insert(const wxArrayString& items, unsigned int pos,
 549                 wxClientData **clientData);
 550
 551     /**
 552         Inserts several items at once into the control.
 553
 554         Notice that calling this method is usually much faster than inserting
 555         them one by one if you need to insert a lot of items.
 556
 557         @param n
 558             Number of items in the @a items array.
 559         @param items
 560             Array of strings of size @a n.
 561         @param pos
 562             Position to insert the items before, zero based.
 563     */
 564     int Insert(unsigned int n, const wxString* items,
 565                 unsigned int pos);
 566
 567     /**
 568         Inserts several items at once into the control.
 569
 570         Notice that calling this method is usually much faster than inserting
 571         them one by one if you need to insert a lot of items.
 572
 573         @param n
 574             Number of items in the @a items array.
 575         @param items
 576             Array of strings of size @a n.
 577         @param pos
 578             Position to insert the new items before, zero based.
 579         @param clientData
 580             Array of client data pointers of size @a n to associate with the
 581             new items.
 582     */
 583     int Insert(unsigned int n, const wxString* items,
 584                 unsigned int pos,
 585                 void** clientData);
 586
 587     /**
 588         Inserts several items at once into the control.
 589
 590         Notice that calling this method is usually much faster than inserting
 591         them one by one if you need to insert a lot of items.
 592
 593         @param n
 594             Number of items in the @a items array.
 595         @param items
 596             Array of strings of size @a n.
 597         @param pos
 598             Position to insert the new items before, zero based.
 599         @param clientData
 600             Array of client data pointers of size @a n to associate with the
 601             new items.
 602     */
 603     int Insert(unsigned int n, const wxString* items,
 604                 unsigned int pos,
 605                 wxClientData** clientData);
 606     //@}
 607
 608     //@{
 609     /**
 610         Replaces the current control contents with the given items.
 611
 612         Notice that calling this method is usually much faster than appending
 613         them one by one if you need to add a lot of items.
 614
 615         @param items
 616             Array of strings to insert.
 617     */
 618     void Set(const wxArrayString& items);
 619
 620     /**
 621         Replaces the current control contents with the given items.
 622
 623         Notice that calling this method is usually much faster than appending
 624         them one by one if you need to add a lot of items.
 625
 626         @param items
 627             Array of strings to insert.
 628         @param clientData
 629             Array of client data pointers of the same size as @a items to
 630             associate with the new items.
 631     */
 632     void Set(const wxArrayString& items, void **clientData);
 633
 634     /**
 635         Replaces the current control contents with the given items.
 636
 637         Notice that calling this method is usually much faster than appending
 638         them one by one if you need to add a lot of items.
 639
 640         @param items
 641             Array of strings to insert.
 642         @param clientData
 643             Array of client data pointers of the same size as @a items to
 644             associate with the new items.
 645     */
 646     void Set(const wxArrayString& items, wxClientData **clientData);
 647
 648     /**
 649         Replaces the current control contents with the given items.
 650
 651         Notice that calling this method is usually much faster than appending
 652         them one by one if you need to add a lot of items.
 653
 654         @param n
 655             Number of items in the @a items array.
 656         @param items
 657             Array of strings of size @a n.
 658     */
 659     void Set(unsigned int n, const wxString* items);
 660
 661     /**
 662         Replaces the current control contents with the given items.
 663
 664         Notice that calling this method is usually much faster than appending
 665         them one by one if you need to add a lot of items.
 666
 667         @param n
 668             Number of items in the @a items array.
 669         @param items
 670             Array of strings of size @a n.
 671         @param clientData
 672             Array of client data pointers of size @a n to associate with the
 673             new items.
 674     */
 675     void Set(unsigned int n, const wxString* items, void** clientData);
 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, wxClientData** clientData);
 692     //@}
 693 };
 694
 695
 696 /**
 697     @class wxControlWithItems
 698
 699     This is convenience class that derives from both wxControl and
 700     wxItemContainer. It is used as basis for some wxWidgets controls
 701     (wxChoice and wxListBox).
 702
 703     @library{wxcore}
 704     @category{ctrl}
 705
 706     @see wxItemContainer, wxItemContainerImmutable
 707 */
 708 class wxControlWithItems : public wxControl, public wxItemContainer
 709 {
 710 };
 711