org-configs/org-hooks.org

   1 #+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
   2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   4 #+TITLE:      List of org-mode hooks - examples of use
   5 #+AUTHOR:     Worg people
   6 #+EMAIL:      bzg AT altern DOT org
   7 #+LANGUAGE:   en
   8 #+PRIORITIES: A C B
   9 #+CATEGORY:   worg
  10
  11 # This file is the default header for new Org files in Worg.  Feel free
  12 # to tailor it to your needs.
  13
  14 [[file:index.org][{Back to Worg's index}]]
  15
  16 This is the list of Org-mode hooks and function variables, with their
  17 documentation strings:
  18
  19 * Hooks and Function variables
  20
  21 ** =org-mode-hook=
  22 Defined in: /org.el/
  23 #+begin_example
  24     Mode hook for Org-mode, run after the mode was turned on.
  25 #+end_example
  26 ** =org-load-hook=
  27 Defined in: /org.el/
  28 #+begin_example
  29     Hook that is run after org.el has been loaded.
  30 #+end_example
  31 ** =org-pre-cycle-hook=
  32 Defined in: /org.el/
  33 #+begin_example
  34     Hook that is run before visibility cycling is happening.
  35     The function(s) in this hook must accept a single argument which indicates
  36     the new state that will be set right after running this hook.  The
  37     argument is a symbol.  Before a global state change, it can have the values
  38     `overview', `content', or `all'.  Before a local state change, it can have
  39     the values `folded', `children', or `subtree'.
  40 #+end_example
  41 ** =org-cycle-hook=
  42 Defined in: /org.el/
  43 #+begin_example
  44     Hook that is run after `org-cycle' has changed the buffer visibility.
  45     The function(s) in this hook must accept a single argument which indicates
  46     the new state that was set by the most recent `org-cycle' command.  The
  47     argument is a symbol.  After a global state change, it can have the values
  48     `overview', `content', or `all'.  After a local state change, it can have
  49     the values `folded', `children', or `subtree'.
  50 #+end_example
  51 ** =org-insert-heading-hook=
  52 Defined in: /org.el/
  53 #+begin_example
  54     Hook being run after inserting a new heading.
  55 #+end_example
  56 ** =org-occur-hook=
  57 Defined in: /org.el/
  58 #+begin_example
  59     Hook that is run after `org-occur' has constructed a sparse tree.
  60     This can be used to recenter the window to show as much of the structure
  61     as possible.
  62 #+end_example
  63 ** =org-make-link-description-function=
  64 Defined in: /org.el/
  65 #+begin_example
  66     Function to use to generate link descriptions from links. If
  67     nil the link location will be used. This function must take two
  68     parameters; the first is the link and the second the description
  69     org-insert-link has generated, and should return the description
  70     to use.
  71 #+end_example
  72 ** =org-link-translation-function=
  73 Defined in: /org.el/
  74 #+begin_example
  75     Function to translate links with different syntax to Org syntax.
  76     This can be used to translate links created for example by the Planner
  77     or emacs-wiki packages to Org syntax.
  78     The function must accept two parameters, a TYPE containing the link
  79     protocol name like \"rmail\" or \"gnus\" as a string, and the linked path,
  80     which is everything after the link protocol.  It should return a cons
  81     with possibly modified values of type and path.
  82     Org contains a function for this, so if you set this variable to
  83     `org-translate-link-from-planner', you should be able follow many
  84     links created by planner.
  85 #+end_example
  86 ** =org-follow-link-hook=
  87 Defined in: /org.el/
  88 #+begin_example
  89     Hook that is run after a link has been followed.
  90 #+end_example
  91 ** =org-confirm-shell-link-function=
  92 Defined in: /org.el/
  93 #+begin_example
  94     Non-nil means ask for confirmation before executing shell links.
  95     Shell links can be dangerous: just think about a link
  96
  97          [[shell:rm -rf ~/*][Google Search]]
  98
  99     This link would show up in your Org-mode document as \"Google Search\",
 100     but really it would remove your entire home directory.
 101     Therefore we advise against setting this variable to nil.
 102     Just change it to `y-or-n-p' if you want to confirm with a
 103     single keystroke rather than having to type \"yes\".
 104 #+end_example
 105 ** =org-confirm-elisp-link-function=
 106 Defined in: /org.el/
 107 #+begin_example
 108     Non-nil means ask for confirmation before executing Emacs Lisp links.
 109     Elisp links can be dangerous: just think about a link
 110
 111          [[elisp:(shell-command \"rm -rf ~/*\")][Google Search]]
 112
 113     This link would show up in your Org-mode document as \"Google Search\",
 114     but really it would remove your entire home directory.
 115     Therefore we advise against setting this variable to nil.
 116     Just change it to `y-or-n-p' if you want to confirm with a
 117     single keystroke rather than having to type \"yes\".
 118 #+end_example
 119 ** =org-refile-target-verify-function=
 120 Defined in: /org.el/
 121 #+begin_example
 122     Function to verify if the headline at point should be a refile target.
 123     The function will be called without arguments, with point at the
 124     beginning of the headline.  It should return t and leave point
 125     where it is if the headline is a valid target for refiling.
 126
 127     If the target should not be selected, the function must return nil.
 128     In addition to this, it may move point to a place from where the search
 129     should be continued.  For example, the function may decide that the entire
 130     subtree of the current entry should be excluded and move point to the end
 131     of the subtree.
 132 #+end_example
 133 ** =org-after-todo-state-change-hook=
 134 Defined in: /org.el/
 135 #+begin_example
 136     Hook which is run after the state of a TODO item was changed.
 137     The new state (a string with a TODO keyword, or nil) is available in the
 138     Lisp variable `state'.
 139 #+end_example
 140 ** =org-blocker-hook=
 141 Defined in: /org.el/
 142 #+begin_example
 143     Hook for functions that are allowed to block a state change.
 144
 145     Each function gets as its single argument a property list, see
 146     `org-trigger-hook' for more information about this list.
 147
 148     If any of the functions in this hook returns nil, the state change
 149     is blocked.
 150 #+end_example
 151 ** =org-trigger-hook=
 152 Defined in: /org.el/
 153 #+begin_example
 154     Hook for functions that are triggered by a state change.
 155
 156     Each function gets as its single argument a property list with at least
 157     the following elements:
 158
 159      (:type type-of-change :position pos-at-entry-start
 160       :from old-state :to new-state)
 161
 162     Depending on the type, more properties may be present.
 163
 164     This mechanism is currently implemented for:
 165
 166     TODO state changes
 167     ------------------
 168     :type  todo-state-change
 169     :from  previous state (keyword as a string), or nil, or a symbol
 170            'todo' or 'done', to indicate the general type of state.
 171     :to    new state, like in :from
 172 #+end_example
 173 ** =org-read-date-minibuffer-setup-hook=
 174 Defined in: /org.el/
 175 #+begin_example
 176     Hook to be used to set up keys for the date/time interface.
 177     Add key definitions to `minibuffer-local-map', which will be a temporary
 178     copy.
 179 #+end_example
 180 ** =org-tags-sort-function=
 181 Defined in: /org.el/
 182 #+begin_example
 183     When set, tags are sorted using this function as a comparator
 184 #+end_example
 185 ** =org-after-tags-change-hook=
 186 Defined in: /org.el/
 187 #+begin_example
 188     Hook that is run after the tags in a line have changed.
 189 #+end_example
 190 ** =org-columns-modify-value-for-display-function=
 191 Defined in: /org.el/
 192 #+begin_example
 193     Function that modifies values for display in column view.
 194     For example, it can be used to cut out a certain part from a time stamp.
 195     The function must take 2 arguments:
 196
 197     column-title    The title of the column (*not* the property name)
 198     value           The value that should be modified.
 199
 200     The function should return the value that should be displayed,
 201     or nil if the normal value should be used.
 202 #+end_example
 203 ** =org-finish-function=
 204 Defined in: /org.el/
 205 #+begin_example
 206     Function to be called when `C-c C-c' is used.
 207     This is for getting out of special buffers like remember.
 208 #+end_example
 209 ** =org-font-lock-hook=
 210 Defined in: /org.el/
 211 #+begin_example
 212     Functions to be called for special font lock stuff.
 213 #+end_example
 214 ** =org-after-demote-entry-hook=
 215 Defined in: /org.el/
 216 #+begin_example
 217     Hook run after an entry has been demoted.
 218     The cursor will be at the beginning of the entry.
 219     When a subtree is being demoted, the hook will be called for each node.
 220 #+end_example
 221 ** =org-after-promote-entry-hook=
 222 Defined in: /org.el/
 223 #+begin_example
 224     Hook run after an entry has been promoted.
 225     The cursor will be at the beginning of the entry.
 226     When a subtree is being promoted, the hook will be called for each node.
 227 #+end_example
 228 ** =org-after-sorting-entries-or-items-hook=
 229 Defined in: /org.el/
 230 #+begin_example
 231     Hook that is run after a bunch of entries or items have been sorted.
 232     When children are sorted, the cursor is in the parent line when this
 233     hook gets called.  When a region or a plain list is sorted, the cursor
 234     will be in the first entry of the sorted region/list.
 235 #+end_example
 236 ** =org-store-link-functions=
 237 Defined in: /org.el/
 238 #+begin_example
 239     List of functions that are called to create and store a link.
 240     Each function will be called in turn until one returns a non-nil
 241     value.  Each function should check if it is responsible for creating
 242     this link (for example by looking at the major mode).
 243     If not, it must exit and return nil.
 244     If yes, it should return a non-nil value after a calling
 245     `org-store-link-props' with a list of properties and values.
 246     Special properties are:
 247
 248     :type         The link prefix. like \"http\".  This must be given.
 249     :link         The link, like \"http://www.astro.uva.nl/~dominik\".
 250                   This is obligatory as well.
 251     :description  Optional default description for the second pair
 252                   of brackets in an Org-mode link.  The user can still change
 253                   this when inserting this link into an Org-mode buffer.
 254
 255     In addition to these, any additional properties can be specified
 256     and then used in remember templates.
 257 #+end_example
 258 ** =org-open-link-functions=
 259 Defined in: /org.el/
 260 #+begin_example
 261     Hook for functions finding a plain text link.
 262     These functions must take a single argument, the link content.
 263     They will be called for links that look like [[link text][description]]
 264     when LINK TEXT does not have a protocol like \"http:\" and does not look
 265     like a filename (e.g. \"./blue.png\").
 266
 267     These functions will be called *before* Org attempts to resolve the
 268     link by doing text searches in the current buffer - so if you want a
 269     link \"[[target]]\" to still find \"<<target>>\", your function should
 270     handle this as a special case.
 271
 272     When the function does handle the link, it must return a non-nil value.
 273     If it decides that it is not responsible for this link, it must return
 274     nil to indicate that that Org-mode can continue with other options
 275     like exact and fuzzy text search.
 276 #+end_example
 277 ** =org-create-file-search-functions=
 278 Defined in: /org.el/
 279 #+begin_example
 280     List of functions to construct the right search string for a file link.
 281     These functions are called in turn with point at the location to
 282     which the link should point.
 283
 284     A function in the hook should first test if it would like to
 285     handle this file type, for example by checking the major-mode or
 286     the file extension.  If it decides not to handle this file, it
 287     should just return nil to give other functions a chance.  If it
 288     does handle the file, it must return the search string to be used
 289     when following the link.  The search string will be part of the
 290     file link, given after a double colon, and `org-open-at-point'
 291     will automatically search for it.  If special measures must be
 292     taken to make the search successful, another function should be
 293     added to the companion hook `org-execute-file-search-functions',
 294     which see.
 295
 296     A function in this hook may also use `setq' to set the variable
 297     `description' to provide a suggestion for the descriptive text to
 298     be used for this link when it gets inserted into an Org-mode
 299     buffer with \\[org-insert-link].
 300 #+end_example
 301 ** =org-execute-file-search-functions=
 302 Defined in: /org.el/
 303 #+begin_example
 304     List of functions to execute a file search triggered by a link.
 305
 306     Functions added to this hook must accept a single argument, the
 307     search string that was part of the file link, the part after the
 308     double colon.  The function must first check if it would like to
 309     handle this search, for example by checking the major-mode or the
 310     file extension.  If it decides not to handle this search, it
 311     should just return nil to give other functions a chance.  If it
 312     does handle the search, it must return a non-nil value to keep
 313     other functions from trying.
 314
 315     Each function can access the current prefix argument through the
 316     variable `current-prefix-argument'.  Note that a single prefix is
 317     used to force opening a link in Emacs, so it may be good to only
 318     use a numeric or double prefix to guide the search function.
 319
 320     In case this is needed, a function in this hook can also restore
 321     the window configuration before `org-open-at-point' was called using:
 322
 323         (set-window-configuration org-window-config-before-follow-link)
 324 #+end_example
 325 ** =org-after-refile-insert-hook=
 326 Defined in: /org.el/
 327 #+begin_example
 328     Hook run after `org-refile' has inserted its stuff at the new location.
 329     Note that this is still *before* the stuff will be removed from
 330     the *old* location.
 331 #+end_example
 332 ** =org-todo-setup-filter-hook=
 333 Defined in: /org.el/
 334 #+begin_example
 335     Hook for functions that pre-filter todo specs.
 336
 337     Each function takes a todo spec and returns either `nil' or the spec
 338     transformed into canonical form." )
 339
 340     (defvar org-todo-get-default-hook nil
 341       "Hook for functions that get a default item for todo.
 342
 343     Each function takes arguments (NEW-MARK OLD-MARK) and returns either
 344     `nil' or a string to be used for the todo mark." )
 345
 346     (defvar org-agenda-headline-snapshot-before-repeat)
 347
 348     (defun org-todo (&optional arg)
 349       "Change the TODO state of an item.
 350     The state of an item is given by a keyword at the start of the heading,
 351     like
 352          *** TODO Write paper
 353          *** DONE Call mom
 354
 355     The different keywords are specified in the variable `org-todo-keywords'.
 356     By default the available states are \"TODO\" and \"DONE\".
 357     So for this example: when the item starts with TODO, it is changed to DONE.
 358     When it starts with DONE, the DONE is removed.  And when neither TODO nor
 359     DONE are present, add TODO at the beginning of the heading.
 360
 361     With C-u prefix arg, use completion to determine the new state.
 362     With numeric prefix arg, switch to that state.
 363     With a double C-u prefix, switch to the next set of TODO keywords (nextset).
 364     With a triple C-u prefix, circumvent any state blocking.
 365
 366     For calling through lisp, arg is also interpreted in the following way:
 367     'none             -> empty state
 368     \"\"(empty string)  -> switch to empty state
 369     'done             -> switch to DONE
 370     'nextset          -> switch to the next set of keywords
 371     'previousset      -> switch to the previous set of keywords
 372     \"WAITING\"         -> switch to the specified keyword, but only if it
 373                          really is a member of `org-todo-keywords'.
 374 #+end_example
 375 ** =org-after-todo-statistics-hook=
 376 Defined in: /org.el/
 377 #+begin_example
 378     Hook that is called after a TODO statistics cookie has been updated.
 379     Each function is called with two arguments: the number of not-done entries
 380     and the number of done entries.
 381
 382     For example, the following function, when added to this hook, will switch
 383     an entry to DONE when all children are done, and back to TODO when new
 384     entries are set to a TODO status.  Note that this hook is only called
 385     when there is a statistics cookie in the headline!
 386
 387      (defun org-summary-todo (n-done n-not-done)
 388        \"Switch entry to DONE when all subentries are done, to TODO otherwise.\"
 389        (let (org-log-done org-log-states)   ; turn off logging
 390          (org-todo (if (= n-not-done 0) \"DONE\" \"TODO\"))))
 391 #+end_example
 392 ** =org-todo-statistics-hook=
 393 Defined in: /org.el/
 394 #+begin_example
 395     Hook that is run whenever Org thinks TODO statistics should be updated.
 396     This hook runs even if there is no statistics cookie present, in which case
 397     `org-after-todo-statistics-hook' would not run.
 398 #+end_example
 399 ** =org-reveal-start-hook=
 400 Defined in: /org.el/
 401 #+begin_example
 402     Hook run before revealing a location.
 403 #+end_example
 404 ** =org-property-changed-functions=
 405 Defined in: /org.el/
 406 #+begin_example
 407     Hook called when the value of a property has changed.
 408     Each hook function should accept two arguments, the name of the property
 409     and the new value.
 410 #+end_example
 411 ** =org-property-allowed-value-functions=
 412 Defined in: /org.el/
 413 #+begin_example
 414     Hook for functions supplying allowed values for a specific property.
 415     The functions must take a single argument, the name of the property, and
 416     return a flat list of allowed values.  If \":ETC\" is one of
 417     the values, this means that these values are intended as defaults for
 418     completion, but that other values should be allowed too.
 419     The functions must return nil if they are not responsible for this
 420     property.
 421 #+end_example
 422 ** =org-ctrl-c-ctrl-c-hook=
 423 Defined in: /org.el/
 424 #+begin_example
 425     Hook for functions attaching themselves to  `C-c C-c'.
 426     This can be used to add additional functionality to the C-c C-c key which
 427     executes context-dependent commands.
 428     Each function will be called with no arguments.  The function must check
 429     if the context is appropriate for it to act.  If yes, it should do its
 430     thing and then return a non-nil value.  If the context is wrong,
 431     just do nothing and return nil.
 432 #+end_example
 433 ** =org-tab-first-hook=
 434 Defined in: /org.el/
 435 #+begin_example
 436     Hook for functions to attach themselves to TAB.
 437     See `org-ctrl-c-ctrl-c-hook' for more information.
 438     This hook runs as the first action when TAB is pressed, even before
 439     `org-cycle' messes around with the `outline-regexp' to cater for
 440     inline tasks and plain list item folding.
 441     If any function in this hook returns t, not other actions like table
 442     field motion visibility cycling will be done.
 443 #+end_example
 444 ** =org-tab-after-check-for-table-hook=
 445 Defined in: /org.el/
 446 #+begin_example
 447     Hook for functions to attach themselves to TAB.
 448     See `org-ctrl-c-ctrl-c-hook' for more information.
 449     This hook runs after it has been established that the cursor is not in a
 450     table, but before checking if the cursor is in a headline or if global cycling
 451     should be done.
 452     If any function in this hook returns t, not other actions like visibility
 453     cycling will be done.
 454 #+end_example
 455 ** =org-tab-after-check-for-cycling-hook=
 456 Defined in: /org.el/
 457 #+begin_example
 458     Hook for functions to attach themselves to TAB.
 459     See `org-ctrl-c-ctrl-c-hook' for more information.
 460     This hook runs after it has been established that not table field motion and
 461     not visibility should be done because of current context.  This is probably
 462     the place where a package like yasnippets can hook in.
 463 #+end_example
 464 ** =org-tab-before-tab-emulation-hook=
 465 Defined in: /org.el/
 466 #+begin_example
 467     Hook for functions to attach themselves to TAB.
 468     See `org-ctrl-c-ctrl-c-hook' for more information.
 469     This hook runs after every other options for TAB have been exhausted, but
 470     before indentation and \t insertion takes place.
 471 #+end_example
 472 ** =org-metaleft-hook=
 473 Defined in: /org.el/
 474 #+begin_example
 475     Hook for functions attaching themselves to `M-left'.
 476     See `org-ctrl-c-ctrl-c-hook' for more information.
 477 #+end_example
 478 ** =org-metaright-hook=
 479 Defined in: /org.el/
 480 #+begin_example
 481     Hook for functions attaching themselves to `M-right'.
 482     See `org-ctrl-c-ctrl-c-hook' for more information.
 483 #+end_example
 484 ** =org-metaup-hook=
 485 Defined in: /org.el/
 486 #+begin_example
 487     Hook for functions attaching themselves to `M-up'.
 488     See `org-ctrl-c-ctrl-c-hook' for more information.
 489 #+end_example
 490 ** =org-metadown-hook=
 491 Defined in: /org.el/
 492 #+begin_example
 493     Hook for functions attaching themselves to `M-down'.
 494     See `org-ctrl-c-ctrl-c-hook' for more information.
 495 #+end_example
 496 ** =org-shiftmetaleft-hook=
 497 Defined in: /org.el/
 498 #+begin_example
 499     Hook for functions attaching themselves to `M-S-left'.
 500     See `org-ctrl-c-ctrl-c-hook' for more information.
 501 #+end_example
 502 ** =org-shiftmetaright-hook=
 503 Defined in: /org.el/
 504 #+begin_example
 505     Hook for functions attaching themselves to `M-S-right'.
 506     See `org-ctrl-c-ctrl-c-hook' for more information.
 507 #+end_example
 508 ** =org-shiftmetaup-hook=
 509 Defined in: /org.el/
 510 #+begin_example
 511     Hook for functions attaching themselves to `M-S-up'.
 512     See `org-ctrl-c-ctrl-c-hook' for more information.
 513 #+end_example
 514 ** =org-shiftmetadown-hook=
 515 Defined in: /org.el/
 516 #+begin_example
 517     Hook for functions attaching themselves to `M-S-down'.
 518     See `org-ctrl-c-ctrl-c-hook' for more information.
 519 #+end_example
 520 ** =org-metareturn-hook=
 521 Defined in: /org.el/
 522 #+begin_example
 523     Hook for functions attaching themselves to `M-RET'.
 524     See `org-ctrl-c-ctrl-c-hook' for more information.
 525 #+end_example
 526 ** =org-shiftup-hook=
 527 Defined in: /org.el/
 528 #+begin_example
 529     Hook for functions attaching themselves to `S-up'.
 530     See `org-ctrl-c-ctrl-c-hook' for more information.
 531 #+end_example
 532 ** =org-shiftup-final-hook=
 533 Defined in: /org.el/
 534 #+begin_example
 535     Hook for functions attaching themselves to `S-up'.
 536     This one runs after all other options except shift-select have been excluded.
 537     See `org-ctrl-c-ctrl-c-hook' for more information.
 538 #+end_example
 539 ** =org-shiftdown-hook=
 540 Defined in: /org.el/
 541 #+begin_example
 542     Hook for functions attaching themselves to `S-down'.
 543     See `org-ctrl-c-ctrl-c-hook' for more information.
 544 #+end_example
 545 ** =org-shiftdown-final-hook=
 546 Defined in: /org.el/
 547 #+begin_example
 548     Hook for functions attaching themselves to `S-down'.
 549     This one runs after all other options except shift-select have been excluded.
 550     See `org-ctrl-c-ctrl-c-hook' for more information.
 551 #+end_example
 552 ** =org-shiftleft-hook=
 553 Defined in: /org.el/
 554 #+begin_example
 555     Hook for functions attaching themselves to `S-left'.
 556     See `org-ctrl-c-ctrl-c-hook' for more information.
 557 #+end_example
 558 ** =org-shiftleft-final-hook=
 559 Defined in: /org.el/
 560 #+begin_example
 561     Hook for functions attaching themselves to `S-left'.
 562     This one runs after all other options except shift-select have been excluded.
 563     See `org-ctrl-c-ctrl-c-hook' for more information.
 564 #+end_example
 565 ** =org-shiftright-hook=
 566 Defined in: /org.el/
 567 #+begin_example
 568     Hook for functions attaching themselves to `S-right'.
 569     See `org-ctrl-c-ctrl-c-hook' for more information.
 570 #+end_example
 571 ** =org-shiftright-final-hook=
 572 Defined in: /org.el/
 573 #+begin_example
 574     Hook for functions attaching themselves to `S-right'.
 575     This one runs after all other options except shift-select have been excluded.
 576     See `org-ctrl-c-ctrl-c-hook' for more information.
 577 #+end_example
 578 ** =org-agenda-before-write-hook=
 579 Defined in: /org-agenda.el/
 580 #+begin_example
 581     Hook run in temporary buffer before writing it to an export file.
 582     A useful function is `org-agenda-add-entry-text'.
 583 #+end_example
 584 ** =org-finalize-agenda-hook=
 585 Defined in: /org-agenda.el/
 586 #+begin_example
 587     Hook run just before displaying an agenda buffer.
 588 #+end_example
 589 ** =org-agenda-entry-text-cleanup-hook=
 590 Defined in: /org-agenda.el/
 591 #+begin_example
 592     Hook that is run after basic cleanup of entry text to be shown in agenda.
 593     This cleanup is done in a temporary buffer, so the function may inspect and
 594     change the entire buffer.
 595     Some default stuff like drawers and scheduling/deadline dates will already
 596     have been removed when this is called, as will any matches for regular
 597     expressions listed in `org-agenda-entry-text-exclude-regexps'.
 598 #+end_example
 599 ** =org-agenda-auto-exclude-function=
 600 Defined in: /org-agenda.el/
 601 #+begin_example
 602     A function called with a tag to decide if it is filtered on '/ RET'.
 603     The sole argument to the function, which is called once for each
 604     possible tag, is a string giving the name of the tag.  The
 605     function should return either nil if the tag should be included
 606     as normal, or \"-<TAG>\" to exclude the tag.
 607     Note that for the purpose of tag filtering, only the lower-case version of
 608     all tags will be considered, so that this function will only ever see
 609     the lower-case version of all tags.
 610 #+end_example
 611 ** =org-agenda-mode-hook=
 612 Defined in: /org-agenda.el/
 613 #+begin_example
 614     Hook for org-agenda-mode, run after the mode is turned on.
 615 #+end_example
 616 ** =org-agenda-skip-function=
 617 Defined in: /org-agenda.el/
 618 #+begin_example
 619     Function to be called at each match during agenda construction.
 620     If this function returns nil, the current match should not be skipped.
 621     Otherwise, the function must return a position from where the search
 622     should be continued.
 623     This may also be a Lisp form, it will be evaluated.
 624     Never set this variable using `setq' or so, because then it will apply
 625     to all future agenda commands.  Instead, bind it with `let' to scope
 626     it dynamically into the agenda-constructing command.  A good way to set
 627     it is through options in org-agenda-custom-commands.
 628 #+end_example
 629 ** =org-agenda-cleanup-fancy-diary-hook=
 630 Defined in: /org-agenda.el/
 631 #+begin_example
 632     Hook run when the fancy diary buffer is cleaned up.
 633 #+end_example
 634 ** =org-agenda-after-show-hook=
 635 Defined in: /org-agenda.el/
 636 #+begin_example
 637     Normal hook run after an item has been shown from the agenda.
 638     Point is in the buffer where the item originated.
 639 #+end_example
 640 ** =org-export-ascii-final-hook=
 641 Defined in: /org-ascii.el/
 642 #+begin_example
 643     Hook run at the end of ASCII export, in the new buffer.
 644 #+end_example
 645 ** =org-clock-heading-function=
 646 Defined in: /org-clock.el/
 647 #+begin_example
 648     When non-nil, should be a function to create `org-clock-heading'.
 649     This is the string shown in the mode line when a clock is running.
 650     The function is called with point at the beginning of the headline.
 651 #+end_example
 652 ** =org-clock-in-prepare-hook=
 653 Defined in: /org-clock.el/
 654 #+begin_example
 655     Hook run when preparing the clock.
 656     This hook is run before anything happens to the task that
 657     you want to clock in.  For example, you can use this hook
 658     to add an effort property.
 659 #+end_example
 660 ** =org-clock-in-hook=
 661 Defined in: /org-clock.el/
 662 #+begin_example
 663     Hook run when starting the clock.
 664 #+end_example
 665 ** =org-clock-out-hook=
 666 Defined in: /org-clock.el/
 667 #+begin_example
 668     Hook run when stopping the current clock.
 669 #+end_example
 670 ** =org-clock-cancel-hook=
 671 Defined in: /org-clock.el/
 672 #+begin_example
 673     Hook run when cancelling the current clock.
 674 #+end_example
 675 ** =org-clock-goto-hook=
 676 Defined in: /org-clock.el/
 677 #+begin_example
 678     Hook run when selecting the currently clocked-in entry.
 679 #+end_example
 680 ** =org-ctags-open-link-functions=
 681 Defined in: /org-ctags.el/
 682 #+begin_example
 683     List of functions to be prepended to ORG-OPEN-LINK-FUNCTIONS when
 684     ORG-CTAGS is active.
 685 #+end_example
 686 ** =org-export-docbook-final-hook=
 687 Defined in: /org-docbook.el/
 688 #+begin_example
 689     Hook run at the end of DocBook export, in the new buffer.
 690 #+end_example
 691 ** =org-export-first-hook=
 692 Defined in: /org-exp.el/
 693 #+begin_example
 694     Hook called as the first thing in each exporter.
 695     Point will be still in the original buffer.
 696     Good for general initialization
 697 #+end_example
 698 ** =org-export-preprocess-hook=
 699 Defined in: /org-exp.el/
 700 #+begin_example
 701     Hook for preprocessing an export buffer.
 702     Pretty much the first thing when exporting is running this hook.
 703     Point will be in a temporary buffer that contains a copy of
 704     the original buffer, or of the section that is being export.
 705     All the other hooks in the org-export-preprocess... category
 706     also work in that temporary buffer, already modified by various
 707     stages of the processing.
 708 #+end_example
 709 ** =org-export-preprocess-after-include-files-hook=
 710 Defined in: /org-exp.el/
 711 #+begin_example
 712     Hook for preprocessing an export buffer.
 713     This is run after the contents of included files have been inserted.
 714 #+end_example
 715 ** =org-export-preprocess-after-tree-selection-hook=
 716 Defined in: /org-exp.el/
 717 #+begin_example
 718     Hook for preprocessing an export buffer.
 719     This is run after selection of trees to be exported has happened.
 720     This selection includes tags-based selection, as well as removal
 721     of commented and archived trees.
 722 #+end_example
 723 ** =org-export-preprocess-after-headline-targets-hook=
 724 Defined in: /org-exp.el/
 725 #+begin_example
 726     Hook for preprocessing export buffer.
 727     This is run just after the headline targets have been defined and
 728     the target-alist has been set up.
 729 #+end_example
 730 ** =org-export-preprocess-before-selecting-backend-code-hook=
 731 Defined in: /org-exp.el/
 732 #+begin_example
 733     Hook for preprocessing an export buffer.
 734     This is run just before backend-specific blocks get selected.
 735 #+end_example
 736 ** =org-export-preprocess-after-blockquote-hook=
 737 Defined in: /org-exp.el/
 738 #+begin_example
 739     Hook for preprocessing an export buffer.
 740     This is run after blockquote/quote/verse/center have been marked
 741     with cookies.
 742 #+end_example
 743 ** =org-export-preprocess-before-normalizing-links-hook=
 744 Defined in: /org-exp.el/
 745 #+begin_example
 746     Hook for preprocessing an export buffer.
 747     This hook is run before links are normalized.
 748 #+end_example
 749 ** =org-export-preprocess-before-backend-specifics-hook=
 750 Defined in: /org-exp.el/
 751 #+begin_example
 752     Hook run before backend-specific functions are called during preprocessing.
 753 #+end_example
 754 ** =org-export-preprocess-final-hook=
 755 Defined in: /org-exp.el/
 756 #+begin_example
 757     Hook for preprocessing an export buffer.
 758     This is run as the last thing in the preprocessing buffer, just before
 759     returning the buffer string to the backend.
 760 #+end_example
 761 ** =org-export-format-drawer-function=
 762 Defined in: /org-exp.el/
 763 #+begin_example
 764     Function to be called to format the contents of a drawer.
 765     The function must accept three parameters:
 766       NAME     the drawer name, like \"PROPERTIES\"
 767       CONTENT  the content of the drawer.
 768       BACKEND  one of the symbols html, docbook, latex, ascii, xoxo
 769     The function should return the text to be inserted into the buffer.
 770     If this is nil, `org-export-format-drawer' is used as a default.
 771 #+end_example
 772 ** =org-feed-after-adding-hook=
 773 Defined in: /org-feed.el/
 774 #+begin_example
 775     Hook that is run after new items have been added to a file.
 776     Depending on `org-feed-save-after-adding', the buffer will already
 777     have been saved.
 778 #+end_example
 779 ** =org-export-html-after-blockquotes-hook=
 780 Defined in: /org-html.el/
 781 #+begin_example
 782     Hook run during HTML export, after blockquote, verse, center are done.
 783 #+end_example
 784 ** =org-export-html-final-hook=
 785 Defined in: /org-html.el/
 786 #+begin_example
 787     Hook run at the end of HTML export, in the new buffer.
 788 #+end_example
 789 ** =org-icalendar-verify-function=
 790 Defined in: /org-icalendar.el/
 791 #+begin_example
 792     Function to verify entries for iCalendar export.
 793     This can be set to a function that will be called at each entry that
 794     is considered for export to iCalendar.  When the function returns nil,
 795     the entry will be skipped.  When it returns a non-nil value, the entry
 796     will be considered for export.
 797     This is used internally when an agenda buffer is exported to an ics file,
 798     to make sure that only entries currently listed in the agenda will end
 799     up in the ics file.  But for normal iCalendar export, you can use this
 800     for whatever you need.
 801 #+end_example
 802 ** =org-before-save-iCalendar-file-hook=
 803 Defined in: /org-icalendar.el/
 804 #+begin_example
 805     Hook run before  an iCalendar file has been saved.
 806     This can be used to modify the result of the export.
 807 #+end_example
 808 ** =org-after-save-iCalendar-file-hook=
 809 Defined in: /org-icalendar.el/
 810 #+begin_example
 811     Hook run after an iCalendar file has been saved.
 812     The iCalendar buffer is still current when this hook is run.
 813     A good way to use this is to tell a desktop calendar application to re-read
 814     the iCalendar file.
 815 #+end_example
 816 ** =org-export-latex-after-initial-vars-hook=
 817 Defined in: /org-latex.el/
 818 #+begin_example
 819     Hook run before LaTeX export.
 820     The exact moment is after the initial variables like org-export-latex-class
 821     have been determined from the environment.
 822 #+end_example
 823 ** =org-export-latex-after-blockquotes-hook=
 824 Defined in: /org-latex.el/
 825 #+begin_example
 826     Hook run during LaTeX export, after blockquote, verse, center are done.
 827 #+end_example
 828 ** =org-export-latex-final-hook=
 829 Defined in: /org-latex.el/
 830 #+begin_example
 831     Hook run in the finalized LaTeX buffer.
 832 #+end_example
 833 ** =org-export-latex-after-save-hook=
 834 Defined in: /org-latex.el/
 835 #+begin_example
 836     Hook run in the finalized LaTeX buffer, after it has been saved.
 837 #+end_example
 838 ** =org-export-latex-format-toc-function=
 839 Defined in: /org-latex.el/
 840 #+begin_example
 841     The function formatting returning the string to createthe table of contents.
 842     The function mus take one parameter, the depth of the table of contents.
 843 #+end_example
 844 ** =org-checkbox-statistics-hook=
 845 Defined in: /org-list.el/
 846 #+begin_example
 847     Hook that is run whenever Org thinks checkbox statistics should be updated.
 848     This hook runs even if `org-provide-checkbox-statistics' is nil, to it can
 849     be used to implement alternative ways of collecting statistics information.
 850 #+end_example
 851 ** =org-mobile-pre-push-hook=
 852 Defined in: /org-mobile.el/
 853 #+begin_example
 854     Hook run before running `org-mobile-push'.
 855     This could be used to clean up `org-mobile-directory', for example to
 856     remove files that used to be included in the agenda but no longer are.
 857     The presence of such files would not really be a problem, but after time
 858     they may accumulate.
 859 #+end_example
 860 ** =org-mobile-post-push-hook=
 861 Defined in: /org-mobile.el/
 862 #+begin_example
 863     Hook run after running `org-mobile-push'.
 864     If Emacs does not have direct write access to the WebDAV directory used
 865     by the mobile device, this hook should be used to copy all files from the
 866     local staging directory `org-mobile-directory' to the WebDAV directory,
 867     for example using `rsync' or `scp'.
 868 #+end_example
 869 ** =org-mobile-pre-pull-hook=
 870 Defined in: /org-mobile.el/
 871 #+begin_example
 872     Hook run before executing `org-mobile-pull'.
 873     If Emacs does not have direct write access to the WebDAV directory used
 874     by the mobile device, this hook should be used to copy the capture file
 875     `mobileorg.org' from the WebDAV location to the local staging
 876     directory `org-mobile-directory'.
 877 #+end_example
 878 ** =org-mobile-post-pull-hook=
 879 Defined in: /org-mobile.el/
 880 #+begin_example
 881     Hook run after running `org-mobile-pull'.
 882     If Emacs does not have direct write access to the WebDAV directory used
 883     by the mobile device, this hook should be used to copy the emptied
 884     capture file `mobileorg.org' back to the WebDAV directory, for example
 885     using `rsync' or `scp'.
 886 #+end_example
 887 ** =org-mobile-before-process-capture-hook=
 888 Defined in: /org-mobile.el/
 889 #+begin_example
 890     Hook that is run after content was moved to `org-mobile-inbox-for-pull'.
 891     The inbox file is visited by the current buffer, and the buffer is
 892     narrowed to the newly captured data.
 893 #+end_example
 894 ** =org-mouse-context-menu-function=
 895 Defined in: /org-mouse.el/
 896 #+begin_example
 897     Function to create the context menu.
 898     The value of this variable is the function invoked by
 899     `org-mouse-context-menu' as the context menu.
 900 #+end_example
 901 ** =org-publish-before-export-hook=
 902 Defined in: /org-publish.el/
 903 #+begin_example
 904     Hook run before export on the Org file.
 905     The hook may modify the file in arbitrary ways before publishing happens.
 906     The original version of the buffer will be restored after publishing.
 907 #+end_example
 908 ** =org-publish-after-export-hook=
 909 Defined in: /org-publish.el/
 910 #+begin_example
 911     Hook run after export on the exported buffer.
 912     Any changes made by this hook will be saved.
 913 #+end_example
 914 ** =org-remember-before-finalize-hook=
 915 Defined in: /org-remember.el/
 916 #+begin_example
 917     Hook that is run right before a remember process is finalized.
 918     The remember buffer is still current when this hook runs.
 919 #+end_example
 920 ** =org-remember-mode-hook=
 921 Defined in: /org-remember.el/
 922 #+begin_example
 923     Hook for the minor `org-remember-mode'.
 924 #+end_example
 925 ** =org-src-mode-hook=
 926 Defined in: /org-src.el/
 927 #+begin_example
 928     Hook  run after Org switched a source code snippet to its Emacs mode.
 929     This hook will run
 930
 931     - when editing a source code snippet with \"C-c '\".
 932     - When formatting a source code snippet for export with htmlize.
 933
 934     You may want to use this hook for example to turn off `outline-minor-mode'
 935     or similar things which you want to have when editing a source code file,
 936     but which mess up the display of a snippet in Org exported files.
 937 #+end_example
 938 ** =org-timer-start-hook=
 939 Defined in: /org-timer.el/
 940 #+begin_example
 941     Hook run after relative timer is started.
 942 #+end_example
 943 ** =org-timer-stop-hook=
 944 Defined in: /org-timer.el/
 945 #+begin_example
 946     Hook run before relative timer is stopped.
 947 #+end_example
 948 ** =org-timer-pause-hook=
 949 Defined in: /org-timer.el/
 950 #+begin_example
 951     Hook run before relative timer is paused.
 952 #+end_example
 953 ** =org-timer-set-hook=
 954 Defined in: /org-timer.el/
 955 #+begin_example
 956     Hook run after countdown timer is set.
 957 #+end_example
 958 ** =org-timer-done-hook=
 959 Defined in: /org-timer.el/
 960 #+begin_example
 961     Hook run after countdown timer reaches zero.
 962 #+end_example
 963 ** =org-timer-cancel-hook=
 964 Defined in: /org-timer.el/
 965 #+begin_example
 966     Hook run before countdown timer is canceled.
 967 #+end_example
 968 ** =org-export-xoxo-final-hook=
 969 Defined in: /org-xoxo.el/
 970 #+begin_example
 971     Hook run after XOXO export, in the new buffer.
 972 #+end_example
 973 * Examples for using hooks
 974
 975 Feel free to give example of how do you use these hooks.  Ideas for
 976 other hooks are also welcome.
 977
 978 ** org-follow-link-hook                                                 :bzg:
 979
 980 If  you want to display dormant article when following Gnus articles:
 981
 982 #+BEGIN_SRC emacs-lisp
 983 (add-hook 'org-follow-link-hook
 984           (lambda () (if (eq major-mode 'gnus-summary-mode)
 985                          (gnus-summary-insert-dormant-articles))))
 986 #+END_SRC
 987
 988 ** org-agenda-after-show-hook
 989
 990 To get a compact view during follow mode in the agenda, you could try
 991 this:
 992
 993 #+begin_src emacs-lisp
 994   (defun my-compact-follow ()
 995     "Make the view compact, then show the necessary minimum."
 996     (ignore-errors
 997       (save-excursion
 998         (while (org-up-heading-safe))
 999         (hide-subtree)))
1000     (let ((org-show-siblings nil)
1001           (org-show-hierarchy-above t))
1002       (org-reveal))
1003     (save-excursion
1004       (org-back-to-heading t)
1005       (show-children)))
1006
1007   (add-hook 'org-agenda-after-show-hook 'my-compact-follow)
1008 #+end_src
1009
1010 # org-add-hook?