Fix missing documentation for several GDI functions.

[wxWidgets.git] / include / wx / ctrlsub.h

diff --git a/include/wx/ctrlsub.h b/include/wx/ctrlsub.h
index c71a87835236cc20fc0973be4db0654b460d0e4f..a55e124148507a59924ed8e654c58cf89d19198c 100644 (file)
--- a/include/wx/ctrlsub.h
+++ b/include/wx/ctrlsub.h
@@ -30,7 +30,7 @@
 // implements an extended interface deriving from this one)
 // ----------------------------------------------------------------------------
 
 // implements an extended interface deriving from this one)
 // ----------------------------------------------------------------------------
 

-class WXDLLEXPORT wxItemContainerImmutable
+class WXDLLIMPEXP_CORE wxItemContainerImmutable

 {
 public:
     wxItemContainerImmutable() { }
 {
 public:
     wxItemContainerImmutable() { }


@@ -73,7 +73,7 @@ public:
     bool SetStringSelection(const wxString& s);
 
     // return the selected string or empty string if none
     bool SetStringSelection(const wxString& s);
 
     // return the selected string or empty string if none

-    wxString GetStringSelection() const;
+    virtual wxString GetStringSelection() const;

 
     // this is the same as SetSelection( for single-selection controls but
     // reads better for multi-selection ones
 
     // this is the same as SetSelection( for single-selection controls but
     // reads better for multi-selection ones


@@ -97,7 +97,7 @@ protected:
 // in this case DoInsertItem() needs to be overridden.
 // ----------------------------------------------------------------------------
 
 // in this case DoInsertItem() needs to be overridden.
 // ----------------------------------------------------------------------------
 

-class WXDLLEXPORT wxItemContainer : public wxItemContainerImmutable
+class WXDLLIMPEXP_CORE wxItemContainer : public wxItemContainerImmutable

 {
 private:
     // AppendItems() and InsertItems() helpers just call DoAppend/InsertItems()
 {
 private:
     // AppendItems() and InsertItems() helpers just call DoAppend/InsertItems()


@@ -122,7 +122,7 @@ private:
     int AppendItems(const wxArrayStringsAdapter& items, void **clientData)
     {
         wxASSERT_MSG( GetClientDataType() != wxClientData_Object,
     int AppendItems(const wxArrayStringsAdapter& items, void **clientData)
     {
         wxASSERT_MSG( GetClientDataType() != wxClientData_Object,

-                      _T("can't mix different types of client data") );
+                      wxT("can't mix different types of client data") );

 
         return AppendItems(items, clientData, wxClientData_Void);
     }
 
         return AppendItems(items, clientData, wxClientData_Void);
     }


@@ -131,9 +131,9 @@ private:
                     wxClientData **clientData)
     {
         wxASSERT_MSG( GetClientDataType() != wxClientData_Void,
                     wxClientData **clientData)
     {
         wxASSERT_MSG( GetClientDataType() != wxClientData_Void,

-                      _T("can't mix different types of client data") );
+                      wxT("can't mix different types of client data") );

 
 

-        return AppendItems(items, wx_reinterpret_cast(void **, clientData),
+        return AppendItems(items, reinterpret_cast<void **>(clientData),

                            wxClientData_Object);
     }
 
                            wxClientData_Object);
     }
 


@@ -142,17 +142,17 @@ private:
                     void **clientData,
                     wxClientDataType type)
     {
                     void **clientData,
                     wxClientDataType type)
     {

-        wxASSERT_MSG( !IsSorted(), _T("can't insert items in sorted control") );
+        wxASSERT_MSG( !IsSorted(), wxT("can't insert items in sorted control") );

 
         wxCHECK_MSG( pos <= GetCount(), wxNOT_FOUND,
 
         wxCHECK_MSG( pos <= GetCount(), wxNOT_FOUND,

-                     _T("position out of range") );
+                     wxT("position out of range") );

 
         // not all derived classes handle empty arrays correctly in
         // DoInsertItems() and besides it really doesn't make much sense to do
         // this (for append it could correspond to creating an initially empty
         // control but why would anybody need to insert 0 items?)
         wxCHECK_MSG( !items.IsEmpty(), wxNOT_FOUND,
 
         // not all derived classes handle empty arrays correctly in
         // DoInsertItems() and besides it really doesn't make much sense to do
         // this (for append it could correspond to creating an initially empty
         // control but why would anybody need to insert 0 items?)
         wxCHECK_MSG( !items.IsEmpty(), wxNOT_FOUND,

-                     _T("need something to insert") );
+                     wxT("need something to insert") );

 
         return DoInsertItems(items, pos, clientData, type);
     }
 
         return DoInsertItems(items, pos, clientData, type);
     }


