/////////////////////////////////////////////////////////////////////////////
// Name: listctrl.h
-// Purpose: documentation for wxListCtrl class
+// Purpose: interface of wxListCtrl
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
@b Mac Note: Starting with 2.8, wxListCtrl uses a native implementation for
report mode, and uses a generic implementation for other modes. You can use the
generic implementation for report mode as well by setting the
- mac.listctrl.always_use_generic wxSystemOption to
+ mac.listctrl.always_use_generic wxSystemOption() to
1.
@beginStyleTable
- @style{wxLC_LIST}:
+ @style{wxLC_LIST}
Multicolumn list view, with optional small icons. Columns are
computed automatically, i.e. you don't set columns as in
wxLC_REPORT. In other words, the list wraps, unlike a wxListBox.
- @style{wxLC_REPORT}:
+ @style{wxLC_REPORT}
Single or multicolumn report view, with optional header.
- @style{wxLC_VIRTUAL}:
+ @style{wxLC_VIRTUAL}
The application provides items text on demand. May only be used
with wxLC_REPORT.
- @style{wxLC_ICON}:
+ @style{wxLC_ICON}
Large icon view, with optional labels.
- @style{wxLC_SMALL_ICON}:
+ @style{wxLC_SMALL_ICON}
Small icon view, with optional labels.
- @style{wxLC_ALIGN_TOP}:
+ @style{wxLC_ALIGN_TOP}
Icons align to the top. Win32 default, Win32 only.
- @style{wxLC_ALIGN_LEFT}:
+ @style{wxLC_ALIGN_LEFT}
Icons align to the left.
- @style{wxLC_AUTOARRANGE}:
+ @style{wxLC_AUTOARRANGE}
Icons arrange themselves. Win32 only.
- @style{wxLC_EDIT_LABELS}:
+ @style{wxLC_EDIT_LABELS}
Labels are editable: the application will be notified when editing
starts.
- @style{wxLC_NO_HEADER}:
+ @style{wxLC_NO_HEADER}
No header in report mode.
- @style{wxLC_SINGLE_SEL}:
+ @style{wxLC_SINGLE_SEL}
Single selection (default is multiple).
- @style{wxLC_SORT_ASCENDING}:
+ @style{wxLC_SORT_ASCENDING}
Sort in ascending order (must still supply a comparison callback in
SortItems.
- @style{wxLC_SORT_DESCENDING}:
+ @style{wxLC_SORT_DESCENDING}
Sort in descending order (must still supply a comparison callback
in SortItems.
- @style{wxLC_HRULES}:
+ @style{wxLC_HRULES}
Draws light horizontal rules between rows in report mode.
- @style{wxLC_VRULES}:
+ @style{wxLC_VRULES}
Draws light vertical rules between columns in report mode.
@endStyleTable
@category{ctrl}
@appearance{listctrl.png}
- @seealso
- @ref overview_wxlistctrloverview "wxListCtrl overview", wxListView, wxListBox,
- wxTreeCtrl, wxImageList, wxListEvent, wxListItem
+ @see @ref overview_wxlistctrloverview "wxListCtrl overview", wxListView,
+ wxListBox, wxTreeCtrl, wxImageList, wxListEvent, wxListItem
*/
class wxListCtrl : public wxControl
{
//@{
/**
Constructor, creating and showing a list control.
-
+
@param parent
Parent window. Must not be @NULL.
@param id
Window validator.
@param name
Window name.
-
+
@see Create(), wxValidator
*/
wxListCtrl();
/**
Arranges the items in icon or small icon view. This only has effect on Win32.
@a flag is one of:
-
+
wxLIST_ALIGN_DEFAULT
-
+
Default alignment.
-
+
wxLIST_ALIGN_LEFT
-
+
Align to the left side of the control.
-
+
wxLIST_ALIGN_TOP
-
+
Align to the top side of the control.
-
+
wxLIST_ALIGN_SNAP_TO_GRID
-
+
Snap to grid.
*/
bool Arrange(int flag = wxLIST_ALIGN_DEFAULT);
SetImageList, delete the list when destroyed). @a which is one of
wxIMAGE_LIST_NORMAL, wxIMAGE_LIST_SMALL, wxIMAGE_LIST_STATE (the last is
unimplemented).
-
+
@see SetImageList()
*/
void AssignImageList(wxImageList* imageList, int which);
/**
Deletes all items in the list control.
- @b NB: This function does @e not send the
+ @note This function does @e not send the
@c wxEVT_COMMAND_LIST_DELETE_ITEM event because deleting many items
from the control would be too slow then (unlike wxListCtrl::DeleteItem).
*/
/**
Find an item nearest this position in the specified direction, starting from
@a start or the beginning if @a start is -1.
-
-
+
+
@b FindItem( start, str, partial = @false )
-
-
+
+
@b FindItemData( start, data )
-
-
+
+
@b FindItemAtPos( start, point, direction )
*/
long FindItem(long start, const wxString& str,
/**
Returns the edit control being currently used to edit a label. Returns @NULL
if no label is being edited.
- @b NB: It is currently only implemented for wxMSW and the generic version,
+ @note It is currently only implemented for wxMSW and the generic version,
not for the native Mac OS X version.
*/
wxTextCtrl* GetEditControl() const;
/**
Returns the specified image list. @a which may be one of:
-
+
@b wxIMAGE_LIST_NORMAL
-
+
The normal (large icon) image list.
-
+
@b wxIMAGE_LIST_SMALL
-
+
The small icon image list.
-
+
@b wxIMAGE_LIST_STATE
-
+
The user-defined state image list (unimplemented).
*/
wxImageList* GetImageList(int which) const;
Returns the colour for this item. If the item has no specific colour, returns
an invalid colour (and not the default background control of the control
itself).
-
+
@see GetItemTextColour()
*/
wxColour GetItemBackgroundColour(long item) const;
Returns the first item with given state following @a item or -1 if
no such item found.
This function may be used to find all selected items in the control like this:
-
+
@a geometry can be one of:
-
+
wxLIST_NEXT_ABOVE
-
+
Searches for an item above the specified item.
-
+
wxLIST_NEXT_ALL
-
+
Searches for subsequent item by index.
-
+
wxLIST_NEXT_BELOW
-
+
Searches for an item below the specified item.
-
+
wxLIST_NEXT_LEFT
-
+
Searches for an item to the left of the specified item.
-
+
wxLIST_NEXT_RIGHT
-
+
Searches for an item to the right of the specified item.
-
- @b NB: this parameter is only supported by wxMSW currently and ignored on
+
+ @note this parameter is only supported by wxMSW currently and ignored on
other platforms.
@a state can be a bitlist of the following:
-
+
wxLIST_STATE_DONTCARE
-
+
Don't care what the state is.
-
+
wxLIST_STATE_DROPHILITED
-
+
The item indicates it is a drop target.
-
+
wxLIST_STATE_FOCUSED
-
+
The item has the focus.
-
+
wxLIST_STATE_SELECTED
-
+
The item is selected.
-
+
wxLIST_STATE_CUT
-
+
The item is selected as part of a cut and paste operation.
*/
long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL,
for GetItemRect().
@a code can be one of @c wxLIST_RECT_BOUNDS,
@c wxLIST_RECT_ICON or @c wxLIST_RECT_LABEL.
- This function is new since wxWidgets version 2.7.0
+
+ @wxsince{2.7.0}
*/
bool GetSubItemRect(long item, long subItem, wxRect& rect,
int code = wxLIST_RECT_BOUNDS) const;
giving details in @e flags. Returns index of the item or @c wxNOT_FOUND
if no item is at the specified point.
@a flags will be a combination of the following flags:
-
+
wxLIST_HITTEST_ABOVE
-
+
Above the client area.
-
+
wxLIST_HITTEST_BELOW
-
+
Below the client area.
-
+
wxLIST_HITTEST_NOWHERE
-
+
In the client area but below the last item.
-
+
wxLIST_HITTEST_ONITEMICON
-
+
On the bitmap associated with an item.
-
+
wxLIST_HITTEST_ONITEMLABEL
-
+
On the label (string) associated with an item.
-
+
wxLIST_HITTEST_ONITEMRIGHT
-
+
In the area to the right of an item.
-
+
wxLIST_HITTEST_ONITEMSTATEICON
-
+
On the state icon for a tree view item that is in a user-defined state.
-
+
wxLIST_HITTEST_TOLEFT
-
+
To the right of the client area.
-
+
wxLIST_HITTEST_TORIGHT
-
+
To the left of the client area.
-
+
wxLIST_HITTEST_ONITEM
-
+
Combination of wxLIST_HITTEST_ONITEMICON, wxLIST_HITTEST_ONITEMLABEL,
wxLIST_HITTEST_ONITEMSTATEICON.
-
+
If @a ptrSubItem is not @NULL and the wxListCtrl is in the report
mode the subitem (or column) number will also be provided.
This feature is only available in version 2.7.0 or higher and is currently only
//@{
/**
Insert an image/string item.
-
+
@param info
wxListItem object
@param index
wxListCtrl will not delete the pointer or keep a reference of it. You can
return the same wxListItemAttr pointer for every OnGetItemAttr call.
The base class version always returns @NULL.
-
+
@see OnGetItemImage(), OnGetItemColumnImage(),
OnGetItemText()
*/
index for the given line and column.
The base class version always calls OnGetItemImage for the first column, else
it returns -1.
-
+
@see OnGetItemText(), OnGetItemImage(),
OnGetItemAttr()
*/
In a control with @c wxLC_REPORT style, OnGetItemImage only gets called for
the first column of each line.
The base class version always returns -1.
-
+
@see OnGetItemText(), OnGetItemColumnImage(),
OnGetItemAttr()
*/
This function @b must be overloaded 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.
-
+
@see SetItemCount(), OnGetItemImage(),
OnGetItemColumnImage(), OnGetItemAttr()
*/
Redraws the given @e item. This is only useful for the virtual list controls
as without calling this function the displayed value of the item doesn't change
even when the underlying data does change.
-
+
@see RefreshItems()
*/
void RefreshItem(long item);
@a dx specifies the number of pixels to scroll. If in list view mode,
@a dx specifies the number of columns to scroll. @a dy always specifies
the number of pixels to scroll vertically.
- @b NB: This method is currently only implemented in the Windows version.
+ @note This method is currently only implemented in the Windows version.
*/
bool ScrollList(int dx, int dy);
unimplemented).
This method does not take ownership of the image list, you have to
delete it yourself.
-
+
@see AssignImageList()
*/
void SetImageList(wxImageList* imageList, int which);
be either an integer or a pointer cast to the @c wxUIntPtr type which is
guaranteed to be large enough to be able to contain all integer types and
pointers.
- This function is new since wxWidgets version 2.8.4
+
+ @wxsince{2.8.4}
*/
bool SetItemPtrData(long item, wxUIntPtr data);
Call this function to sort the items in the list control. Sorting is done
using the specified @a fnSortCallBack function. This function must have the
following prototype:
-
+
It is called each time when the two items must be compared and should return 0
if the items are equal, negative value if the first item is less than the
second one and positive value if the first one is greater than the second one
(the same convention as used by @c qsort(3)).
-
+
@param item1
client data associated with the first item (NOT the index).
@param item2
};
+
/**
@class wxListEvent
@wxheader{listctrl.h}
@library{wxbase}
@category{events}
- @seealso
- wxListCtrl
+ @see wxListCtrl
*/
class wxListEvent : public wxNotifyEvent
{
/**
Constructor.
*/
- wxListEvent(WXTYPE commandType = 0, int id = 0);
+ wxListEvent(wxEventType commandType = 0, int id = 0);
/**
For @c EVT_LIST_CACHE_HINT event only: return the first item which the
};
+
/**
@class wxListItemAttr
@wxheader{listctrl.h}
@library{wxbase}
@category{FIXME}
- @seealso
- @ref overview_wxlistctrloverview "wxListCtrl overview", wxListCtrl, wxListItem
+ @see @ref overview_wxlistctrloverview "wxListCtrl overview", wxListCtrl,
+ wxListItem
*/
class wxListItemAttr
{
};
+
/**
@class wxListView
@wxheader{listctrl.h}
@category{ctrl}
@appearance{listview.png}
- @seealso
- wxListView::SetColumnImage
+ @see wxListView::SetColumnImage
*/
class wxListView : public wxListCtrl
{
public:
/**
Resets the column image -- after calling this function, no image will be shown.
-
+
@param col
the column to clear image for
-
+
@see SetColumnImage()
*/
void ClearColumnImage(int col);
Returns the first selected item in a (presumably) multiple selection control.
Together with GetNextSelected() it can be
used to iterate over all selected items in the control.
-
+
@returns The first selected item, if any, -1 otherwise.
*/
long GetFirstSelected() const;
/**
Returns the currently focused item or -1 if none.
-
+
@see IsSelected(), Focus()
*/
long GetFocusedItem() const;
/**
Used together with GetFirstSelected() to
iterate over all selected items in the control.
-
+
@returns Returns the next selected item or -1 if there are no more of
them.
*/
/**
Returns @true if the item with the given @a index is selected,
@false otherwise.
-
+
@see GetFirstSelected(), GetNextSelected()
*/
bool IsSelected(long index) const;
/**
Selects or unselects the given item.
-
+
@param n
the item to select or unselect
@param on
if @true (default), selects the item, otherwise unselects it
-
+
@see wxListCtrl::SetItemState
*/
void Select(bool on = true);
/**
Sets the column image for the specified column. To use the column images, the
control must have a valid image list with at least one image.
-
+
@param col
the column to set image for
@param image
};
+
/**
@class wxListItem
@wxheader{listctrl.h}
/**
Returns a bit mask indicating which fields of the structure are valid;
can be any combination of the following values:
-
+
wxLIST_MASK_STATE
-
+
@b GetState is valid.
-
+
wxLIST_MASK_TEXT
-
+
@b GetText is valid.
-
+
wxLIST_MASK_IMAGE
-
+
@b GetImage is valid.
-
+
wxLIST_MASK_DATA
-
+
@b GetData is valid.
-
+
wxLIST_MASK_WIDTH
-
+
@b GetWidth is valid.
-
+
wxLIST_MASK_FORMAT
-
+
@b GetFormat is valid.
*/
long GetMask() const;
/**
Returns a bit field representing the state of the item. Can be any
combination of:
-
+
wxLIST_STATE_DONTCARE
-
+
Don't care what the state is. Win32 only.
-
+
wxLIST_STATE_DROPHILITED
-
+
The item is highlighted to receive a drop event. Win32 only.
-
+
wxLIST_STATE_FOCUSED
-
+
The item has the focus.
-
+
wxLIST_STATE_SELECTED
-
+
The item is selected.
-
+
wxLIST_STATE_CUT
-
+
The item is in the cut state. Win32 only.
*/
long GetState() const;
*/
void SetWidth(int width);
};
+
projects / wxWidgets.git / blobdiff