From 7e927174396443cdc4c5544dad13faca7299d183 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Wed, 8 Dec 2021 17:12:41 +1100 Subject: Cleanup: move public doc-strings into headers for 'windowmanager' Ref T92709 --- source/blender/windowmanager/gizmo/WM_gizmo_api.h | 121 ++++++++++++++++++++- .../blender/windowmanager/gizmo/intern/wm_gizmo.c | 45 +------- .../windowmanager/gizmo/intern/wm_gizmo_group.c | 21 ---- .../gizmo/intern/wm_gizmo_group_type.c | 6 - .../windowmanager/gizmo/intern/wm_gizmo_intern.h | 20 ++++ .../windowmanager/gizmo/intern/wm_gizmo_map.c | 35 ------ .../gizmo/intern/wm_gizmo_target_props.c | 7 -- .../windowmanager/gizmo/intern/wm_gizmo_type.c | 5 - .../blender/windowmanager/gizmo/wm_gizmo_wmapi.h | 42 ++++++- 9 files changed, 175 insertions(+), 127 deletions(-) (limited to 'source/blender/windowmanager/gizmo') diff --git a/source/blender/windowmanager/gizmo/WM_gizmo_api.h b/source/blender/windowmanager/gizmo/WM_gizmo_api.h index c7a4b064d0e..497e4f6e5fc 100644 --- a/source/blender/windowmanager/gizmo/WM_gizmo_api.h +++ b/source/blender/windowmanager/gizmo/WM_gizmo_api.h @@ -61,19 +61,42 @@ extern "C" { struct wmGizmo *WM_gizmo_new_ptr(const struct wmGizmoType *gzt, struct wmGizmoGroup *gzgroup, struct PointerRNA *properties); +/** + * \param idname: Must be a valid gizmo type name, + * if you need to check it exists use #WM_gizmo_new_ptr + * because callers of this function don't NULL check the return value. + */ struct wmGizmo *WM_gizmo_new(const char *idname, struct wmGizmoGroup *gzgroup, struct PointerRNA *properties); +/** + * \warning this doesn't check #wmGizmoMap (highlight, selection etc). + * Typical use is when freeing the windowing data, + * where caller can manage clearing selection, highlight... etc. + */ void WM_gizmo_free(struct wmGizmo *gz); +/** + * Free \a gizmo and unlink from \a gizmolist. + * \a gizmolist is allowed to be NULL. + */ void WM_gizmo_unlink(ListBase *gizmolist, struct wmGizmoMap *gzmap, struct wmGizmo *gz, struct bContext *C); +/** + * Remove from selection array without running callbacks. + */ bool WM_gizmo_select_unlink(struct wmGizmoMap *gzmap, struct wmGizmo *gz); bool WM_gizmo_select_set(struct wmGizmoMap *gzmap, struct wmGizmo *gz, bool select); bool WM_gizmo_highlight_set(struct wmGizmoMap *gzmap, struct wmGizmo *gz); +/** + * Special function to run from setup so gizmos start out interactive. + * + * We could do this when linking them, + * but this complicates things since the window update code needs to run first. + */ void WM_gizmo_modal_set_from_setup(struct wmGizmoMap *gzmap, struct bContext *C, struct wmGizmo *gz, @@ -87,17 +110,30 @@ struct PointerRNA *WM_gizmo_operator_set(struct wmGizmo *gz, struct IDProperty *properties); int WM_gizmo_operator_invoke(struct bContext *C, struct wmGizmo *gz, struct wmGizmoOpElem *gzop); -/* callbacks */ +/* Callbacks. */ + void WM_gizmo_set_fn_custom_modal(struct wmGizmo *gz, wmGizmoFnModal fn); void WM_gizmo_set_matrix_location(struct wmGizmo *gz, const float origin[3]); +/** + * #wmGizmo.matrix utility, set the orientation by it's Z axis. + */ void WM_gizmo_set_matrix_rotation_from_z_axis(struct wmGizmo *gz, const float z_axis[3]); +/** + * #wmGizmo.matrix utility, set the orientation by it's Y/Z axis. + */ void WM_gizmo_set_matrix_rotation_from_yz_axis(struct wmGizmo *gz, const float y_axis[3], const float z_axis[3]); void WM_gizmo_set_matrix_offset_location(struct wmGizmo *gz, const float offset[3]); +/** + * #wmGizmo.matrix_offset utility, set the orientation by it's Z axis. + */ void WM_gizmo_set_matrix_offset_rotation_from_z_axis(struct wmGizmo *gz, const float z_axis[3]); +/** + * #wmGizmo.matrix_offset utility, set the orientation by it's Y/Z axis. + */ void WM_gizmo_set_matrix_offset_rotation_from_yz_axis(struct wmGizmo *gz, const float y_axis[3], const float z_axis[3]); @@ -128,14 +164,30 @@ void WM_gizmo_calc_matrix_final_no_offset(const struct wmGizmo *gz, float r_mat[ void WM_gizmo_calc_matrix_final(const struct wmGizmo *gz, float r_mat[4][4]); -/* properties */ +/* Properties. */ + void WM_gizmo_properties_create_ptr(struct PointerRNA *ptr, struct wmGizmoType *gzt); void WM_gizmo_properties_create(struct PointerRNA *ptr, const char *gtstring); +/** + * Similar to #WM_gizmo_properties_create + * except its uses ID properties used for key-maps and macros. + */ void WM_gizmo_properties_alloc(struct PointerRNA **ptr, struct IDProperty **properties, const char *gtstring); void WM_gizmo_properties_sanitize(struct PointerRNA *ptr, const bool no_context); +/** + * Set all props to their default. + * + * \param do_update: Only update un-initialized props. + * + * \note There's nothing specific to gizmos here. + * This could be made a general function. + */ bool WM_gizmo_properties_default(struct PointerRNA *ptr, const bool do_update); +/** + * Remove all props without #PROP_SKIP_SAVE. + */ void WM_gizmo_properties_reset(struct wmGizmo *gz); void WM_gizmo_properties_clear(struct PointerRNA *ptr); void WM_gizmo_properties_free(struct PointerRNA *ptr); @@ -146,7 +198,13 @@ void WM_gizmotype_append(void (*gtfunc)(struct wmGizmoType *)); void WM_gizmotype_append_ptr(void (*gtfunc)(struct wmGizmoType *, void *), void *userdata); bool WM_gizmotype_remove(struct bContext *C, struct Main *bmain, const char *idname); void WM_gizmotype_remove_ptr(struct bContext *C, struct Main *bmain, struct wmGizmoType *gzt); +/** + * Free but don't remove from ghash. + */ void WM_gizmotype_free_ptr(struct wmGizmoType *gzt); +/** + * Caller must free. + */ void WM_gizmotype_iter(struct GHashIterator *ghi); /* wm_gizmo_group_type.c */ @@ -155,8 +213,15 @@ struct wmGizmoGroupType *WM_gizmogrouptype_append(void (*wtfunc)(struct wmGizmoG struct wmGizmoGroupType *WM_gizmogrouptype_append_ptr(void (*wtfunc)(struct wmGizmoGroupType *, void *), void *userdata); +/** + * Caller must free. + */ void WM_gizmogrouptype_iter(struct GHashIterator *ghi); +/** + * Append and insert into a gizmo typemap. + * This is most common for C gizmos which are enabled by default. + */ struct wmGizmoGroupTypeRef *WM_gizmogrouptype_append_and_link( struct wmGizmoMapType *gzmap_type, void (*wtfunc)(struct wmGizmoGroupType *)); @@ -167,6 +232,10 @@ void WM_gizmoconfig_update_tag_group_type_init(struct wmGizmoMapType *gzmap_type struct wmGizmoGroupType *gzgt); void WM_gizmoconfig_update_tag_group_type_remove(struct wmGizmoMapType *gzmap_type, struct wmGizmoGroupType *gzgt); +/** + * Run in case new types have been added (runs often, early exit where possible). + * Follows #WM_keyconfig_update conventions. + */ void WM_gizmoconfig_update(struct Main *bmain); void WM_gizmoconfig_update_tag_group_remove(struct wmGizmoMap *gzmap); @@ -222,7 +291,8 @@ bool WM_gizmo_target_property_float_range_get(const struct wmGizmo *gz, int WM_gizmo_target_property_array_length(const struct wmGizmo *gz, struct wmGizmoProperty *gz_prop); -/* definitions */ +/* Definitions. */ + const struct wmGizmoPropertyType *WM_gizmotype_target_property_find(const struct wmGizmoType *gzt, const char *idname); void WM_gizmotype_target_property_def(struct wmGizmoType *gzt, @@ -230,14 +300,21 @@ void WM_gizmotype_target_property_def(struct wmGizmoType *gzt, int data_type, int array_length); -/* utilities */ +/* Utilities. */ + void WM_gizmo_do_msg_notify_tag_refresh(struct bContext *C, struct wmMsgSubscribeKey *msg_key, struct wmMsgSubscribeValue *msg_val); +/** + * Runs on the "prepare draw" pass, drawing the region clears. + */ void WM_gizmo_target_property_subscribe_all(struct wmGizmo *gz, struct wmMsgBus *mbus, struct ARegion *region); +/** + * Auto-key function if auto-key is enabled. + */ void WM_gizmo_target_property_anim_autokey(struct bContext *C, const struct wmGizmo *gz, struct wmGizmoProperty *gz_prop); @@ -256,6 +333,7 @@ struct wmKeyMap *WM_gizmogroup_setup_keymap_generic_maybe_drag(const struct wmGi struct wmKeyConfig *kc); /* Utility functions (not callbacks). */ + struct wmKeyMap *WM_gizmo_keymap_generic_with_keyconfig(struct wmKeyConfig *kc); struct wmKeyMap *WM_gizmo_keymap_generic(struct wmWindowManager *wm); @@ -268,19 +346,29 @@ struct wmKeyMap *WM_gizmo_keymap_generic_drag(struct wmWindowManager *wm); struct wmKeyMap *WM_gizmo_keymap_generic_click_drag_with_keyconfig(struct wmKeyConfig *kc); struct wmKeyMap *WM_gizmo_keymap_generic_click_drag(struct wmWindowManager *wm); +/** + * Drag or press depending on preference. + */ struct wmKeyMap *WM_gizmo_keymap_generic_maybe_drag_with_keyconfig(struct wmKeyConfig *kc); struct wmKeyMap *WM_gizmo_keymap_generic_maybe_drag(struct wmWindowManager *wm); void WM_gizmogroup_ensure_init(const struct bContext *C, struct wmGizmoGroup *gzgroup); /* Sort utilities for use with 'BLI_listbase_sort'. */ + int WM_gizmo_cmp_temp_fl(const void *gz_a_ptr, const void *gz_b_ptr); int WM_gizmo_cmp_temp_fl_reverse(const void *gz_a_ptr, const void *gz_b_ptr); /* -------------------------------------------------------------------- */ /* wmGizmoMap */ +/** + * Creates a gizmo-map with all registered gizmos for that type + */ struct wmGizmoMap *WM_gizmomap_new_from_type(const struct wmGizmoMapType_Params *gzmap_params); +/** + * Re-create the gizmos (use when changing theme settings). + */ void WM_gizmomap_reinit(struct wmGizmoMap *gzmap); const struct ListBase *WM_gizmomap_group_list(struct wmGizmoMap *gzmap); struct wmGizmoGroup *WM_gizmomap_group_find(struct wmGizmoMap *gzmap, const char *idname); @@ -298,6 +386,12 @@ void WM_gizmomap_draw(struct wmGizmoMap *gzmap, const struct bContext *C, const eWM_GizmoFlagMapDrawStep drawstep); void WM_gizmomap_add_handlers(struct ARegion *region, struct wmGizmoMap *gzmap); +/** + * Select/Deselect all selectable gizmos in \a gzmap. + * \return if selection has changed. + * + * TODO: select all by type. + */ bool WM_gizmomap_select_all(struct bContext *C, struct wmGizmoMap *gzmap, const int action); bool WM_gizmomap_cursor_set(const struct wmGizmoMap *gzmap, struct wmWindow *win); void WM_gizmomap_message_subscribe(const struct bContext *C, @@ -305,6 +399,9 @@ void WM_gizmomap_message_subscribe(const struct bContext *C, struct ARegion *region, struct wmMsgBus *mbus); bool WM_gizmomap_is_any_selected(const struct wmGizmoMap *gzmap); +/** + * \note We could use a callback to define bounds, for now just use matrix location. + */ bool WM_gizmomap_minmax(const struct wmGizmoMap *gzmap, bool use_hidden, bool use_select, @@ -327,6 +424,10 @@ struct wmGizmoGroupTypeRef *WM_gizmomaptype_group_find(struct wmGizmoMapType *gz const char *idname); struct wmGizmoGroupTypeRef *WM_gizmomaptype_group_find_ptr(struct wmGizmoMapType *gzmap_type, const struct wmGizmoGroupType *gzgt); +/** + * Use this for registering gizmos on startup. + * For runtime, use #WM_gizmomaptype_group_link_runtime. + */ struct wmGizmoGroupTypeRef *WM_gizmomaptype_group_link(struct wmGizmoMapType *gzmap_type, const char *idname); struct wmGizmoGroupTypeRef *WM_gizmomaptype_group_link_ptr(struct wmGizmoMapType *gzmap_type, @@ -345,6 +446,9 @@ void WM_gizmomaptype_group_unlink(struct bContext *C, struct wmGizmoMapType *gzmap_type, const struct wmGizmoGroupType *gzgt); +/** + * Unlike #WM_gizmomaptype_group_unlink this doesn't maintain correct state, simply free. + */ void WM_gizmomaptype_group_free(struct wmGizmoGroupTypeRef *gzgt); /* -------------------------------------------------------------------- */ @@ -362,6 +466,9 @@ bool WM_gizmo_group_type_ensure_ptr_ex(struct wmGizmoGroupType *gzgt, bool WM_gizmo_group_type_ensure_ptr(struct wmGizmoGroupType *gzgt); bool WM_gizmo_group_type_ensure(const char *idname); +/** + * Call #WM_gizmo_group_type_free_ptr after to remove & free. + */ void WM_gizmo_group_type_remove_ptr_ex(struct Main *bmain, struct wmGizmoGroupType *gzgt, struct wmGizmoMapType *gzmap_type); @@ -380,7 +487,9 @@ void WM_gizmo_group_unlink_delayed_ptr_from_space(struct wmGizmoGroupType *gzgt, void WM_gizmo_group_type_free_ptr(wmGizmoGroupType *gzgt); bool WM_gizmo_group_type_free(const char *idname); -/* Has the result of unlinking and linking (re-initializes gizmo's). */ +/** + * Has the result of unlinking and linking (re-initializes gizmo's). + */ void WM_gizmo_group_type_reinit_ptr_ex(struct Main *bmain, struct wmGizmoGroupType *gzgt, struct wmGizmoMapType *gzmap_type); @@ -388,6 +497,7 @@ void WM_gizmo_group_type_reinit_ptr(struct Main *bmain, struct wmGizmoGroupType void WM_gizmo_group_type_reinit(struct Main *bmain, const char *idname); /* Utilities */ + bool WM_gizmo_context_check_drawstep(const struct bContext *C, eWM_GizmoFlagMapDrawStep step); void WM_gizmo_group_remove_by_tool(struct bContext *C, @@ -398,6 +508,7 @@ void WM_gizmo_group_remove_by_tool(struct bContext *C, void WM_gizmo_group_tag_remove(struct wmGizmoGroup *gzgroup); /* Wrap Group Type Callbacks. */ + bool WM_gizmo_group_type_poll(const struct bContext *C, const struct wmGizmoGroupType *gzgt); void WM_gizmo_group_refresh(const struct bContext *C, struct wmGizmoGroup *gzgroup); diff --git a/source/blender/windowmanager/gizmo/intern/wm_gizmo.c b/source/blender/windowmanager/gizmo/intern/wm_gizmo.c index cfedd67b2f0..d4f11c79d46 100644 --- a/source/blender/windowmanager/gizmo/intern/wm_gizmo.c +++ b/source/blender/windowmanager/gizmo/intern/wm_gizmo.c @@ -106,11 +106,6 @@ wmGizmo *WM_gizmo_new_ptr(const wmGizmoType *gzt, wmGizmoGroup *gzgroup, Pointer return gz; } -/** - * \param idname: Must be a valid gizmo type name, - * if you need to check it exists use #WM_gizmo_new_ptr - * because callers of this function don't NULL check the return value. - */ wmGizmo *WM_gizmo_new(const char *idname, wmGizmoGroup *gzgroup, PointerRNA *properties) { const wmGizmoType *gzt = WM_gizmotype_find(idname, false); @@ -143,11 +138,6 @@ static void wm_gizmo_register(wmGizmoGroup *gzgroup, wmGizmo *gz) wm_gizmogroup_gizmo_register(gzgroup, gz); } -/** - * \warning this doesn't check #wmGizmoMap (highlight, selection etc). - * Typical use is when freeing the windowing data, - * where caller can manage clearing selection, highlight... etc. - */ void WM_gizmo_free(wmGizmo *gz) { if (gz->type->free != NULL) { @@ -187,10 +177,6 @@ void WM_gizmo_free(wmGizmo *gz) MEM_freeN(gz); } -/** - * Free \a gizmo and unlink from \a gizmolist. - * \a gizmolist is allowed to be NULL. - */ void WM_gizmo_unlink(ListBase *gizmolist, wmGizmoMap *gzmap, wmGizmo *gz, bContext *C) { if (gz->state & WM_GIZMO_STATE_HIGHLIGHT) { @@ -300,9 +286,6 @@ static void wm_gizmo_set_matrix_rotation_from_yz_axis__internal(float matrix[4][ normalize_v3(matrix[0]); } -/** - * wmGizmo.matrix utils. - */ void WM_gizmo_set_matrix_rotation_from_z_axis(wmGizmo *gz, const float z_axis[3]) { wm_gizmo_set_matrix_rotation_from_z_axis__internal(gz->matrix_basis, z_axis); @@ -318,9 +301,6 @@ void WM_gizmo_set_matrix_location(wmGizmo *gz, const float origin[3]) copy_v3_v3(gz->matrix_basis[3], origin); } -/** - * wmGizmo.matrix_offset utils. - */ void WM_gizmo_set_matrix_offset_rotation_from_z_axis(wmGizmo *gz, const float z_axis[3]) { wm_gizmo_set_matrix_rotation_from_z_axis__internal(gz->matrix_offset, z_axis); @@ -388,12 +368,7 @@ void WM_gizmo_set_fn_custom_modal(struct wmGizmo *gz, wmGizmoFnModal fn) /** \} */ /* -------------------------------------------------------------------- */ -/** - * Add/Remove \a gizmo to selection. - * Reallocates memory for selected gizmos so better not call for selecting multiple ones. - * - * \return if the selection has changed. - */ + bool wm_gizmo_select_set_ex( wmGizmoMap *gzmap, wmGizmo *gz, bool select, bool use_array, bool use_callback) { @@ -429,7 +404,6 @@ bool wm_gizmo_select_set_ex( return changed; } -/* Remove from selection array without running callbacks. */ bool WM_gizmo_select_unlink(wmGizmoMap *gzmap, wmGizmo *gz) { return wm_gizmo_select_set_ex(gzmap, gz, false, true, false); @@ -454,12 +428,6 @@ bool wm_gizmo_select_and_highlight(bContext *C, wmGizmoMap *gzmap, wmGizmo *gz) return false; } -/** - * Special function to run from setup so gizmos start out interactive. - * - * We could do this when linking them, - * but this complicates things since the window update code needs to run first. - */ void WM_gizmo_modal_set_from_setup(struct wmGizmoMap *gzmap, struct bContext *C, struct wmGizmo *gz, @@ -634,8 +602,6 @@ void WM_gizmo_properties_create(PointerRNA *ptr, const char *gtstring) } } -/* similar to the function above except its uses ID properties - * used for keymaps and macros */ void WM_gizmo_properties_alloc(PointerRNA **ptr, IDProperty **properties, const char *gtstring) { if (*properties == NULL) { @@ -680,14 +646,6 @@ void WM_gizmo_properties_sanitize(PointerRNA *ptr, const bool no_context) RNA_STRUCT_END; } -/** - * Set all props to their default. - * - * \param do_update: Only update un-initialized props. - * - * \note There's nothing specific to gizmos here. - * This could be made a general function. - */ bool WM_gizmo_properties_default(PointerRNA *ptr, const bool do_update) { bool changed = false; @@ -715,7 +673,6 @@ bool WM_gizmo_properties_default(PointerRNA *ptr, const bool do_update) return changed; } -/* remove all props without PROP_SKIP_SAVE */ void WM_gizmo_properties_reset(wmGizmo *gz) { if (gz->ptr->data) { diff --git a/source/blender/windowmanager/gizmo/intern/wm_gizmo_group.c b/source/blender/windowmanager/gizmo/intern/wm_gizmo_group.c index b6d759eb95f..216bc260743 100644 --- a/source/blender/windowmanager/gizmo/intern/wm_gizmo_group.c +++ b/source/blender/windowmanager/gizmo/intern/wm_gizmo_group.c @@ -63,9 +63,6 @@ /** \name wmGizmoGroup * \{ */ -/** - * Create a new gizmo-group from \a gzgt. - */ wmGizmoGroup *wm_gizmogroup_new_from_type(wmGizmoMap *gzmap, wmGizmoGroupType *gzgt) { wmGizmoGroup *gzgroup = MEM_callocN(sizeof(*gzgroup), "gizmo-group"); @@ -148,9 +145,6 @@ void WM_gizmo_group_tag_remove(wmGizmoGroup *gzgroup) } } -/** - * Add \a gizmo to \a gzgroup and make sure its name is unique within the group. - */ void wm_gizmogroup_gizmo_register(wmGizmoGroup *gzgroup, wmGizmo *gz) { BLI_assert(BLI_findindex(&gzgroup->gizmos, gz) == -1); @@ -234,10 +228,6 @@ wmGizmo *wm_gizmogroup_find_intersected_gizmo(wmWindowManager *wm, return NULL; } -/** - * Adds all gizmos of \a gzgroup that can be selected to the head of \a listbase. - * Added items need freeing! - */ void wm_gizmogroup_intersectable_gizmos_to_list(wmWindowManager *wm, const wmGizmoGroup *gzgroup, const int event_modifier, @@ -821,7 +811,6 @@ struct wmKeyMap *WM_gizmo_keymap_generic_click_drag(wmWindowManager *wm) return WM_gizmo_keymap_generic_click_drag_with_keyconfig(wm->defaultconf); } -/** Drag or press depending on preference. */ struct wmKeyMap *WM_gizmo_keymap_generic_maybe_drag_with_keyconfig(wmKeyConfig *kc) { const char *idname = "Generic Gizmo Maybe Drag"; @@ -862,10 +851,6 @@ struct wmGizmoGroupTypeRef *WM_gizmomaptype_group_find(struct wmGizmoMapType *gz return NULL; } -/** - * Use this for registering gizmos on startup. - * For runtime, use #WM_gizmomaptype_group_link_runtime. - */ wmGizmoGroupTypeRef *WM_gizmomaptype_group_link(wmGizmoMapType *gzmap_type, const char *idname) { wmGizmoGroupType *gzgt = WM_gizmogrouptype_find(idname, false); @@ -939,9 +924,6 @@ wmGizmoGroup *WM_gizmomaptype_group_init_runtime_with_region(wmGizmoMapType *gzm return gzgroup; } -/** - * Unlike #WM_gizmomaptype_group_unlink this doesn't maintain correct state, simply free. - */ void WM_gizmomaptype_group_free(wmGizmoGroupTypeRef *gzgt_ref) { MEM_freeN(gzgt_ref); @@ -1059,9 +1041,6 @@ bool WM_gizmo_group_type_ensure(const char *idname) return WM_gizmo_group_type_ensure_ptr(gzgt); } -/** - * Call #WM_gizmo_group_type_free_ptr after to remove & free. - */ void WM_gizmo_group_type_remove_ptr_ex(struct Main *bmain, wmGizmoGroupType *gzgt, wmGizmoMapType *gzmap_type) diff --git a/source/blender/windowmanager/gizmo/intern/wm_gizmo_group_type.c b/source/blender/windowmanager/gizmo/intern/wm_gizmo_group_type.c index 6a793d52f74..0a36068bb21 100644 --- a/source/blender/windowmanager/gizmo/intern/wm_gizmo_group_type.c +++ b/source/blender/windowmanager/gizmo/intern/wm_gizmo_group_type.c @@ -71,7 +71,6 @@ wmGizmoGroupType *WM_gizmogrouptype_find(const char *idname, bool quiet) return NULL; } -/* caller must free */ void WM_gizmogrouptype_iter(GHashIterator *ghi) { BLI_ghashIterator_init(ghi, global_gizmogrouptype_hash); @@ -127,10 +126,6 @@ wmGizmoGroupType *WM_gizmogrouptype_append_ptr(void (*wtfunc)(struct wmGizmoGrou return gzgt; } -/** - * Append and insert into a gizmo typemap. - * This is most common for C gizmos which are enabled by default. - */ wmGizmoGroupTypeRef *WM_gizmogrouptype_append_and_link(wmGizmoMapType *gzmap_type, void (*wtfunc)(struct wmGizmoGroupType *)) { @@ -190,7 +185,6 @@ void wm_gizmogrouptype_free(void) global_gizmogrouptype_hash = NULL; } -/* called on initialize WM_init() */ void wm_gizmogrouptype_init(void) { /* reserve size is set based on blender default setup */ diff --git a/source/blender/windowmanager/gizmo/intern/wm_gizmo_intern.h b/source/blender/windowmanager/gizmo/intern/wm_gizmo_intern.h index dd2db209771..b6912d79076 100644 --- a/source/blender/windowmanager/gizmo/intern/wm_gizmo_intern.h +++ b/source/blender/windowmanager/gizmo/intern/wm_gizmo_intern.h @@ -29,6 +29,12 @@ struct wmKeyConfig; /* -------------------------------------------------------------------- */ /* wmGizmo */ +/** + * Add/Remove \a gizmo to selection. + * Reallocates memory for selected gizmos so better not call for selecting multiple ones. + * + * \return if the selection has changed. + */ bool wm_gizmo_select_set_ex( struct wmGizmoMap *gzmap, struct wmGizmo *gz, bool select, bool use_array, bool use_callback); bool wm_gizmo_select_and_highlight(bContext *C, struct wmGizmoMap *gzmap, struct wmGizmo *gz); @@ -54,9 +60,15 @@ enum { TWEAK_MODAL_SNAP_OFF, }; +/** + * Create a new gizmo-group from \a gzgt. + */ struct wmGizmoGroup *wm_gizmogroup_new_from_type(struct wmGizmoMap *gzmap, struct wmGizmoGroupType *gzgt); void wm_gizmogroup_free(bContext *C, struct wmGizmoGroup *gzgroup); +/** + * Add \a gizmo to \a gzgroup and make sure its name is unique within the group. + */ void wm_gizmogroup_gizmo_register(struct wmGizmoGroup *gzgroup, struct wmGizmo *gz); struct wmGizmoGroup *wm_gizmogroup_find_by_type(const struct wmGizmoMap *gzmap, const struct wmGizmoGroupType *gzgt); @@ -66,6 +78,10 @@ struct wmGizmo *wm_gizmogroup_find_intersected_gizmo(wmWindowManager *wm, const int event_modifier, const int mval[2], int *r_part); +/** + * Adds all gizmos of \a gzgroup that can be selected to the head of \a listbase. + * Added items need freeing! + */ void wm_gizmogroup_intersectable_gizmos_to_list(wmWindowManager *wm, const struct wmGizmoGroup *gzgroup, const int event_modifier, @@ -137,6 +153,10 @@ struct wmGizmoMapType { }; void wm_gizmomap_select_array_clear(struct wmGizmoMap *gzmap); +/** + * Deselect all selected gizmos in \a gzmap. + * \return if selection has changed. + */ bool wm_gizmomap_deselect_all(struct wmGizmoMap *gzmap); void wm_gizmomap_select_array_shrink(struct wmGizmoMap *gzmap, int len_subtract); void wm_gizmomap_select_array_push_back(struct wmGizmoMap *gzmap, wmGizmo *gz); diff --git a/source/blender/windowmanager/gizmo/intern/wm_gizmo_map.c b/source/blender/windowmanager/gizmo/intern/wm_gizmo_map.c index 6f952bc9526..d3e682f1490 100644 --- a/source/blender/windowmanager/gizmo/intern/wm_gizmo_map.c +++ b/source/blender/windowmanager/gizmo/intern/wm_gizmo_map.c @@ -176,9 +176,6 @@ static wmGizmoMap *wm_gizmomap_new_from_type_ex(struct wmGizmoMapType *gzmap_typ return gzmap; } -/** - * Creates a gizmo-map with all registered gizmos for that type - */ wmGizmoMap *WM_gizmomap_new_from_type(const struct wmGizmoMapType_Params *gzmap_params) { wmGizmoMapType *gzmap_type = WM_gizmomaptype_ensure(gzmap_params); @@ -207,7 +204,6 @@ void wm_gizmomap_remove(wmGizmoMap *gzmap) MEM_freeN(gzmap); } -/** Re-create the gizmos (use when changing theme settings). */ void WM_gizmomap_reinit(wmGizmoMap *gzmap) { wmGizmoMapType *gzmap_type = gzmap->type; @@ -246,9 +242,6 @@ bool WM_gizmomap_is_any_selected(const wmGizmoMap *gzmap) return gzmap->gzmap_context.select.len != 0; } -/** - * \note We could use a callback to define bounds, for now just use matrix location. - */ bool WM_gizmomap_minmax(const wmGizmoMap *gzmap, bool UNUSED(use_hidden), bool use_select, @@ -713,10 +706,6 @@ static wmGizmo *gizmo_find_intersected_3d(bContext *C, return result; } -/** - * Try to find a gizmo under the mouse position. 2D intersections have priority over - * 3D ones (could check for smallest screen-space distance but not needed right now). - */ wmGizmo *wm_gizmomap_highlight_find(wmGizmoMap *gzmap, bContext *C, const wmEvent *event, @@ -843,10 +832,6 @@ void wm_gizmomaps_handled_modal_update(bContext *C, wmEvent *event, wmEventHandl CTX_wm_region_set(C, region); } -/** - * Deselect all selected gizmos in \a gzmap. - * \return if selection has changed. - */ bool wm_gizmomap_deselect_all(wmGizmoMap *gzmap) { wmGizmoMapSelectState *msel = &gzmap->gzmap_context.select; @@ -903,12 +888,6 @@ static bool wm_gizmomap_select_all_intern(bContext *C, wmGizmoMap *gzmap) return changed; } -/** - * Select/Deselect all selectable gizmos in \a gzmap. - * \return if selection has changed. - * - * TODO: select all by type. - */ bool WM_gizmomap_select_all(bContext *C, wmGizmoMap *gzmap, const int action) { bool changed = false; @@ -932,10 +911,6 @@ bool WM_gizmomap_select_all(bContext *C, wmGizmoMap *gzmap, const int action) return changed; } -/** - * Prepare context for gizmo handling (but only if area/region is - * part of screen). Version of #wm_handler_op_context for gizmos. - */ void wm_gizmomap_handler_context_op(bContext *C, wmEventHandler_Op *handler) { bScreen *screen = CTX_wm_screen(C); @@ -1037,9 +1012,6 @@ wmGizmo *wm_gizmomap_highlight_get(wmGizmoMap *gzmap) return gzmap->gzmap_context.highlight; } -/** - * Caller should call exit when (enable == False). - */ void wm_gizmomap_modal_set( wmGizmoMap *gzmap, bContext *C, wmGizmo *gz, const wmEvent *event, bool enable) { @@ -1247,9 +1219,6 @@ void wm_gizmomaptypes_free(void) } } -/** - * Initialize keymaps for all existing gizmo-groups - */ void wm_gizmos_keymap(wmKeyConfig *keyconf) { LISTBASE_FOREACH (wmGizmoMapType *, gzmap_type, &gizmomaptypes) { @@ -1293,10 +1262,6 @@ void WM_gizmoconfig_update_tag_group_remove(wmGizmoMap *gzmap) wm_gzmap_type_update_flag |= WM_GIZMOTYPE_GLOBAL_UPDATE_REMOVE; } -/** - * Run in case new types have been added (runs often, early exit where possible). - * Follows #WM_keyconfig_update conventions. - */ void WM_gizmoconfig_update(struct Main *bmain) { if (G.background) { diff --git a/source/blender/windowmanager/gizmo/intern/wm_gizmo_target_props.c b/source/blender/windowmanager/gizmo/intern/wm_gizmo_target_props.c index 63e833d73c3..57555fb5416 100644 --- a/source/blender/windowmanager/gizmo/intern/wm_gizmo_target_props.c +++ b/source/blender/windowmanager/gizmo/intern/wm_gizmo_target_props.c @@ -319,10 +319,6 @@ void WM_gizmo_do_msg_notify_tag_refresh(bContext *UNUSED(C), WM_gizmomap_tag_refresh(gzmap); } -/** - * Runs on the "prepare draw" pass, - * drawing the region clears. - */ void WM_gizmo_target_property_subscribe_all(wmGizmo *gz, struct wmMsgBus *mbus, ARegion *region) { if (gz->type->target_property_defs_len) { @@ -355,9 +351,6 @@ void WM_gizmo_target_property_subscribe_all(wmGizmo *gz, struct wmMsgBus *mbus, } } -/** - * Auto-key function if auto-key is enabled. - */ void WM_gizmo_target_property_anim_autokey(bContext *C, const wmGizmo *UNUSED(gz), wmGizmoProperty *gz_prop) diff --git a/source/blender/windowmanager/gizmo/intern/wm_gizmo_type.c b/source/blender/windowmanager/gizmo/intern/wm_gizmo_type.c index 1523246d08b..602100a624e 100644 --- a/source/blender/windowmanager/gizmo/intern/wm_gizmo_type.c +++ b/source/blender/windowmanager/gizmo/intern/wm_gizmo_type.c @@ -78,7 +78,6 @@ const wmGizmoType *WM_gizmotype_find(const char *idname, bool quiet) return NULL; } -/* caller must free */ void WM_gizmotype_iter(GHashIterator *ghi) { BLI_ghashIterator_init(ghi, global_gizmotype_hash); @@ -118,9 +117,6 @@ void WM_gizmotype_append_ptr(void (*gtfunc)(struct wmGizmoType *, void *), void wm_gizmotype_append__end(mt); } -/** - * Free but don't remove from ghash. - */ void WM_gizmotype_free_ptr(wmGizmoType *gzt) { if (gzt->rna_ext.srna) { /* python gizmo, allocs own string */ @@ -195,7 +191,6 @@ void wm_gizmotype_free(void) global_gizmotype_hash = NULL; } -/* called on initialize WM_init() */ void wm_gizmotype_init(void) { /* reserve size is set based on blender default setup */ diff --git a/source/blender/windowmanager/gizmo/wm_gizmo_wmapi.h b/source/blender/windowmanager/gizmo/wm_gizmo_wmapi.h index 18b3f40aba6..0612ba97db0 100644 --- a/source/blender/windowmanager/gizmo/wm_gizmo_wmapi.h +++ b/source/blender/windowmanager/gizmo/wm_gizmo_wmapi.h @@ -40,37 +40,63 @@ extern "C" { #endif /* -------------------------------------------------------------------- */ -/* wmGizmo */ +/** \name #wmGizmo + * \{ */ /* wm_gizmo_type.c, for init/exit */ + void wm_gizmotype_free(void); +/** + * Called on initialize #WM_init(). + */ void wm_gizmotype_init(void); /* wm_gizmogroup_type.c, for init/exit */ + void wm_gizmogrouptype_free(void); +/** + * Called on initialize #WM_init(). + */ void wm_gizmogrouptype_init(void); +/** \} */ + /* -------------------------------------------------------------------- */ -/* wmGizmoGroup */ +/** \name #wmGizmoGroup + * \{ */ void GIZMOGROUP_OT_gizmo_select(struct wmOperatorType *ot); void GIZMOGROUP_OT_gizmo_tweak(struct wmOperatorType *ot); bool wm_gizmogroup_is_any_selected(const struct wmGizmoGroup *gzgroup); +/** \} */ + /* -------------------------------------------------------------------- */ -/* wmGizmoMap */ +/** \name #wmGizmoMap + * \{ */ void wm_gizmomap_remove(struct wmGizmoMap *gzmap); +/** + * Initialize key-maps for all existing gizmo-groups + */ void wm_gizmos_keymap(struct wmKeyConfig *keyconf); void wm_gizmomaps_handled_modal_update(bContext *C, struct wmEvent *event, struct wmEventHandler_Op *handler); +/** + * Prepare context for gizmo handling (but only if area/region is + * part of screen). Version of #wm_handler_op_context for gizmos. + */ void wm_gizmomap_handler_context_op(bContext *C, struct wmEventHandler_Op *handler); void wm_gizmomap_handler_context_gizmo(bContext *C, struct wmEventHandler_Gizmo *handler); +/** + * Try to find a gizmo under the mouse position. 2D intersections have priority over + * 3D ones (could check for smallest screen-space distance but not needed right now). + */ struct wmGizmo *wm_gizmomap_highlight_find(struct wmGizmoMap *gzmap, bContext *C, const struct wmEvent *event, @@ -80,6 +106,9 @@ bool wm_gizmomap_highlight_set(struct wmGizmoMap *gzmap, struct wmGizmo *gz, int part); struct wmGizmo *wm_gizmomap_highlight_get(struct wmGizmoMap *gzmap); +/** + * Caller should call exit when (enable == False). + */ void wm_gizmomap_modal_set(struct wmGizmoMap *gzmap, bContext *C, struct wmGizmo *gz, @@ -90,11 +119,16 @@ struct wmGizmo *wm_gizmomap_modal_get(struct wmGizmoMap *gzmap); struct wmGizmo **wm_gizmomap_selected_get(wmGizmoMap *gzmap, int *r_selected_len); struct ListBase *wm_gizmomap_groups_get(wmGizmoMap *gzmap); +/** \} */ + /* -------------------------------------------------------------------- */ -/* wmGizmoMapType */ +/** \name #wmGizmoMapType + * \{ */ void wm_gizmomaptypes_free(void); +/** \} */ + #ifdef __cplusplus } #endif -- cgit v1.2.3