@@ -167,7 +167,7 @@ private:
                      void **clientData)
     {
         wxASSERT_MSG( GetClientDataType() != wxClientData_Object,
                      void **clientData)
     {
         wxASSERT_MSG( GetClientDataType() != wxClientData_Object,

-                      _T("can't mix different types of client data") );
+                      wxT("can't mix different types of client data") );

 
         return InsertItems(items, pos, clientData, wxClientData_Void);
     }
 
         return InsertItems(items, pos, clientData, wxClientData_Void);
     }


@@ -177,10 +177,10 @@ private:
                      wxClientData **clientData)
     {
         wxASSERT_MSG( GetClientDataType() != wxClientData_Void,
                      wxClientData **clientData)
     {
         wxASSERT_MSG( GetClientDataType() != wxClientData_Void,

-                      _T("can't mix different types of client data") );
+                      wxT("can't mix different types of client data") );

 
         return InsertItems(items, pos,
 
         return InsertItems(items, pos,

-                           wx_reinterpret_cast(void **, clientData),
+                           reinterpret_cast<void **>(clientData),

                            wxClientData_Object);
     }
 
                            wxClientData_Object);
     }
 


@@ -296,8 +296,13 @@ public:
     void SetClientData(unsigned int n, void* clientData);
     void* GetClientData(unsigned int n) const;
 
     void SetClientData(unsigned int n, void* clientData);
     void* GetClientData(unsigned int n) const;
 

+    // SetClientObject() takes ownership of the pointer, GetClientObject()
+    // returns it but keeps the ownership while DetachClientObject() expects
+    // the caller to delete the pointer and also resets the internally stored
+    // one to NULL for this item

     void SetClientObject(unsigned int n, wxClientData* clientData);
     wxClientData* GetClientObject(unsigned int n) const;
     void SetClientObject(unsigned int n, wxClientData* clientData);
     wxClientData* GetClientObject(unsigned int n) const;

+    wxClientData* DetachClientObject(unsigned int n);

 
     // return the type of client data stored in this control: usually it just
     // returns m_clientDataItemsType but must be overridden in the controls
 
     // return the type of client data stored in this control: usually it just
     // returns m_clientDataItemsType but must be overridden in the controls


@@ -390,45 +395,58 @@ private:
     wxClientDataType m_clientDataItemsType;
 };
 
     wxClientDataType m_clientDataItemsType;
 };
 

