Double List Picker

• Download source files - 8.79 Kb
• Download demo project - 126 Kb

Introduction

It is quite common in applications to see two lists, where the user can 'move' one or more items from one list to the other. For instance, one list may show a list of users in a group, while the other list shows those user not in the group. The user can then add users to the group or remove them from the group.

Whilst it's not very difficult to simply add two lists to your application, along with buttons for moving the items, this control makes it easier by wrapping up the lists and the buttons, along with labels for the lists. The control supports dynamic resizing, and allows access to the lists directly, or via its own functions

How to use it

Using the CDoubleListPicker class is very straightforward. Follow the steps below to add one to an existing project.

1. After putting the source files (DoubleListPicker.cpp and DoubleListPicker.h) into the directory you wish to use them from, add the files to your Visual Studio project.
2. In the resource editor, add a static control where you wish the picker to be located, and give it an id other than its default IDC_STATIC.
3. It's a good idea to give it a Client edge or Static edge so that you can see where the edge of the control is at design-time. (These styles will be removed at run-time when sub-classing the control. Don't give it a border unless you really want a border, as this (WS_BORDER) cannot be removed at run-time.)
4. If you want to able to tab to the control then give it the Tab stop property.
5. In Class Wizard add a member variable for your static control, selecting "Control" from the "Category" list, and selecting "CDoubleListPicker" from the "Variable Type" list. (If CDoubleListPicker does not appear in the list, you may need to delete your class wizard file (.clw) and regenerate it).

Documentation

The list controls, labels, and buttons are created by the control on creation, or on sub-classing. The 'child' controls are created as siblings of the controls rather than children as this means that tabbing, accelerators etc will still work correctly.

The picker control will manage these child controls as though it were one control, so that resizing, hiding/showing, enabling/disabling etc of the picker will move/show/hide etc the child controls accordingly.

In order to get the picker control to be able to handle the list and button notifications, these controls are sub-classed, and the notification reflected, and passed on to the picker control. After reflection they are then passed on the picker's parent, and so it is possible to act on any notifications there if required.

Functions

The public functions in the class are as follows:

CDoubleListPicker();

Standard empty constructor

virtual BOOL Create(LPCTSTR lpszTitle, DWORD dwStyle, const RECT& rect, CWnd* pParentWnd, UINT nID);

This is virtually identical to CStatic::Create except that it grabs the supplied window text to use as the control's title text, and adds the WS_CHILD style. It then calls CStatic::Create to do the creation.

int AddListItem(BOOL bLeft, LPCSTR lpszItem, LPVOID lpData);

int AddListItem(BOOL bLeft, LPCSTR lpszItem, DWORD dwData = 0);

These functions can be used to add an item to either the left-hand list (if bLeft is TRUE) or the right-hand list (bLeft is FALSE). In addition to specifying a string to be added to the list, you can (optionally) specify data to be attached to the list item, as a void pointer, or a DWORD respectively.

int AddListItems(BOOL bLeft, const CStringArray& saItems);

int AddListItems(BOOL bLeft, const CStringList& slistItems);

These functions allow you to add more than one item to the lists at a time, from a CStringArray or CStringList respectively. If bLeft is TRUE then the items will be added to the left-hand list, else they will be added to the right-hand list. The functions return the number of items added to the list. It is not possible to add data using these functions.

int GetListItems(BOOL bLeft, CStringArray& saItems);

int GetListItems(BOOL bLeft, CStringList& slistItems);

Similarly to the functions above, this will retrieve the items from a list into a CStringArray or CStringList respectively. Again bLeft specifies which list's items to retrieve. The functions return the number of items retrieved.

void SetListSort(BOOL bLeft, BOOL bSort = TRUE);

This function can be used to toggle whether either of the lists is sorted. It may be called before or after the control has been created.

void SetListMultiSel(BOOL bLeft, BOOL bMultiSel = TRUE);

This function can be used to toggle whether either of the lists is allows multiple (extended) selection. It may be called before or after the control has been created.

void SetTitle(LPCSTR lpszTitle = NULL);

This function sets the control's title. It may be called before or after the control has been created.

void SetLabels(LPCSTR lpszLabelLeft = NULL, LPCSTR lpszLabelRight = NULL);

This function sets either the left- or right-hand side label. It may be called before or after the control has been created.

CListBox& GetListCtrl(BOOL bLeft = TRUE);

This function returns a reference to either the left- or right-hand side list control.

CStatic& GetLabelCtrl(BOOL bLeft = TRUE);

This function returns a reference to either the left- or right-hand side label control.

CStatic& GetTitleCtrl();

This function returns a reference to the title static control.

CString GetTitle();

This function returns the current title text.

CString GetLabel(BOOL bLeft = TRUE);

This functions returns the current label text for either list.

void SetHorizontal(BOOL bHorizontal = TRUE);

Set the lists horizontally.

BOOL GetHorizontal() const;

Returns whether the lists are placed horizontally.

Enumerations

To allow the picker's parent to act on notification messages, the picker's controls IDs are enumerated as follows:

CDoubleListPicker::ID_TITLE               // Title static control
CDoubleListPicker::ID_LABEL_LEFT          // Left label
CDoubleListPicker::ID_LABEL_RIGHT         // Right Label
CDoubleListPicker::ID_BTN_MOVE_RIGHT      // ">" button
CDoubleListPicker::ID_BTN_MOVE_LEFT       // "<" button
CDoubleListPicker::ID_BTN_MOVE_ALL_RIGHT  // ">>" button
CDoubleListPicker::ID_BTN_MOVE_ALL_LEFT   // "<<" button
CDoubleListPicker::ID_LIST_LEFT           // Left list
CDoubleListPicker::ID_LIST_RIGHT          // Right list

History

Version 2.1 - 09-Jul-2003

• Updated to support Unicode.

Version 2 - 07-Feb-2003

• Added facility to show the lists horizontally. Uses code based on code by Anneke Sicherer-Roetman (drawing to a bitmap device context) and Stefan Schwedt (drawing rotated text)

Version 1 - 31 Jul 2002

• First version