List drag
Volume Number: 9
Issue Number: 6
Column Tag: Pascal Workshop
Start Dragging My Lists Around 
Here’s 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 orsource 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 list’s 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 unit’s 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 List’s 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
cursor’s 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 unit’s
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 list’s items can be
dragged into. 2) specify (using the kDragToOwnList, kDragOutside, and
kDragToOtherList constants) what kinds of drags can be done with the source list’s
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 don’t 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 can’t 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, e specially 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 don’t 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 unit’s global variables}
PROCEDURE SetDragEnvironment (DestDialog :
DialogPtr);
{Call this procedure when you switch dialogs}
FUNCTION LtoLClickProc : BOOLEAN;