cheng/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update the documentation for wxListCtrl column ordering

Browse Source
This commit is contained in:
Ian McInerney 2021-04-17 19:34:26 +01:00 committed by Vadim Zeitlin
parent 797bc2c087
commit 48b1175f61
1 changed files with 49 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
interface/wx/listctrl.h
View File

@ -152,6 +152,40 @@ enum
modes. You can use the generic implementation for report mode as well by setting
the @c mac.listctrl.always_use_generic system option (see wxSystemOptions) to 1.
@subsection column_order Column Ordering
By default, the columns of a list control appear on the screen in order
of their indices, i.e. column 0 appears first, then column 1 next,
and so on. However this can be changed by using the SetColumnsOrder() function
to arbitrarily reorder the columns visual order.
The user can also rearrange the columns interactively by dragging them.
In this case, the index of the column is not the same as its order and
the functions GetColumnOrder() and GetColumnIndexFromOrder() should be
used to translate between them.
@note All the other functions still work with the column indices,
i.e. the visual positioning of the columns on screen doesn't affect the
code setting or getting their values for example.
Example of reordering columns:
@code
wxListCtrl *list = new wxListCtrl(...);
for ( int i = 0; i < 3; i++ )
list->InsertColumn(i, wxString::Format("Column %d", i));
wxArrayInt order(3);
order[0] = 2;
order[1] = 0;
order[2] = 1;
list->SetColumnsOrder(order);
// now list->GetColumnsOrder() will return order and
// list->GetColumnIndexFromOrder(n) will return order[n] and
// list->GetColumnOrder() will return 1, 2 and 0 for the column 0,
// 1 and 2 respectively
@endcode
@beginStyleTable
@style{wxLC_LIST}
@ -538,8 +572,10 @@ public:
corresponds to the value of the element number @a pos in the array
returned by GetColumnsOrder().
Please see SetColumnsOrder() documentation for an example and
additional remarks about the columns ordering.
@note This function makes sense for report view only and currently is only
implemented in the wxMSW port. Use @c wxHAS_LISTCTRL_COLUMN_ORDER to guard uses
of this function so that they will start working under the other platforms when
support for the column reordering is added there.
@see GetColumnOrder()
*/
@ -552,8 +588,10 @@ public:
given visual position, e.g. calling it with @a col equal to 0 returns
the index of the first shown column.
Please see SetColumnsOrder() documentation for an example and
additional remarks about the columns ordering.
@note This function makes sense for report view only and currently is only
implemented in the wxMSW port. Use @c wxHAS_LISTCTRL_COLUMN_ORDER to guard uses
of this function so that they will start working under the other platforms when
support for the column reordering is added there.
@see GetColumnsOrder(), GetColumnIndexFromOrder()
*/
@ -569,8 +607,10 @@ public:
On error, an empty array is returned.
Please see SetColumnsOrder() documentation for an example and
additional remarks about the columns ordering.
@note This function makes sense for report view only and currently is only
implemented in the wxMSW port. Use @c wxHAS_LISTCTRL_COLUMN_ORDER to guard uses
of this function so that they will start working under the other platforms when
support for the column reordering is added there.
@see GetColumnOrder(), GetColumnIndexFromOrder()
*/
@ -1027,17 +1067,6 @@ public:
/**
Changes the order in which the columns are shown.
By default, the columns of a list control appear on the screen in order
of their indices, i.e. the column 0 appears first, the column 1 next
and so on. However by using this function it is possible to arbitrarily
reorder the columns visual order and the user can also rearrange the
columns interactively by dragging them. In this case, the index of the
column is not the same as its order and the functions GetColumnOrder()
and GetColumnIndexFromOrder() should be used to translate between them.
Notice that all the other functions still work with the column indices,
i.e. the visual positioning of the columns on screen doesn't affect the
code setting or getting their values for example.
The @a orders array must have the same number elements as the number of
columns and contain each position exactly once. Its n-th element
contains the index of the column to be shown in n-th position, so for a
@ -1045,28 +1074,9 @@ public:
results in the third column being displayed first, the first one next
and the second one last.
Example of using it:
@code
wxListCtrl *list = new wxListCtrl(...);
for ( int i = 0; i < 3; i++ )
list->InsertColumn(i, wxString::Format("Column %d", i));
wxArrayInt order(3);
order[0] = 2;
order[1] = 0;
order[2] = 1;
list->SetColumnsOrder(order);
// now list->GetColumnsOrder() will return order and
// list->GetColumnIndexFromOrder(n) will return order[n] and
// list->GetColumnOrder() will return 1, 2 and 0 for the column 0,
// 1 and 2 respectively
@endcode
Please notice that this function makes sense for report view only and
currently is only implemented in wxMSW port. To avoid explicit tests
for @c __WXMSW__ in your code, please use @c wxHAS_LISTCTRL_COLUMN_ORDER
as this will allow it to start working under the other platforms when
@note This function makes sense for report view only and currently is only
implemented in the wxMSW port. Use @c wxHAS_LISTCTRL_COLUMN_ORDER to guard uses
of this function so that they will start working under the other platforms when
support for the column reordering is added there.
@see GetColumnsOrder()