From ffc4c126f5416b04a01653e7a03451797b98aba4 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Tue, 7 Dec 2021 17:19:15 +1100 Subject: Cleanup: move public doc-strings into headers for 'blenkernel' - Added space below non doc-string comments to make it clear these aren't comments for the symbols directly below them. - Use doxy sections for some headers. - Minor improvements to doc-strings. Ref T92709 --- source/blender/blenkernel/BKE_workspace.h | 59 +++++++++++++++++++++++++++++-- 1 file changed, 56 insertions(+), 3 deletions(-) (limited to 'source/blender/blenkernel/BKE_workspace.h') diff --git a/source/blender/blenkernel/BKE_workspace.h b/source/blender/blenkernel/BKE_workspace.h index 82a4e5fe08e..ff4e21732c4 100644 --- a/source/blender/blenkernel/BKE_workspace.h +++ b/source/blender/blenkernel/BKE_workspace.h @@ -31,9 +31,17 @@ struct bScreen; struct bToolRef; /* -------------------------------------------------------------------- */ -/* Create, delete, init */ +/** \name Create, Delete, Initialize + * \{ */ struct WorkSpace *BKE_workspace_add(struct Main *bmain, const char *name); +/** + * Remove \a workspace by freeing itself and its data. This is a higher-level wrapper that + * calls #workspace_free_data (through #BKE_id_free) to free the workspace data, and frees + * other data-blocks owned by \a workspace and its layouts (currently that is screens only). + * + * Always use this to remove (and free) workspaces. Don't free non-ID workspace members here. + */ void BKE_workspace_remove(struct Main *bmain, struct WorkSpace *workspace); struct WorkSpaceInstanceHook *BKE_workspace_instance_hook_create(const struct Main *bmain, @@ -41,6 +49,9 @@ struct WorkSpaceInstanceHook *BKE_workspace_instance_hook_create(const struct Ma void BKE_workspace_instance_hook_free(const struct Main *bmain, struct WorkSpaceInstanceHook *hook); +/** + * Add a new layout to \a workspace for \a screen. + */ struct WorkSpaceLayout *BKE_workspace_layout_add(struct Main *bmain, struct WorkSpace *workspace, struct bScreen *screen, @@ -51,17 +62,36 @@ void BKE_workspace_layout_remove(struct Main *bmain, void BKE_workspace_relations_free(ListBase *relation_list); +/** \} */ + /* -------------------------------------------------------------------- */ -/* General Utils */ +/** \name General Utilities + * \{ */ struct WorkSpaceLayout *BKE_workspace_layout_find(const struct WorkSpace *workspace, const struct bScreen *screen) ATTR_NONNULL() ATTR_WARN_UNUSED_RESULT; +/** + * Find the layout for \a screen without knowing which workspace to look in. + * Can also be used to find the workspace that contains \a screen. + * + * \param r_workspace: Optionally return the workspace that contains the + * looked up layout (if found). + */ struct WorkSpaceLayout *BKE_workspace_layout_find_global(const struct Main *bmain, const struct bScreen *screen, struct WorkSpace **r_workspace) ATTR_NONNULL(1, 2); +/** + * Circular workspace layout iterator. + * + * \param callback: Custom function which gets executed for each layout. + * Can return false to stop iterating. + * \param arg: Custom data passed to each \a callback call. + * + * \return the layout at which \a callback returned false. + */ struct WorkSpaceLayout *BKE_workspace_layout_iter_circular( const struct WorkSpace *workspace, struct WorkSpaceLayout *start, @@ -72,8 +102,11 @@ struct WorkSpaceLayout *BKE_workspace_layout_iter_circular( void BKE_workspace_tool_remove(struct WorkSpace *workspace, struct bToolRef *tref) ATTR_NONNULL(1, 2); +/** \} */ + /* -------------------------------------------------------------------- */ -/* Getters/Setters */ +/** \name Getters/Setters + * \{ */ #define GETTER_ATTRS ATTR_NONNULL() ATTR_WARN_UNUSED_RESULT #define SETTER_ATTRS ATTR_NONNULL(1) @@ -81,8 +114,23 @@ void BKE_workspace_tool_remove(struct WorkSpace *workspace, struct bToolRef *tre struct WorkSpace *BKE_workspace_active_get(struct WorkSpaceInstanceHook *hook) GETTER_ATTRS; void BKE_workspace_active_set(struct WorkSpaceInstanceHook *hook, struct WorkSpace *workspace) SETTER_ATTRS; +/** + * Get the layout that is active for \a hook (which is the visible layout for the active workspace + * in \a hook). + */ struct WorkSpaceLayout *BKE_workspace_active_layout_get(const struct WorkSpaceInstanceHook *hook) GETTER_ATTRS; +/** + * \brief Activate a layout + * + * Sets \a layout as active for \a workspace when activated through or already active in \a hook. + * So when the active workspace of \a hook is \a workspace, \a layout becomes the active layout of + * \a hook too. See #BKE_workspace_active_set(). + * + * \a workspace does not need to be active for this. + * + * #WorkSpaceInstanceHook.act_layout should only be modified directly to update the layout pointer. + */ void BKE_workspace_active_layout_set(struct WorkSpaceInstanceHook *hook, const int winid, struct WorkSpace *workspace, @@ -100,6 +148,9 @@ void BKE_workspace_layout_name_set(struct WorkSpace *workspace, const char *new_name) ATTR_NONNULL(); struct bScreen *BKE_workspace_layout_screen_get(const struct WorkSpaceLayout *layout) GETTER_ATTRS; +/** + * Get the layout to be activated should \a workspace become or be the active workspace in \a hook. + */ struct WorkSpaceLayout *BKE_workspace_active_layout_for_workspace_get( const struct WorkSpaceInstanceHook *hook, const struct WorkSpace *workspace) GETTER_ATTRS; @@ -111,6 +162,8 @@ void BKE_workspace_id_tag_all_visible(struct Main *bmain, int tag) ATTR_NONNULL( #undef GETTER_ATTRS #undef SETTER_ATTRS +/** \} */ + #ifdef __cplusplus } #endif -- cgit v1.2.3 From 3d3bc748849834ef74563deb603ab43859cffeeb Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Fri, 7 Jan 2022 11:38:08 +1100 Subject: Cleanup: remove redundant const qualifiers for POD types MSVC used to warn about const mismatch for arguments passed by value. Remove these as newer versions of MSVC no longer show this warning. --- source/blender/blenkernel/BKE_workspace.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'source/blender/blenkernel/BKE_workspace.h') diff --git a/source/blender/blenkernel/BKE_workspace.h b/source/blender/blenkernel/BKE_workspace.h index ff4e21732c4..0f609be67de 100644 --- a/source/blender/blenkernel/BKE_workspace.h +++ b/source/blender/blenkernel/BKE_workspace.h @@ -45,7 +45,7 @@ struct WorkSpace *BKE_workspace_add(struct Main *bmain, const char *name); void BKE_workspace_remove(struct Main *bmain, struct WorkSpace *workspace); struct WorkSpaceInstanceHook *BKE_workspace_instance_hook_create(const struct Main *bmain, - const int winid); + int winid); void BKE_workspace_instance_hook_free(const struct Main *bmain, struct WorkSpaceInstanceHook *hook); @@ -97,7 +97,7 @@ struct WorkSpaceLayout *BKE_workspace_layout_iter_circular( struct WorkSpaceLayout *start, bool (*callback)(const struct WorkSpaceLayout *layout, void *arg), void *arg, - const bool iter_backward); + bool iter_backward); void BKE_workspace_tool_remove(struct WorkSpace *workspace, struct bToolRef *tref) ATTR_NONNULL(1, 2); @@ -132,13 +132,13 @@ struct WorkSpaceLayout *BKE_workspace_active_layout_get(const struct WorkSpaceIn * #WorkSpaceInstanceHook.act_layout should only be modified directly to update the layout pointer. */ void BKE_workspace_active_layout_set(struct WorkSpaceInstanceHook *hook, - const int winid, + int winid, struct WorkSpace *workspace, struct WorkSpaceLayout *layout) SETTER_ATTRS; struct bScreen *BKE_workspace_active_screen_get(const struct WorkSpaceInstanceHook *hook) GETTER_ATTRS; void BKE_workspace_active_screen_set(struct WorkSpaceInstanceHook *hook, - const int winid, + int winid, struct WorkSpace *workspace, struct bScreen *screen) SETTER_ATTRS; -- cgit v1.2.3