
A drag list box is a special type of list box that enables the user to drag items from one position to another. An application can use a drag list box to display strings in a particular sequence and allow the user to change the sequence by dragging the items into position.
Drag list boxes have the same window styles and process the same messages as standard list boxes. To create a drag list box, first create a standard list box and then call the MakeDragList function. To convert a list box in a dialog box to a drag list box, you can call MakeDragList when the WM_INITDIALOG message is processed.
A drag list box notifies the parent window of drag events by sending it a drag list message. The parent window must process the drag list message.
The drag list box registers this message when the MakeDragList function is called. To get the message identifier (numeric value) of the drag list message, call the RegisterWindowMessage function and specify the DRAGLISTMSGSTRING value.
The wParam parameter of the drag list message is the control identifier for the drag list box. The lParam parameter is the address of a DRAGLISTINFO structure, which contains the notification code for the drag event and other information. The return value of the message depends on the notification.
The drag list notification message, which is identified by the uNotification member of the DRAGLISTINFO structure included with the drag list message, can be DL_BEGINDRAG, DL_DRAGGING, DL_CANCELDRAG, or DL_DROPPED.
The DL_BEGINDRAG notification message is sent when the cursor is on a list item and the user clicks the left mouse button. The parent window can return TRUE to begin the drag operation or FALSE to disallow dragging. In this way, the parent window can enable dragging for some list items and disable it for others. You can determine which list item is at the specified location by using the LBItemFromPt function.
If dragging is in effect, the DL_DRAGGING notification message is sent whenever the mouse is moved, or at regular intervals if the mouse is not being moved. The parent window should first determine the list item under the cursor by using LBItemFromPt and then draw the insert icon by using the DrawInsert function. By specifying TRUE for the bAutoScroll parameter of LBItemFromPt, you can cause the list box to scroll by one line if the cursor is above or below its client area. The value you return for this notification specifies the type of mouse cursor that the drag list box should set.
The DL_CANCELDRAG notification message is sent if the user cancels a drag operation by clicking the right mouse button or pressing the ESC key. The DL_DROPPED notification message is sent if the user completes a drag operation by releasing the left mouse button, even if the cursor is not over a list item. The drag list box releases the mouse capture before sending either notification. The return value of these two notifications is ignored.
The following functions, notification messages, and structures are associated with drag list boxes.
| Functions |
| DrawInsert |
| LBItemFromPt |
| MakeDragList |
| Notifications |
| DL_BEGINDRAG |
| DL_CANCELDRAG |
| DL_DRAGGING |
| DL_DROPPED |
| Structures |
| DRAGLISTINFO |
The following references are drag list box functions.
void DrawInsert(
HWND handParent,
HWND hLB,
int nItem
);
Draws the insert icon in the parent window of the specified drag list box.
int LBItemFromPt(
HWND hLB,
POINT pt,
BOOL bAutoScroll
);
Retrieves the index of the item at the specified point in a list box.
The LBItemFromPt function only scrolls the list box if a minimum amount of time has passed since it last did so. Timing prevents the list box from scrolling too quickly if the function is called repeatedly in rapid successionfor example, when DL_DRAGGING notification messages or WM_MOUSEMOVE messages are processed.
If the specified point is outside the client area of the list box and bAutoScroll is TRUE, the function scrolls the list box instead of returning an item identifier.
BOOL MakeDragList(
HWND hLB
);
Changes the specified single-selection list box to a drag list box.
The following references are drag list box notifications.
DL_BEGINDRAG
idCtl = (WPARAM)(int) wParam;
pDragInfo = (LPARAM)(LPDRAGLISTINFO) lParam;
Notifies the drag list box's parent window that the user has clicked the left mouse button on an item. A drag list box sends DL_BEGINDRAG in the form of a drag list message.
When processing this notification message, a window procedure typically determines the list item at the specified cursor position by using the LBItemFromPt function. It then returns TRUE or FALSE, depending on whether the item should be dragged. Before returning TRUE, the window procedure should save the index of the list item so the application knows which item to move or copy when the drag operation is completed.
DL_CANCELDRAG
idCtl = (WPARAM)(int) wParam;
pDragInfo = (LPARAM)(LPDRAGLISTINFO) lParam;
Signals that the user has canceled a drag operation by clicking the right mouse button or pressing the ESC key. A drag list box sends DL_CANCELDRAG to its parent window in the form of a drag list message.
By processing the DL_CANCELDRAG notification message, an application can reset its internal state to indicate that dragging is not in effect.
DL_DRAGGING
idCtl = (WPARAM)(int) wParam;
pDragInfo = (LPARAM)(LPDRAGLISTINFO) lParam;
Signals that the user has moved the mouse while dragging an item. DL_DRAGGING is also sent periodically during dragging even if the mouse is not moved. A drag list box sends this notification to its parent window in the form of a drag list message.
A window procedure typically processes the DL_DRAGGING notification message by determining the item under the cursor and then drawing an insert icon. To get the item under the cursor, use the LBItemFromPt function, specifying TRUE for the bAutoScroll parameter. This option causes the drag list box to scroll periodically if the cursor is above or below its client area. To draw the insert icon, use the DrawInsert function.
DL_BEGINDRAG
idCtl = (WPARAM)(int) wParam;
pDragInfo = (LPARAM)(LPDRAGLISTINFO) lParam;
Signals that the user has completed a drag operation by releasing the left mouse button. A drag list box sends DL_DROPPED to its parent window in the form of a drag list message.
This notification is normally processed by inserting the item being dragged into the list in front of the item under the cursor. To retrieve the index of the item at the cursor position, use the LBItemFromPt function. Note that the DL_DROPPED notification message is sent even if the cursor is not on a list item. In that case, LBItemFromPt returns -1.
The following reference is a drag list box structure.
Typedef struct {
UINT uNotification;
HWND hWnd;
POINT ptCursor;
} DRAGLISTINFO, FAR *LPDRAGLISTINFO;
Contains information about a drag event. The pointer to DRAGLISTINFO is passed as the lParam parameter of the drag list message.
| DL_BEGINDRAG | The user has clicked the left mouse button on a list item. |
| DL_CANCELDRAG | The user has canceled the drag operation by clicking the right mouse button or pressing the ESC key. |
| DL_DRAGGING | The user has moved the mouse while dragging an item. |
| DL_DROPPED | The user has released the left mouse button, completing a drag operation. |
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.