* mu4e: add hooks mu4e-headers-found-hook and mu4e-update-pre-hook, document them.

mu4e/mu4e-headers.el

@@ -209,6 +209,11 @@ PREDICATE-FUNC as PARAM. This is useful for getting user-input.")
 (defvar mu4e-headers-full-search nil
   "Whether to show all results.
 If this is nil show results up to `mu4e-search-results-limit')")
+
+(defvar mu4e-headers-found-hook nil
+  "Hook run just *after* all of the headers for the last search
+query have been received and are displayed.")
+
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
 
@@ -477,6 +482,9 @@ if provided, or at the end of the buffer otherwise."
 (defconst mu4e~no-matches     (purecopy "No matching messages found"))
 (defconst mu4e~end-of-results (purecopy "End of search results"))
 
+
+
+
 (defun mu4e~headers-found-handler (count)
   "Create a one line description of the number of headers found
 after the end of the search results."
@@ -491,9 +499,11 @@ after the end of the search results."
 	(insert (propertize str 'face 'mu4e-system-face 'intangible t))
 	(unless (= 0 count)
 	  (mu4e-message "Found %d matching message%s"
-	    count (if (= 1 count) "" "s"))
-	  ;; highlight the first message
-	  (mu4e~headers-highlight (mu4e~headers-docid-at-point (point-min)))))))))
+	    count (if (= 1 count) "" "s"))))
+      ;; highlight the first message
+      (mu4e~headers-highlight (mu4e~headers-docid-at-point (point-min)))
+      ;; run-hooks
+      (run-hooks 'mu4e-headers-found-hook)))))
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
 

mu4e/mu4e-utils.el

@@ -804,6 +804,7 @@ The messages are inserted into the process buffer."
 run-in-background is non-nil (or called with prefix-argument), run
 in the background; otherwise, pop up a window."
   (interactive "P")
+  (run-hooks 'mu4e-update-pre-hook)
   (unless mu4e-get-mail-command
     (mu4e-error "`mu4e-get-mail-command' is not defined"))
   (let* ((process-connection-type t)
@@ -827,7 +828,7 @@ in the background; otherwise, pop up a window."
 		(buf (process-buffer proc))
 		(visible-window (get-buffer-window buf 'visible)))
 	  (message nil)
-	  ;; there may be an error, give the user up to 5 seconds to check
+	  ;; there may be an erro, give the user up to 5 seconds to check
 	  (when maybe-error (sit-for 5))
 	  (mu4e-update-index)
 	  (when (and (buffer-live-p buf) visible-window)

mu4e/mu4e-vars.el

@@ -78,6 +78,11 @@ mu4e."
   :group 'mu4e
   :safe 'integerp)
 
+(defvar mu4e-update-pre-hook nil
+  "Hook run just *before* the mail-retrieval / database updating process starts.
+ You can use this hook for example to `mu4e-get-mail-command' with
+ some specific setting.")
+
 (defvar mu4e-hide-index-messages nil
   "If non-nil, mu4e does not show the \"Indexing...\" messages, or
   any messages relating to updated contacts.")
@@ -128,7 +133,7 @@ personal message. This is used when indexing messages."
   `format-time-string'."
   :type 'string
   :group 'mu4e)
-  
+
 (defvar mu4e-debug nil
   "When set to non-nil, log debug information to the *mu4e-log* buffer.")
 

mu4e/mu4e.texi

@@ -477,6 +477,11 @@ A simple setup could look something like:
    mu4e-update-interval 300)             ;; update every 5 minutes
 @end lisp
 
+A hook @code{mu4e-update-pre-hook} is available which is run right before
+starting the process, which you can for example to influence
+@code{mu4e-get-mail-command} based on the the current situation (location,
+time of day, ...).
+
 It is possible to get notifications when the indexing process does any updates
 - for example when receiving new mail. See @code{mu4e-index-updated-hook} and
 some tips on its usage in the @ref{FAQ}.
@@ -582,7 +587,7 @@ correctly, and then shows you the @t{mu4e} main view. Its major mode is
 
 
 @menu
-* Overview: MV Overview. 
+* Overview: MV Overview.
 * Basic actions::
 * Bookmarks: MV Bookmarks.
 * Miscellaneous::
@@ -764,6 +769,9 @@ Jamie Zawinski's mail threading algorithm,
 found during the indexing process, and if there is no current
 user-interaction. If you do not want such automatic updates, set
 @code{mu4e-headers-auto-update} to @code{nil}.
+@item There is a hook-function @code{mu4e-headers-found-hook} available which
+is invoked just after @t{mu4e} has completed showing the messages in the
+headers-view.
 @end itemize
 
 @node Keybindings
@@ -917,7 +925,7 @@ include a new header @t{Recip#} with the number of recipients.
 
 Note that this function can be used in both the headers-view and the
 message-view; if you need something specific for one of these, you can check
-for the mode in your function. 
+for the mode in your function.
 
 @node HV Actions
 @section Actions
@@ -1281,12 +1289,12 @@ For more information, see the @command{mu-verify} manual page.
 
 Sometimes the normal headers that @t{mu4e} offers (Date, From, To, Subject
 etc.) may not be enough. For these cases, @t{mu4e} offers @emph{custom
-headers} in both the headers-view and the message-view. 
+headers} in both the headers-view and the message-view.
 
 See @ref{HV Custom headers} for an example of this; the difference for the
 message-view is that you should add your custom header to
 @code{mu4e-view-fields} rather than @code{mu4e-headers-fields}.
- 
+
 @node MSGV Actions
 @section Actions
 
@@ -2268,7 +2276,7 @@ guidelines for doing so.
 
 @menu
 * Extension points::
-* Available functions:: 
+* Available functions::
 * Message functions::
 * Utility functions::
 @end menu
@@ -2911,8 +2919,8 @@ In this chapter we list a number of actual and anticipated questions and their
 answers.
 
 @menu
-* General:: 
-* Reading messages:: 
+* General::
+* Reading messages::
 * Writing messages::
 * Known issues::
 @end menu