Make wxTopLevelWindow::GetDefaultSize() public and document it.

[wxWidgets.git] / interface / wx / listctrl.h

diff --git a/interface/wx/listctrl.h b/interface/wx/listctrl.h
index 1a73747bc644b70e49cf5fa3c51dc69dc4ee5a47..bb6865f7e2e8c83ccd413171cd0ac14f47d522ad 100644 (file)
--- a/interface/wx/listctrl.h
+++ b/interface/wx/listctrl.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxListCtrl
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxListCtrl
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -19,7 +19,7 @@
     and attributes) is managed by the main program and is requested by the control
     itself only when needed which allows to have controls with millions of items
     without consuming much memory. To use virtual list control you must use
     and attributes) is managed by the main program and is requested by the control
     itself only when needed which allows to have controls with millions of items
     without consuming much memory. To use virtual list control you must use

-    wxListCtrl::SetItemCount first and overload at least wxListCtrl::OnGetItemText
+    wxListCtrl::SetItemCount first and override at least wxListCtrl::OnGetItemText

     (and optionally wxListCtrl::OnGetItemImage or wxListCtrl::OnGetItemColumnImage and
     wxListCtrl::OnGetItemAttr) to return the information about the items when the
     control requests it.
     (and optionally wxListCtrl::OnGetItemImage or wxListCtrl::OnGetItemColumnImage and
     wxListCtrl::OnGetItemAttr) to return the information about the items when the
     control requests it.


@@ -83,12 +83,12 @@
     @endStyleTable
 
 
     @endStyleTable
 
 

-    @beginEventTable{wxListEvent}
+    @beginEventEmissionTable{wxListEvent}

     @event{EVT_LIST_BEGIN_DRAG(id, func)}
            Begin dragging with the left mouse button.
     @event{EVT_LIST_BEGIN_RDRAG(id, func)}
            Begin dragging with the right mouse button..
     @event{EVT_LIST_BEGIN_DRAG(id, func)}
            Begin dragging with the left mouse button.
     @event{EVT_LIST_BEGIN_RDRAG(id, func)}
            Begin dragging with the right mouse button..

-    @event{EVT_BEGIN_LABEL_EDIT(id, func)}
+    @event{EVT_LIST_BEGIN_LABEL_EDIT(id, func)}

            Begin editing a label. This can be prevented by calling Veto().
     @event{EVT_LIST_END_LABEL_EDIT(id, func)}
            Finish editing a label. This can be prevented by calling Veto().
            Begin editing a label. This can be prevented by calling Veto().
     @event{EVT_LIST_END_LABEL_EDIT(id, func)}
            Finish editing a label. This can be prevented by calling Veto().


@@ -151,9 +151,10 @@ public:
             Window identifier. The value wxID_ANY indicates a default value.
         @param pos
             Window position.
             Window identifier. The value wxID_ANY indicates a default value.
         @param pos
             Window position.

+            If ::wxDefaultPosition is specified then a default position is chosen.

         @param size
             Window size.
         @param size
             Window size.

-            If wxDefaultSize is specified then the window is sized appropriately.
+            If ::wxDefaultSize is specified then the window is sized appropriately.

         @param style
             Window style. See wxListCtrl.
         @param validator
         @param style
             Window style. See wxListCtrl.
         @param validator


@@ -244,7 +245,30 @@ public:
         will be sent which can be vetoed as well.
     */
     wxTextCtrl* EditLabel(long item,
         will be sent which can be vetoed as well.
     */
     wxTextCtrl* EditLabel(long item,

-                          wxClassInfo* textControlClass = CLASSINFO(wxTextCtrl));
+                          wxClassInfo* textControlClass = wxCLASSINFO(wxTextCtrl));
+
+    /**
+        Finish editing the label.
+
+        This method allows to programmatically end editing a list control item
+        in place. Usually it will only be called when editing is in progress,
+        i.e. if GetEditControl() returns non-NULL. In particular, do not call
+        it from EVT_LIST_BEGIN_LABEL_EDIT handler as the edit control is not
+        yet fully created by then, just veto the event in this handler instead
+        to prevent the editing from even starting.
+
+        Notice that calling this method will result in EVT_LIST_END_LABEL_EDIT
+        event being generated.
+
+        Currently only implemented in wxMSW.
+
+        @param cancel If @true, discard the changes made by user, as if @c
+            Escape key was pressed. Otherwise, accept the changes as if @c
+            Return was pressed.
+        @return @true if item editing wad finished or @false if no item as
+            being edited.
+     */
+    bool EndEditLabel(bool cancel);

 
     /**
         Ensures this item is visible.
 
     /**
         Ensures this item is visible.


@@ -256,6 +280,8 @@ public:
         beginning if start is @c -1. The string comparison is case insensitive.
 
         If @a partial is @true then this method will look for items which begin with @a str.
         beginning if start is @c -1. The string comparison is case insensitive.
 
         If @a partial is @true then this method will look for items which begin with @a str.

+
+        @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.

     */
     long FindItem(long start, const wxString& str,
                   bool partial = false);
     */
     long FindItem(long start, const wxString& str,
                   bool partial = false);


