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