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 true, if either untyped data (@c void*) or object data (wxClientData*)
 353        is associated with the items of the control.
 354     */
 355     bool HasClientData() const;
 356
 357     /**
 358        Returns true, if object data (wxClientData*)
 359        is associated with the items of the control.
 360     */
 361     bool HasClientObjectData() const;
 362
 363     /**
 364        Returns true, if untyped data (@c void*)
 365        is associated with the items of the control.
 366     */
 367     bool HasClientUntypedData() const;
 368
 369
 370     //@{
 371
 372     /**
 373         Returns a pointer to the client data associated with the given item (if
 374         any).  It is an error to call this function for a control which doesn't
 375         have untyped client data at all although it is OK to call it even if
 376         the given item doesn't have any client data associated with it (but
 377         other items do).
 378
 379         @param n
 380             The zero-based position of the item.
 381
 382         @return A pointer to the client data, or @NULL if not present.
 383     */
 384     void* GetClientData(unsigned int n) const;
 385
 386     /**
 387         Returns a pointer to the client data associated with the given item (if
 388         any).  It is an error to call this function for a control which doesn't
 389         have typed client data at all although it is OK to call it even if the
 390         given item doesn't have any client data associated with it (but other
 391         items do).
 392
 393         @param n
 394             The zero-based position of the item.
 395
 396         @return A pointer to the client data, or @NULL if not present.
 397     */
 398     wxClientData* GetClientObject(unsigned int n) const;
 399
 400     /**
 401         Associates the given untyped client data pointer with the given item.
 402         Note that it is an error to call this function if any typed client data
 403         pointers had been associated with the control items before.
 404
 405         @param n
 406             The zero-based item index.
 407         @param data
 408             The client data to associate with the item.
 409     */
 410     void SetClientData(unsigned int n, void* data);
 411
 412     /**
 413         Associates the given typed client data pointer with the given item: the
 414         @a data object will be deleted when the item is deleted (either
 415         explicitly by using Delete() or implicitly when the control itself is
 416         destroyed).  Note that it is an error to call this function if any
 417         untyped client data pointers had been associated with the control items
 418         before.
 419
 420         @param n
 421             The zero-based item index.
 422         @param data
 423             The client data to associate with the item.
 424     */
 425     void SetClientObject(unsigned int n, wxClientData* data);
 426
 427     //@}
 428
 429     //@{
 430
 431     /**
 432         Inserts item into the control.
 433
 434         @param item
 435             String to add.
 436         @param pos
 437             Position to insert item before, zero based.
 438
 439         @return The return value is the index of the newly inserted item.
 440                 If the insertion failed for some reason, -1 is returned.
 441     */
 442     int Insert(const wxString& item, unsigned int pos);
 443
 444     /**
 445         Inserts item into the control.
 446
 447         @param item
 448             String to add.
 449         @param pos
 450             Position to insert item before, zero based.
 451         @param clientData
 452             Pointer to client data to associate with the new item.
 453
 454         @return The return value is the index of the newly inserted item.
 455                 If the insertion failed for some reason, -1 is returned.
 456     */
 457     int Insert(const wxString& item, unsigned int pos, void* clientData);
 458
 459     /**
 460         Inserts item into the control.
 461
 462         @param item
 463             String to add.
 464         @param pos
 465             Position to insert item before, zero based.
 466         @param clientData
 467             Pointer to client data to associate with the new item.
 468
 469         @return The return value is the index of the newly inserted item.
 470                 If the insertion failed for some reason, -1 is returned.
 471     */
 472     int Insert(const wxString& item, unsigned int pos,
 473                wxClientData* clientData);
 474
 475     /**
 476         Inserts several items at once into the control.
 477
 478         Notice that calling this method is usually much faster than inserting
 479         them one by one if you need to insert a lot of items.
 480
 481         @param items
 482             Array of strings to insert.
 483         @param pos
 484             Position to insert the items before, zero based.
 485     */
 486     int Insert(const wxArrayString& items, unsigned int pos);
 487
 488     /**
 489         Inserts several items at once into the control.
 490
 491         Notice that calling this method is usually much faster than inserting
 492         them one by one if you need to insert a lot of items.
 493
 494         @param items
 495             Array of strings to insert.
 496         @param pos
 497             Position to insert the items before, zero based.
 498         @param clientData
 499             Array of client data pointers of the same size as @a items to
 500             associate with the new items.
 501     */
 502     int Insert(const wxArrayString& items, unsigned int pos,
 503                 void **clientData);
 504
 505     /**
 506         Inserts several items at once into the control.
 507
 508         Notice that calling this method is usually much faster than inserting
 509         them one by one if you need to insert a lot of items.
 510
 511         @param items
 512             Array of strings to insert.
 513         @param pos
 514             Position to insert the items before, zero based.
 515         @param clientData
 516             Array of client data pointers of the same size as @a items to
 517             associate with the new items.
 518     */
 519     int Insert(const wxArrayString& items, unsigned int pos,
 520                 wxClientData **clientData);
 521
 522     /**
 523         Inserts several items at once into the control.
 524
 525         Notice that calling this method is usually much faster than inserting
 526         them one by one if you need to insert a lot of items.
 527
 528         @param n
 529             Number of items in the @a items array.
 530         @param items
 531             Array of strings of size @a n.
 532         @param pos
 533             Position to insert the items before, zero based.
 534     */
 535     int Insert(unsigned int n, const wxString* items,
 536                 unsigned int pos);
 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 n
 545             Number of items in the @a items array.
 546         @param items
 547             Array of strings of size @a n.
 548         @param pos
 549             Position to insert the new items before, zero based.
 550         @param clientData
 551             Array of client data pointers of size @a n to associate with the
 552             new items.
 553     */
 554     int Insert(unsigned int n, const wxString* items,
 555                 unsigned int pos,
 556                 void** clientData);
 557
 558     /**
 559         Inserts several items at once into the control.
 560
 561         Notice that calling this method is usually much faster than inserting
 562         them one by one if you need to insert a lot of items.
 563
 564         @param n
 565             Number of items in the @a items array.
 566         @param items
 567             Array of strings of size @a n.
 568         @param pos
 569             Position to insert the new items before, zero based.
 570         @param clientData
 571             Array of client data pointers of size @a n to associate with the
 572             new items.
 573     */
 574     int Insert(unsigned int n, const wxString* items,
 575                 unsigned int pos,
 576                 wxClientData** clientData);
 577     //@}
 578
 579     //@{
 580     /**
 581         Replaces the current control contents with the given items.
 582
 583         Notice that calling this method is usually much faster than appending
 584         them one by one if you need to add a lot of items.
 585
 586         @param items
 587             Array of strings to insert.
 588     */
 589     void Set(const wxArrayString& items);
 590
 591     /**
 592         Replaces the current control contents with the given items.
 593
 594         Notice that calling this method is usually much faster than appending
 595         them one by one if you need to add a lot of items.
 596
 597         @param items
 598             Array of strings to insert.
 599         @param clientData
 600             Array of client data pointers of the same size as @a items to
 601             associate with the new items.
 602     */
 603     void Set(const wxArrayString& items, void **clientData);
 604
 605     /**
 606         Replaces the current control contents with the given items.
 607
 608         Notice that calling this method is usually much faster than appending
 609         them one by one if you need to add a lot of items.
 610
 611         @param items
 612             Array of strings to insert.
 613         @param clientData
 614             Array of client data pointers of the same size as @a items to
 615             associate with the new items.
 616     */
 617     void Set(const wxArrayString& items, wxClientData **clientData);
 618
 619     /**
 620         Replaces the current control contents with the given items.
 621
 622         Notice that calling this method is usually much faster than appending
 623         them one by one if you need to add a lot of items.
 624
 625         @param n
 626             Number of items in the @a items array.
 627         @param items
 628             Array of strings of size @a n.
 629     */
 630     void Set(unsigned int n, const wxString* 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 n
 639             Number of items in the @a items array.
 640         @param items
 641             Array of strings of size @a n.
 642         @param clientData
 643             Array of client data pointers of size @a n to associate with the
 644             new items.
 645     */
 646     void Set(unsigned int n, const wxString* items, void** 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         @param clientData
 659             Array of client data pointers of size @a n to associate with the
 660             new items.
 661     */
 662     void Set(unsigned int n, const wxString* items, wxClientData** clientData);
 663     //@}
 664 };
 665
 666
 667 /**
 668     @class wxControlWithItems
 669
 670     This is convenience class that derives from both wxControl and
 671     wxItemContainer. It is used as basis for some wxWidgets controls
 672     (wxChoice and wxListBox).
 673
 674     @library{wxcore}
 675     @category{ctrl}
 676
 677     @see wxItemContainer, wxItemContainerImmutable
 678 */
 679 class wxControlWithItems : public wxControl, public wxItemContainer
 680 {
 681 };
 682