8. Internal Drag And Drop

The file `internal-drag-and-drop.el', which is shipped with `hm--html-menus', provides a general package for internal drag and drop in emacs. "General" means that it can be used apart from hm--html-mode in any other mode.

You can start such an action by clicking with the mouse in the source buffer and then in the destination buffer. The action may depend on the points where you've clicked with the mouse, on the state of the region, the point, the mark and any other properties of the source and the destination buffers. The actions are defined by the variable idd-actions, which is a buffer local variable.

8.1 Drag And Drop Customization

Since the XEmacs 19.15 and 20.2 a special package can be used for the customization of lisp packages. The internal drag and drop package uses now also this feature. Therefore you can set all user variables with the help of the Customize submenu, which can be selected in the Option menu. If you use it, the variables will currently be saved in a special customization file. Please look at the `NEWS' file or the info manuals of the XEmacs to find out more about the customization package.

The internal drag and drop functions may be used in all modes. Therefore their general customization isn't done in `hm--html-configuration.el'. Its variables are defined in the file `internal-drag-and-drop.el' instead. You can set them in your `.emacs' or in one of the other emacs init files (e.g. `default.el'). The following subsections describe the main customization variables.

8.1.1 Defining The Drag And Drop Actions

The drag and drop actions are commands which are called after an internal drag and drop. They depend on the source and the destination of the drag and drop. Drag and drop actions are defined by the variable:

• idd-actions: A list with actions, depending on the source and the destination of the drag and drop command.

The list looks like:

'((<destination-specification-1> (<source-specification-1> <action-1-1>)
                            (<source-specification-2> <action-1-2>)
                                            :
   )
  (<destination-specification-2> (<source-specification-1> <action-2-1>)
                            (<source-specification-2> <action-2-2>)
                                            :
   )
                          :
  )

'([(<specification-type> <value>)])

<specification-type> :==
idd-if-minor-mode-p | idd-if-buffer-name-p |
idd-if-region-active-p | idd-if-url-at-point-p |
idd-if-major-mode-p | idd-if-variable-non-nil-p |
idd-if-dired-file-on-line-p |
idd-if-dired-no-file-on-line-p |
idd-if-local-file-p | idd-if-buffer-name-p |
idd-if-modifiers-p | ...

The <specification-type> - functions must have two arguments. The first one is the source or destination and the second is the <value>. It must return nil, if the test wasn't successful, and a number (in general 1), which specifies the weight of the test function. The weights of all single tests are added to a summary weight and assigned to the action. The action with the highest weight is called from the action handler. Look at the definition of idd-if-major-mode-p, idd-if-minor-mode-p and so on for examples. Look at the function idd-get-source-or-destination-alist, if you want to know the structure of the source-or-destination argument of these functions.

The <destination-specification> looks like <source-specification>, but in general it could be set to nil in mode specific idd-action lists.

If <destination-specification-1> or <source-specification-1> is set to nil, then every source or source matches. idd-actions is a buffer local variable, which should be at least mode depended. So if the <destination-specification-1> is set to nil it says, that the destination buffer must only have a specific mode. However, it's also possible to define a general idd-actions list, where the destination mode is specified by idd-if-major-mode-p.

<action> is a function which has two arguments. The first specifies the source and the second the destination. Look at the function definition of idd-action-copy-region and idd-action-copy-replace-region. They are examples for such actions.

The following is an example for hm--html-mode:

(defvar idd-actions
  '((nil (((idd-if-major-mode-p . dired-mode)
           (idd-if-dired-file-on-line-p . ".*\\.\\(gif\\)\\|\\(jpq\\)"))
          hm--html-idd-add-include-image-from-dired-line)
         (((idd-if-major-mode-p . dired-mode)
           (idd-if-dired-no-file-on-line-p . nil))
          hm--html-idd-add-file-link-to-file-on-dired-line)
         (((idd-if-major-mode-p . dired-mode)
           (idd-if-dired-no-file-on-line-p . t))
          hm--html-idd-add-file-link-to-directory-of-buffer)
         (((idd-if-major-mode-p . w3-mode)
           (idd-if-url-at-point-p . t))
          hm--html-idd-add-html-link-from-w3-buffer-point)
         (((idd-if-major-mode-p . w3-mode))
          hm--html-idd-add-html-link-to-w3-buffer)
         (((idd-if-local-file-p . t))
          hm--html-idd-add-file-link-to-buffer)))

8.1.2 The Mouse Bindings

The following three variables determine the mouse bindings and the mouse behaviour for the internal drag and drop package:

• idd-global-mouse-keys: The mouse keys for the command idd-mouse-drag-and-drop. The command idd-mouse-drag-and-drop is bound during the loading of the package `internal-drag-and-drop' to these keys in the global keymap. The drag and drop action must be bound global, because the drag and drop action must be started by a click in the source buffer. Therefore no action will be performed if the mouse keys are not bound to idd-mouse-drag-and-drop in the destination buffer.

  Set it to nil, if you don't want to bind this function during loading.

  If the command is already bound in the global keymap during loading, then this key sequence will not be bound.

  By default the mouse binding is meta control button1.

• idd-global-help-mouse-keys: The mouse keys for the command idd-help-mouse-drag-and-drop. The command idd-help-mouse-drag-and-drop is bound during the loading of the package `internal-drag-and-drop' to these keys in the global keymap.

  Set it to nil if you don't want to bind this function during loading.

  If the command is already bound in the global keymap during loading, then this key sequence will not be bound.

  By default the mouse binding is meta control button3.

