List drag
Volume Number: | | 9
|
Issue Number: | | 6
|
Column Tag: | | Pascal Workshop
|
Related Info: List Manager Quickdraw
Start Dragging My Lists Around
Heres a way to drag items from one list to another
By Eric Rosé, Pittsburgh, Pennsylvania
Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.
About the author
Eric Rosé has a BS in Computer Science, is recently married, and is now trying to escape from a Masters program in Electrical and Computer Engineering so that he can get back to hacking Macintosh code.
A Question of Style
Anyone who has used the Font/DA Mover has probably experienced some degree of frustration in the clumsiness of having to select an item in the list, then click on a button to move or delete it. Trying to use this interface in a situation where you have more than two lists and could drag to and remove items from any one of them would quickly lead to a bewildering profusion of buttons which would leave even the hardiest user gasping for breath (besides being annoying to code up).
If you have seen the AppleShare Administrator you know that there is a more elegant and more intuitive way to handle this problem: simply allow the user to click on an object in a list and drag it into another list. For months I tried to find out if anyone had written up a TechNote on how to do this; failing to find one, I decided to roll my own solution. Here it is.
The Creeping Feature Creature
To do simple dragging between two lists, all you really need is a moderately complex LClikLoop routine (IM IV:266). In the pursuit of a more general and extendable solution to the problem, I decided to write a generic LClikLoop routine and package it in a unit which the programmer could customize. Among the features the unit provides are: 1) Letting the user drag from one list to any number of other lists; 2) Programmer-defined actions to be taken when a user drags items from one list to another list, to that same list, to a region outside of all the lists, and to a region outside the dialog (these actions could be unique for each source and destination list); 3) Different possible dragging options for each list (i.e., you can drag items between A and B, but not within A, but you can only drag items within list B). This third option is included for completeness - it could lead to a lot of confusion if not managed consistently.
Nuts & Bolts
As it stands, the LToLDragUnit provides three interface routines and whatever list variables and constants you want to include. If you want to use the dragging LClikLoop, you should define all of your ListHandle variables inside the file DragUnitUserDefs.i, and then include LtoLDragUnit in the USES clause for any unit that uses those list variables. I include a constant for each list (generally the dialog item number of the user item in which the list is placed) which I store in the lists RefCon field so that I can tell the lists apart when I am handed a handle to one. If you have a different method, feel free to not include the constants; LtoLDragUnit does not directly reference any of these constants or variables, but you will most likely have to use them in the routines you define. Anyway, enough idle banter; on to a discussion of the interface routines!
InitLtoLDrag
This simple routine should be called once when your program first starts up. All it does is set initial values for the units global variables.
SetDragEnvironment
Another simple routine; you should call this whenever you switch from one dialog which uses the LtoLDragUnit to another. For example, if you have two dialogs with draggable lists, whenever one is activated you should call this routine with its dialog pointer.
LtoLClickProc
This is the generic ClikLoop routine. A pointer to it should be stored in the LClikLoop field of any list you want to be draggable (see TestDrag.p for examples of how to do this). When it is called, it stores the position where the mouse was clicked, then calls your SetSourceDestLists routine (described later) and promptly exits so that the item you clicked on can be hilighted. If the mouse button is still down, it promptly re-executes and continues with the main body of the routine which performs the following actions: 1) find the selected cell and get its rectangle; 2) Define a LimitRect and SlopRect for use with DragGrayRgn (IM I:294); if the list can only drag within itself, the LimitRect is the Lists view rectangle, otherwise it is the entire dialog; 3) Call DragGrayRgn to let the user drag the item around; 4) Call one of your four action routines depending on where the item was released and which drag options are available.
At this point, mention should be made of DragProc. This routine is responsible for hilighting the list items you pass over so that you know where the item will be inserted when it is released, and whether or not you can insert an item in a particular list. First it checks to see whether you can drag items within the source list. If so, it calls CheckList which hilights the cell in the source list which is underneath the cursors current position. Then it checks to see whether you can drag to any other list, and, if so, performs the same actions for each possible destination list.
So What Do You Have To Do?
I hear you cry? In order for the LtoLDragUnit to do anything useful, you must supply five routines - the routines which are declared as forward in the units implementation section. These routines should be defined in the file DragUnitUserProcs.i. I will now discuss each of these routines in detail.
SetSourceDestLists
When the user first clicks in a lists (the source list), LtoLClickProc calls this routine so that you can 1) specify which other lists the source lists items can be dragged into. 2) specify (using the kDragToOwnList, kDragOutside, and kDragToOtherList constants) what kinds of drags can be done with the source lists items. To specify the destination lists, set gNumDestLists to the number of possible destination lists and store handles to each destination list in the first gNumDestLists entries in the gDestLists array. To specify the kind of drags to perform, set the gDragStyle variable to any combination of the three style constants (they can be added together to provide multiple effects).
DragToDestAction
This routine is called when kDragToOtherList is set and the user has dragged an item from the source list and released it over one of the destination lists. You are given a handle to the source and destination lists, along with the coordinates of the cell being dragged and the cell it was released over. What you do with that information is purely up to you.
DragToSourceAction
This routine is called when kDragToOwnList is set and the user has successfully dragged an item within the source list. You are given a handle to the source list, along with the coordinates of the cell being dragged and the cell it was released over. Again, what happens is for you to decide.
DragOutsideAction
This routine is called only if kDragOutside is set and 1) If kDragToOwnList is not set and the user drags an item from the source list back into itself; 2) If the item is released over a list which is not specified as a destination list in the SetSourceDestLists routine, or 3) If the item is not released over a list at all.
BadDragAction
This routine is called in two different cases: 1) If kDragToOwnList is set and the item is released outside of the source list, or 2) If kDragToOwnList is not set and the item is dragged outside of the dialog.
A Contrived Example
The source code in the file TestDrag.p presents an example of how to use the LtoLDragUnit routines (albeit in an extremely contrived way). It creates a modal dialog with three list variables. Items can be dragged from List1 to either List2 or List3, but not back into List1. Items from List2 can be dragged either into List2 or List3. Items from List3 can be dragged to either List1 or List2, but not back into List3. Items from all three of these lists can be dragged outside. For the purposes of this example, I have defined the meanings of the four action routines as follows: 1) DragToDestAction: insert the item from the source list into the destination list at the position where it was released, pushing the item already there down one row; 2) DragToSourceAction: swap the item being dragged with the item it was released over; 3) DragOutsideAction: delete the item being dragged from the source list; 4) BadDragAction: beep at the user to let them know they messed up, but dont affect any of the lists.
Future Enhancements
Using your own LClikLoop means that the automatic scrolling provided by the default loop is deactivated; in other words, you cant click in the list and then scroll it up or down by dragging inside the list with the mouse button held down. It might be nice to figure out how to add this feature, especially for a list with the kDragToOwnList feature set. Another interesting feature would be to be able to cause the destination lists to scroll up or down when you drag over them. A warning: LAutoScroll is rude enough to not save the penstate before it scrolls, so if you dont manually save and restore the penstate before scrolling you get some very fascinating update problems with DragGrayRgn. Feel free to experiment, and please let me know if you find solutions to either of these problems. Good hacking to you all!
Listing: LtoLDragUnit.p
{This unit lets you implement dragging items}
{between lists}
UNIT LToLDragUnit;
INTERFACE
USES
MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf;
PROCEDURE InitLtoLDrag;
{Initialize the units global variables}
PROCEDURE SetDragEnvironment (DestDialog :
DialogPtr);
{Call this procedure when you switch dialogs}
FUNCTION LtoLClickProc : BOOLEAN;
{The item dragging Clickproc}
{$i DragUnitUserDefs.i}
IMPLEMENTATION
VAR
gSourceList: ListHandle;
gDestLists : ARRAY [1..10] OF ListHandle;
gNumDestLists : Integer;
gTheDialog : DialogPtr;
gDragStyle : Integer;
AnchorDefined : BOOLEAN;
AnchorPoint,
OldPoint,
NextPoint : Point;
CONST
kDragToOwnList = $01;
kDragToOtherList= $02;
kDragOutside = $04;
kInvalidDrag = $8000;
kMaxDestLists = 10;
{The following routines should be defined by}
{the programmer in DragUnitUserProcs.i}
PROCEDURE DragToDestAction (SourceList : ListHandle;
SourceCell : Point; DestList :
ListHandle; DestCell : Point); FORWARD;
{action to take if the user drags an item from}
{the source list to the destination list}
PROCEDURE DragToSourceAction (SourceList :
ListHandle; SourceCell, DestCell : Point); FORWARD;
{action to be taken if the user drags an item}
{within the source list}
PROCEDURE BadDragAction (SourceList :
ListHandle; SourceCell : Point); FORWARD;
{action to be taken if the user drags an item}
{and releases it outside the draggable area}
PROCEDURE DragOutsideAction (SourceList :
ListHandle; SourceCell : Point); FORWARD;
{action to be taken if the user drags an item}
{and releases it within the draggable area, but}
{not inside of any of the lists}
PROCEDURE SetSourceDestLists (ClickPt : Point); FORWARD;
{For the selected list, define which lists its}
{items can be dragged to, and what kind of drags}
{can be performed}}
{------------------------}
PROCEDURE InitLtoLDrag;
VAR
i : Integer;
BEGIN
SetPt(AnchorPoint, 0, 0);
AnchorDefined := FALSE;
OldPoint := AnchorPoint;
NextPoint := AnchorPoint;
gSourceList := NIL;
FOR i := 1 TO kMaxDestLists DO
gDestLists[i] := NIL;
gNumdestLists := 0;
END;
{------------------------}
PROCEDURE SetDragEnvironment (DestDialog : DialogPtr);
BEGIN
gTheDialog := DestDialog;
END;
{------------------------}
FUNCTION FindCell(VAR Selected_Cell :
Point; TheList : ListHandle) : BOOLEAN;
{Return the currently selected cell in TheList}
BEGIN
SetPt(Selected_Cell, 0, 0);
FindCell:= LGetSelect(TRUE,
Selected_Cell, TheList);
END;
{------------------------}
FUNCTION CanDragToSelf : BOOLEAN;
BEGIN
CanDragToSelf := BAND(kDragToOwnList,
gDragStyle) > 0;
END;
{------------------------}
FUNCTION CanDragToOther : BOOLEAN;
BEGIN
CanDragToOther := BAND(kDragToOtherList,
gDragStyle) > 0
END;
{------------------------}
FUNCTION CanDragOutside : BOOLEAN;
BEGIN
CanDragOutside := BAND(kDragOutSide, gDragStyle) > 0;
END;
{------------------------}
PROCEDURE DragProc;
VAR
MPos : Point;
WhichCell: Point;
TempRect : Rect;
i : Integer;
PROCEDURE CheckOtherList(TheList:ListHandle);
BEGIN
IF TheList = NIL THEN
EXIT(CheckotherList);
TempRect := TheList^^.rView;
IF PtInRect(MPos, TempRect) THEN
BEGIN
MPos.v := ((MPos.v - TempRect.Top) DIV
TheList^^.CellSize.v) +
TheList^^.Visible.Top;
MPos.h := 0;
IF FindCell(WhichCell, TheList) THEN
BEGIN
IF NOT(EqualPt(WhichCell, MPos)) THEN
BEGIN
LSetSelect (FALSE, WhichCell, TheList);
LSetSelect (TRUE, MPos, TheList);
END; {equalpt}
END {FindCell}
ELSE
LSetSelect (TRUE, MPos, TheList);
END; {PtInRect}
END;
BEGIN
GetMouse(MPos);
IF CanDragToSelf THEN
BEGIN
TempRect := gSourceList^^.rView;
IF PtInRect(MPos, TempRect) THEN
BEGIN
MPos.v := ((MPos.v - TempRect.Top) DIV
gSourceList^^.CellSize.v) +
gSourceList^^.Visible.Top;
MPos.h := 0;
IF FindCell(WhichCell, gSourceList) THEN
BEGIN
IF NOT(EqualPt(WhichCell, MPos)) THEN
BEGIN
LSetSelect(FALSE,WhichCell,gSourceList);
LSetSelect (TRUE, MPos, gSourceList);
END; {equalpt}
END {FindCell}
ELSE
LSetSelect (TRUE, MPos, gSourceList);
END; {PtInRect}
END; {DragProc}
IF CanDragToOther THEN
FOR i := 1 TO gNumDestLists DO
CheckOtherList(gDestLists[i]);
END;
FUNCTION LtoLClickProc : BOOLEAN;
VAR
R : RgnHandle;
OldState : PenState;
TT, L : LongInt;
B : BOOLEAN;
DestCell,
SourceCell,
SelectedCell : Point;
CellRect : Rect;
LimitRect,
SlopRect : Rect;
i : Integer;
TempRect : Rect;
BEGIN
LtoLClickProc := TRUE;
IF NOT(AnchorDefined) THEN
BEGIN
AnchorDefined := TRUE; {store the point where}
GetMouse(AnchorPoint); {we initially clicked }
{Call this to set the lists we can drag to}
SetSourceDestLists (AnchorPoint);
EXIT(LtoLClickProc);{exit here so that}
END {the cell will be hilighted}
ELSE
AnchorDefined := FALSE;
IF FindCell(SourceCell, gSourceList) THEN
BEGIN
LRect(CellRect, SourceCell, gSourceList);
IF CanDragToSelf & NOT(CanDragToOther) THEN
BEGIN
SetRect(LimitRect, gSourceList^^.rView.Left +
(AnchorPoint.h - CellRect.Left),
gSourceList^^.rView.Top +
(AnchorPoint.v - CellRect.Top),
gSourceList^^.rView.Right -
(CellRect.Right - AnchorPoint.h),
gSourceList^^.rView.Bottom -
(CellRect.Bottom - AnchorPoint.v));
SlopRect := gSourceList^^.rView;
END
ELSE
BEGIN
SetRect(LimitRect, gTheDialog^.PortRect.Left
+ (AnchorPoint.h - CellRect.Left),
gTheDialog^.PortRect.Top +
(AnchorPoint.v - CellRect.Top),
gTheDialog^.PortRect.Right -
(CellRect.Right - AnchorPoint.h),
gTheDialog^.PortRect.Bottom -
(CellRect.Bottom - AnchorPoint.v));
SlopRect := gTheDialog^.PortRect;
END;
{now that we have selected a cell, use}
{DragGrayRgn to drag it around}
InsetRect (SlopRect, -1, -1);
R := NewRgn;
RectRgn(R, CellRect);
L := DragGrayRgn(R, AnchorPoint, LimitRect,
SlopRect, noConstraint, @DragProc);
IF HiWord(L) = kInvalidDrag THEN
BadDragAction (gSourceList, SourceCell)
ELSE
BEGIN
DestCell.v := AnchorPoint.v + HiWord(L);
DestCell.h := AnchorPoint.h + LoWord(L);
IF PtInRect(DestCell, gSourceList^^.rView) &
CanDragToSelf THEN
BEGIN
IF FindCell(DestCell, gSourceList) THEN
DragToSourceAction (gSourceList,
SourceCell, DestCell);
END
ELSE
BEGIN
IF CanDragToOther THEN
BEGIN
FOR i := 1 TO gNumDestLists DO
BEGIN
IF (gDestLists[i] <> NIL) &
(PtInRect(DestCell,
gDestLists[i]^^.rView)) &
FindCell(DestCell, gDestLists[i])
THEN
BEGIN
DragToDestAction (gSourceList,
SourceCell, gDestLists[i],
DestCell);
EXIT(LtoLClickProc);
END; {if FindCell}
END; {for}
END; {if CanDragToOther}
IF CanDragOutSide THEN
DragOutsideAction (gSourceList, SourceCell);
END; {else}
END; {if not kinvaliddrag}
END; {FindCell}
END; {LtoLClickProc}
{$i DragUnitUserProcs.i}
END.
-------------------------
listing: DragActionProcs.i
{This include file contains the action procedures for each of the different
kinds of drags you can do from one list to another or to itself}
PROCEDURE SetSourceDestLists (ClickPt : Point);
BEGIN
IF PtInRect(AnchorPoint, gList1^^.RView) THEN
BEGIN
gSourceList := gList1;
gDestLists[1] := gList2;
gDestLists[2] := gList3;
gNumDestLists := 2;
gDragStyle := kDragToOtherList + kDragOutside;
END
ELSE
IF PtInRect(ClickPt, gList2^^.RView) THEN
BEGIN
gSourceList := gList2;
gDestLists[1] := gList3;
gNumDestLists := 1;
gDragStyle := kDragToOtherList +
kDragToOwnList + kDragOutside;
END
ELSE
IF PtInRect(ClickPt, gList3^^.RView) THEN
BEGIN
gSourceList := gList3;
gDestLists[1] := gList1;
gDestLists[2] := gList2;
gNumDestLists := 2;
gDragStyle := kDragToOtherList + kDragOutside;
END;
END;
{------------------------}
PROCEDURE DragToDestAction (SourceList :
ListHandle; SourceCell : Point; DestList :
ListHandle; DestCell : Point);
VAR
STemp : Str255;
DLen : Integer;
BEGIN
DLen := SizeOF(STemp);
LGetCell(@Stemp, DLen, SourceCell, SourceList);
DestCell.v := LAddRow (1, DestCell.v, DestList);
LSetCell (@Stemp, DLen, DestCell, DestList);
END;
{------------------------}
PROCEDURE DragToSourceAction (SourceList :
ListHandle; SourceCell, DestCell : Point);
VAR
STemp, DTemp : Str255;
SLen, DLen : Integer;
BEGIN
DLen := SizeOF(STemp); SLen := SizeOF(STemp);
LGetCell (@STemp, SLen, SourceCell, SourceList);
LGetCell (@DTemp, DLen, DestCell, SourceList);
LSetCell (@STemp, SLen, DestCell, SourceList);
LSetCell (@DTemp, DLen, SourceCell, SourceList);
END;
{------------------------}
PROCEDURE BadDragAction (SourceList :
ListHandle; SourceCell : Point);
BEGIN
Sysbeep(1);
END;
{------------------------}
PROCEDURE DragOutsideAction (SourceList :
ListHandle; SourceCell : Point);
BEGIN
LDelRow (1, SourceCell.v, SourceList);
END;
-------------------------
File DragUnitUserDefs.p
VAR
gList1, gList2, gList3 : ListHandle;
CONST
U_List1= 3;
U_List2= 2;
U_List3= 5;
-------------------------
listing: TestDrag.p
PROGRAM TestDrag;
USES
MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf,
LtoLDragUnit;
CONST
kDialogID= 128;
B_OK = 1;
kReturn= 13;
kEnter = 3;
kInvalidDrag = $8000;
VAR
gDragDialog: DialogPtr;
ExitDialog : BOOLEAN;
{------------------------}
FUNCTION FindCell(VAR Selected_Cell : Point;
TheList : ListHandle) : BOOLEAN;
BEGIN
SetPt(Selected_Cell, 0, 0);
FindCell:= LGetSelect(TRUE, Selected_Cell, TheList);
END;
{------------------------}
PROCEDURE AddListString(theString:Str255; VAR
theList:ListHandle; AddWhere : Integer);
{This is a routine used to add strings to an }
{existing list}
VAR
cSize : Point;
Whichcell: Point;
BEGIN
IF (theList <> NIL) THEN
BEGIN
cSize.h := 0;
cSize.v := LAddRow(1, AddWhere, theList);
LSetCell(@TheString[1], length(TheString),
cSize, theList);
LDraw(cSize, theList); {Draw the new string}
END;
END;
{------------------------}
PROCEDURE DrawList (TheWindow : WindowPtr;
TheItem : Integer);
{Draw/Update the list which is connected to}
{the useritem TheItem}
VAR
TempRect : Rect;
DType : Integer;
DItem : Handle;
BEGIN
IF gDragDialog = NIL THEN EXIT(DrawList);
GetDItem(gDragDialog, TheItem, DType, DItem, tempRect);
InsetRect(TempRect, -1, -1);
FrameRect(TempRect);
CASE TheItem OF
U_List1:LUpdate(gDragDialog^.VisRgn, gList1);
U_List2:LUpdate(gDragDialog^.VisRgn, gList2);
U_List3:LUpdate(gDragDialog^.VisRgn, gList3);
END;
END;
{------------------------}
PROCEDURE MakeList (WhichList : Integer; VAR
ListVar : ListHandle);
VAR
DType : Integer;
DItem : Handle;
RView,
DBounds: Rect;
CSize : Point;
BEGIN
GetDItem (gDragDialog, WhichList, DType, DItem, RView);
SetRect(DBounds, 0, 0, 1, 0);
SetPt(CSize, RView.Right - RView.Left, 16);
ListVar := LNew (RView, DBounds, CSize, 0,
gDragDialog, TRUE, FALSE, FALSE, TRUE);
ListVar^^.lClikLoop := ProcPtr(@LtoLClickProc);
ListVar^^.RefCon := WhichList;
SetDItem(gDragDialog, WhichList, DType,
Handle(@DrawList), RView);
END;
{------------------------}
FUNCTION DetectListClick (VAR TheList :
ListHandle; TheEvent : EventRecord) : BOOLEAN;
{Detect clicks in a list}
VAR
MyPt : Point;
BEGIN
DetectListClick := FALSE;
IF TheList=NIL THEN EXIT(DetectListClick);
MyPt := theEvent.where;
GlobalToLocal(MyPt);
DetectListClick := LClick(myPt,
theEvent.modifiers, TheList);
END; {procedure}
{------------------------}
FUNCTION MyFilter (theDialog : DialogPtr; VAR
theEvent : EventRecord; VAR itemHit : integer) : BOOLEAN;
{catch clicks in the lists or ok equivalents}
VAR
chCode : Integer;
BEGIN
MyFilter := FALSE;
CASE theEvent.what OF
KeyDown, AutoKey :
WITH theEvent DO
BEGIN
chCode := BitAnd(message, CharCodeMask);
IF (chCode = kEnter) | (chCode = kReturn)
THEN
ExitDialog := TRUE;
END; {with}
MouseDown :
MyFilter:=DetectListClick(gList1,TheEvent) |
DetectListClick(gList2,TheEvent) |
DetectListClick(gList3,TheEvent);
END; {case}
END; {MyFilter}
{------------------------}
PROCEDURE DoDragDialog;
VAR
TempRect : Rect;
SavePort : GrafPtr;
ItemHit: Integer;
i : Integer;
FUNCTION ToStr (tempint : LongInt) : Str255;
VAR
Tempstr : Str255;
BEGIN
NumToString(tempint, tempstr);
ToStr := tempstr;
END;
BEGIN
ExitDialog := FALSE;
SetRect (TempRect, 100, 100, 400, 400);
gDragDialog := GetNewDialog (kDialogID, NIL, WindowPtr(-1));
IF gDragDialog = NIL THEN EXIT (DoDragDialog);
GetPort(SavePort);
SetPort(gDragDialog);
MakeList (U_List1, gList1);
MakeList (U_List2, gList2);
MakeList (U_List3, gList3);
LDoDraw(FALSE, gList1);
LDoDraw(FALSE, gList2);
LDoDraw(FALSE, gList3);
FOR i := 1 to 20 DO
BEGIN
AddListString(Concat(List 1, # ,ToStr(i)), gList1, i);
AddListString(Concat(List 2, # ,ToStr(i)), gList2, i);
AddListString(Concat(List 3, # ,ToStr(i)), gList3, i);
END;
LDoDraw(TRUE, gList1);
LDoDraw(TRUE, gList2);
LDoDraw(TRUE, gList3);
SetDragEnvironment (gDragDialog);
REPEAT
ModalDialog(@MyFilter, itemHit);
IF ItemHit = B_OK THEN ExitDialog := TRUE;
UNTIL ExitDialog;
LDispose(gList1);
LDispose(gList2);
LDispose(gList3);
DisposDialog(gDragDialog);
SetPort(SavePort);
END;
{------------------------}
PROCEDURE Initialize;
BEGIN
InitGraf(@thePort);
InitFonts;
InitWindows;
InitMenus;
TEInit;
InitDialogs(NIL);
InitCursor;
InitLtoLDrag;
Flushevents(everyevent, 0);
gDragDialog := NIL;
END;
BEGIN
Initialize;
DoDragDialog;
END.