unofficial mirror of help-gnu-emacs@gnu.org
 help / color / mirror / Atom feed
* using keyword arguments in define-minor-mode
@ 2022-02-04 11:10 goncholden via Users list for the GNU Emacs text editor
  2022-02-04 11:38 ` Tassilo Horn
  0 siblings, 1 reply; 5+ messages in thread
From: goncholden via Users list for the GNU Emacs text editor @ 2022-02-04 11:10 UTC (permalink / raw)
  To: goncholden via Users list for the GNU Emacs text editor

Been advised against the long obsolete form for define-minor-mode, but using keyword arguments instead. But need some examples. Particularly for indicating in the mode-line.

(define-minor-mode rich-minor-mode
"docstring"

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: using keyword arguments in define-minor-mode
  2022-02-04 11:10 using keyword arguments in define-minor-mode goncholden via Users list for the GNU Emacs text editor
@ 2022-02-04 11:38 ` Tassilo Horn
  2022-02-04 11:51   ` goncholden
  0 siblings, 1 reply; 5+ messages in thread
From: Tassilo Horn @ 2022-02-04 11:38 UTC (permalink / raw)
  To: goncholden; +Cc: help-gnu-emacs

goncholden via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> writes:

> Been advised against the long obsolete form for define-minor-mode, but
> using keyword arguments instead. But need some examples. Particularly
> for indicating in the mode-line.
>
> (define-minor-mode rich-minor-mode
> "docstring"

Have a look at `C-h f define-minor-mode' which explains those keyword
arguments.

(define-minor-mode my-super-mode
  "This is the docstring."
  :lighter "ModeLineIndicator"
  ...)

Bye,
Tassilo



^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: using keyword arguments in define-minor-mode
  2022-02-04 11:38 ` Tassilo Horn
@ 2022-02-04 11:51   ` goncholden
  2022-02-04 12:52     ` Tassilo Horn
  0 siblings, 1 reply; 5+ messages in thread
From: goncholden @ 2022-02-04 11:51 UTC (permalink / raw)
  To: Tassilo Horn; +Cc: help-gnu-emacs


------- Original Message -------

On Friday, February 4th, 2022 at 11:38 AM, Tassilo Horn <tsdh@gnu.org> wrote:

> goncholden via Users list for the GNU Emacs text editor help-gnu-emacs@gnu.org writes:
>
> > Been advised against the long obsolete form for define-minor-mode, but
> > using keyword arguments instead. But need some examples. Particularly
> > for indicating in the mode-line.
> >
> > (define-minor-mode rich-minor-mode
> >
> > "docstring"
>
> Have a look at `C-h f define-minor-mode' which explains those keyword
> arguments.
>
> (define-minor-mode my-super-mode
> "This is the docstring."
> :lighter "ModeLineIndicator"
> ...)
>
> Bye,
> Tassilo

Tassilo, regarding :init-value, what is it, and how does it work?






^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: using keyword arguments in define-minor-mode
  2022-02-04 11:51   ` goncholden
@ 2022-02-04 12:52     ` Tassilo Horn
  2022-02-06  8:58       ` Kevin Vigouroux via Users list for the GNU Emacs text editor
  0 siblings, 1 reply; 5+ messages in thread
From: Tassilo Horn @ 2022-02-04 12:52 UTC (permalink / raw)
  To: goncholden; +Cc: help-gnu-emacs

goncholden <goncholden@protonmail.com> writes:

>> Have a look at `C-h f define-minor-mode' which explains those keyword
>> arguments.
>>
>> (define-minor-mode my-super-mode
>> "This is the docstring."
>> :lighter "ModeLineIndicator"
>> ...)
>
> Tassilo, regarding :init-value, what is it, and how does it work?

The docs say:

--8<---------------cut here---------------start------------->8---
:init-value VAL	the initial value of the mode’s variable.
		Note that the minor mode function won’t be called by setting
		this option, so the value *reflects* the minor mode’s natural
		initial state, rather than *setting* it.
		In the vast majority of cases it should be nil.
		Not used if you also specify :variable.
--8<---------------cut here---------------end--------------->8---

I'm not exactly sure how it works but would simply follow the advice of
letting it be nil, i.e., not specify :init-value t.