• idd-drag-and-drop-mouse-binding-type: The type of the drag and drop mouse binding. The value may be click or press-button-during-move. A value of click means that you have to click over the source, release the button and click it again over the destination. A value of press-button-during-move means that you have to press the button down over the source and hold it until the mouse pointer is over the destination.

  The disadvantage of the press-button-during-move type compared with the click type is that you can't select a destination region, and therefore a drag and drop action depending on a selected region can't be started with that type of mouse binding.

8.1.3 The Drag And Drop Mouse Pointer

In the XEmacs the mouse pointer glyph (shape) can be set to any glyph. This is used during the drag and drop command to indicate, that the command is active. There exists the following three variables to customize this:

• idd-mouse-pointer-image: The name of the xbm file with the mouse pointer image. By default this is the file `drop'. There exists also a file called `dropmsk', which contains the mask image. The mask file is loaded automatically.

• idd-data-directory: The name fo the directory, where the file idd-mouse-pointer-image is searched. By default this is the subdirectory `idd' in the XEmacs install directory data-directory.

• idd-overwrite-mouse-pointers: A list with pointer glyph variables, which should be overwritten by the idd-drag-and-drop-pointer-glyph. If it is nil, the pointer wont be changed. Currently it must be nil in the Emacs.

If one of the variables idd-mouse-pointer-image or idd-data-directory is changed, the command idd-make-drag-and-drop-pointer-glyph must be called. This command builds the mouse pointer glyph, which is stored in idd-drag-and-drop-pointer-glyph.

I don't know how to set the mouse pointer in the Emacs to a drag and drop image. Any hints for doing this are welcome.

8.2 The Drag And Drop Commands

There are 2 groups of commands. The first contains commands which perform the drag and drop action and the second displays help messages about a possible drag and drop action.

8.2.1 Performing The Drag And Drop Action

The following five commands perform internal drag and drop actions:

• idd-mouse-drag-and-drop: Performs a drag and drop action. It calls the command idd-mouse-drag-and-drop-click or idd-mouse-drag-and-drop-press-button-during-move depending on the value of idd-drag-and-drop-mouse-binding-type. However you've set this, you start a drag and drop action with this command by pressing down its mouse button over the source. This command is bound by default to a global mouse key sequence. See section 8.1.2 The Mouse Bindings.

• idd-start-mouse-drag-and-drop: Starts a drag and drop command. This command could be used to start a drag and drop command without a button event. Therefore this should not be bound directly to a mouse button. This command can be used to start a drag and drop action with a click on a menu item or tool bar icon. After that you have to press a mouse button over the source. The rest depends on the value of idd-drag-and-drop-mouse-binding-type, as with the command idd-mouse-drag-and-drop.

• idd-help-start-action: It is possible to display a help buffer with a message in it, which describes the action instead of performing it immediately (see section 8.2.2 Displaying Help On Drag And Drop). In this case you can perform the action by clicking on a special extent in the help buffer, which runs this command.

• idd-mouse-drag-and-drop-press-button-during-move: Performs a drag and drop action in a more traditional way than idd-mouse-drag-and-drop-click. First you press the button over the source and then move with the depressed button to the destination, where you release the button. This must be bound to a mouse button. The SOURCE-EVENT must be a button-press-event.

  The disadvantage of this command compared with the command idd-mouse-drag-and-drop-click is, that you can't select a destination region.

  You should bind the command idd-mouse-drag-and-drop instead of this one, because it's then possible to switch between both drag and drop behaviours by changing only one variable.

• idd-mouse-drag-and-drop-click: Performs a drag and drop action in a more useful way than idd-mouse-drag-and-drop-press-button-during-move. First you click on the source and then on the destination. This must be bound to a mouse button. The SOURCE-EVENT must be a button-press-event.

  You should bind the command idd-mouse-drag-and-drop instead of this one, because it's then possible to switch between both drag and drop behaviours by changing only one variable.

8.2.2 Displaying Help On Drag And Drop

It's possible to display a buffer with a help message describing the action being considered before actually performing it. To perform the action, you then click on a special extent in the help buffer. To get the help buffer, you do the same things as you do to perform the action itself. Only the mouse key differs. There are two commands for this:

• idd-help-mouse-drag-and-drop: Displays help about the drag and drop action. It works similarly to idd-mouse-drag-and-drop (see section 8.2.1 Performing The Drag And Drop Action).

  By default this command is globally bound to meta control button3. This may be changed with the variable idd-global-help-mouse-keys (see section 8.1.2 The Mouse Bindings).

• idd-start-help-mouse-drag-and-drop: Starts displaying help about the drag and drop action. It works similarly to idd-start-mouse-drag-and-drop (see section 8.2.1 Performing The Drag And Drop Action) and can be used to start the help by clicking on a menu item or a tool bar icon.