From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel 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 Message-ID: <20190908094155.GA4443@ACM> References: <20190825102323.5080620CD5@vcs0.savannah.gnu.org> <20190825190637.GE4724@ACM> <838srhghoc.fsf@gnu.org> <20190826162651.GA4137@ACM> <83ef17gaar.fsf@gnu.org> <20190827200520.GC20676@ACM> <8336hjbzn5.fsf@gnu.org> <20190831105316.GA4822@ACM> <83woet8uh5.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="124939"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Mutt/1.10.1 (2018-07-13) Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Sep 08 11:42:50 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1i6tia-000WJu-AK for ged-emacs-devel@m.gmane.org; Sun, 08 Sep 2019 11:42:48 +0200 Original-Received: from localhost ([::1]:47680 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i6tiY-0005JF-Ov for ged-emacs-devel@m.gmane.org; Sun, 08 Sep 2019 05:42:46 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:43816) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i6thp-0005J8-Nf for emacs-devel@gnu.org; Sun, 08 Sep 2019 05:42:02 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1i6tho-0000OH-Ag for emacs-devel@gnu.org; Sun, 08 Sep 2019 05:42:01 -0400 Original-Received: from colin.muc.de ([193.149.48.1]:54500 helo=mail.muc.de) by eggs.gnu.org with smtp (Exim 4.71) (envelope-from ) id 1i6tho-0000MK-1S for emacs-devel@gnu.org; Sun, 08 Sep 2019 05:42:00 -0400 Original-Received: (qmail 27751 invoked by uid 3782); 8 Sep 2019 09:41:57 -0000 Original-Received: from acm.muc.de (p2E5D5E86.dip0.t-ipconnect.de [46.93.94.134]) by colin.muc.de (tmda-ofmipd) with ESMTP; Sun, 08 Sep 2019 11:41:56 +0200 Original-Received: (qmail 4712 invoked by uid 1000); 8 Sep 2019 09:41:56 -0000 Content-Disposition: inline In-Reply-To: <83woet8uh5.fsf@gnu.org> X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de X-detected-operating-system: by eggs.gnu.org: FreeBSD 9.x [fuzzy] X-Received-From: 193.149.48.1 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:239937 Archived-At: 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 > > 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).