Looking at the occurrences of :init-value t in emacs, it's set for
minor-modes which default to "on" and are activated by other means than
the minor-mode function.  For example, mwheel.el does:

--8<---------------cut here---------------start------------->8---

(define-minor-mode mouse-wheel-mode
  "Toggle mouse wheel support (Mouse Wheel mode)."
  :init-value t
  :global t
  :group 'mouse
  ;; Remove previous bindings, if any.
  (mouse-wheel--remove-bindings)
  ;; Setup bindings as needed.
  (when mouse-wheel-mode
    (mouse-wheel--setup-bindings)))

(when mouse-wheel-mode
  (mouse-wheel--setup-bindings))
--8<---------------cut here---------------end--------------->8---

I really see no good reason for this gymnastics but guess that's
historical cruft and today you'd just write

--8<---------------cut here---------------start------------->8---
(define-minor-mode mouse-wheel-mode
  "Toggle mouse wheel support (Mouse Wheel mode)."
  :global t
  :group 'mouse
  ;; Remove previous bindings, if any.
  (mouse-wheel--remove-bindings)
  ;; Setup bindings as needed.
  (when mouse-wheel-mode
    (mouse-wheel--setup-bindings)))

(mouse-wheel-mode 1)
--8<---------------cut here---------------end--------------->8---

in order to define a default-on minor-mode.

Another example is `line-number-mode':

--8<---------------cut here---------------start------------->8---
(define-minor-mode line-number-mode
  "Toggle line number display in the mode line (Line Number mode).

Line numbers do not appear for very large buffers and buffers
with very long lines; see variables `line-number-display-limit'
and `line-number-display-limit-width'.

See `mode-line-position-line-format' for how this number is
presented."
  :init-value t :global t :group 'mode-line)
--8<---------------cut here---------------end--------------->8---

In this case, the mode doesn't do anything but toggling that variable,
but the variable `line-number-mode' is used elsewhere to check if the
line number should be displayed in the mode-line.  So here, the
minor-mode is only a convenience feature so that you can do

  M-x line-number-mode RET

instead of

  M-x set-variable RET line-number-mode RET t RET.

Another use-case for :init-value t seems to be in combination with
:initialize 'custom-initialize-delay which seems to set the mode's
variable somehow using customize which in turn will call the mode's
function.  Something like that.  Given that :initialize is not even
documented, I guess that's a usage only for emacs-internal minor-modes.
Maybe Stefan can say something about this.

Bye,
Tassilo



^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: using keyword arguments in define-minor-mode
  2022-02-04 12:52     ` Tassilo Horn
@ 2022-02-06  8:58       ` Kevin Vigouroux via Users list for the GNU Emacs text editor
  0 siblings, 0 replies; 5+ messages in thread
From: Kevin Vigouroux via Users list for the GNU Emacs text editor @ 2022-02-06  8:58 UTC (permalink / raw)
  To: help-gnu-emacs

I don’t know if it’s enough to look at the docstring of
`define-minor-mode' when things are new.

• Emacs Lisp Ref. manual, section 23.3.3 “Defining Minor Modes”
- https://www.gnu.org/software/emacs/manual/html_node/elisp/Defining-Minor-Modes.html

#+begin_quote
By default, it also defines a variable named MODE, which is set to ‘t’
or ‘nil’ by enabling or disabling the mode. The variable is initialized
to INIT-VALUE. Except in unusual circumstances (see below), this value
must be ‘nil’.
#+end_quote

#+begin_quote
The initial value must be ‘nil’ except in cases where (1) the mode is
preloaded in Emacs, or (2) it is painless for loading to enable the mode
even though the user did not request it. For instance, if the mode has
no effect unless something else is enabled, and will always be loaded by
that time, enabling it by default is harmless. But these are unusual
circumstances. Normally, the initial value must be ‘nil’.
#+end_quote
-- 
Kevin Vigouroux
Best regards



^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2022-02-06  8:58 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-02-04 11:10 using keyword arguments in define-minor-mode goncholden via Users list for the GNU Emacs text editor
2022-02-04 11:38 ` Tassilo Horn
2022-02-04 11:51   ` goncholden
2022-02-04 12:52     ` Tassilo Horn
2022-02-06  8:58       ` Kevin Vigouroux via Users list for the GNU Emacs text editor

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).