/[emacs]/emacs/lispref/text.texi
ViewVC logotype

Diff of /emacs/lispref/text.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.83 by kfstorm, Tue Jan 11 00:12:09 2005 UTC revision 1.84 by rms, Wed Jan 12 05:14:03 2005 UTC
# Line 3394  buffer. Line 3394  buffer.
3394  @subsection Enabling Mouse-1 to Follow Links  @subsection Enabling Mouse-1 to Follow Links
3395  @cindex follow links  @cindex follow links
3396    
3397    Traditionally, Emacs uses a @key{mouse-1} click to set point and a    The normal Emacs command for activating text in read-only buffers is
3398  @key{mouse-2} click to follow a link, whereas most other applications  @key{Mouse-2}, which includes following textual links.  However, most
3399  use a @key{mouse-1} click for both purposes, depending on whether you  graphical applications use @key{Mouse-1} for following links.  For
3400  click outside or inside a link.  compatibility, @key{Mouse-1} follows links in Emacs too, when you
3401    click on a link quickly without moving the mouse.  The user can
3402    Starting with Emacs release 21.4, the user visible behaviour of a  customize this behaviour through the variable
3403  @key{mouse-1} click on a link has been changed to match this  @code{mouse-1-click-follows-link}.
3404  context-sentitive dual behaviour.  The user can customize this  
3405  behaviour through the variable @code{mouse-1-click-follows-link}.    To define text as a link at the Lisp level, you should bind
3406    @key{Mouse-2} to a command to follow the link.  Then, to indicate
3407    However, at the Lisp level, @key{mouse-2} is still used as the  that @key{Mouse-1} should also follow the link, here is what you do:
 action for the clickable text corresponding to the link, and the  
 clickable text must be explicitly marked as a link for a @key{mouse-1}  
 click to follow the link.  
   
   There are several methods that can be used to identify a clickable  
 text as a link:  
3408    
3409  @table @asis  @table @asis
3410  @item follow-link property  @item @code{follow-link} property
3411    If the clickable text has a non-@code{nil} @code{follow-link} text or overlay
   If the clickable text has a non-nil @code{follow-link} text or overlay  
3412  property, the value of that property determines what to do.  property, the value of that property determines what to do.
3413    
3414  @item follow-link event  @item @code{follow-link} event
3415    If there is a binding for the @code{follow-link} event, either on
   If there is a binding for the @code{follow-link} event, either on  
3416  the clickable text or in the local keymap, the binding of that event  the clickable text or in the local keymap, the binding of that event
3417  determines whether the mouse click position is inside a link:  determines whether the mouse click position is inside a link.
3418    @end table
3419    
3420  @table @asis    Regardless of where the @code{follow-link} value comes from, that
3421  @item mouse-face  value is used according to the following table to determine whether
3422    the given position is inside a link, and (if so) to compute an
3423    @dfn{action code} saying how @key{Mouse-1} should handle the link.
3424    
3425    If the binding is @code{mouse-face}, the mouse click position is  @table @asis
3426  inside a link if there is a non-nil @code{mouse-face} property at  @item @code{mouse-face}
3427  that position.  A value of @code{t} is used to determine what to do next.  If the value is @code{mouse-face}, a position is inside a link if
3428    there is a non-@code{nil} @code{mouse-face} property at that position.
3429    The action code is always @code{t}.
3430    
3431  For example, here is how @key{mouse-1} are setup in info mode:  For example, here is how Info mode handles @key{Mouse-1}:
3432    
3433  @example  @example
3434  (define-key Info-mode-map [follow-link] 'mouse-face)  (define-key Info-mode-map [follow-link] 'mouse-face)
3435  @end example  @end example
3436    
3437  @item a function  @item a function
3438    If the value is a function, @var{func}, then a position @var{pos} is
3439    inside a link if @code{(@var{func} @var{pos})} evaluates to
3440    non-@code{nil}.  The value returned by @var{func} serves as the action
3441    code.
3442    
3443    If the binding is a function, @var{func}, the mouse click position,  For example, here is how pcvs enables @key{Mouse-1} to follow links on
3444  @var{pos}, is inside a link if the call @code{(@var{func} @var{pos})}  file names only:
 returns non-@code{nil}.  The return value from that call determines  
 what to do next.  
   
 For example, here is how pcvs enables @key{mouse-1} on file names only:  
