Drag List Boxes

Drag List Boxes


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.

arrowy.gifUsing Drag List Boxes

arrowy.gifDrag List Box Reference

Using Drag List Boxes

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.

Drag List Box Messages

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.

Drag List Box Notification Messages

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.

Drag List Box Reference

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

Functions

The following references are drag list box functions.

DrawInsert
void DrawInsert(
    HWND handParent,	
    HWND hLB,	
    int nItem	
   );	

Draws the insert icon in the parent window of the specified drag list box.

handParent
Handle to the parent window of the drag list box.
hLB
Handle to the drag list box.
nItem
Identifier of the icon item to be drawn.
LBItemFromPt
int LBItemFromPt(
    HWND hLB,	
    POINT pt,	
    BOOL bAutoScroll	
   );	

Retrieves the index of the item at the specified point in a list box.

hLB
Handle to the list box to check.
pt
POINT structure that contains the screen coordinates to check.
bAutoScroll
Scroll flag. If this parameter is TRUE and the point is directly above or below the list box, the function scrolls the list box by one line and returns -1. Otherwise, the function does not scroll the 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 succession—for 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.

MakeDragList
BOOL MakeDragList(
    HWND hLB	
   );	

Changes the specified single-selection list box to a drag list box.

hLB
Handle to the single-selection list box.

Notifications

The following references are drag list box notifications.

DL_BEGINDRAG
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.

idCtl
Control identifier of the drag list box.
pDragInfo
Address of a DRAGLISTINFO structure that contains the DL_BEGINDRAG notification code, the handle to the drag list box, and the cursor position.

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
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.

idCtl
Control identifier of the drag list box.
pDragInfo
Address of a DRAGLISTINFO structure that contains the DL_CANCELDRAG notification code, the handle to the drag list box, and the cursor position.

By processing the DL_CANCELDRAG notification message, an application can reset its internal state to indicate that dragging is not in effect.

DL_DRAGGING
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.

idCtl
Control identifier of the drag list box.
pDragInfo
Address of a DRAGLISTINFO structure that contains the DL_DRAGGING notification code, the handle to the drag list box, and the cursor position.

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_DROPPED
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.

idCtl
Control identifier of the drag list box.
pDragInfo
Address of a DRAGLISTINFO structure that contains the DL_DROPPED notification code, the handle to the drag list box, and the cursor position.

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.

Structures

The following reference is a drag list box structure.

DRAGLISTINFO
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.

uNotification
Notification code that specifies the type of drag event. This member can be one of the following values:
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.
hWnd
Handle to the drag list box.
ptCursor
POINT structure that contains the current x- and y-coordinates of the mouse cursor.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.