@@ -263,18 +289,35 @@ public:
     /**
         Find an item whose data matches this data, starting from start or the
         beginning if 'start' is @c -1.
     /**
         Find an item whose data matches this data, starting from start or the
         beginning if 'start' is @c -1.

+
+        @beginWxPerlOnly
+        In wxPerl this method is implemented as FindItemData(start, data).
+        @endWxPerlOnly
+
+        @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.

     */
     long FindItem(long start, wxUIntPtr data);
 
     /**
         Find an item nearest this position in the specified direction,
         starting from @a start or the beginning if @a start is -1.
     */
     long FindItem(long start, wxUIntPtr data);
 
     /**
         Find an item nearest this position in the specified direction,
         starting from @a start or the beginning if @a start is -1.

+
+        @beginWxPerlOnly
+        In wxPerl this method is implemented as FindItemAtPos(start, pt, direction).
+        @endWxPerlOnly
+
+        @return The next matching item if any or @c -1 (wxNOT_FOUND) otherwise.

     */
     long FindItem(long start, const wxPoint& pt, int direction);
 
     /**
         Gets information about this column.
         See SetItem() for more information.
     */
     long FindItem(long start, const wxPoint& pt, int direction);
 
     /**
         Gets information about this column.
         See SetItem() for more information.

+
+        @beginWxPerlOnly
+        In wxPerl this method takes only the @a col parameter and
+        returns a @c Wx::ListItem (or @c undef).
+        @endWxPerlOnly

     */
     bool GetColumn(int col, wxListItem& item) const;
 
     */
     bool GetColumn(int col, wxListItem& item) const;
 


@@ -358,6 +401,11 @@ public:
         You must call @e info.SetId() to set the ID of item you're interested in
         before calling this method, and @e info.SetMask() with the flags indicating
         what fields you need to retrieve from @a info.
         You must call @e info.SetId() to set the ID of item you're interested in
         before calling this method, and @e info.SetMask() with the flags indicating
         what fields you need to retrieve from @a info.

+
+        @beginWxPerlOnly
+        In wxPerl this method takes as parameter the ID of the item
+        and (optionally) the column, and returns a Wx::ListItem object.
+        @endWxPerlOnly

     */
     bool GetItem(wxListItem& info) const;
 
     */
     bool GetItem(wxListItem& info) const;
 


@@ -387,6 +435,11 @@ public:
 
     /**
         Returns the position of the item, in icon or small icon view.
 
     /**
         Returns the position of the item, in icon or small icon view.

+
+        @beginWxPerlOnly
+        In wxPerl this method takes only the @a item parameter and
+        returns a @c Wx::Point (or @c undef).
+        @endWxPerlOnly

     */
     bool GetItemPosition(long item, wxPoint& pos) const;
 
     */
     bool GetItemPosition(long item, wxPoint& pos) const;
 


@@ -395,6 +448,11 @@ public:
         coordinates.
 
         @a code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL.
         coordinates.
 
         @a code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL.

+
+        @beginWxPerlOnly
+        In wxPerl this method takes only the @a item and @a code parameters and
+        returns a @c Wx::Rect (or @c undef).
+        @endWxPerlOnly

     */
     bool GetItemRect(long item, wxRect& rect,
                      int code = wxLIST_RECT_BOUNDS) const;
     */
     bool GetItemRect(long item, wxRect& rect,
                      int code = wxLIST_RECT_BOUNDS) const;


@@ -414,8 +472,14 @@ public:
 
     /**
         Gets the item text for this item.
 
     /**
         Gets the item text for this item.

+
+        @param item
+            Item (zero-based) index.
+        @param col
+            Item column (zero-based) index. Column 0 is the default. This
+            parameter is new in wxWidgets 2.9.1.

     */
     */

-    wxString GetItemText(long item) const;
+    wxString GetItemText(long item, int col = 0) const;

 
     /**
         Returns the colour for this item.
 
     /**
         Returns the colour for this item.


@@ -540,6 +604,11 @@ public:
         the host system or the value stored in @a ptrSubItem will be always -1.
         To compile this feature into wxWidgets library you need to have access to
         commctrl.h of version 4.70 that is provided by Microsoft.
         the host system or the value stored in @a ptrSubItem will be always -1.
         To compile this feature into wxWidgets library you need to have access to
         commctrl.h of version 4.70 that is provided by Microsoft.

+
+        @beginWxPerlOnly
+        In wxPerl this method only takes the @a point parameter
+        and returns a 2-element list (item, flags).
+        @endWxPerlOnly

     */
     long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL) const;
 
     */
     long HitTest(const wxPoint& point, int& flags, long* ptrSubItem = NULL) const;
 


@@ -570,6 +639,10 @@ public:
             Index of the new item, supplied by the application
         @param label
             String label
             Index of the new item, supplied by the application
         @param label
             String label

+
+        @beginWxPerlOnly
+        In wxPerl this method is implemented as InsertStringItem(index, label).
+        @endWxPerlOnly

     */
     long InsertItem(long index, const wxString& label);
 
     */
     long InsertItem(long index, const wxString& label);
 


