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