-// this macro must (unfortunately) be used in any class deriving from both
-// wxItemContainer and wxControl because otherwise there is ambiguity when
-// calling GetClientXXX() functions -- the compiler can't choose between the
-// two versions
-#define wxCONTROL_ITEMCONTAINER_CLIENTDATAOBJECT_RECAST                    \
-    void SetClientData(void *data)                                         \
-        { wxEvtHandler::SetClientData(data); }                             \
-    void *GetClientData() const                                            \
-        { return wxEvtHandler::GetClientData(); }                          \
-    void SetClientObject(wxClientData *data)                               \
-        { wxEvtHandler::SetClientObject(data); }                           \
-    wxClientData *GetClientObject() const                                  \
-        { return wxEvtHandler::GetClientObject(); }                        \
-    void SetClientData(unsigned int n, void* clientData)                   \
-        { wxItemContainer::SetClientData(n, clientData); }                 \
-    void* GetClientData(unsigned int n) const                              \
-        { return wxItemContainer::GetClientData(n); }                      \
-    void SetClientObject(unsigned int n, wxClientData* clientData)         \
-        { wxItemContainer::SetClientObject(n, clientData); }               \
-    wxClientData* GetClientObject(unsigned int n) const                    \
+// Inheriting directly from a wxWindow-derived class and wxItemContainer
+// unfortunately introduces an ambiguity for all GetClientXXX() methods as they
+// are inherited twice: the "global" versions from wxWindow and the per-item
+// versions taking the index from wxItemContainer.
+//
+// So we need to explicitly resolve them and this helper template class is
+// provided to do it. To use it, simply inherit from wxWindowWithItems<Window,
+// Container> instead of Window and Container interface directly.
+template <class W, class C>
+class wxWindowWithItems : public W, public C
+{
+public:
+    typedef W BaseWindowClass;
+    typedef C BaseContainerInterface;
+
+    wxWindowWithItems() { }
+
+    void SetClientData(void *data)
+        { BaseWindowClass::SetClientData(data); }
+    void *GetClientData() const
+        { return BaseWindowClass::GetClientData(); }
+    void SetClientObject(wxClientData *data)
+        { BaseWindowClass::SetClientObject(data); }
+    wxClientData *GetClientObject() const
+        { return BaseWindowClass::GetClientObject(); }
+
+    void SetClientData(unsigned int n, void* clientData)
+        { wxItemContainer::SetClientData(n, clientData); }
+    void* GetClientData(unsigned int n) const
+        { return wxItemContainer::GetClientData(n); }
+    void SetClientObject(unsigned int n, wxClientData* clientData)
+        { wxItemContainer::SetClientObject(n, clientData); }
+    wxClientData* GetClientObject(unsigned int n) const

         { return wxItemContainer::GetClientObject(n); }
         { return wxItemContainer::GetClientObject(n); }

+};

 
 

-class WXDLLEXPORT wxControlWithItemsBase : public wxControl,
-                                           public wxItemContainer
+class WXDLLIMPEXP_CORE wxControlWithItemsBase :
+    public wxWindowWithItems<wxControl, wxItemContainer>

 {
 public:
     wxControlWithItemsBase() { }
 
 {
 public:
     wxControlWithItemsBase() { }
 

-    // we have to redefine these functions here to avoid ambiguities in classes
-    // deriving from us which would arise otherwise because both base classses
-    // have the methods with the same names - hopefully, a smart compiler can
-    // optimize away these simple inline wrappers so we don't suffer much from
-    // this
-    wxCONTROL_ITEMCONTAINER_CLIENTDATAOBJECT_RECAST
-

     // usually the controls like list/combo boxes have their own background
     // colour
     virtual bool ShouldInheritColours() const { return false; }
 
     // usually the controls like list/combo boxes have their own background
     // colour
     virtual bool ShouldInheritColours() const { return false; }
 

+
+    // Implementation only from now on.
+
+    // Generate an event of the given type for the selection change.
+    void SendSelectionChangedEvent(wxEventType eventType);
+

 protected:
     // fill in the client object or data field of the event as appropriate
     //
 protected:
     // fill in the client object or data field of the event as appropriate
     //


@@ -437,7 +455,7 @@ protected:
     void InitCommandEventWithItems(wxCommandEvent& event, int n);
 
 private:
     void InitCommandEventWithItems(wxCommandEvent& event, int n);
 
 private:

-    DECLARE_NO_COPY_CLASS(wxControlWithItemsBase)
+    wxDECLARE_NO_COPY_CLASS(wxControlWithItemsBase);

 };
 
 // define the platform-specific wxControlWithItems class
 };
 
 // define the platform-specific wxControlWithItems class


@@ -446,14 +464,14 @@ private:
 #elif defined(__WXMOTIF__)
     #include "wx/motif/ctrlsub.h"
 #else
 #elif defined(__WXMOTIF__)
     #include "wx/motif/ctrlsub.h"
 #else

-    class WXDLLEXPORT wxControlWithItems : public wxControlWithItemsBase
+    class WXDLLIMPEXP_CORE wxControlWithItems : public wxControlWithItemsBase

     {
     public:
         wxControlWithItems() { }
 
     private:
         DECLARE_ABSTRACT_CLASS(wxControlWithItems)
     {
     public:
         wxControlWithItems() { }
 
     private:
         DECLARE_ABSTRACT_CLASS(wxControlWithItems)

-        DECLARE_NO_COPY_CLASS(wxControlWithItems)
+        wxDECLARE_NO_COPY_CLASS(wxControlWithItems);

     };
 #endif
 
     };
 #endif