defcustom :type to use for a key sequence?

defcustom :type to use for a key sequence?

[Drew Adams]

I sent this question to gnu-emacs-help a while back. I got one reply saying
that there is no better choice, for now, than `sexp', and that this
(key-sequence typing) was to be reviewed for possible enhancement after the
release.

Can someone confirm that `sexp' is the best choice here, for now? Thanks.

        Suppose I have this:

        (defcustom the-key [(meta ?\ )] "...")
        (define-key my-map the-key 'the-cmd))

        A user might customize which key sequence is bound to `the-cmd'.

        What :type is appropriate for the defcustom? I don't see a type
        ready-made for key sequences.  Just `string'?  Or is a `choice' of
        `string' and (what kind of?) `vector' appropriate?  How can the
        :type allow for any key sequence (besides using just `sexp')?  Thx.

Re: defcustom :type to use for a key sequence?

[Kim F. Storm]

"Drew Adams" <drew.adams@oracle.com> writes:

> I sent this question to gnu-emacs-help a while back. I got one reply saying
> that there is no better choice, for now, than `sexp', and that this
> (key-sequence typing) was to be reviewed for possible enhancement after the
> release.
>
> Can someone confirm that `sexp' is the best choice here, for now? Thanks.

IMO, this is better (using a string type):

  (defcustom the-key "M-SPC" :type 'string)
  (define-key my-map (kbd the-key) 'the-cmd)

It would be very useful to have a :type 'kbd that could DTRT
re. :set etc.



>         (defcustom the-key [(meta ?\ )] "...")
>         (define-key my-map the-key 'the-cmd))


>
>         Suppose I have this:
>
>         (defcustom the-key [(meta ?\ )] "...")
>         (define-key my-map the-key 'the-cmd))
>
>         A user might customize which key sequence is bound to `the-cmd'.
>
>         What :type is appropriate for the defcustom? I don't see a type
>         ready-made for key sequences.  Just `string'?  Or is a `choice' of
>         `string' and (what kind of?) `vector' appropriate?  How can the
>         :type allow for any key sequence (besides using just `sexp')?  Thx.
>
>
>
> _______________________________________________
> Emacs-devel mailing list
> Emacs-devel@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-devel
>
>

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: defcustom :type to use for a key sequence?

[Lennart Borgman]

Kim F. Storm wrote:

>"Drew Adams" <drew.adams@oracle.com> writes:
>
>  
>
>>I sent this question to gnu-emacs-help a while back. I got one reply saying
>>that there is no better choice, for now, than `sexp', and that this
>>(key-sequence typing) was to be reviewed for possible enhancement after the
>>release.
>>
>>Can someone confirm that `sexp' is the best choice here, for now? Thanks.
>>    
>>
>
>IMO, this is better (using a string type):
>  
>
IMO a sexp is better since it is more flexible. The doc string could 
have an example or link to an example.

>It would be very useful to have a :type 'kbd that could DTRT
>re. :set etc.
>
Agree.

Re: defcustom :type to use for a key sequence?

[Kim F. Storm]

Lennart Borgman <lennart.borgman.073@student.lu.se> writes:

> IMO a sexp is better since it is more flexible.

Really?  Can you please be more specific. 

What type of event cannot be expressed via the kbd macro?

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: defcustom :type to use for a key sequence?

[Lennart Borgman]

Kim F. Storm wrote:

>Lennart Borgman <lennart.borgman.073@student.lu.se> writes:
>
>  
>
>>IMO a sexp is better since it is more flexible.
>>    
>>
>
>Really?  Can you please be more specific. 
>
>What type of event cannot be expressed via the kbd macro?
>  
>
I do not know. That was not what I meant. I just meant that a string can 
be entered like for example "\C-g" when you use :type 'sexp.

Re: defcustom :type to use for a key sequence?

[Kim F. Storm]

Lennart Borgman <lennart.borgman.073@student.lu.se> writes:

> Kim F. Storm wrote:
>
>>Lennart Borgman <lennart.borgman.073@student.lu.se> writes:
>>
>>  
>>
>>>IMO a sexp is better since it is more flexible.
>>>    
>>>
>>
>> Really?  Can you please be more specific. 
>>
>>What type of event cannot be expressed via the kbd macro?
>>  
>>
> I do not know. That was not what I meant. I just meant that a string
> can be entered like for example "\C-g" when you use :type 'sexp.

With my suggestion, you just write C-g -- much simpler and equally flexible.

A user must know a lot about internal representation -- with my suggestion,
he just has to do C-h c to learn how to write the keys he's interested in
and copy the output directly to the field.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: defcustom :type to use for a key sequence?

[Lennart Borgman]

Kim F. Storm wrote:

>Lennart Borgman <lennart.borgman.073@student.lu.se> writes:
>
>  
>
>>Kim F. Storm wrote:
>>
>>    
>>
>>>Lennart Borgman <lennart.borgman.073@student.lu.se> writes:
>>>
>>> 
>>>
>>>      
>>>
>>>>IMO a sexp is better since it is more flexible.
>>>>   
>>>>
>>>>        
>>>>
>>>Really?  Can you please be more specific. 
>>>
>>>What type of event cannot be expressed via the kbd macro?
>>> 
>>>
>>>      
>>>
>>I do not know. That was not what I meant. I just meant that a string
>>can be entered like for example "\C-g" when you use :type 'sexp.
>>    
>>
>
>With my suggestion, you just write C-g -- much simpler and equally flexible.
>
>A user must know a lot about internal representation -- with my suggestion,
>he just has to do C-h c to learn how to write the keys he's interested in
>and copy the output directly to the field.
>  
>
I am beginning to see you point now ;-)  -- yes, it is nice. Though the 
doc string for kbd should maybe tell that the output from C-h c is 
compatible with it?

Re: defcustom :type to use for a key sequence?

[Kim F. Storm]

storm@cua.dk (Kim F. Storm) writes:

> With my suggestion, you just write C-g -- much simpler and equally flexible.
>
> A user must know a lot about internal representation -- with my suggestion,
> he just has to do C-h c to learn how to write the keys he's interested in
> and copy the output directly to the field.


There is already a :type key-sequence (defined as a restricted-sexp),
but it is only used in one place:

M-x customize-variable RET mouse-region-delete-keys RET

.. which seems to be completely broken when I try it.
E.g. if I press one of the "INS" buttons strange things happen.


I still think it would make a lot of sense to make :type key-sequence
edit a string rather than a sexp.

The actual value would still be a vector or string, but before editing
it would be passed through "key-description" to give the string to
edit, and after editing the string would be passed through "kbd" (aka
"read-kbd-macro") to make the value to save in the variable.

It would be great if there was some way to actually press the keys
to insert, rather than to have to spell them out -- is there some
way to bind a key to have a special meaning while editing such a string?
E.g. to add C-M-S-$ to the string, one could press e.g. C-u C-M-S-$

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: defcustom :type to use for a key sequence?

[Lennart Borgman]

Kim F. Storm wrote:

>storm@cua.dk (Kim F. Storm) writes:
>
>  
>
>>With my suggestion, you just write C-g -- much simpler and equally flexible.
>>
>>A user must know a lot about internal representation -- with my suggestion,
>>he just has to do C-h c to learn how to write the keys he's interested in
>>and copy the output directly to the field.
>>    
>>
>
>
>There is already a :type key-sequence (defined as a restricted-sexp),
>but it is only used in one place:
>
>M-x customize-variable RET mouse-region-delete-keys RET
>
>.. which seems to be completely broken when I try it.
>E.g. if I press one of the "INS" buttons strange things happen.
>
>
>I still think it would make a lot of sense to make :type key-sequence
>edit a string rather than a sexp.
>
>The actual value would still be a vector or string, but before editing
>it would be passed through "key-description" to give the string to
>edit, and after editing the string would be passed through "kbd" (aka
>"read-kbd-macro") to make the value to save in the variable.
>
>It would be great if there was some way to actually press the keys
>to insert, rather than to have to spell them out -- is there some
>way to bind a key to have a special meaning while editing such a string?
>E.g. to add C-M-S-$ to the string, one could press e.g. C-u C-M-S-$
>  
>
I do not think it is implemented now, but it would be rather easy to do 
I believe. Just add a keymap to the field where you enter the keys. But 
it seems a little bit more complicated to edit it, but not at all 
impossible.

Re: defcustom :type to use for a key sequence?

[Richard M. Stallman]

    I still think it would make a lot of sense to make :type key-sequence
    edit a string rather than a sexp.

    The actual value would still be a vector or string, but before editing
    it would be passed through "key-description" to give the string to
    edit, and after editing the string would be passed through "kbd" (aka
    "read-kbd-macro") to make the value to save in the variable.

That could be a big improvement.  Would you like to do it?

This is a new feature (isn't it? please correct me if I'm wrong),
so fixing it now to work well when first released is appropriate.

    It would be great if there was some way to actually press the keys
    to insert, rather than to have to spell them out -- is there some
    way to bind a key to have a special meaning while editing such a string?
    E.g. to add C-M-S-$ to the string, one could press e.g. C-u C-M-S-$

That could also be a big improvement, but how to reconcile these two
features?  It could appear as a string, with a box which you click on
to enter a new key by typing it.

Re: defcustom :type to use for a key sequence?

[Kim F. Storm]

"Richard M. Stallman" <rms@gnu.org> writes:

>     I still think it would make a lot of sense to make :type key-sequence
>     edit a string rather than a sexp.
>
>     The actual value would still be a vector or string, but before editing
>     it would be passed through "key-description" to give the string to
>     edit, and after editing the string would be passed through "kbd" (aka
>     "read-kbd-macro") to make the value to save in the variable.
>
> That could be a big improvement.  Would you like to do it?

Patch included below.  Works like a charm :-)

Would some "widget expert" please take a look at the two "what is this
good for" questions...

> This is a new feature (isn't it? please correct me if I'm wrong),
> so fixing it now to work well when first released is appropriate.

Right!  The key-sequence widget was added quite recently, and
only mouse-region-delete-keys uses it.

>
>     It would be great if there was some way to actually press the keys
>     to insert, rather than to have to spell them out -- is there some
>     way to bind a key to have a special meaning while editing such a string?
>     E.g. to add C-M-S-$ to the string, one could press e.g. C-u C-M-S-$
>
> That could also be a big improvement, but how to reconcile these two
> features?  It could appear as a string, with a box which you click on
> to enter a new key by typing it.

Easy :-)

With the code below, C-q followed by KEY or EVENT simply inserts the
string representation of the key or event "at point".

This seems logical as meaning "quote next key chord".

Well, it steals the binding which allowed you to enter arbitrary
numeric values, but I don't see the purpose of that! Why would anyone
want to create a binding for a key they cannot type?

The help-echo is changed accordingly.



Index: wid-edit.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/wid-edit.el,v
retrieving revision 1.157
diff -c -r1.157 wid-edit.el
*** wid-edit.el	17 Dec 2005 08:52:54 -0000	1.157
--- wid-edit.el	20 Dec 2005 14:41:54 -0000
***************
*** 3161,3188 ****
      (widget-apply widget :notify widget event)
      (widget-setup)))
  \f
  (defvar widget-key-sequence-prompt-value-history nil
    "History of input to `widget-key-sequence-prompt-value'.")
  
! ;; This mostly works, but I am pretty sure it needs more change
! ;; to be 100% correct.  I don't know what the change should be -- rms.
  
  (define-widget 'key-sequence 'restricted-sexp
!   "A Lisp function."
    :prompt-value 'widget-field-prompt-value
    :prompt-internal 'widget-symbol-prompt-internal
!   :prompt-match 'fboundp
    :prompt-history 'widget-key-sequence-prompt-value-history
    :action 'widget-field-action
    :match-alternatives '(stringp vectorp)
!   :validate (lambda (widget)
! 	      (unless (or (stringp (widget-value widget))
! 			  (vectorp (widget-value widget)))
! 		(widget-put widget :error (format "Invalid key sequence: %S"
! 						  (widget-value widget)))
! 		widget))
!   :value 'ignore
    :tag "Key sequence")
  \f
  (define-widget 'sexp 'editable-field
    "An arbitrary Lisp expression."
--- 3161,3224 ----
      (widget-apply widget :notify widget event)
      (widget-setup)))
  \f
+ ;;; I'm not sure about what this is good for?  KFS.
  (defvar widget-key-sequence-prompt-value-history nil
    "History of input to `widget-key-sequence-prompt-value'.")
  
! (defvar widget-key-sequence-default-value [ignore]
!   "Default value for an empty key sequence.")
! 
! (defvar widget-key-sequence-map
!   (let ((map (make-sparse-keymap)))
!     (set-keymap-parent map widget-field-keymap)
!     (define-key map [(control ?q)] 'widget-key-sequence-read-event)
!     map))
  
  (define-widget 'key-sequence 'restricted-sexp
!   "A key sequence."
    :prompt-value 'widget-field-prompt-value
    :prompt-internal 'widget-symbol-prompt-internal
! ; :prompt-match 'fboundp   ;; What was this good for?  KFS
    :prompt-history 'widget-key-sequence-prompt-value-history
    :action 'widget-field-action
    :match-alternatives '(stringp vectorp)
!   :format "%{%t%}: %v"
!   :validate 'widget-key-sequence-validate
!   :value-to-internal 'widget-key-sequence-value-to-internal
!   :value-to-external 'widget-key-sequence-value-to-external
!   :value widget-key-sequence-default-value
!   :keymap widget-key-sequence-map
!   :help-echo "C-q: insert KEY or EVENT; RET: enter value"
    :tag "Key sequence")
+ 
+ (defun widget-key-sequence-read-event (ev)
+   (interactive (list (read-event "Insert KEY or EVENT: ")))
+   (if (/= (char-before) ?\s) (insert " "))
+   (insert (key-description (list ev)))
+   (if (memq 'down (event-modifiers ev))
+       (insert " " (key-description (list (read-event))))))
+ 
+ (defun widget-key-sequence-validate (widget)
+   (unless (or (stringp (widget-value widget))
+ 	      (vectorp (widget-value widget)))
+     (widget-put widget :error (format "Invalid key sequence: %S"
+ 				      (widget-value widget)))
+     widget))
+ 
+ (defun widget-key-sequence-value-to-internal (widget value)
+   (if (widget-apply widget :match value)
+       (if (equal value widget-key-sequence-default-value)
+ 	  ""
+ 	(key-description value))
+     value))
+ 
+ (defun widget-key-sequence-value-to-external (widget value)
+   (if (stringp value)
+       (if (string-match "\\`[[:space:]]*\\'" value)
+ 	  widget-key-sequence-default-value
+ 	(read-kbd-macro value))
+     value))
+ 
  \f
  (define-widget 'sexp 'editable-field
    "An arbitrary Lisp expression."

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: defcustom :type to use for a key sequence?

[Richard M. Stallman]

    Well, it steals the binding which allowed you to enter arbitrary
    numeric values, but I don't see the purpose of that! Why would anyone
    want to create a binding for a key they cannot type?

For use on a different terminal, perhaps.  If you log in from
different terminals and use the same .emacs file, you might want
to do this.

So it is not such an unreasonable thing to do.

However, I don't see why you can't put back the numeric input feature.
After all, people don't need C-q to insert a self-inserting key
in this field, any more than they need C-q to insert such characters
in any buffer.

With that change, your C-q replacement would have no disadvantages and
might as well be installed.  But it does have a drawback as a solution
to this problem: it isn't self-evident.  It would be something you
just have to know.  That is not ideal.

That is why I suggested adding a button meaning "type a key sequence".
A button would be self-evident, and would not get in the way of any
other commands.

Want to do that, too?

Re: defcustom :type to use for a key sequence?

[David Kastrup]

"Richard M. Stallman" <rms@gnu.org> writes:

> With that change, your C-q replacement would have no disadvantages
> and might as well be installed.  But it does have a drawback as a
> solution to this problem: it isn't self-evident.  It would be
> something you just have to know.  That is not ideal.

How about S-C-q be an event-quote character in general?  Or at least
in contexts like Lisp buffers?  One can't type it on a tty, but since
you can't type interesting events on a tty anyway, this would not be a
drawback.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

RE: defcustom :type to use for a key sequence?

[Drew Adams]

    IMO, this is better (using a string type):

      (defcustom the-key "M-SPC" :type 'string)
      (define-key my-map (kbd the-key) 'the-cmd)

Looks good, but how to, for instance, get the equivalent of each of these,
which are not the same?

 (define-key my-map [S-tab] 'the-cmd)
 (define-key my-map [S-iso-lefttab] 'the-cmd)
 (define-key my-map [(shift ?\t)] 'the-cmd)

I guess the last one would be done using S-TAB as input (so, `(kbd
"S-TAB")'). (Is that correct?) But how would you input, say, the first one
as a string? Would you input <S-tab> (so, `(kbd "<S-tab>")')? Or is it
S-<tab> (so, `(kbd "S-<tab>")')? Or are those two different keys, both of
which are different from S-TAB?

Obviously, I'm not real clear on `kbd'.  I don't find the Elisp manual too
helpful on that either.

If the external string (print) representation were used, as I think you
suggest, then users would need to know the various string representations.
That sounds like a good way to go. However, IMO, the presentation in the
Elisp manual would need to be a bit better, if we start expecting users to
use things like "<S-tab>" vs "S-TAB" to define bindings.

Also, would the Emacs (not just Elisp) manual then also need to describe the
string (print) representations? Maybe it's normal that only the Elisp manual
describes key-binding syntax, but if we expect Customize users to specify
key sequences using string (print) representations, then they will need to
know the syntax. I don't know - I guess we could assume that such
Customization would be for Elisp-savvy users (after all, we also allow :type
`sexp').

In any case, even the Elisp manual doesn't explain the `kbd' syntax clearly,
IMO. It gives a few simple examples (no menu items, for example), says that
the syntax is "the syntax used in this manual" (whatever that is - where is
that described?), and ends by sending you to node Edit Keyboard Macro(emacs)
for the full syntax explanation ("same syntax that Edit Macro mode uses for
editing keyboard macros"). However, I don't see any such syntax description
at the referenced node, Edit Keyboard Macro. Is that perhaps the wrong xref?

I'd like to see a good, clear description of how to specify any and all
bindings with `kbd'. It also deserves a better place than the Info page
"Keymap Terminology". This is about key-sequence syntax for use with `kbd';
it's not about keymap terminology.

(Did I notice a thread here lately about the manual being updated in this
regard? I'm looking at an old manual from July, so my comments here might be
out-of-date.)

    It would be very useful to have a :type 'kbd that could DTRT
    re. :set etc.

Yes. Although the name should be something more readable, such as :type
'key-sequence. It's bad enough that we use "key sequence" to stand for mouse
and menu events too, but "kbd" emphasizes the _keyboard_ far too much. Also,
there is no reason to use an abbreviation here.

    >         (defcustom the-key [(meta ?\ )] "...")
    >         (define-key my-map the-key 'the-cmd))
    >
    >         Suppose I have this:
    >
    >         (defcustom the-key [(meta ?\ )] "...")
    >         (define-key my-map the-key 'the-cmd))
    >
    >         A user might customize which key sequence is bound to
    >         `the-cmd'.
    >
    >         What :type is appropriate for the defcustom? I don't
    >         see a type ready-made for key sequences.  Just `string'?
    >         Or is a `choice' of `string' and (what kind of?)
    >         `vector' appropriate?  How can the :type allow for any
    >         key sequence (besides using just `sexp')?

Re: defcustom :type to use for a key sequence?

[Kim F. Storm]

"Drew Adams" <drew.adams@oracle.com> writes:

> Obviously, I'm not real clear on `kbd'.  I don't find the Elisp manual too
> helpful on that either.

True.

> If the external string (print) representation were used, as I think you
> suggest, then users would need to know the various string representations.
> That sounds like a good way to go. However, IMO, the presentation in the
> Elisp manual would need to be a bit better, if we start expecting users to
> use things like "<S-tab>" vs "S-TAB" to define bindings.

With the patch I just sent, you can customize the-key by pressing C-q
followed by the actual key chord.  So if you press shift+tab, it
inserts "the right thing" whether <S-tab> or "S-TAB" is needed.

>
> Also, would the Emacs (not just Elisp) manual then also need to describe the
> string (print) representations? Maybe it's normal that only the Elisp manual
> describes key-binding syntax, but if we expect Customize users to specify
> key sequences using string (print) representations, then they will need to
> know the syntax.

They just need to know about C-q ...

> I'd like to see a good, clear description of how to specify any and all
> bindings with `kbd'.

Me too...  Let's hope someone volounteers to write it!

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

RE: defcustom :type to use for a key sequence?

[Drew Adams]

    > Obviously, I'm not real clear on `kbd'.  I don't find the
    > Elisp manual too helpful on that either.

    True.

    > If the external string (print) representation were used, as I
    > think you suggest, then users would need to know the various
    > string representations.  That sounds like a good way to go.
    > However, IMO, the presentation in the Elisp manual would need
    > to be a bit better, if we start expecting users to
    > use things like "<S-tab>" vs "S-TAB" to define bindings.

    With the patch I just sent, you can customize the-key by pressing C-q
    followed by the actual key chord.  So if you press shift+tab, it
    inserts "the right thing" whether <S-tab> or "S-TAB" is needed.

That would be very good (natural). This should be mentioned in the manual
and in the Customize UI somehow.

    > Also, would the Emacs (not just Elisp) manual then also need
    > to describe the string (print) representations? Maybe it's
    > normal that only the Elisp manual describes key-binding
    > syntax, but if we expect Customize users to specify
    > key sequences using string (print) representations, then they
    > will need to know the syntax.

    They just need to know about C-q ...

    > I'd like to see a good, clear description of how to specify
    > any and all bindings with `kbd'.

    Me too...  Let's hope someone volounteers to write it!

Thanks for working on this, Kim. I haven't tried it yet, but it sounds
great.