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