diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-06-02 10:15:05 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-06-02 10:35:24 +0300 |
commit | 507c19c0f7a1dc7a46ec8ac19d9e904c9e825a9b (patch) | |
tree | c1bd0ecc61a155a299a19038dccdd4ca34f32205 /source/blender/blenkernel/BKE_callbacks.h | |
parent | 3b3742c75fb0960997cb28742c0879412004358d (diff) |
Docs: formalize naming for generic callbacks in BKE_callbacks.h
Add a doc-string explaining the purpose of each call back and
how they should be used.
Also add a currently unused callback 'POST_FAIL' that is to be used in
cases the action fails - giving script authors, a guarantee that a
call to `pre` will always have a matching `post/post_fail` call.
- D11422: adds a callback that can use 'post_fail'.
- T88696: proposed these conventions.
Diffstat (limited to 'source/blender/blenkernel/BKE_callbacks.h')
-rw-r--r-- | source/blender/blenkernel/BKE_callbacks.h | 59 |
1 files changed, 54 insertions, 5 deletions
diff --git a/source/blender/blenkernel/BKE_callbacks.h b/source/blender/blenkernel/BKE_callbacks.h index f04b5e45720..ef2a0ed34a0 100644 --- a/source/blender/blenkernel/BKE_callbacks.h +++ b/source/blender/blenkernel/BKE_callbacks.h @@ -30,11 +30,60 @@ struct Main; struct PointerRNA; /** - * Common suffix uses: - * - ``_PRE/_POST``: - * For handling discrete non-interactive events. - * - ``_INIT/_COMPLETE/_CANCEL``: - * For handling jobs (which may in turn cause other handlers to be called). + Callbacks for One Off Actions + * ============================= + * + * - `{ACTION}` use in cases where only a single callback is required, + * `VERSION_UPDATE` and `RENDER_STATS` for example. + * + * \note avoid single callbacks if there is a chance `PRE/POST` are useful to differentiate + * since renaming callbacks may break Python scripts. + * + * Callbacks for Common Actions + * ============================ + * + * - `{ACTION}_PRE` run before the action. + * - `{ACTION}_POST` run after the action. + * + * Optional Additional Callbacks + * ----------------------------- + * + * - `{ACTION}_INIT` when the handler may manipulate the context used to run the action. + * + * Examples where `INIT` functions may be useful are: + * + * - When rendering, an `INIT` function may change the camera or render settings, + * things which a `PRE` function can't support as this information has already been used. + * - When saving an `INIT` function could temporarily change the preferences. + * + * - `{ACTION}_POST_FAIL` should be included if the action may fail. + * + * Use this so a call to the `PRE` callback always has a matching call to `POST` or `POST_FAIL`. + * + * \note in most cases only `PRE/POST` are required. + * + * Callbacks for Background/Modal Tasks + * ==================================== + * + * - `{ACTION}_INIT` + * - `{ACTION}_COMPLETE` when a background job has finished. + * - `{ACTION}_CANCEL` When a background job is canceled partway through. + * + * While cancellation may be caused by any number of reasons, common causes may include: + * + * - Explicit user cancellation. + * - Exiting Blender. + * - Failure to acquire resources (such as disk-full, out of memory ... etc). + * + * \note `PRE/POST` handlers may be used along side modal task handlers + * as is the case for rendering, where rendering an animation uses modal task handlers, + * rendering a single frame has `PRE/POST` handlers. + * + * Python Access + * ============= + * + * All callbacks here must be exposed via the Python module `bpy.app.handlers`, + * see `bpy_app_handlers.c`. */ typedef enum { BKE_CB_EVT_FRAME_CHANGE_PRE, |