docs/dnd.txt

   1                 Nautilus dnd code.
   2                 ------------------
   3
   4
   5 Nautilus dnd code is pretty compilcated, it has a lot of entry points and exit points.
   6 Trying to clarify this now.
   7
   8 You have to implement:
   9
  10 If you are a source:
  11     drag_begin
  12     drag_end
  13     drag_get_data
  14
  15 If you are a destination:
  16    drag_motion
  17    drag_data_received
  18    drag_drop
  19    drag_leave
  20
  21
  22    1) Source
  23    ---------
  24
  25 if you are a source, you have to start a drag trough gtk_drag_begin.
  26 This will call drag_begin signal in the source.
  27 Then, when the destination calls gtk_drag_finish, drag_end will be
  28 called in the source.
  29
  30 drag_get_data will be called in the source when the destination
  31 calls gtk_drag_get_data
  32
  33 So, the source is very easy to write: it just needs to implement
  34 those 3 signals and it should not have any memory management issue.
  35
  36
  37    2) Destination
  38    --------------
  39
  40 Things get a little bit complicated.
  41 when the dragging cursor gets in your window, you will get drag_motion
  42 events. In nautilus, we do many things in this function:
  43         - we start auto-scrolling if it is necessary.
  44         - we call nautilus_*_ensure_data
  45         - we prelight what is under the cursor if it can accept the drag.
  46         - we try to expand what is under you if it can accept the drop (tree view)
  47
  48 nautilus_*_ensure_data is vital. It calls gtk_drag_get_data to get the
  49 data from the source. this allows the destination to store it in advance and use it
  50 to know if what is under the cursor can accept the drag.
  51
  52 Then, when the drop occurs, drag_drop is called on the destination.
  53 drag_drop calls gtk_drag_get_data to get the data from the source to do its drop.
  54 Then, drag_data_received is called when the data is received.
  55 There, we can do the actual operation involved by the drop.
  56 Also, just before the drag_drop event, a drag_leave event is triggered.
  57
  58 If no drop occurs, a drag_leave occurs.
  59
  60 So, drag_data_received does 2 things: it is called to get the data when we are
  61 in motion and store it. It is also called to do the actual drop operation when
  62 a drop happened.
  63
  64 So, drag_data_received usually does 2 tests: it tests if the data was received.
  65 If it was received, it stores it.
  66 Then it tests if the drop occured just before. If so, it does the operation.
  67
  68 This schema involves careful memory management:
  69      1) 2 exit points in destination. (drag_leave and drag_data_received)
  70      2) a lot of things are done in the callbacks so you have to take into
  71      account all the possible code paths.
  72
  73 To solve 1), we should use ONE destroy function which cleans up the drag data.
  74 To solve 2), we have to be very careful where we call this fution from.
  75
  76 This function has to clean up:
  77      - the list of expanded nodes (tree view).
  78      - the autoscroll code.
  79      - the prelighting code.
  80      It also has to set drag_info->need_to_destroy to TRUE
  81      so that during the next drag in this widget, the
  82      rest of the drag data is destroyed before begening the actual
  83      new drag.
  84
  85 When we receive a drag_motion, we first test for need_to_destroy and
  86 destroy the rest of the data left from the previous drag. This code
  87 has to destroy/reset:
  88      - the drag data.
  89      - the boolean vars used to store the state of the drag.
  90
  91
  92