Re: using keyword arguments in define-minor-mode

[Tassilo Horn]

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