3445    
3446  @example  @example
3447  (define-key map [follow-link]  (define-key map [follow-link]
# Line 3452  For example, here is how pcvs enables @k Line 3449  For example, here is how pcvs enables @k
3449      (if (eq (get-char-property pos 'face) 'cvs-filename-face) t)))      (if (eq (get-char-property pos 'face) 'cvs-filename-face) t)))
3450  @end example  @end example
3451    
3452  @item anthing else  @item anything else
3453    If the value is anything else, it is the action code.
   If the binding is anything else, the binding determines what to do.  
 @end table  
   
3454  @end table  @end table
3455    
3456  @noindent  @noindent
3457  The resulting value determined above is interpreted as follows:  Here's how the action code determines what @key{Mouse-1} should do:
3458    
3459  @table @asis  @table @asis
3460  @item a string  @item a string
3461    If the action code is a string, the @key{Mouse-1} event is translated
3462    If the value is a string, the @key{mouse-1} event is translated into  into the first character of the string, i.e., the action of the
3463  the first character of the string, i.e. the action of the @key{mouse-1}  @key{Mouse-1} click is the local or global binding of that character.
3464  click is the local or global binding of that character.  Thus, if the action code is @code{"foo"}, @key{Mouse-1} translates
3465    into @kbd{f}.
3466    
3467  @item a vector  @item a vector
3468    If the action code is is a vector, the @key{Mouse-1} event is
3469    If the value is is a vector, the @key{mouse-1} event is translated  translated into the first element of that vector, i.e,. the action of
3470  into the first element of that vector, i.e. the action of the  the @key{Mouse-1} click is the local or global binding of that event.
3471  @key{mouse-1} click is the local or global binding of that event.  Thus, if the action code is @code{[?f ?o ?o]}, @key{Mouse-1}
3472    translates into @kbd{f}.
3473  @item anthing else  
3474    @item anything else
3475    For any other non-nil valule, the @key{mouse-1} event is translated  For any other non-@code{nil} action code, the @code{mouse-1} event is
3476  into a @key{mouse-2} event at the same position.  translated into a @code{mouse-2} event at the same position.
3477  @end table  @end table
3478    
3479    To use @key{mouse-1} on a button defined with @code{define-button-type},    To define @key{Mouse-1} to activate a button defined with
3480  give the button a @code{follow-link} property with a value as  @code{define-button-type}, give the button a @code{follow-link}
3481  specified above to determine how to follow the link.  property with a value as specified above to determine how to follow
3482    the link.
3483    To use @key{mouse-1} on a widget defined with @code{define-widget},  @c ??? That is not clear.  This needs an example or an xref.
3484  give the widget a @code{:follow-link} property with a value  
3485  as specified above to determine how to follow the link.    To define @key{Mouse-1} on a widget defined with
3486    @code{define-widget}, give the widget a @code{:follow-link} property
3487    with a value as specified above to determine how to follow the link.
3488    @c ??? That is not clear.  This needs an example or an xref.
3489    
3490  @defun mouse-on-link-p pos  @defun mouse-on-link-p pos
3491  @tindex mouse-on-link-p  @tindex mouse-on-link-p
3492  Return non-@code{nil} if @var{pos} is on a link in the current buffer.  This function returns non-@code{nil} if position @var{pos} in the
3493    current buffer is on a link.
3494  @end defun  @end defun
3495    
3496  @node Fields  @node Fields

Legend:
Removed from v.1.83  
changed lines
  Added in v.1.84

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26