unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
From: Alan Mackenzie <acm@muc.de>
To: Eli Zaretskii <eliz@gnu.org>
Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
Subject: Margins example in the Elisp manual.  [Was: [Emacs-diffs] master 29d1c72: Introduce new value t for compilation-context-lines to eliminate scrolling]
Date: Sun, 8 Sep 2019 09:41:56 +0000	[thread overview]
Message-ID: <20190908094155.GA4443@ACM> (raw)
In-Reply-To: <83woet8uh5.fsf@gnu.org>

Hello, Eli.

On Sat, Aug 31, 2019 at 14:06:30 +0300, Eli Zaretskii wrote:
> > Date: Sat, 31 Aug 2019 10:53:16 +0000
> > From: Alan Mackenzie <acm@muc.de>
> > Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org

[ .... ]

> > As above, I think a complete example in the "Display Margins" page would
> > be helpful.  I'll get around to formulating this some time (soon?).

> Thanks.

OK, here's a first draught of the example, based on the emacs-26 branch.
As always, comments and criticism are welcome.



diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 55a0a2f924..f2379cc8c7 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -4956,6 +4956,64 @@ Display Margins
 selected window is used.
 @end defun
 
+@menu
+* Margin Example::              A working example of the use of margins.
+@end menu
+
+@node Margin Example
+@subsubsection Margin Example
+@cindex margin example
+@findex foo-mode
+
+The following incomplete, but working, minor mode illustrates one way
+of using margins in your code (@pxref{Display Margins}).  To see it
+working, load the code into your Emacs, then toggle the minor mode on
+with @kbd{M-x foo-mode @key{RET}} in some window.  You will see a two
+character left margin containing the string ''=>'' on the line
+containing point.
+
+@example
+(defvar-local foo-arrow-overlay nil
+  "Overlay with the before-string property of `foo-dummy-string'.
+
+When non-nil, this overlay causes redisplay to display `foo-margin-string'
+at the overlay's start position.")
+
+(defconst foo-margin-string
+  (propertize "=>" 'face 'default)
+  "The string which will appear in the margin in foo mode.")
+
+(defconst foo-dummy-string
+  (propertize ">" 'display
+              `((margin left-margin) ,foo-margin-string))
+  "A string which is only a placeholder for foo-margin-string.
+Actual value is never used, only the text property.")
+
+(defun foo-post-command-hook ()
+  (when foo-arrow-overlay
+    (move-overlay foo-arrow-overlay
+                  (line-beginning-position) (line-beginning-position))))
+(add-hook 'post-command-hook #'foo-post-command-hook)
+
+(defvar-local foo-mode nil)
+(defun foo-mode (&optional arg)
+  "Minor mode to indicate current line by a \"=>\" in the margin."
+  (interactive "P")
+  (setq foo-mode
+        (cond
+         ((null arg) (not foo-mode))
+         ((> arg 0) t)
+         (t nil)))
+  (if foo-mode
+      (progn
+        (setq foo-arrow-overlay (make-overlay (point) (point)))
+        (overlay-put foo-arrow-overlay 'before-string foo-dummy-string)
+        (set-window-margins (selected-window) (+ (or (car (window-margins)) 0) 2)))
+    (delete-overlay foo-arrow-overlay)
+    (setq foo-arrow-overlay nil)
+    (set-window-margins (selected-window) (- (car (window-margins)) 2))))
+@end example
+
 @node Images
 @section Images
 @cindex images in buffers


-- 
Alan Mackenzie (Nuremberg, Germany).



  parent reply	other threads:[~2019-09-08  9:41 UTC|newest]

Thread overview: 23+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <20190825102322.19558.22771@vcs0.savannah.gnu.org>
     [not found] ` <20190825102323.5080620CD5@vcs0.savannah.gnu.org>
2019-08-25 18:39   ` [Emacs-diffs] master 29d1c72: Introduce new value t for compilation-context-lines to eliminate scrolling Stefan Monnier
2019-08-25 19:06     ` Alan Mackenzie
2019-08-25 19:37       ` Eli Zaretskii
2019-08-26 16:26         ` Alan Mackenzie
2019-08-26 16:29           ` Eli Zaretskii
2019-08-27 20:05             ` Alan Mackenzie
2019-08-29 18:22               ` Eli Zaretskii
2019-08-31 10:53                 ` Alan Mackenzie
2019-08-31 11:06                   ` Eli Zaretskii
2019-09-02 19:34                     ` Alan Mackenzie
2019-09-03  2:25                       ` Eli Zaretskii
2019-09-08  9:41                     ` Alan Mackenzie [this message]
2019-09-08 17:06                       ` Margins example in the Elisp manual. [Was: [Emacs-diffs] master 29d1c72: Introduce new value t for compilation-context-lines to eliminate scrolling] Eli Zaretskii
2019-08-27 19:36         ` [Emacs-diffs] master 29d1c72: Introduce new value t for compilation-context-lines to eliminate scrolling Alan Mackenzie
2019-08-27 19:49           ` Eli Zaretskii
2019-08-27 20:07             ` Stefan Monnier
2019-08-27 19:59           ` Stefan Monnier
2019-08-31 11:31             ` Alan Mackenzie
2019-08-31 12:07               ` martin rudalics
2019-08-31 12:45                 ` Alan Mackenzie
2019-08-25 20:54       ` Stefan Monnier
2019-08-27 19:46         ` Alan Mackenzie
2019-08-27 20:05           ` Stefan Monnier

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.gnu.org/software/emacs/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190908094155.GA4443@ACM \
    --to=acm@muc.de \
    --cc=eliz@gnu.org \
    --cc=emacs-devel@gnu.org \
    --cc=monnier@iro.umontreal.ca \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

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).