@@ -580,6 +653,10 @@ public:
             Index of the new item, supplied by the application
         @param imageIndex
             Index into the image list associated with this control and view style
             Index of the new item, supplied by the application
         @param imageIndex
             Index into the image list associated with this control and view style

+
+        @beginWxPerlOnly
+        In wxPerl this method is implemented as InsertImageItem(index, imageIndex).
+        @endWxPerlOnly

     */
     long InsertItem(long index, int imageIndex);
 
     */
     long InsertItem(long index, int imageIndex);
 


@@ -592,6 +669,10 @@ public:
             String label
         @param imageIndex
             Index into the image list associated with this control and view style
             String label
         @param imageIndex
             Index into the image list associated with this control and view style

+
+        @beginWxPerlOnly
+        In wxPerl this method is implemented as InsertImageStringItem(index, label, imageIndex).
+        @endWxPerlOnly

     */
     long InsertItem(long index, const wxString& label,
                     int imageIndex);
     */
     long InsertItem(long index, const wxString& label,
                     int imageIndex);


@@ -842,7 +923,7 @@ public:
         using the specified @a fnSortCallBack function. This function must have the
         following prototype:
         @code
         using the specified @a fnSortCallBack function. This function must have the
         following prototype:
         @code

-        int wxCALLBACK wxListCompareFunction(long item1, long item2, long sortData)
+        int wxCALLBACK wxListCompareFunction(long item1, long item2, wxIntPtr sortData)

         @endcode
 
         It is called each time when the two items must be compared and should return 0
         @endcode
 
         It is called each time when the two items must be compared and should return 0


@@ -859,13 +940,19 @@ public:
         items in the control.
 
         Please see the @ref page_samples_listctrl for an example of using this function.
         items in the control.
 
         Please see the @ref page_samples_listctrl for an example of using this function.

+
+        @beginWxPerlOnly
+        In wxPerl the comparison function must take just two parameters;
+        however, you may use a closure to achieve an effect similar to the
+        SortItems third parameter.
+        @endWxPerlOnly

     */
     */

-    bool SortItems(wxListCtrlCompare fnSortCallBack, long data);
+    bool SortItems(wxListCtrlCompare fnSortCallBack, wxIntPtr data);

 
 protected:
 
     /**
 
 protected:
 
     /**

-        This function may be overloaded in the derived class for a control with
+        This function may be overridden in the derived class for a control with

         @c wxLC_VIRTUAL style. It should return the attribute for the specified
         @c item or @NULL to use the default appearance parameters.
 
         @c wxLC_VIRTUAL style. It should return the attribute for the specified
         @c item or @NULL to use the default appearance parameters.
 


@@ -897,7 +984,7 @@ protected:
     virtual wxListItemAttr* OnGetItemColumnAttr(long item, long column) const;
 
     /**
     virtual wxListItemAttr* OnGetItemColumnAttr(long item, long column) const;
 
     /**

-        Overload this function in the derived class for a control with
+        Override this function in the derived class for a control with

         @c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image
         index for the given line and column.
 
         @c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image
         index for the given line and column.
 


@@ -910,9 +997,9 @@ protected:
     virtual int OnGetItemColumnImage(long item, long column) const;
 
     /**
     virtual int OnGetItemColumnImage(long item, long column) const;
 
     /**

-        This function must be overloaded in the derived class for a control with
+        This function must be overridden in the derived class for a control with

         @c wxLC_VIRTUAL style having an "image list" (see SetImageList(); if the
         @c wxLC_VIRTUAL style having an "image list" (see SetImageList(); if the

-        control doesn't have an image list, it is not necessary to overload it).
+        control doesn't have an image list, it is not necessary to override it).

         It should return the index of the items image in the controls image list
         or -1 for no image.
 
         It should return the index of the items image in the controls image list
         or -1 for no image.
 


@@ -926,7 +1013,7 @@ protected:
     virtual int OnGetItemImage(long item) const;
 
     /**
     virtual int OnGetItemImage(long item) const;
 
     /**

-        This function @b must be overloaded in the derived class for a control with
+        This function @b must be overridden in the derived class for a control with

         @c wxLC_VIRTUAL style. It should return the string containing the text of
         the given @a column for the specified @c item.
 
         @c wxLC_VIRTUAL style. It should return the string containing the text of
         the given @a column for the specified @c item.
 


@@ -1084,7 +1171,7 @@ public:
     Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem.
 
     @library{wxbase}
     Represents the attributes (color, font, ...) of a wxListCtrl's wxListItem.
 
     @library{wxbase}

-    @category{ctrl}
+    @category{data}

 
     @see @ref overview_listctrl, wxListCtrl, wxListItem
 */
 
     @see @ref overview_listctrl, wxListCtrl, wxListItem
 */


@@ -1296,7 +1383,7 @@ enum wxListColumnFormat
     If the colour/font is not specified, the default list control colour/font is used.
 
     @library{wxbase}
     If the colour/font is not specified, the default list control colour/font is used.
 
     @library{wxbase}

-    @category{ctrl}
+    @category{data}

 
     @see wxListCtrl
 */
 
     @see wxListCtrl
 */