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/WM_api.h | 613 ++++++++++++++++++++- source/blender/windowmanager/WM_keymap.h | 32 +- source/blender/windowmanager/WM_toolsystem.h | 21 + 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 +- source/blender/windowmanager/intern/wm.c | 15 - source/blender/windowmanager/intern/wm_cursors.c | 8 +- source/blender/windowmanager/intern/wm_dragdrop.c | 43 -- .../blender/windowmanager/intern/wm_event_query.c | 24 - .../blender/windowmanager/intern/wm_event_system.c | 85 +-- source/blender/windowmanager/intern/wm_files.c | 31 -- .../blender/windowmanager/intern/wm_files_link.c | 8 - source/blender/windowmanager/intern/wm_gesture.c | 3 - .../blender/windowmanager/intern/wm_gesture_ops.c | 22 - source/blender/windowmanager/intern/wm_init_exit.c | 20 - source/blender/windowmanager/intern/wm_jobs.c | 18 - source/blender/windowmanager/intern/wm_keymap.c | 9 +- .../blender/windowmanager/intern/wm_keymap_utils.c | 5 - source/blender/windowmanager/intern/wm_menu_type.c | 1 - .../windowmanager/intern/wm_operator_props.c | 53 -- .../windowmanager/intern/wm_operator_type.c | 33 +- .../windowmanager/intern/wm_operator_utils.c | 7 - source/blender/windowmanager/intern/wm_operators.c | 71 +-- .../blender/windowmanager/intern/wm_panel_type.c | 1 - source/blender/windowmanager/intern/wm_stereo.c | 4 - source/blender/windowmanager/intern/wm_subwindow.c | 1 - .../blender/windowmanager/intern/wm_toolsystem.c | 19 - .../blender/windowmanager/intern/wm_uilist_type.c | 16 - source/blender/windowmanager/intern/wm_window.c | 91 --- .../message_bus/intern/wm_message_bus.c | 13 - .../message_bus/intern/wm_message_bus_intern.h | 3 + .../windowmanager/message_bus/wm_message_bus.h | 10 + source/blender/windowmanager/wm.h | 53 +- source/blender/windowmanager/wm_event_system.h | 41 +- source/blender/windowmanager/wm_files.h | 23 + source/blender/windowmanager/wm_window.h | 63 +++ .../windowmanager/xr/intern/wm_xr_actionmap.c | 13 - .../blender/windowmanager/xr/intern/wm_xr_draw.c | 6 - .../blender/windowmanager/xr/intern/wm_xr_intern.h | 12 + .../windowmanager/xr/intern/wm_xr_session.c | 12 - 47 files changed, 1030 insertions(+), 775 deletions(-) (limited to 'source') diff --git a/source/blender/windowmanager/WM_api.h b/source/blender/windowmanager/WM_api.h index c41c328c006..b0f89487f15 100644 --- a/source/blender/windowmanager/WM_api.h +++ b/source/blender/windowmanager/WM_api.h @@ -84,11 +84,24 @@ typedef struct wmGizmoMap wmGizmoMap; typedef struct wmGizmoMapType wmGizmoMapType; typedef struct wmJob wmJob; -/* general API */ +/* General API. */ + +/** + * Used for setting app-template from the command line: + * - non-empty string: overrides. + * - empty string: override, using no app template. + * - NULL: clears override. + */ void WM_init_state_app_template_set(const char *app_template); const char *WM_init_state_app_template_get(void); +/** + * Called when no ghost system was initialized. + */ void WM_init_state_size_set(int stax, int stay, int sizx, int sizy); +/** + * For border-less and border windows set from command-line. + */ void WM_init_state_fullscreen_set(void); void WM_init_state_normal_set(void); void WM_init_state_maximized_set(void); @@ -97,9 +110,21 @@ void WM_init_window_focus_set(bool do_it); void WM_init_native_pixels(bool do_it); void WM_init_tablet_api(void); +/** + * Initialize Blender and load the startup file & preferences + * (only called once). + */ void WM_init(struct bContext *C, int argc, const char **argv); +/** + * \note doesn't run exit() call #WM_exit() for that. + */ void WM_exit_ex(struct bContext *C, const bool do_python); +/** + * \brief Main exit function to close Blender ordinarily. + * \note Use #wm_exit_schedule_delayed() to close Blender from an operator. + * Might leak memory otherwise. + */ void WM_exit(struct bContext *C) ATTR_NORETURN; void WM_main(struct bContext *C) ATTR_NORETURN; @@ -111,6 +136,10 @@ void WM_init_opengl(void); void WM_check(struct bContext *C); void WM_reinit_gizmomap_all(struct Main *bmain); +/** + * Needed for cases when operators are re-registered + * (when operator type pointers are stored). + */ void WM_script_tag_reload(void); wmWindow *WM_window_find_under_cursor(const wmWindowManager *wm, @@ -125,13 +154,30 @@ void WM_window_pixel_sample_read(const wmWindowManager *wm, uint *WM_window_pixels_read(struct wmWindowManager *wm, struct wmWindow *win, int r_size[2]); +/** + * Support for native pixel size + * + * \note macOS retina opens window in size X, but it has up to 2 x more pixels. + */ int WM_window_pixels_x(const struct wmWindow *win); int WM_window_pixels_y(const struct wmWindow *win); +/** + * Get boundaries usable by all window contents, including global areas. + */ void WM_window_rect_calc(const struct wmWindow *win, struct rcti *r_rect); +/** + * Get boundaries usable by screen-layouts, excluding global areas. + * \note Depends on #U.dpi_fac. Should that be outdated, call #WM_window_set_dpi first. + */ void WM_window_screen_rect_calc(const struct wmWindow *win, struct rcti *r_rect); bool WM_window_is_fullscreen(const struct wmWindow *win); bool WM_window_is_maximized(const struct wmWindow *win); +/** + * Some editor data may need to be synced with scene data (3D View camera and layers). + * This function ensures data is synced for editors + * in visible work-spaces and their visible layouts. + */ void WM_windows_scene_data_sync(const ListBase *win_lb, struct Scene *scene) ATTR_NONNULL(); struct Scene *WM_windows_scene_get_from_screen(const struct wmWindowManager *wm, const struct bScreen *screen) @@ -145,6 +191,9 @@ struct WorkSpace *WM_windows_workspace_get_from_screen(const wmWindowManager *wm struct Scene *WM_window_get_active_scene(const struct wmWindow *win) ATTR_NONNULL() ATTR_WARN_UNUSED_RESULT; +/** + * \warning Only call outside of area/region loops. + */ void WM_window_set_active_scene(struct Main *bmain, struct bContext *C, struct wmWindow *win, @@ -159,6 +208,9 @@ struct WorkSpaceLayout *WM_window_get_active_layout(const struct wmWindow *win) void WM_window_set_active_layout(struct wmWindow *win, struct WorkSpace *workspace, struct WorkSpaceLayout *layout) ATTR_NONNULL(1); +/** + * Get the active screen of the active workspace in \a win. + */ struct bScreen *WM_window_get_active_screen(const struct wmWindow *win) ATTR_NONNULL() ATTR_WARN_UNUSED_RESULT; void WM_window_set_active_screen(struct wmWindow *win, @@ -185,6 +237,14 @@ typedef enum eWindowAlignment { WIN_ALIGN_PARENT_CENTER, } eWindowAlignment; +/** + * \param space_type: SPACE_VIEW3D, SPACE_INFO, ... (eSpace_Type) + * \param toplevel: Not a child owned by other windows. A peer of main window. + * \param dialog: whether this should be made as a dialog-style window + * \param temp: whether this is considered a short-lived window + * \param alignment: how this window is positioned relative to its parent + * \return the window or NULL in case of failure. + */ struct wmWindow *WM_window_open(struct bContext *C, const char *title, int x, @@ -208,6 +268,10 @@ void WM_autosave_init(struct wmWindowManager *wm); bool WM_recover_last_session(struct bContext *C, struct ReportList *reports); void WM_file_tag_modified(void); +/** + * \note `scene` (and related `view_layer` and `v3d`) pointers may be NULL, + * in which case no instantiation of linked objects, collections etc. will be performed. + */ struct ID *WM_file_link_datablock(struct Main *bmain, struct Scene *scene, struct ViewLayer *view_layer, @@ -216,6 +280,10 @@ struct ID *WM_file_link_datablock(struct Main *bmain, const short id_code, const char *id_name, int flag); +/** + * \note `scene` (and related `view_layer` and `v3d`) pointers may be NULL, + * in which case no instantiation of appended objects, collections etc. will be performed. + */ struct ID *WM_file_append_datablock(struct Main *bmain, struct Scene *scene, struct ViewLayer *view_layer, @@ -226,14 +294,24 @@ struct ID *WM_file_append_datablock(struct Main *bmain, int flag); void WM_lib_reload(struct Library *lib, struct bContext *C, struct ReportList *reports); -/* mouse cursors */ +/* Mouse cursors. */ + void WM_cursor_set(struct wmWindow *win, int curs); bool WM_cursor_set_from_tool(struct wmWindow *win, const ScrArea *area, const ARegion *region); void WM_cursor_modal_set(struct wmWindow *win, int val); void WM_cursor_modal_restore(struct wmWindow *win); +/** + * To allow usage all over, we do entire WM. + */ void WM_cursor_wait(bool val); +/** + * \param bounds: can be NULL + */ void WM_cursor_grab_enable(struct wmWindow *win, int wrap, bool hide, int bounds[4]); void WM_cursor_grab_disable(struct wmWindow *win, const int mouse_ungrab_xy[2]); +/** + * After this you can call restore too. + */ void WM_cursor_time(struct wmWindow *win, int nr); struct wmPaintCursor *WM_paint_cursor_activate( @@ -249,10 +327,16 @@ void WM_paint_cursor_remove_by_type(struct wmWindowManager *wm, void (*free)(void *)); void WM_paint_cursor_tag_redraw(struct wmWindow *win, struct ARegion *region); +/** + * This function requires access to the GHOST_SystemHandle (g_system). + */ void WM_cursor_warp(struct wmWindow *win, int x, int y); +/** + * Set x, y to values we can actually position the cursor to. + */ void WM_cursor_compatible_xy(wmWindow *win, int *x, int *y); -/* handlers */ +/* Handlers. */ typedef bool (*EventHandlerPoll)(const ARegion *region, const struct wmEvent *event); struct wmEventHandler_Keymap *WM_event_add_keymap_handler(ListBase *handlers, wmKeyMap *keymap); @@ -261,7 +345,9 @@ struct wmEventHandler_Keymap *WM_event_add_keymap_handler_poll(ListBase *handler EventHandlerPoll poll); struct wmEventHandler_Keymap *WM_event_add_keymap_handler_v2d_mask(ListBase *handlers, wmKeyMap *keymap); -/* priority not implemented, it adds in begin */ +/** + * \note Priorities not implemented yet, for time being just insert in begin of list. + */ struct wmEventHandler_Keymap *WM_event_add_keymap_handler_priority(ListBase *handlers, wmKeyMap *keymap, int priority); @@ -319,6 +405,10 @@ struct wmEventHandler_UI *WM_event_add_ui_handler(const struct bContext *C, wmUIHandlerRemoveFunc remove_fn, void *user_data, const char flag); +/** + * \param postpone: Enable for `win->modalhandlers`, + * this is in a running for () loop in wm_handlers_do(). + */ void WM_event_remove_ui_handler(ListBase *handlers, wmUIHandlerFunc handle_fn, wmUIHandlerRemoveFunc remove_fn, @@ -331,13 +421,24 @@ void WM_event_free_ui_handler_all(struct bContext *C, wmUIHandlerRemoveFunc remove_fn); struct wmEventHandler_Op *WM_event_add_modal_handler(struct bContext *C, struct wmOperator *op); +/** + * Modal handlers store a pointer to an area which might be freed while the handler runs. + * Use this function to NULL all handler pointers to \a old_area. + */ void WM_event_modal_handler_area_replace(wmWindow *win, const struct ScrArea *old_area, struct ScrArea *new_area); +/** + * Modal handlers store a pointer to a region which might be freed while the handler runs. + * Use this function to NULL all handler pointers to \a old_region. + */ void WM_event_modal_handler_region_replace(wmWindow *win, const struct ARegion *old_region, struct ARegion *new_region); +/** + * Called on exit or remove area, only here call cancel callback. + */ void WM_event_remove_handlers(struct bContext *C, ListBase *handlers); /* handler flag */ @@ -366,11 +467,20 @@ void WM_event_add_notifier_ex(struct wmWindowManager *wm, void *reference); void WM_event_add_notifier(const struct bContext *C, unsigned int type, void *reference); void WM_main_add_notifier(unsigned int type, void *reference); +/** + * Clear notifiers by reference, Used so listeners don't act on freed data. + */ void WM_main_remove_notifier_reference(const void *reference); void WM_main_remap_editor_id_reference(struct ID *old_id, struct ID *new_id); /* reports */ +/** + * Show the report in the info header. + */ void WM_report_banner_show(void); +/** + * Hide all currently displayed banners and abort their timer. + */ void WM_report_banners_cancel(struct Main *bmain); void WM_report(eReportType type, const char *message); void WM_reportf(eReportType type, const char *format, ...) ATTR_PRINTF_FORMAT(2, 3); @@ -398,44 +508,87 @@ void WM_event_remove_timer(struct wmWindowManager *wm, void WM_event_remove_timer_notifier(struct wmWindowManager *wm, struct wmWindow *win, struct wmTimer *timer); +/** + * To (de)activate running timers temporary. + */ void WM_event_timer_sleep(struct wmWindowManager *wm, struct wmWindow *win, struct wmTimer *timer, bool do_sleep); -/* operator api, default callbacks */ -/* invoke callback, uses enum property named "type" */ +/* Operator API, default callbacks. */ + +/** + * Helper to get select and tweak-transform to work conflict free and as desired. See + * #WM_operator_properties_generic_select() for details. + * + * To be used together with #WM_generic_select_invoke() and + * #WM_operator_properties_generic_select(). + */ int WM_generic_select_modal(struct bContext *C, struct wmOperator *op, const struct wmEvent *event); +/** + * Helper to get select and tweak-transform to work conflict free and as desired. See + * #WM_operator_properties_generic_select() for details. + * + * To be used together with #WM_generic_select_modal() and + * #WM_operator_properties_generic_select(). + */ int WM_generic_select_invoke(struct bContext *C, struct wmOperator *op, const struct wmEvent *event); void WM_operator_view3d_unit_defaults(struct bContext *C, struct wmOperator *op); int WM_operator_smooth_viewtx_get(const struct wmOperator *op); +/** + * Invoke callback, uses enum property named "type". + */ int WM_menu_invoke_ex(struct bContext *C, struct wmOperator *op, wmOperatorCallContext opcontext); int WM_menu_invoke(struct bContext *C, struct wmOperator *op, const struct wmEvent *event); +/** + * Call an existent menu. The menu can be created in C or Python. + */ void WM_menu_name_call(struct bContext *C, const char *menu_name, short context); +/** + * Similar to #WM_enum_search_invoke, but draws previews. Also, this can't + * be used as invoke callback directly since it needs additional info. + */ int WM_enum_search_invoke_previews(struct bContext *C, struct wmOperator *op, short prv_cols, short prv_rows); int WM_enum_search_invoke(struct bContext *C, struct wmOperator *op, const struct wmEvent *event); -/* invoke callback, confirm menu + exec */ +/** + * Invoke callback, confirm menu + exec. + */ int WM_operator_confirm(struct bContext *C, struct wmOperator *op, const struct wmEvent *event); int WM_operator_confirm_or_exec(struct bContext *C, struct wmOperator *op, const struct wmEvent *event); -/* invoke callback, file selector "filepath" unset + exec */ +/** + * Invoke callback, file selector "filepath" unset + exec. + * + * #wmOperatorType.invoke, opens file-select if path property not set, otherwise executes. + */ int WM_operator_filesel(struct bContext *C, struct wmOperator *op, const struct wmEvent *event); bool WM_operator_filesel_ensure_ext_imtype(wmOperator *op, const struct ImageFormatData *im_format); -/* poll callback, context checks */ +/** Callback for #wmOperatorType.poll */ bool WM_operator_winactive(struct bContext *C); -/* invoke callback, exec + redo popup */ +/** + * Invoke callback, exec + redo popup. + * + * Same as #WM_operator_props_popup but don't use operator redo. + * just wraps #WM_operator_props_dialog_popup. + */ int WM_operator_props_popup_confirm(struct bContext *C, struct wmOperator *op, const struct wmEvent *event); +/** + * Same as #WM_operator_props_popup but call the operator first, + * This way - the button values correspond to the result of the operator. + * Without this, first access to a button will make the result jump, see T32452. + */ int WM_operator_props_popup_call(struct bContext *C, struct wmOperator *op, const struct wmEvent *event); @@ -446,6 +599,9 @@ int WM_operator_props_dialog_popup(struct bContext *C, struct wmOperator *op, in int WM_operator_redo_popup(struct bContext *C, struct wmOperator *op); int WM_operator_ui_popup(struct bContext *C, struct wmOperator *op, int width); +/** + * Can't be used as an invoke directly, needs message arg (can be NULL). + */ int WM_operator_confirm_message_ex(struct bContext *C, struct wmOperator *op, const char *title, @@ -454,24 +610,60 @@ int WM_operator_confirm_message_ex(struct bContext *C, const wmOperatorCallContext opcontext); int WM_operator_confirm_message(struct bContext *C, struct wmOperator *op, const char *message); -/* operator api */ +/* Operator API. */ + void WM_operator_free(struct wmOperator *op); void WM_operator_free_all_after(wmWindowManager *wm, struct wmOperator *op); +/** + * Use with extreme care! + * Properties, custom-data etc - must be compatible. + * + * \param op: Operator to assign the type to. + * \param ot: Operator type to assign. + */ void WM_operator_type_set(struct wmOperator *op, struct wmOperatorType *ot); void WM_operator_stack_clear(struct wmWindowManager *wm); +/** + * This function is needed in the case when an addon id disabled + * while a modal operator it defined is running. + */ void WM_operator_handlers_clear(wmWindowManager *wm, struct wmOperatorType *ot); bool WM_operator_poll(struct bContext *C, struct wmOperatorType *ot); bool WM_operator_poll_context(struct bContext *C, struct wmOperatorType *ot, short context); +/** + * For running operators with frozen context (modal handlers, menus). + * + * \param store: Store settings for re-use. + * + * \warning do not use this within an operator to call its self! T29537. + */ int WM_operator_call_ex(struct bContext *C, struct wmOperator *op, const bool store); int WM_operator_call(struct bContext *C, struct wmOperator *op); +/** + * This is intended to be used when an invoke operator wants to call exec on its self + * and is basically like running op->type->exec() directly, no poll checks no freeing, + * since we assume whoever called invoke will take care of that + */ int WM_operator_call_notest(struct bContext *C, struct wmOperator *op); +/** + * Execute this operator again, put here so it can share above code + */ int WM_operator_repeat(struct bContext *C, struct wmOperator *op); int WM_operator_repeat_last(struct bContext *C, struct wmOperator *op); +/** + * \return true if #WM_operator_repeat can run. + * Simple check for now but may become more involved. + * To be sure the operator can run call `WM_operator_poll(C, op->type)` also, since this call + * checks if #WM_operator_repeat() can run at all, not that it WILL run at any time. + */ bool WM_operator_repeat_check(const struct bContext *C, struct wmOperator *op); bool WM_operator_is_repeat(const struct bContext *C, const struct wmOperator *op); bool WM_operator_name_poll(struct bContext *C, const char *opstring); +/** + * Invokes operator in context. + */ int WM_operator_name_call_ptr(struct bContext *C, struct wmOperatorType *ot, wmOperatorCallContext context, @@ -484,6 +676,13 @@ int WM_operator_name_call_with_properties(struct bContext *C, const char *opstring, wmOperatorCallContext context, struct IDProperty *properties); +/** + * Similar to #WM_operator_name_call called with #WM_OP_EXEC_DEFAULT context. + * + * - #wmOperatorType is used instead of operator name since python already has the operator type. + * - `poll()` must be called by python before this runs. + * - reports can be passed to this function (so python can report them as exceptions). + */ int WM_operator_call_py(struct bContext *C, struct wmOperatorType *ot, wmOperatorCallContext context, @@ -497,15 +696,30 @@ void WM_operator_name_call_ptr_with_depends_on_cursor(struct bContext *C, PointerRNA *properties, const char *drawstr); -/* Used for keymap and macro items. */ +/** + * Similar to the function above except its uses ID properties used for key-maps and macros. + */ void WM_operator_properties_alloc(struct PointerRNA **ptr, struct IDProperty **properties, const char *opstring); -/* Make props context sensitive or not. */ +/** + * Make props context sensitive or not. + */ void WM_operator_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 operators here. + * This could be made a general function. + */ bool WM_operator_properties_default(struct PointerRNA *ptr, const bool do_update); +/** + * Remove all props without #PROP_SKIP_SAVE. + */ void WM_operator_properties_reset(struct wmOperator *op); void WM_operator_properties_create(struct PointerRNA *ptr, const char *opstring); void WM_operator_properties_create_ptr(struct PointerRNA *ptr, struct wmOperatorType *ot); @@ -513,18 +727,28 @@ void WM_operator_properties_clear(struct PointerRNA *ptr); void WM_operator_properties_free(struct PointerRNA *ptr); bool WM_operator_check_ui_empty(struct wmOperatorType *ot); +/** + * Return false, if the UI should be disabled. + */ bool WM_operator_check_ui_enabled(const struct bContext *C, const char *idname); IDProperty *WM_operator_last_properties_ensure_idprops(struct wmOperatorType *ot); void WM_operator_last_properties_ensure(struct wmOperatorType *ot, struct PointerRNA *ptr); wmOperator *WM_operator_last_redo(const struct bContext *C); +/** + * Use for drag & drop a path or name with operators invoke() function. + */ ID *WM_operator_drop_load_path(struct bContext *C, struct wmOperator *op, const short idcode); bool WM_operator_last_properties_init(struct wmOperator *op); bool WM_operator_last_properties_store(struct wmOperator *op); /* wm_operator_props.c */ + void WM_operator_properties_confirm_or_exec(struct wmOperatorType *ot); +/** + * Default properties for file-select. + */ void WM_operator_properties_filesel(struct wmOperatorType *ot, int filter, short type, @@ -532,36 +756,91 @@ void WM_operator_properties_filesel(struct wmOperatorType *ot, short flag, short display, short sort); +/** + * Disable using cursor position, + * use when view operators are initialized from buttons. + */ void WM_operator_properties_use_cursor_init(struct wmOperatorType *ot); void WM_operator_properties_border(struct wmOperatorType *ot); void WM_operator_properties_border_to_rcti(struct wmOperator *op, struct rcti *rect); void WM_operator_properties_border_to_rctf(struct wmOperator *op, rctf *rect); +/** + * Use with #WM_gesture_box_invoke + */ void WM_operator_properties_gesture_box_ex(struct wmOperatorType *ot, bool deselect, bool extend); void WM_operator_properties_gesture_box(struct wmOperatorType *ot); void WM_operator_properties_gesture_box_select(struct wmOperatorType *ot); void WM_operator_properties_gesture_box_zoom(struct wmOperatorType *ot); +/** + * Use with #WM_gesture_lasso_invoke + */ void WM_operator_properties_gesture_lasso(struct wmOperatorType *ot); +/** + * Use with #WM_gesture_straightline_invoke + */ void WM_operator_properties_gesture_straightline(struct wmOperatorType *ot, int cursor); +/** + * Use with #WM_gesture_circle_invoke + */ void WM_operator_properties_gesture_circle(struct wmOperatorType *ot); void WM_operator_properties_mouse_select(struct wmOperatorType *ot); void WM_operator_properties_select_all(struct wmOperatorType *ot); void WM_operator_properties_select_action(struct wmOperatorType *ot, int default_action, bool hide_gui); +/** + * Only #SELECT / #DESELECT. + */ void WM_operator_properties_select_action_simple(struct wmOperatorType *ot, int default_action, bool hide_gui); +/** + * Use for all select random operators. + * Adds properties: percent, seed, action. + */ void WM_operator_properties_select_random(struct wmOperatorType *ot); int WM_operator_properties_select_random_seed_increment_get(wmOperator *op); void WM_operator_properties_select_operation(struct wmOperatorType *ot); +/** + * \note Some tools don't support XOR/AND. + */ void WM_operator_properties_select_operation_simple(struct wmOperatorType *ot); void WM_operator_properties_select_walk_direction(struct wmOperatorType *ot); +/** + * Selecting and tweaking items are overlapping operations. Getting both to work without conflicts + * requires special care. See + * https://wiki.blender.org/wiki/Human_Interface_Guidelines/Selection#Select-tweaking for the + * desired behavior. + * + * For default click selection (with no modifier keys held), the select operators can do the + * following: + * - On a mouse press on an unselected item, change selection and finish immediately after. + * This sends an undo push and allows transform to take over should a tweak event be caught now. + * - On a mouse press on a selected item, don't change selection state, but start modal execution + * of the operator. Idea is that we wait with deselecting other items until we know that the + * intention wasn't to tweak (mouse press+drag) all selected items. + * - If a tweak is recognized before the release event happens, cancel the operator, so that + * transform can take over and no undo-push is sent. + * - If the release event occurs rather than a tweak one, deselect all items but the one under the + * cursor, and finish the modal operator. + * + * This utility, together with #WM_generic_select_invoke() and #WM_generic_select_modal() should + * help getting the wanted behavior to work. Most generic logic should be handled in these, so that + * the select operators only have to care for the case dependent handling. + * + * Every select operator has slightly different requirements, e.g. sequencer strip selection + * also needs to account for handle selection. This should be the baseline behavior though. + */ void WM_operator_properties_generic_select(struct wmOperatorType *ot); + struct CheckerIntervalParams { int nth; /* bypass when set to zero */ int skip; int offset; }; +/** + * \param nth_can_disable: Enable if we want to be able to select no interval at all. + */ void WM_operator_properties_checker_interval(struct wmOperatorType *ot, bool nth_can_disable); void WM_operator_properties_checker_interval_from_op(struct wmOperator *op, struct CheckerIntervalParams *op_params); @@ -578,7 +857,17 @@ bool WM_operator_properties_checker_interval_test(const struct CheckerIntervalPa /* Show the properties sidebar by default. */ #define WM_FILESEL_SHOW_PROPS (1 << 5) -/* operator as a python command (resultuing string must be freed) */ +/** + * Operator as a Python command (resulting string must be freed). + * + * Print a string representation of the operator, + * with the arguments that it runs so Python can run it again. + * + * When calling from an existing #wmOperator, better to use simple version: + * `WM_operator_pystring(C, op);` + * + * \note Both \a op and \a opptr may be `NULL` (\a op is only used for macro operators). + */ char *WM_operator_pystring_ex(struct bContext *C, struct wmOperator *op, const bool all_args, @@ -589,16 +878,32 @@ char *WM_operator_pystring(struct bContext *C, struct wmOperator *op, const bool all_args, const bool macro_args); +/** + * \return true if the string was shortened. + */ bool WM_operator_pystring_abbreviate(char *str, int str_len_max); char *WM_prop_pystring_assign(struct bContext *C, struct PointerRNA *ptr, struct PropertyRNA *prop, int index); +/** + * Convert: `some.op` -> `SOME_OT_op` or leave as-is. + */ void WM_operator_bl_idname(char *to, const char *from); +/** + * Convert: `SOME_OT_op` -> `some.op` or leave as-is. + */ void WM_operator_py_idname(char *to, const char *from); +/** + * Sanity check to ensure #WM_operator_bl_idname won't fail. + * \returns true when there are no problems with \a idname, otherwise report an error. + */ bool WM_operator_py_idname_ok_or_report(struct ReportList *reports, const char *classname, const char *idname); +/** + * Calculate the path to `ptr` from context `C`, or return NULL if it can't be calculated. + */ char *WM_context_path_resolve_property_full(const struct bContext *C, const PointerRNA *ptr, PropertyRNA *prop, @@ -606,16 +911,46 @@ char *WM_context_path_resolve_property_full(const struct bContext *C, char *WM_context_path_resolve_full(struct bContext *C, const PointerRNA *ptr); /* wm_operator_type.c */ + struct wmOperatorType *WM_operatortype_find(const char *idname, bool quiet); +/** + * \note Caller must free. + */ void WM_operatortype_iter(struct GHashIterator *ghi); void WM_operatortype_append(void (*opfunc)(struct wmOperatorType *)); void WM_operatortype_append_ptr(void (*opfunc)(struct wmOperatorType *, void *), void *userdata); void WM_operatortype_append_macro_ptr(void (*opfunc)(struct wmOperatorType *, void *), void *userdata); +/** + * Called on initialize WM_exit(). + */ void WM_operatortype_remove_ptr(struct wmOperatorType *ot); bool WM_operatortype_remove(const char *idname); +/** + * Remove memory of all previously executed tools. + */ void WM_operatortype_last_properties_clear_all(void); +/** + * Tag all operator-properties of \a ot defined after calling this, until + * the next #WM_operatortype_props_advanced_end call (if available), with + * #OP_PROP_TAG_ADVANCED. Previously defined ones properties not touched. + * + * Calling this multiple times without a call to #WM_operatortype_props_advanced_end, + * all calls after the first one are ignored. Meaning all proprieties defined after the + * first call are tagged as advanced. + * + * This doesn't do the actual tagging, #WM_operatortype_props_advanced_end does which is + * called for all operators during registration (see #wm_operatortype_append__end). + */ void WM_operatortype_props_advanced_begin(struct wmOperatorType *ot); +/** + * Tags all operator-properties of \a ot defined since the first + * #WM_operatortype_props_advanced_begin call, + * or the last #WM_operatortype_props_advanced_end call, with #OP_PROP_TAG_ADVANCED. + * + * \note This is called for all operators during registration (see #wm_operatortype_append__end). + * So it does not need to be explicitly called in operator-type definition. + */ void WM_operatortype_props_advanced_end(struct wmOperatorType *ot); #define WM_operatortype_prop_tag(property, tags) \ @@ -625,6 +960,9 @@ void WM_operatortype_props_advanced_end(struct wmOperatorType *ot); } \ (void)0 +/** + * \note Names have to be static for now. + */ struct wmOperatorType *WM_operatortype_append_macro(const char *idname, const char *name, const char *description, @@ -636,26 +974,57 @@ const char *WM_operatortype_name(struct wmOperatorType *ot, struct PointerRNA *p char *WM_operatortype_description(struct bContext *C, struct wmOperatorType *ot, struct PointerRNA *properties); +/** + * Use when we want a label, preferring the description. + */ char *WM_operatortype_description_or_name(struct bContext *C, struct wmOperatorType *ot, struct PointerRNA *properties); /* wm_operator_utils.c */ + +/** + * Allow an operator with only and execute function to run modally, + * re-doing the action, using vertex coordinate store/restore instead of operator undo. + */ void WM_operator_type_modal_from_exec_for_object_edit_coords(struct wmOperatorType *ot); /* wm_uilist_type.c */ + +/** + * Called on initialize #WM_init() + */ void WM_uilisttype_init(void); struct uiListType *WM_uilisttype_find(const char *idname, bool quiet); bool WM_uilisttype_add(struct uiListType *ult); void WM_uilisttype_remove_ptr(struct Main *bmain, struct uiListType *ult); void WM_uilisttype_free(void); +/** + * The "full" list-ID is an internal name used for storing and identifying a list. It is built like + * this: + * "{uiListType.idname}_{list_id}", whereby "list_id" is an optional parameter passed to + * `UILayout.template_list()`. If it is not set, the full list-ID is just "{uiListType.idname}_". + * + * Note that whenever the Python API refers to the list-ID, it's the short, "non-full" one it + * passed to `UILayout.template_list()`. C code can query that through + * #WM_uilisttype_list_id_get(). + */ void WM_uilisttype_to_full_list_id(const struct uiListType *ult, const char *list_id, char r_full_list_id[]); +/** + * Get the "non-full" list-ID, see #WM_uilisttype_to_full_list_id() for details. + * + * \note Assumes `uiList.list_id` was set using #WM_uilisttype_to_full_list_id()! + */ const char *WM_uilisttype_list_id_get(const struct uiListType *ult, struct uiList *list); /* wm_menu_type.c */ + +/** + * \note Called on initialize #WM_init(). + */ void WM_menutype_init(void); struct MenuType *WM_menutype_find(const char *idname, bool quiet); void WM_menutype_iter(struct GHashIterator *ghi); @@ -665,6 +1034,10 @@ void WM_menutype_free(void); bool WM_menutype_poll(struct bContext *C, struct MenuType *mt); /* wm_panel_type.c */ + +/** + * Called on initialize #WM_init(). + */ void WM_paneltype_init(void); void WM_paneltype_clear(void); struct PanelType *WM_paneltype_find(const char *idname, bool quiet); @@ -692,6 +1065,11 @@ int WM_gesture_lasso_invoke(struct bContext *C, const struct wmEvent *event); int WM_gesture_lasso_modal(struct bContext *C, struct wmOperator *op, const struct wmEvent *event); void WM_gesture_lasso_cancel(struct bContext *C, struct wmOperator *op); +/** + * helper function, we may want to add options for conversion to view space + * + * caller must free. + */ const int (*WM_gesture_lasso_path_to_array(struct bContext *C, struct wmOperator *op, int *mcoords_len))[2]; @@ -699,18 +1077,38 @@ const int (*WM_gesture_lasso_path_to_array(struct bContext *C, int WM_gesture_straightline_invoke(struct bContext *C, struct wmOperator *op, const struct wmEvent *event); +/** + * This invoke callback starts the straight-line gesture with a viewport preview to the right side + * of the line. + */ int WM_gesture_straightline_active_side_invoke(struct bContext *C, struct wmOperator *op, const struct wmEvent *event); +/** + * This modal callback calls exec once per mouse move event while the gesture is active with the + * updated line start and end values, so it can be used for tools that have a real time preview + * (like a gradient updating in real time over the mesh). + */ int WM_gesture_straightline_modal(struct bContext *C, struct wmOperator *op, const struct wmEvent *event); +/** + * This modal one-shot callback only calls exec once after the gesture finishes without any updates + * during the gesture execution. Should be used for operations that are intended to be applied once + * without real time preview (like a trimming tool that only applies the bisect operation once + * after finishing the gesture as the bisect operation is too heavy to be computed in real time for + * a preview). + */ int WM_gesture_straightline_oneshot_modal(struct bContext *C, struct wmOperator *op, const struct wmEvent *event); void WM_gesture_straightline_cancel(struct bContext *C, struct wmOperator *op); /* Gesture manager API */ + +/** + * Context checked on having screen, window and area. + */ struct wmGesture *WM_gesture_new(struct wmWindow *window, const struct ARegion *region, const struct wmEvent *event, @@ -720,15 +1118,34 @@ void WM_gestures_remove(struct wmWindow *win); void WM_gestures_free_all(struct wmWindow *win); bool WM_gesture_is_modal_first(const struct wmGesture *gesture); -/* fileselecting support */ +/* File-selecting support. */ + +/** + * The idea here is to keep a handler alive on window queue, owning the operator. + * The file window can send event to make it execute, thus ensuring + * executing happens outside of lower level queues, with UI refreshed. + * Should also allow multi-window solutions. + */ void WM_event_add_fileselect(struct bContext *C, struct wmOperator *op); void WM_event_fileselect_event(struct wmWindowManager *wm, void *ophandle, int eventval); +/** + * Sets the active region for this space from the context. + * + * \see #BKE_area_find_region_active_win + */ void WM_operator_region_active_win_set(struct bContext *C); +/** + * Only finish + pass through for press events (allowing press-tweak). + */ int WM_operator_flag_only_pass_through_on_press(int retval, const struct wmEvent *event); -/* drag and drop */ +/* Drag and drop. */ + +/** + * Note that the pointer should be valid allocated and not on stack. + */ struct wmDrag *WM_event_start_drag( struct bContext *C, int icon, int type, void *poin, double value, unsigned int flags); void WM_event_drag_image(struct wmDrag *, struct ImBuf *, float scale, int sx, int sy); @@ -750,30 +1167,63 @@ void WM_drag_draw_default_fn(struct bContext *C, struct wmWindow *win, struct wmDrag *drag, const int xy[2]); +/** + * `spaceid` / `regionid` are zero for window drop maps. + */ ListBase *WM_dropboxmap_find(const char *idname, int spaceid, int regionid); /* ID drag and drop */ + +/** + * \param flag_extra: Additional linking flags (from #eFileSel_Params_Flag). + */ ID *WM_drag_asset_id_import(wmDragAsset *asset_drag, int flag_extra); bool WM_drag_asset_will_import_linked(const wmDrag *drag); void WM_drag_add_local_ID(struct wmDrag *drag, struct ID *id, struct ID *from_parent); struct ID *WM_drag_get_local_ID(const struct wmDrag *drag, short idcode); struct ID *WM_drag_get_local_ID_from_event(const struct wmEvent *event, short idcode); +/** + * Check if the drag data is either a local ID or an external ID asset of type \a idcode. + */ bool WM_drag_is_ID_type(const struct wmDrag *drag, int idcode); +/** + * \note: Does not store \a asset in any way, so it's fine to pass a temporary. + */ wmDragAsset *WM_drag_create_asset_data(const struct AssetHandle *asset, struct AssetMetaData *metadata, const char *path, int import_type); struct wmDragAsset *WM_drag_get_asset_data(const struct wmDrag *drag, int idcode); struct AssetMetaData *WM_drag_get_asset_meta_data(const struct wmDrag *drag, int idcode); +/** + * When dragging a local ID, return that. Otherwise, if dragging an asset-handle, link or append + * that depending on what was chosen by the drag-box (currently append only in fact). + * + * Use #WM_drag_free_imported_drag_ID() as cancel callback of the drop-box, so that the asset + * import is rolled back if the drop operator fails. + * + * \param flag: #eFileSel_Params_Flag passed to linking code. + */ struct ID *WM_drag_get_local_ID_or_import_from_asset(const struct wmDrag *drag, int idcode); +/** + * \brief Free asset ID imported for canceled drop. + * + * If the asset was imported (linked/appended) using #WM_drag_get_local_ID_or_import_from_asset()` + * (typically via a #wmDropBox.copy() callback), we want the ID to be removed again if the drop + * operator cancels. + * This is for use as #wmDropBox.cancel() callback. + */ void WM_drag_free_imported_drag_ID(struct Main *bmain, struct wmDrag *drag, struct wmDropBox *drop); struct wmDragAssetCatalog *WM_drag_get_asset_catalog_data(const struct wmDrag *drag); +/** + * \note: Does not store \a asset in any way, so it's fine to pass a temporary. + */ void WM_drag_add_asset_list_item(wmDrag *drag, const struct bContext *C, const struct AssetLibraryReference *asset_library_ref, @@ -790,6 +1240,10 @@ void wmWindowViewport(struct wmWindow *win); /* OpenGL utilities with safety check */ void wmOrtho2(float x1, float x2, float y1, float y2); /* use for conventions (avoid hard-coded offsets all over) */ + +/** + * Default pixel alignment for regions. + */ void wmOrtho2_region_pixelspace(const struct ARegion *region); void wmOrtho2_pixelspace(const float x, const float y); void wmGetProjectionMatrix(float mat[4][4], const struct rcti *winrct); @@ -836,6 +1290,12 @@ enum { * if having hard coded values is a problem */ }; +/** + * \return current job or adds new job, but doesn't run it. + * + * \note every owner only gets a single job, + * adding a new one will stop running job and when stopped it starts the new one. + */ struct wmJob *WM_jobs_get(struct wmWindowManager *wm, struct wmWindow *win, const void *owner, @@ -843,9 +1303,15 @@ struct wmJob *WM_jobs_get(struct wmWindowManager *wm, int flag, int job_type); +/** + * Returns true if job runs, for UI (progress) indicators. + */ bool WM_jobs_test(const struct wmWindowManager *wm, const void *owner, int job_type); float WM_jobs_progress(const struct wmWindowManager *wm, const void *owner); const char *WM_jobs_name(const struct wmWindowManager *wm, const void *owner); +/** + * Time that job started. + */ double WM_jobs_starttime(const struct wmWindowManager *wm, const void *owner); void *WM_jobs_customdata(struct wmWindowManager *wm, const void *owner); void *WM_jobs_customdata_from_type(struct wmWindowManager *wm, int job_type); @@ -867,12 +1333,28 @@ void WM_jobs_callbacks(struct wmJob *, void (*update)(void *), void (*endjob)(void *)); +/** + * If job running, the same owner gave it a new job. + * if different owner starts existing startjob, it suspends itself + */ void WM_jobs_start(struct wmWindowManager *wm, struct wmJob *); +/** + * Signal job(s) from this owner or callback to stop, timer is required to get handled. + */ void WM_jobs_stop(struct wmWindowManager *wm, const void *owner, void *startjob); +/** + * Actually terminate thread and job timer. + */ void WM_jobs_kill(struct wmWindowManager *wm, void *owner, void (*)(void *, short int *, short int *, float *)); +/** + * Wait until every job ended. + */ void WM_jobs_kill_all(struct wmWindowManager *wm); +/** + * Wait until every job ended, except for one owner (used in undo to keep screen job alive). + */ void WM_jobs_kill_all_except(struct wmWindowManager *wm, const void *owner); void WM_jobs_kill_type(struct wmWindowManager *wm, const void *owner, int job_type); @@ -881,16 +1363,27 @@ bool WM_jobs_has_running(const struct wmWindowManager *wm); void WM_job_main_thread_lock_acquire(struct wmJob *job); void WM_job_main_thread_lock_release(struct wmJob *job); -/* clipboard */ +/* Clipboard. */ + +/** + * Return text from the clipboard. + * + * \note Caller needs to check for valid utf8 if this is a requirement. + */ char *WM_clipboard_text_get(bool selection, int *r_len); +/** + * Convenience function for pasting to areas of Blender which don't support newlines. + */ char *WM_clipboard_text_get_firstline(bool selection, int *r_len); void WM_clipboard_text_set(const char *buf, bool selection); /* progress */ + void WM_progress_set(struct wmWindow *win, float progress); void WM_progress_clear(struct wmWindow *win); /* Draw (for screenshot) */ + void *WM_draw_cb_activate(struct wmWindow *win, void (*draw)(const struct wmWindow *, void *), void *customdata); @@ -902,21 +1395,29 @@ void WM_draw_region_viewport_bind(struct ARegion *region); void WM_draw_region_viewport_unbind(struct ARegion *region); /* Region drawing */ + void WM_draw_region_free(struct ARegion *region, bool hide); struct GPUViewport *WM_draw_region_get_viewport(struct ARegion *region); struct GPUViewport *WM_draw_region_get_bound_viewport(struct ARegion *region); void WM_main_playanim(int argc, const char **argv); -/* debugging only, convenience function to write on crash */ +/** + * Debugging only, convenience function to write on crash. + * Convenient to save a blend file from a debugger. + */ bool write_crash_blend(void); -/* Lock the interface for any communication */ +/** + * Lock the interface for any communication. + */ void WM_set_locked_interface(struct wmWindowManager *wm, bool lock); void WM_event_tablet_data_default_set(struct wmTabletData *tablet_data); -/* For testing only 'G_FLAG_EVENT_SIMULATE' */ +/** + * For testing only, see #G_FLAG_EVENT_SIMULATE. + */ struct wmEvent *WM_event_add_simulate(struct wmWindow *win, const struct wmEvent *event_to_add); const char *WM_window_cursor_keymap_status_get(const struct wmWindow *win, @@ -925,28 +1426,60 @@ const char *WM_window_cursor_keymap_status_get(const struct wmWindow *win, void WM_window_cursor_keymap_status_refresh(struct bContext *C, struct wmWindow *win); void WM_window_status_area_tag_redraw(struct wmWindow *win); +/** + * Similar to #BKE_screen_area_map_find_area_xy and related functions, + * use here since the area is stored in the window manager. + */ struct ScrArea *WM_window_status_area_find(struct wmWindow *win, struct bScreen *screen); bool WM_window_modal_keymap_status_draw(struct bContext *C, struct wmWindow *win, struct uiLayout *layout); /* wm_event_query.c */ + +/** + * For debugging only, getting inspecting events manually is tedious. + */ void WM_event_print(const struct wmEvent *event); int WM_event_modifier_flag(const struct wmEvent *event); +/** + * For modal callbacks, check configuration for how to interpret exit with tweaks. + */ bool WM_event_is_modal_tweak_exit(const struct wmEvent *event, int tweak_event); bool WM_event_is_last_mousemove(const struct wmEvent *event); bool WM_event_is_mouse_drag(const struct wmEvent *event); bool WM_event_is_mouse_drag_or_press(const wmEvent *event); +/** + * Detect motion between selection (callers should only use this for selection picking), + * typically mouse press/click events. + * + * \param mval: Region relative coordinates, call with (-1, -1) resets the last cursor location. + * \returns True when there was motion since last called. + * + * NOTE(@campbellbarton): The logic used here isn't foolproof. + * It's possible that users move the cursor past #WM_EVENT_CURSOR_MOTION_THRESHOLD then back to + * a position within the threshold (between mouse clicks). + * In practice users never reported this since the threshold is very small (a few pixels). + * To prevent the unlikely case of values matching from another region, + * changing regions resets this value to (-1, -1). + */ bool WM_cursor_test_motion_and_update(const int mval[2]) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT; int WM_event_drag_threshold(const struct wmEvent *event); bool WM_event_drag_test(const struct wmEvent *event, const int prev_xy[2]); bool WM_event_drag_test_with_delta(const struct wmEvent *event, const int delta[2]); -/* event map */ +/** + * Event map that takes preferences into account. + */ int WM_userdef_event_map(int kmitype); +/** + * Use so we can check if 'wmEvent.type' is released in modal operators. + * + * An alternative would be to add a 'wmEvent.type_nokeymap'... or similar. + */ int WM_userdef_event_type_from_keymap_type(int kmitype); #ifdef WITH_INPUT_NDOF @@ -963,6 +1496,10 @@ void WM_event_ndof_to_quat(const struct wmNDOFMotionData *ndof, float q[4]); bool WM_event_is_xr(const struct wmEvent *event); #endif +/** + * If this is a tablet event, return tablet pressure and set `*pen_flip` + * to 1 if the eraser tool is being used, 0 otherwise. + */ float WM_event_tablet_data(const struct wmEvent *event, int *pen_flip, float tilt[2]); bool WM_event_is_tablet(const struct wmEvent *event); @@ -974,6 +1511,7 @@ bool WM_event_is_ime_switch(const struct wmEvent *event); #endif /* wm_tooltip.c */ + typedef struct ARegion *(*wmTooltipInitFn)(struct bContext *C, struct ARegion *region, int *pass, @@ -1003,6 +1541,7 @@ void WM_tooltip_refresh(struct bContext *C, struct wmWindow *win); double WM_tooltip_time_closed(void); /* wm_utils.c */ + struct wmGenericCallback *WM_generic_callback_steal(struct wmGenericCallback *callback); void WM_generic_callback_free(struct wmGenericCallback *callback); @@ -1012,7 +1551,15 @@ bool WM_region_use_viewport(struct ScrArea *area, struct ARegion *region); #ifdef WITH_XR_OPENXR /* wm_xr_session.c */ + +/** + * Check if the XR-Session was triggered. + * If an error happened while trying to start a session, this returns false too. + */ bool WM_xr_session_exists(const wmXrData *xr); +/** + * Check if the session is running, according to the OpenXR definition. + */ bool WM_xr_session_is_ready(const wmXrData *xr); struct wmXrSessionState *WM_xr_session_state_handle_get(const wmXrData *xr); struct ScrArea *WM_xr_session_area_get(const wmXrData *xr); @@ -1045,8 +1592,10 @@ void WM_xr_session_state_navigation_reset(struct wmXrSessionState *state); struct ARegionType *WM_xr_surface_controller_region_type_get(void); /* wm_xr_actions.c */ + /* XR action functions to be called pre-XR session start. * NOTE: The "destroy" functions can also be called post-session start. */ + bool WM_xr_action_set_create(wmXrData *xr, const char *action_set_name); void WM_xr_action_set_destroy(wmXrData *xr, const char *action_set_name); bool WM_xr_action_create(wmXrData *xr, @@ -1080,7 +1629,9 @@ void WM_xr_action_binding_destroy(wmXrData *xr, const char *action_name, const char *profile_path); -/* If action_set_name is NULL, then all action sets will be treated as active. */ +/** + * If action_set_name is NULL, then all action sets will be treated as active. + */ bool WM_xr_active_action_set_set(wmXrData *xr, const char *action_set_name); bool WM_xr_controller_pose_actions_set(wmXrData *xr, @@ -1088,7 +1639,9 @@ bool WM_xr_controller_pose_actions_set(wmXrData *xr, const char *grip_action_name, const char *aim_action_name); -/* XR action functions to be called post-XR session start. */ +/** + * XR action functions to be called post-XR session start. + */ bool WM_xr_action_state_get(const wmXrData *xr, const char *action_set_name, const char *action_name, @@ -1107,9 +1660,13 @@ void WM_xr_haptic_action_stop(wmXrData *xr, const char *subaction_path); /* wm_xr_actionmap.c */ + XrActionMap *WM_xr_actionmap_new(struct wmXrRuntimeData *runtime, const char *name, bool replace_existing); +/** + * Ensure unique name among all action maps. + */ void WM_xr_actionmap_ensure_unique(struct wmXrRuntimeData *runtime, XrActionMap *actionmap); XrActionMap *WM_xr_actionmap_add_copy(struct wmXrRuntimeData *runtime, XrActionMap *am_src); bool WM_xr_actionmap_remove(struct wmXrRuntimeData *runtime, XrActionMap *actionmap); @@ -1125,15 +1682,25 @@ void WM_xr_actionmap_selected_index_set(struct wmXrRuntimeData *runtime, short i XrActionMapItem *WM_xr_actionmap_item_new(XrActionMap *actionmap, const char *name, bool replace_existing); +/** + * Ensure unique name among all action map items. + */ void WM_xr_actionmap_item_ensure_unique(XrActionMap *actionmap, XrActionMapItem *ami); XrActionMapItem *WM_xr_actionmap_item_add_copy(XrActionMap *actionmap, XrActionMapItem *ami_src); bool WM_xr_actionmap_item_remove(XrActionMap *actionmap, XrActionMapItem *ami); XrActionMapItem *WM_xr_actionmap_item_find(XrActionMap *actionmap, const char *name); +/** + * Similar to #wm_xr_actionmap_item_properties_set() + * but checks for the #eXrActionType and #wmOperatorType having changed. + */ void WM_xr_actionmap_item_properties_update_ot(XrActionMapItem *ami); XrActionMapBinding *WM_xr_actionmap_binding_new(XrActionMapItem *ami, const char *name, bool replace_existing); +/** + * Ensure unique name among all action map bindings. + */ void WM_xr_actionmap_binding_ensure_unique(XrActionMapItem *ami, XrActionMapBinding *amb); XrActionMapBinding *WM_xr_actionmap_binding_add_copy(XrActionMapItem *ami, XrActionMapBinding *amb_src); diff --git a/source/blender/windowmanager/WM_keymap.h b/source/blender/windowmanager/WM_keymap.h index 0633ffe55ea..4d1f2d979cb 100644 --- a/source/blender/windowmanager/WM_keymap.h +++ b/source/blender/windowmanager/WM_keymap.h @@ -55,6 +55,9 @@ void WM_keyconfig_update_operatortype(void); void WM_keymap_clear(struct wmKeyMap *keymap); +/** + * Always add item. + */ wmKeyMapItem *WM_keymap_add_item( struct wmKeyMap *keymap, const char *idname, int type, int val, int modifier, int keymodifier); wmKeyMapItem *WM_keymap_add_item_copy(struct wmKeyMap *keymap, wmKeyMapItem *kmi_src); @@ -91,16 +94,30 @@ bool WM_keymap_item_compare(const struct wmKeyMapItem *k1, const struct wmKeyMap /* keymap_utils.c */ -/** Wrappers for #WM_keymap_add_item */ +/* Wrappers for #WM_keymap_add_item */ + +/** + * Menu wrapper for #WM_keymap_add_item. + */ wmKeyMapItem *WM_keymap_add_menu( struct wmKeyMap *keymap, const char *idname, int type, int val, int modifier, int keymodifier); +/** + * Pie-menu wrapper for #WM_keymap_add_item. + */ wmKeyMapItem *WM_keymap_add_menu_pie( struct wmKeyMap *keymap, const char *idname, int type, int val, int modifier, int keymodifier); +/** + * Panel (popover) wrapper for #WM_keymap_add_item. + */ wmKeyMapItem *WM_keymap_add_panel( struct wmKeyMap *keymap, const char *idname, int type, int val, int modifier, int keymodifier); +/** + * Tool wrapper for #WM_keymap_add_item. + */ wmKeyMapItem *WM_keymap_add_tool( struct wmKeyMap *keymap, const char *idname, int type, int val, int modifier, int keymodifier); +/** Useful for mapping numbers to an enum. */ void WM_keymap_add_context_enum_set_items(wmKeyMap *keymap, const struct EnumPropertyItem *items, const char *data_path, @@ -110,6 +127,12 @@ void WM_keymap_add_context_enum_set_items(wmKeyMap *keymap, int keymodifier); wmKeyMap *WM_keymap_guess_from_context(const struct bContext *C); + +/** + * Guess an appropriate key-map from the operator name. + * + * \note Needs to be kept up to date with Key-map and Operator naming. + */ wmKeyMap *WM_keymap_guess_opname(const struct bContext *C, const char *opname); bool WM_keymap_uses_event_modifier(const wmKeyMap *keymap, const int event_modifier); @@ -149,6 +172,9 @@ void WM_modalkeymap_assign(struct wmKeyMap *km, const char *opname); /* Keymap Editor */ void WM_keymap_restore_to_default(struct wmKeyMap *keymap, struct wmWindowManager *wm); +/** + * Properties can be NULL, otherwise the arg passed is used and ownership is given to the `kmi`. + */ void WM_keymap_item_properties_reset(struct wmKeyMapItem *kmi, struct IDProperty *properties); void WM_keymap_item_restore_to_default(wmWindowManager *wm, struct wmKeyMap *keymap, @@ -168,6 +194,10 @@ int WM_keymap_item_raw_to_string(const short shift, const bool compact, char *result, const int result_len); +/** + * \param include_mask, exclude_mask: + * Event types to include/exclude when looking up keys (#eEventType_Mask). + */ wmKeyMapItem *WM_key_event_operator(const struct bContext *C, const char *opname, wmOperatorCallContext opcontext, diff --git a/source/blender/windowmanager/WM_toolsystem.h b/source/blender/windowmanager/WM_toolsystem.h index eb89fca7b56..32b9cf1d7ba 100644 --- a/source/blender/windowmanager/WM_toolsystem.h +++ b/source/blender/windowmanager/WM_toolsystem.h @@ -69,6 +69,9 @@ void WM_toolsystem_unlink(struct bContext *C, struct WorkSpace *workspace, const void WM_toolsystem_refresh(struct bContext *C, struct WorkSpace *workspace, const bToolKey *tkey); void WM_toolsystem_reinit(struct bContext *C, struct WorkSpace *workspace, const bToolKey *tkey); +/** + * Operate on all active tools. + */ void WM_toolsystem_unlink_all(struct bContext *C, struct WorkSpace *workspace); void WM_toolsystem_refresh_all(struct bContext *C, struct WorkSpace *workspace); void WM_toolsystem_reinit_all(struct bContext *C, struct wmWindow *win); @@ -79,6 +82,12 @@ void WM_toolsystem_ref_set_from_runtime(struct bContext *C, const struct bToolRef_Runtime *tref_rt, const char *idname); +/** + * Sync the internal active state of a tool back into the tool system, + * this is needed for active brushes where the real active state is not stored in the tool system. + * + * \see #toolsystem_ref_link + */ void WM_toolsystem_ref_sync_from_context(struct Main *bmain, struct WorkSpace *workspace, struct bToolRef *tref); @@ -98,8 +107,12 @@ void WM_toolsystem_update_from_context(struct bContext *C, struct ViewLayer *view_layer, struct ScrArea *area); +/** + * For paint modes to support non-brush tools. + */ bool WM_toolsystem_active_tool_is_brush(const struct bContext *C); +/** Follow #wmMsgNotifyFn spec. */ void WM_toolsystem_do_msg_notify_tag_refresh(struct bContext *C, struct wmMsgSubscribeKey *msg_key, struct wmMsgSubscribeValue *msg_val); @@ -129,6 +142,14 @@ void WM_toolsystem_ref_properties_init_for_keymap(struct bToolRef *tref, struct PointerRNA *src_ptr, struct wmOperatorType *ot); +/** + * Use to update the active tool (shown in the top bar) in the least disruptive way. + * + * This is a little involved since there may be multiple valid active tools + * depending on the mode and space type. + * + * Used when undoing since the active mode may have changed. + */ void WM_toolsystem_refresh_active(struct bContext *C); void WM_toolsystem_refresh_screen_area(struct WorkSpace *workspace, 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 diff --git a/source/blender/windowmanager/intern/wm.c b/source/blender/windowmanager/intern/wm.c index 13ee7d7f894..40f8da63e11 100644 --- a/source/blender/windowmanager/intern/wm.c +++ b/source/blender/windowmanager/intern/wm.c @@ -341,13 +341,6 @@ void WM_operator_free_all_after(wmWindowManager *wm, struct wmOperator *op) } } -/** - * Use with extreme care!, - * properties, custom-data etc - must be compatible. - * - * \param op: Operator to assign the type to. - * \param ot: Operator type to assign. - */ void WM_operator_type_set(wmOperator *op, wmOperatorType *ot) { /* Not supported for Python. */ @@ -377,8 +370,6 @@ static void wm_reports_free(wmWindowManager *wm) WM_event_remove_timer(wm, NULL, wm->reports.reporttimer); } -/* All operations get registered in the windowmanager here. */ -/* Called on event handling by event_system.c. */ void wm_operator_register(bContext *C, wmOperator *op) { wmWindowManager *wm = CTX_wm_manager(C); @@ -415,10 +406,6 @@ void WM_operator_stack_clear(wmWindowManager *wm) WM_main_add_notifier(NC_WM | ND_HISTORY, NULL); } -/** - * This function is needed in the case when an addon id disabled - * while a modal operator it defined is running. - */ void WM_operator_handlers_clear(wmWindowManager *wm, wmOperatorType *ot) { LISTBASE_FOREACH (wmWindow *, win, &wm->windows) { @@ -551,7 +538,6 @@ void wm_clear_default_size(bContext *C) } } -/* On startup, it adds all data, for matching. */ void wm_add_default(Main *bmain, bContext *C) { wmWindowManager *wm = BKE_libblock_alloc(bmain, ID_WM, "WinMan", 0); @@ -573,7 +559,6 @@ void wm_add_default(Main *bmain, bContext *C) wm_window_make_drawable(wm, win); } -/* Context is allowed to be NULL, do not free wm itself (lib_id.c). */ void wm_close_and_free(bContext *C, wmWindowManager *wm) { if (wm->autosavetimer) { diff --git a/source/blender/windowmanager/intern/wm_cursors.c b/source/blender/windowmanager/intern/wm_cursors.c index 9c020b16234..74ec2bcd41f 100644 --- a/source/blender/windowmanager/intern/wm_cursors.c +++ b/source/blender/windowmanager/intern/wm_cursors.c @@ -222,7 +222,6 @@ void WM_cursor_modal_restore(wmWindow *win) win->lastcursor = 0; } -/* to allow usage all over, we do entire WM */ void WM_cursor_wait(bool val) { if (!G.background) { @@ -240,9 +239,6 @@ void WM_cursor_wait(bool val) } } -/** - * \param bounds: can be NULL - */ void WM_cursor_grab_enable(wmWindow *win, int wrap, bool hide, int bounds[4]) { /* Only grab cursor when not running debug. @@ -307,9 +303,10 @@ static void wm_cursor_warp_relative(wmWindow *win, int x, int y) WM_cursor_warp(win, cx + x, cy + y); } -/* give it a modal keymap one day? */ bool wm_cursor_arrow_move(wmWindow *win, const wmEvent *event) { + /* TODO: give it a modal keymap? Hard coded for now */ + if (win && event->val == KM_PRESS) { /* Must move at least this much to avoid rounding in WM_cursor_warp. */ float fac = GHOST_GetNativePixelSize(win->ghostwin); @@ -334,7 +331,6 @@ bool wm_cursor_arrow_move(wmWindow *win, const wmEvent *event) return 0; } -/* after this you can call restore too */ void WM_cursor_time(wmWindow *win, int nr) { /* 10 8x8 digits */ diff --git a/source/blender/windowmanager/intern/wm_dragdrop.c b/source/blender/windowmanager/intern/wm_dragdrop.c index bc87347b2f3..e1017c4236e 100644 --- a/source/blender/windowmanager/intern/wm_dragdrop.c +++ b/source/blender/windowmanager/intern/wm_dragdrop.c @@ -89,7 +89,6 @@ typedef struct wmDropBoxMap { } wmDropBoxMap; -/* spaceid/regionid is zero for window drop maps */ ListBase *WM_dropboxmap_find(const char *idname, int spaceid, int regionid) { LISTBASE_FOREACH (wmDropBoxMap *, dm, &dropboxes) { @@ -153,7 +152,6 @@ void wm_dropbox_free(void) /* *********************************** */ -/* note that the pointer should be valid allocated and not on stack */ wmDrag *WM_event_start_drag( struct bContext *C, int icon, int type, void *poin, double value, unsigned int flags) { @@ -208,11 +206,6 @@ wmDrag *WM_event_start_drag( return drag; } -/** - * Additional work to cleanly end dragging. Additional because this doesn't actually remove the - * drag items. Should be called whenever dragging is stopped (successful or not, also when - * canceled). - */ void wm_drags_exit(wmWindowManager *wm, wmWindow *win) { bool any_active = false; @@ -403,7 +396,6 @@ void wm_drop_prepare(bContext *C, wmDrag *drag, wmDropBox *drop) wm_drags_exit(CTX_wm_manager(C), CTX_wm_window(C)); } -/* called in inner handler loop, region context */ void wm_drags_check_ops(bContext *C, const wmEvent *event) { wmWindowManager *wm = CTX_wm_manager(C); @@ -424,11 +416,6 @@ void wm_drags_check_ops(bContext *C, const wmEvent *event) } } -/** - * The operator of a dropbox should always be executed in the context determined by the mouse - * coordinates. The dropbox poll should check the context area and region as needed. - * So this always returns #WM_OP_INVOKE_DEFAULT. - */ wmOperatorCallContext wm_drop_operator_context_get(const wmDropBox *UNUSED(drop)) { return WM_OP_INVOKE_DEFAULT; @@ -484,17 +471,11 @@ ID *WM_drag_get_local_ID_from_event(const wmEvent *event, short idcode) return WM_drag_get_local_ID(lb->first, idcode); } -/** - * Check if the drag data is either a local ID or an external ID asset of type \a idcode. - */ bool WM_drag_is_ID_type(const wmDrag *drag, int idcode) { return WM_drag_get_local_ID(drag, idcode) || WM_drag_get_asset_data(drag, idcode); } -/** - * \note: Does not store \a asset in any way, so it's fine to pass a temporary. - */ wmDragAsset *WM_drag_create_asset_data(const AssetHandle *asset, AssetMetaData *metadata, const char *path, @@ -542,9 +523,6 @@ struct AssetMetaData *WM_drag_get_asset_meta_data(const wmDrag *drag, int idcode return NULL; } -/** - * \param flag_extra: Additional linking flags (from #eFileSel_Params_Flag). - */ ID *WM_drag_asset_id_import(wmDragAsset *asset_drag, const int flag_extra) { /* Only support passing in limited flags. */ @@ -603,15 +581,6 @@ bool WM_drag_asset_will_import_linked(const wmDrag *drag) return asset_drag->import_type == FILE_ASSET_IMPORT_LINK; } -/** - * When dragging a local ID, return that. Otherwise, if dragging an asset-handle, link or append - * that depending on what was chosen by the drag-box (currently append only in fact). - * - * Use #WM_drag_free_imported_drag_ID() as cancel callback of the drop-box, so that the asset - * import is rolled back if the drop operator fails. - * - * \param flag: #eFileSel_Params_Flag passed to linking code. - */ ID *WM_drag_get_local_ID_or_import_from_asset(const wmDrag *drag, int idcode) { if (!ELEM(drag->type, WM_DRAG_ASSET, WM_DRAG_ID)) { @@ -631,14 +600,6 @@ ID *WM_drag_get_local_ID_or_import_from_asset(const wmDrag *drag, int idcode) return WM_drag_asset_id_import(asset_drag, 0); } -/** - * \brief Free asset ID imported for canceled drop. - * - * If the asset was imported (linked/appended) using #WM_drag_get_local_ID_or_import_from_asset()` - * (typically via a #wmDropBox.copy() callback), we want the ID to be removed again if the drop - * operator cancels. - * This is for use as #wmDropBox.cancel() callback. - */ void WM_drag_free_imported_drag_ID(struct Main *bmain, wmDrag *drag, wmDropBox *drop) { if (drag->type != WM_DRAG_ASSET) { @@ -673,9 +634,6 @@ wmDragAssetCatalog *WM_drag_get_asset_catalog_data(const wmDrag *drag) return drag->poin; } -/** - * \note: Does not store \a asset in any way, so it's fine to pass a temporary. - */ void WM_drag_add_asset_list_item( wmDrag *drag, /* Context only needed for the hack in #ED_asset_handle_get_full_library_path(). */ @@ -912,7 +870,6 @@ void WM_drag_draw_default_fn(bContext *C, wmWindow *win, wmDrag *drag, const int wm_drag_draw_default(C, win, drag, xy); } -/* Called in #wm_draw_window_onscreen. */ void wm_drags_draw(bContext *C, wmWindow *win) { int xy[2]; diff --git a/source/blender/windowmanager/intern/wm_event_query.c b/source/blender/windowmanager/intern/wm_event_query.c index ef733837bf7..22cd68ddbd7 100644 --- a/source/blender/windowmanager/intern/wm_event_query.c +++ b/source/blender/windowmanager/intern/wm_event_query.c @@ -71,7 +71,6 @@ static void event_ids_from_type_and_value(const short type, } } -/* for debugging only, getting inspecting events manually is tedious */ void WM_event_print(const wmEvent *event) { if (event) { @@ -218,7 +217,6 @@ bool WM_event_type_mask_test(const int event_type, const enum eEventType_Mask ma /** \name Event Motion Queries * \{ */ -/* for modal callbacks, check configuration for how to interpret exit with tweaks. */ bool WM_event_is_modal_tweak_exit(const wmEvent *event, int tweak_event) { /* if the release-confirm userpref setting is enabled, @@ -276,20 +274,6 @@ bool WM_event_is_mouse_drag_or_press(const wmEvent *event) (ISMOUSE_BUTTON(event->type) && (event->val == KM_PRESS)); } -/** - * Detect motion between selection (callers should only use this for selection picking), - * typically mouse press/click events. - * - * \param mval: Region relative coordinates, call with (-1, -1) resets the last cursor location. - * \returns True when there was motion since last called. - * - * NOTE(@campbellbarton): The logic used here isn't foolproof. - * It's possible that users move the cursor past #WM_EVENT_CURSOR_MOTION_THRESHOLD then back to - * a position within the threshold (between mouse clicks). - * In practice users never reported this since the threshold is very small (a few pixels). - * To prevent the unlikely case of values matching from another region, - * changing regions resets this value to (-1, -1). - */ bool WM_cursor_test_motion_and_update(const int mval[2]) { static int mval_prev[2] = {-1, -1}; @@ -360,11 +344,6 @@ int WM_userdef_event_map(int kmitype) return kmitype; } -/** - * Use so we can check if 'wmEvent.type' is released in modal operators. - * - * An alternative would be to add a 'wmEvent.type_nokeymap'... or similar. - */ int WM_userdef_event_type_from_keymap_type(int kmitype) { switch (kmitype) { @@ -447,7 +426,6 @@ bool WM_event_is_xr(const struct wmEvent *event) /** \name Event Tablet Input Access * \{ */ -/* applies the global tablet pressure correction curve */ float wm_pressure_curve(float pressure) { if (U.pressure_threshold_max != 0.0f) { @@ -463,8 +441,6 @@ float wm_pressure_curve(float pressure) return pressure; } -/* if this is a tablet event, return tablet pressure and set *pen_flip - * to 1 if the eraser tool is being used, 0 otherwise */ float WM_event_tablet_data(const wmEvent *event, int *pen_flip, float tilt[2]) { if (tilt) { diff --git a/source/blender/windowmanager/intern/wm_event_system.c b/source/blender/windowmanager/intern/wm_event_system.c index 0b28b6b4b57..3e9bf413c9f 100644 --- a/source/blender/windowmanager/intern/wm_event_system.c +++ b/source/blender/windowmanager/intern/wm_event_system.c @@ -288,9 +288,6 @@ void WM_main_add_notifier(unsigned int type, void *reference) note->reference = reference; } -/** - * Clear notifiers by reference, Used so listeners don't act on freed data. - */ void WM_main_remove_notifier_reference(const void *reference) { Main *bmain = G_MAIN; @@ -387,11 +384,6 @@ void wm_event_do_depsgraph(bContext *C, bool is_after_open_file) } } -/** - * Was part of #wm_event_do_notifiers, - * split out so it can be called once before entering the #WM_main loop. - * This ensures operators don't run before the UI and depsgraph are initialized. - */ void wm_event_do_refresh_wm_and_depsgraph(bContext *C) { wmWindowManager *wm = CTX_wm_manager(C); @@ -428,7 +420,6 @@ static void wm_event_execute_timers(bContext *C) CTX_wm_window_set(C, NULL); } -/* Called in mainloop. */ void wm_event_do_notifiers(bContext *C) { /* Run the timer before assigning 'wm' in the unlikely case a timer loads a file, see T80028. */ @@ -756,9 +747,6 @@ static void wm_event_handler_ui_cancel(bContext *C) * Access to #wmWindowManager.reports * \{ */ -/** - * Show the report in the info header. - */ void WM_report_banner_show(void) { wmWindowManager *wm = G_MAIN->wm.first; @@ -774,9 +762,6 @@ void WM_report_banner_show(void) wm_reports->reporttimer->customdata = rti; } -/** - * Hide all currently displayed banners and abort their timer. - */ void WM_report_banners_cancel(Main *bmain) { wmWindowManager *wm = bmain->wm.first; @@ -859,9 +844,9 @@ bool WM_operator_poll(bContext *C, wmOperatorType *ot) return true; } -/* sets up the new context and calls 'wm_operator_invoke()' with poll_only */ bool WM_operator_poll_context(bContext *C, wmOperatorType *ot, short context) { + /* Sets up the new context and calls #wm_operator_invoke() with poll_only. */ return wm_operator_call_internal(C, ot, NULL, NULL, context, true, NULL); } @@ -896,11 +881,6 @@ bool WM_operator_check_ui_empty(wmOperatorType *ot) return true; } -/** - * Sets the active region for this space from the context. - * - * \see #BKE_area_find_region_active_win - */ void WM_operator_region_active_win_set(bContext *C) { ScrArea *area = CTX_wm_area(C); @@ -1107,13 +1087,6 @@ static int wm_operator_exec_notest(bContext *C, wmOperator *op) return retval; } -/** - * For running operators with frozen context (modal handlers, menus). - * - * \param store: Store settings for re-use. - * - * \warning do not use this within an operator to call its self! T29537. - */ int WM_operator_call_ex(bContext *C, wmOperator *op, const bool store) { return wm_operator_exec(C, op, false, store); @@ -1124,19 +1097,11 @@ int WM_operator_call(bContext *C, wmOperator *op) return WM_operator_call_ex(C, op, false); } -/** - * This is intended to be used when an invoke operator wants to call exec on its self - * and is basically like running op->type->exec() directly, no poll checks no freeing, - * since we assume whoever called invoke will take care of that - */ int WM_operator_call_notest(bContext *C, wmOperator *op) { return wm_operator_exec_notest(C, op); } -/** - * Execute this operator again, put here so it can share above code - */ int WM_operator_repeat(bContext *C, wmOperator *op) { const int op_flag = OP_IS_REPEAT; @@ -1153,12 +1118,6 @@ int WM_operator_repeat_last(bContext *C, wmOperator *op) op->flag &= ~op_flag; return ret; } -/** - * \return true if #WM_operator_repeat can run. - * Simple check for now but may become more involved. - * To be sure the operator can run call `WM_operator_poll(C, op->type)` also, since this call - * checks if #WM_operator_repeat() can run at all, not that it WILL run at any time. - */ bool WM_operator_repeat_check(const bContext *UNUSED(C), wmOperator *op) { if (op->type->exec != NULL) { @@ -1596,7 +1555,6 @@ static int wm_operator_call_internal(bContext *C, return 0; } -/* Invokes operator in context. */ int WM_operator_name_call_ptr(bContext *C, wmOperatorType *ot, wmOperatorCallContext context, @@ -1639,9 +1597,6 @@ int WM_operator_name_call_with_properties(struct bContext *C, return WM_operator_name_call_ptr(C, ot, context, &props_ptr); } -/** - * Call an existent menu. The menu can be created in C or Python. - */ void WM_menu_name_call(bContext *C, const char *menu_name, short context) { wmOperatorType *ot = WM_operatortype_find("WM_OT_call_menu", false); @@ -1652,13 +1607,6 @@ void WM_menu_name_call(bContext *C, const char *menu_name, short context) WM_operator_properties_free(&ptr); } -/** - * Similar to #WM_operator_name_call called with #WM_OP_EXEC_DEFAULT context. - * - * - #wmOperatorType is used instead of operator name since python already has the operator type. - * - `poll()` must be called by python before this runs. - * - reports can be passed to this function (so python can report them as exceptions). - */ int WM_operator_call_py(bContext *C, wmOperatorType *ot, wmOperatorCallContext context, @@ -1863,9 +1811,9 @@ void WM_operator_name_call_ptr_with_depends_on_cursor(bContext *C, * General API for different handler types. * \{ */ -/* Future extra customadata free? */ void wm_event_free_handler(wmEventHandler *handler) { + /* Future extra customa-data free? */ MEM_freeN(handler); } @@ -1937,7 +1885,6 @@ static void wm_handler_op_context(bContext *C, wmEventHandler_Op *handler, const } } -/* Called on exit or remove area, only here call cancel callback. */ void WM_event_remove_handlers(bContext *C, ListBase *handlers) { wmWindowManager *wm = CTX_wm_manager(C); @@ -3539,8 +3486,6 @@ static void wm_event_handle_xrevent(bContext *C, } #endif /* WITH_XR_OPENXR */ -/* Called in main loop. */ -/* Goes over entire hierarchy: events -> window -> screen -> area -> region. */ void wm_event_do_handlers(bContext *C) { wmWindowManager *wm = CTX_wm_manager(C); @@ -3850,12 +3795,6 @@ void WM_event_fileselect_event(wmWindowManager *wm, void *ophandle, int eventval /* Operator is supposed to have a filled "path" property. */ /* Optional property: file-type (XXX enum?) */ -/** - * The idea here is to keep a handler alive on window queue, owning the operator. - * The file window can send event to make it execute, thus ensuring - * executing happens outside of lower level queues, with UI refreshed. - * Should also allow multiwin solutions. - */ void WM_event_add_fileselect(bContext *C, wmOperator *op) { wmWindowManager *wm = CTX_wm_manager(C); @@ -3954,10 +3893,6 @@ wmEventHandler_Op *WM_event_add_modal_handler(bContext *C, wmOperator *op) return handler; } -/** - * Modal handlers store a pointer to an area which might be freed while the handler runs. - * Use this function to NULL all handler pointers to \a old_area. - */ void WM_event_modal_handler_area_replace(wmWindow *win, const ScrArea *old_area, ScrArea *new_area) { LISTBASE_FOREACH (wmEventHandler *, handler_base, &win->modalhandlers) { @@ -3972,10 +3907,6 @@ void WM_event_modal_handler_area_replace(wmWindow *win, const ScrArea *old_area, } } -/** - * Modal handlers store a pointer to a region which might be freed while the handler runs. - * Use this function to NULL all handler pointers to \a old_region. - */ void WM_event_modal_handler_region_replace(wmWindow *win, const ARegion *old_region, ARegion *new_region) @@ -4166,7 +4097,6 @@ struct wmEventHandler_Keymap *WM_event_add_keymap_handler_dynamic( return handler; } -/* Priorities not implemented yet, for time being just insert in begin of list. */ wmEventHandler_Keymap *WM_event_add_keymap_handler_priority(ListBase *handlers, wmKeyMap *keymap, int UNUSED(priority)) @@ -4273,7 +4203,6 @@ wmEventHandler_UI *WM_event_add_ui_handler(const bContext *C, return handler; } -/* Set "postpone" for win->modalhandlers, this is in a running for () loop in wm_handlers_do(). */ void WM_event_remove_ui_handler(ListBase *handlers, wmUIHandlerFunc handle_fn, wmUIHandlerRemoveFunc remove_fn, @@ -4338,9 +4267,10 @@ wmEventHandler_Dropbox *WM_event_add_dropbox_handler(ListBase *handlers, ListBas return handler; } -/* XXX(ton): solution works, still better check the real cause. */ void WM_event_remove_area_handler(ListBase *handlers, void *area) { + /* XXX(ton): solution works, still better check the real cause. */ + LISTBASE_FOREACH_MUTABLE (wmEventHandler *, handler_base, handlers) { if (handler_base->type == WM_HANDLER_TYPE_UI) { wmEventHandler_UI *handler = (wmEventHandler_UI *)handler_base; @@ -4766,9 +4696,6 @@ static wmEvent *wm_event_add_trackpad(wmWindow *win, const wmEvent *event, int d return event_new; } -/** - * Windows store own event queues #wmWindow.event_queue (no #bContext here). - */ void wm_event_add_ghostevent(wmWindowManager *wm, wmWindow *win, int type, void *customdata) { if (UNLIKELY(G.f & G_FLAG_EVENT_SIMULATE)) { @@ -5386,10 +5313,6 @@ const char *WM_window_cursor_keymap_status_get(const wmWindow *win, return NULL; } -/** - * Similar to #BKE_screen_area_map_find_area_xy and related functions, - * use here since the area is stored in the window manager. - */ ScrArea *WM_window_status_area_find(wmWindow *win, bScreen *screen) { if (screen->state == SCREENFULL) { diff --git a/source/blender/windowmanager/intern/wm_files.c b/source/blender/windowmanager/intern/wm_files.c index e95ce98352a..a2a09f9b0bc 100644 --- a/source/blender/windowmanager/intern/wm_files.c +++ b/source/blender/windowmanager/intern/wm_files.c @@ -171,9 +171,6 @@ void WM_file_tag_modified(void) } } -/** - * Check if there is data that would be lost when closing the current file without saving. - */ bool wm_file_or_session_data_has_unsaved_changes(const Main *bmain, const wmWindowManager *wm) { return !wm->file_saved || ED_image_should_save_modified(bmain) || @@ -1035,12 +1032,6 @@ static struct { bool override; } wm_init_state_app_template = {{0}}; -/** - * Used for setting app-template from the command line: - * - non-empty string: overrides. - * - empty string: override, using no app template. - * - NULL: clears override. - */ void WM_init_state_app_template_set(const char *app_template) { if (app_template) { @@ -1064,16 +1055,6 @@ const char *WM_init_state_app_template_get(void) /** \name Read Startup & Preferences Blend-File API * \{ */ -/** - * Called on startup, (context entirely filled with NULLs) - * or called for 'New File' both `startup.blend` and `userpref.blend` are checked. - * - * \param r_params_file_read_post: Support postponed initialization, - * needed for initial startup when only some sub-systems have been initialized. - * When non-null, #wm_file_read_post doesn't run, instead it's arguments are stored - * in this return argument. - * The caller is responsible for calling #wm_homefile_read_post with this return argument. - */ void wm_homefile_read_ex(bContext *C, const struct wmHomeFileRead_Params *params_homefile, ReportList *reports, @@ -1409,10 +1390,6 @@ void wm_homefile_read(bContext *C, wm_homefile_read_ex(C, params_homefile, reports, NULL); } -/** - * Special case, support deferred execution of #wm_file_read_post, - * Needed when loading for the first time to workaround order of initialization bug, see T89046. - */ void wm_homefile_read_post(struct bContext *C, const struct wmFileReadPost_Params *params_file_read_post) { @@ -1724,7 +1701,6 @@ static ImBuf *blend_file_thumb_from_camera(const bContext *C, return ibuf; } -/* easy access from gdb */ bool write_crash_blend(void) { char path[FILE_MAX]; @@ -2009,9 +1985,6 @@ void WM_autosave_init(wmWindowManager *wm) wm_autosave_timer_begin(wm); } -/** - * Run the auto-save timer action. - */ void wm_autosave_timer(Main *bmain, wmWindowManager *wm, wmTimer *UNUSED(wt)) { wm_autosave_timer_end(wm); @@ -3813,10 +3786,6 @@ static void wm_free_operator_properties_callback(void *user_data) IDP_FreeProperty(properties); } -/** - * \return True if the dialog was created, the calling operator should return #OPERATOR_INTERFACE - * then. - */ bool wm_operator_close_file_dialog_if_needed(bContext *C, wmOperator *op, wmGenericCallbackFn post_action_fn) diff --git a/source/blender/windowmanager/intern/wm_files_link.c b/source/blender/windowmanager/intern/wm_files_link.c index 00ac1c2ffe6..1b60167be4f 100644 --- a/source/blender/windowmanager/intern/wm_files_link.c +++ b/source/blender/windowmanager/intern/wm_files_link.c @@ -552,10 +552,6 @@ static ID *wm_file_link_append_datablock_ex(Main *bmain, return id; } -/* - * NOTE: `scene` (and related `view_layer` and `v3d`) pointers may be NULL, in which case no - * instantiation of linked objects, collections etc. will be performed. - */ ID *WM_file_link_datablock(Main *bmain, Scene *scene, ViewLayer *view_layer, @@ -570,10 +566,6 @@ ID *WM_file_link_datablock(Main *bmain, bmain, scene, view_layer, v3d, filepath, id_code, id_name, flag); } -/* - * NOTE: `scene` (and related `view_layer` and `v3d`) pointers may be NULL, in which case no - * instantiation of appended objects, collections etc. will be performed. - */ ID *WM_file_append_datablock(Main *bmain, Scene *scene, ViewLayer *view_layer, diff --git a/source/blender/windowmanager/intern/wm_gesture.c b/source/blender/windowmanager/intern/wm_gesture.c index ab971901a20..47f51214a8e 100644 --- a/source/blender/windowmanager/intern/wm_gesture.c +++ b/source/blender/windowmanager/intern/wm_gesture.c @@ -50,7 +50,6 @@ #include "BIF_glutil.h" -/* context checked on having screen, window and area */ wmGesture *WM_gesture_new(wmWindow *window, const ARegion *region, const wmEvent *event, int type) { wmGesture *gesture = MEM_callocN(sizeof(wmGesture), "new gesture"); @@ -129,7 +128,6 @@ bool WM_gesture_is_modal_first(const wmGesture *gesture) return (gesture->is_active_prev == false); } -/* tweak and line gestures */ int wm_gesture_evaluate(wmGesture *gesture, const wmEvent *event) { if (gesture->type == WM_GESTURE_TWEAK) { @@ -515,7 +513,6 @@ static void wm_gesture_draw_cross(wmWindow *win, wmGesture *gt) immUnbindProgram(); } -/* called in wm_draw.c */ void wm_gesture_draw(wmWindow *win) { wmGesture *gt = (wmGesture *)win->gesture.first; diff --git a/source/blender/windowmanager/intern/wm_gesture_ops.c b/source/blender/windowmanager/intern/wm_gesture_ops.c index 19b678d79d8..a4f633d9726 100644 --- a/source/blender/windowmanager/intern/wm_gesture_ops.c +++ b/source/blender/windowmanager/intern/wm_gesture_ops.c @@ -569,7 +569,6 @@ static void gesture_tweak_modal(bContext *C, const wmEvent *event) } } -/* standard tweak, called after window handlers passed on event */ void wm_tweakevent_test(bContext *C, const wmEvent *event, int action) { wmWindow *win = CTX_wm_window(C); @@ -750,11 +749,6 @@ void WM_gesture_lines_cancel(bContext *C, wmOperator *op) gesture_modal_end(C, op); } -/** - * helper function, we may want to add options for conversion to view space - * - * caller must free. - */ const int (*WM_gesture_lasso_path_to_array(bContext *UNUSED(C), wmOperator *op, int *r_mcoords_len))[2] @@ -889,10 +883,6 @@ int WM_gesture_straightline_invoke(bContext *C, wmOperator *op, const wmEvent *e return OPERATOR_RUNNING_MODAL; } -/** - * This invoke callback starts the straightline gesture with a viewport preview to the right side - * of the line. - */ int WM_gesture_straightline_active_side_invoke(bContext *C, wmOperator *op, const wmEvent *event) { WM_gesture_straightline_invoke(C, op, event); @@ -928,11 +918,6 @@ static void wm_gesture_straightline_do_angle_snap(rcti *rect) rect->ymax = (int)line_snapped_end[1]; } -/** - * This modal callback calls exec once per mouse move event while the gesture is active with the - * updated line start and end values, so it can be used for tools that have a real time preview - * (like a gradient updating in real time over the mesh). - */ int WM_gesture_straightline_modal(bContext *C, wmOperator *op, const wmEvent *event) { wmGesture *gesture = op->customdata; @@ -1012,13 +997,6 @@ int WM_gesture_straightline_modal(bContext *C, wmOperator *op, const wmEvent *ev return OPERATOR_RUNNING_MODAL; } -/** - * This modal one-shot callback only calls exec once after the gesture finishes without any updates - * during the gesture execution. Should be used for operations that are intended to be applied once - * without real time preview (like a trimming tool that only applies the bisect operation once - * after finishing the gesture as the bisect operation is too heavy to be computed in real time for - * a preview). - */ int WM_gesture_straightline_oneshot_modal(bContext *C, wmOperator *op, const wmEvent *event) { wmGesture *gesture = op->customdata; diff --git a/source/blender/windowmanager/intern/wm_init_exit.c b/source/blender/windowmanager/intern/wm_init_exit.c index 1a45e535a4a..4b3bc009388 100644 --- a/source/blender/windowmanager/intern/wm_init_exit.c +++ b/source/blender/windowmanager/intern/wm_init_exit.c @@ -223,10 +223,6 @@ static void sound_jack_sync_callback(Main *bmain, int mode, double time) } } -/** - * Initialize Blender and load the startup file & preferences - * (only called once). - */ void WM_init(bContext *C, int argc, const char **argv) { @@ -432,10 +428,6 @@ static int wm_exit_handler(bContext *C, const wmEvent *event, void *userdata) return WM_UI_HANDLER_BREAK; } -/** - * Cause a delayed #WM_exit() - * call to avoid leaking memory when trying to exit from within operators. - */ void wm_exit_schedule_delayed(const bContext *C) { /* What we do here is a little bit hacky, but quite simple and doesn't require bigger @@ -449,9 +441,6 @@ void wm_exit_schedule_delayed(const bContext *C) WM_event_add_mousemove(win); /* ensure handler actually gets called */ } -/** - * \note doesn't run exit() call #WM_exit() for that. - */ void WM_exit_ex(bContext *C, const bool do_python) { wmWindowManager *wm = C ? CTX_wm_manager(C) : NULL; @@ -656,11 +645,6 @@ void WM_exit_ex(bContext *C, const bool do_python) BKE_tempdir_session_purge(); } -/** - * \brief Main exit function to close Blender ordinarily. - * \note Use #wm_exit_schedule_delayed() to close Blender from an operator. - * Might leak memory otherwise. - */ void WM_exit(bContext *C) { WM_exit_ex(C, true); @@ -678,10 +662,6 @@ void WM_exit(bContext *C) exit(G.is_break == true); } -/** - * Needed for cases when operators are re-registered - * (when operator type pointers are stored). - */ void WM_script_tag_reload(void) { UI_interface_tag_script_reload(); diff --git a/source/blender/windowmanager/intern/wm_jobs.c b/source/blender/windowmanager/intern/wm_jobs.c index 2604105896d..66277ec57f4 100644 --- a/source/blender/windowmanager/intern/wm_jobs.c +++ b/source/blender/windowmanager/intern/wm_jobs.c @@ -187,12 +187,6 @@ static wmJob *wm_job_find(const wmWindowManager *wm, const void *owner, const in /* ******************* public API ***************** */ -/** - * \return current job or adds new job, but doesn't run it. - * - * \note every owner only gets a single job, - * adding a new one will stop running job and when stopped it starts the new one. - */ wmJob *WM_jobs_get(wmWindowManager *wm, wmWindow *win, const void *owner, @@ -223,7 +217,6 @@ wmJob *WM_jobs_get(wmWindowManager *wm, return wm_job; } -/* returns true if job runs, for UI (progress) indicators */ bool WM_jobs_test(const wmWindowManager *wm, const void *owner, int job_type) { /* job can be running or about to run (suspended) */ @@ -281,7 +274,6 @@ static void wm_jobs_update_progress_bars(wmWindowManager *wm) } } -/* time that job started */ double WM_jobs_starttime(const wmWindowManager *wm, const void *owner) { const wmJob *wm_job = wm_job_find(wm, owner, WM_JOB_TYPE_ANY); @@ -447,10 +439,6 @@ static void wm_jobs_test_suspend_stop(wmWindowManager *wm, wmJob *test) #endif } -/** - * if job running, the same owner gave it a new job. - * if different owner starts existing startjob, it suspends itself - */ void WM_jobs_start(wmWindowManager *wm, wmJob *wm_job) { if (wm_job->running) { @@ -550,7 +538,6 @@ static void wm_jobs_kill_job(wmWindowManager *wm, wmJob *wm_job) } } -/* wait until every job ended */ void WM_jobs_kill_all(wmWindowManager *wm) { wmJob *wm_job; @@ -563,7 +550,6 @@ void WM_jobs_kill_all(wmWindowManager *wm) SEQ_prefetch_stop_all(); } -/* wait until every job ended, except for one owner (used in undo to keep screen job alive) */ void WM_jobs_kill_all_except(wmWindowManager *wm, const void *owner) { LISTBASE_FOREACH_MUTABLE (wmJob *, wm_job, &wm->jobs) { @@ -584,7 +570,6 @@ void WM_jobs_kill_type(struct wmWindowManager *wm, const void *owner, int job_ty } } -/* signal job(s) from this owner or callback to stop, timer is required to get handled */ void WM_jobs_stop(wmWindowManager *wm, const void *owner, void *startjob) { LISTBASE_FOREACH (wmJob *, wm_job, &wm->jobs) { @@ -596,7 +581,6 @@ void WM_jobs_stop(wmWindowManager *wm, const void *owner, void *startjob) } } -/* actually terminate thread and job timer */ void WM_jobs_kill(wmWindowManager *wm, void *owner, void (*startjob)(void *, short int *, short int *, float *)) @@ -608,7 +592,6 @@ void WM_jobs_kill(wmWindowManager *wm, } } -/* kill job entirely, also removes timer itself */ void wm_jobs_timer_end(wmWindowManager *wm, wmTimer *wt) { LISTBASE_FOREACH (wmJob *, wm_job, &wm->jobs) { @@ -619,7 +602,6 @@ void wm_jobs_timer_end(wmWindowManager *wm, wmTimer *wt) } } -/* hardcoded to event TIMERJOBS */ void wm_jobs_timer(wmWindowManager *wm, wmTimer *wt) { LISTBASE_FOREACH_MUTABLE (wmJob *, wm_job, &wm->jobs) { diff --git a/source/blender/windowmanager/intern/wm_keymap.c b/source/blender/windowmanager/intern/wm_keymap.c index 35f6ce40dba..eb8f885dc83 100644 --- a/source/blender/windowmanager/intern/wm_keymap.c +++ b/source/blender/windowmanager/intern/wm_keymap.c @@ -189,7 +189,6 @@ static bool wm_keymap_item_equals(wmKeyMapItem *a, wmKeyMapItem *b) (a->flag & KMI_REPEAT_IGNORE) == (b->flag & KMI_REPEAT_IGNORE))); } -/* properties can be NULL, otherwise the arg passed is used and ownership is given to the kmi */ void WM_keymap_item_properties_reset(wmKeyMapItem *kmi, struct IDProperty *properties) { if (LIKELY(kmi->ptr)) { @@ -514,7 +513,6 @@ static void keymap_item_set_id(wmKeyMap *keymap, wmKeyMapItem *kmi) } } -/* always add item */ wmKeyMapItem *WM_keymap_add_item( wmKeyMap *keymap, const char *idname, int type, int val, int modifier, int keymodifier) { @@ -1150,7 +1148,6 @@ const char *WM_key_event_string(const short type, const bool compact) return CTX_IFACE_(BLT_I18NCONTEXT_UI_EVENTS, it->name); } -/* TODO: also support (some) value, like e.g. double-click? */ int WM_keymap_item_raw_to_string(const short shift, const short ctrl, const short alt, @@ -1162,6 +1159,8 @@ int WM_keymap_item_raw_to_string(const short shift, char *result, const int result_len) { + /* TODO: also support (some) value, like e.g. double-click? */ + #define ADD_SEP \ if (p != buf) { \ *p++ = ' '; \ @@ -1676,10 +1675,6 @@ static bool kmi_filter_is_visible_type_mask(const wmKeyMap *km, kmi_filter_is_visible(km, kmi, user_data)); } -/** - * \param include_mask, exclude_mask: - * Event types to include/exclude when looking up keys (#eEventType_Mask). - */ wmKeyMapItem *WM_key_event_operator(const bContext *C, const char *opname, wmOperatorCallContext opcontext, diff --git a/source/blender/windowmanager/intern/wm_keymap_utils.c b/source/blender/windowmanager/intern/wm_keymap_utils.c index 795f78e215f..d424eef8262 100644 --- a/source/blender/windowmanager/intern/wm_keymap_utils.c +++ b/source/blender/windowmanager/intern/wm_keymap_utils.c @@ -43,7 +43,6 @@ /** \name Wrappers for #WM_keymap_add_item * \{ */ -/* menu wrapper for WM_keymap_add_item */ wmKeyMapItem *WM_keymap_add_menu( wmKeyMap *keymap, const char *idname, int type, int val, int modifier, int keymodifier) { @@ -73,7 +72,6 @@ wmKeyMapItem *WM_keymap_add_panel( return kmi; } -/* tool wrapper for WM_keymap_add_item */ wmKeyMapItem *WM_keymap_add_tool( wmKeyMap *keymap, const char *idname, int type, int val, int modifier, int keymodifier) { @@ -83,7 +81,6 @@ wmKeyMapItem *WM_keymap_add_tool( return kmi; } -/** Useful for mapping numbers to an enum. */ void WM_keymap_add_context_enum_set_items(wmKeyMap *keymap, const EnumPropertyItem *items, const char *data_path, @@ -203,8 +200,6 @@ wmKeyMap *WM_keymap_guess_from_context(const bContext *C) return km; } -/* Guess an appropriate keymap from the operator name */ -/* Needs to be kept up to date with Keymap and Operator naming */ wmKeyMap *WM_keymap_guess_opname(const bContext *C, const char *opname) { /* Op types purposely skipped for now: diff --git a/source/blender/windowmanager/intern/wm_menu_type.c b/source/blender/windowmanager/intern/wm_menu_type.c index bcaa2243f9f..799b6fc2e52 100644 --- a/source/blender/windowmanager/intern/wm_menu_type.c +++ b/source/blender/windowmanager/intern/wm_menu_type.c @@ -77,7 +77,6 @@ void WM_menutype_freelink(MenuType *mt) UNUSED_VARS_NDEBUG(ok); } -/* called on initialize WM_init() */ void WM_menutype_init(void) { /* reserve size is set based on blender default setup */ diff --git a/source/blender/windowmanager/intern/wm_operator_props.c b/source/blender/windowmanager/intern/wm_operator_props.c index 898671706d1..a5887fc07b3 100644 --- a/source/blender/windowmanager/intern/wm_operator_props.c +++ b/source/blender/windowmanager/intern/wm_operator_props.c @@ -72,7 +72,6 @@ static const EnumPropertyItem *wm_operator_properties_filesel_sort_items_itemf( return items; } -/* default properties for fileselect */ void WM_operator_properties_filesel(wmOperatorType *ot, int filter, short type, @@ -262,9 +261,6 @@ void WM_operator_properties_select_action(wmOperatorType *ot, int default_action wm_operator_properties_select_action_ex(ot, default_action, select_actions, hide_gui); } -/** - * only SELECT/DESELECT - */ void WM_operator_properties_select_action_simple(wmOperatorType *ot, int default_action, bool hide_gui) @@ -278,10 +274,6 @@ void WM_operator_properties_select_action_simple(wmOperatorType *ot, wm_operator_properties_select_action_ex(ot, default_action, select_actions, hide_gui); } -/** - * Use for all select random operators. - * Adds properties: percent, seed, action. - */ void WM_operator_properties_select_random(wmOperatorType *ot) { RNA_def_float_factor(ot->srna, @@ -357,9 +349,6 @@ void WM_operator_properties_border_to_rctf(struct wmOperator *op, rctf *rect) BLI_rctf_rcti_copy(rect, &rect_i); } -/** - * Use with #WM_gesture_box_invoke - */ void WM_operator_properties_gesture_box_ex(wmOperatorType *ot, bool deselect, bool extend) { PropertyRNA *prop; @@ -381,10 +370,6 @@ void WM_operator_properties_gesture_box_ex(wmOperatorType *ot, bool deselect, bo } } -/** - * Disable using cursor position, - * use when view operators are initialized from buttons. - */ void WM_operator_properties_use_cursor_init(wmOperatorType *ot) { PropertyRNA *prop = RNA_def_boolean(ot->srna, @@ -418,7 +403,6 @@ void WM_operator_properties_select_operation(wmOperatorType *ot) RNA_def_property_flag(prop, PROP_SKIP_SAVE); } -/* Some tools don't support XOR/AND. */ void WM_operator_properties_select_operation_simple(wmOperatorType *ot) { static const EnumPropertyItem select_mode_items[] = { @@ -450,31 +434,6 @@ void WM_operator_properties_select_walk_direction(wmOperatorType *ot) RNA_def_property_flag(prop, PROP_SKIP_SAVE); } -/** - * Selecting and tweaking items are overlapping operations. Getting both to work without conflicts - * requires special care. See - * https://wiki.blender.org/wiki/Human_Interface_Guidelines/Selection#Select-tweaking for the - * desired behavior. - * - * For default click selection (with no modifier keys held), the select operators can do the - * following: - * - On a mouse press on an unselected item, change selection and finish immediately after. - * This sends an undo push and allows transform to take over should a tweak event be caught now. - * - On a mouse press on a selected item, don't change selection state, but start modal execution - * of the operator. Idea is that we wait with deselecting other items until we know that the - * intention wasn't to tweak (mouse press+drag) all selected items. - * - If a tweak is recognized before the release event happens, cancel the operator, so that - * transform can take over and no undo-push is sent. - * - If the release event occurs rather than a tweak one, deselect all items but the one under the - * cursor, and finish the modal operator. - * - * This utility, together with #WM_generic_select_invoke() and #WM_generic_select_modal() should - * help getting the wanted behavior to work. Most generic logic should be handled in these, so that - * the select operators only have to care for the case dependent handling. - * - * Every select operator has slightly different requirements, e.g. sequencer strip selection - * also needs to account for handle selection. This should be the baseline behavior though. - */ void WM_operator_properties_generic_select(wmOperatorType *ot) { /* On the initial mouse press, this is set by #WM_generic_select_modal() to let the select @@ -499,9 +458,6 @@ void WM_operator_properties_gesture_box_zoom(wmOperatorType *ot) RNA_def_property_flag(prop, PROP_HIDDEN | PROP_SKIP_SAVE); } -/** - * Use with #WM_gesture_lasso_invoke - */ void WM_operator_properties_gesture_lasso(wmOperatorType *ot) { PropertyRNA *prop; @@ -509,9 +465,6 @@ void WM_operator_properties_gesture_lasso(wmOperatorType *ot) RNA_def_property_flag(prop, PROP_HIDDEN | PROP_SKIP_SAVE); } -/** - * Use with #WM_gesture_straightline_invoke - */ void WM_operator_properties_gesture_straightline(wmOperatorType *ot, int cursor) { PropertyRNA *prop; @@ -541,9 +494,6 @@ void WM_operator_properties_gesture_straightline(wmOperatorType *ot, int cursor) } } -/** - * Use with #WM_gesture_circle_invoke - */ void WM_operator_properties_gesture_circle(wmOperatorType *ot) { PropertyRNA *prop; @@ -582,9 +532,6 @@ void WM_operator_properties_mouse_select(wmOperatorType *ot) RNA_def_property_flag(prop, PROP_SKIP_SAVE); } -/** - * \param nth_can_disable: Enable if we want to be able to select no interval at all. - */ void WM_operator_properties_checker_interval(wmOperatorType *ot, bool nth_can_disable) { const int nth_default = nth_can_disable ? 0 : 1; diff --git a/source/blender/windowmanager/intern/wm_operator_type.c b/source/blender/windowmanager/intern/wm_operator_type.c index 0e30df4ec99..0f6096e7b8b 100644 --- a/source/blender/windowmanager/intern/wm_operator_type.c +++ b/source/blender/windowmanager/intern/wm_operator_type.c @@ -89,7 +89,6 @@ wmOperatorType *WM_operatortype_find(const char *idname, bool quiet) return NULL; } -/* caller must free */ void WM_operatortype_iter(GHashIterator *ghi) { BLI_ghashIterator_init(ghi, global_ops_hash); @@ -132,7 +131,8 @@ static void wm_operatortype_append__end(wmOperatorType *ot) BLI_ghash_insert(global_ops_hash, (void *)ot->idname, ot); } -/* all ops in 1 list (for time being... needs evaluation later) */ +/* All ops in 1 list (for time being... needs evaluation later). */ + void WM_operatortype_append(void (*opfunc)(wmOperatorType *)) { wmOperatorType *ot = wm_operatortype_append__begin(); @@ -149,7 +149,6 @@ void WM_operatortype_append_ptr(void (*opfunc)(wmOperatorType *, void *), void * /** \} */ -/* called on initialize WM_exit() */ void WM_operatortype_remove_ptr(wmOperatorType *ot) { BLI_assert(ot == WM_operatortype_find(ot->idname, false)); @@ -184,7 +183,6 @@ bool WM_operatortype_remove(const char *idname) return true; } -/* called on initialize WM_init() */ void wm_operatortype_init(void) { /* reserve size is set based on blender default setup */ @@ -215,18 +213,6 @@ void wm_operatortype_free(void) global_ops_hash = NULL; } -/** - * Tag all operator-properties of \a ot defined after calling this, until - * the next #WM_operatortype_props_advanced_end call (if available), with - * #OP_PROP_TAG_ADVANCED. Previously defined ones properties not touched. - * - * Calling this multiple times without a call to #WM_operatortype_props_advanced_end, - * all calls after the first one are ignored. Meaning all proprieties defined after the - * first call are tagged as advanced. - * - * This doesn't do the actual tagging, #WM_operatortype_props_advanced_end does which is - * called for all operators during registration (see #wm_operatortype_append__end). - */ void WM_operatortype_props_advanced_begin(wmOperatorType *ot) { if (ot_prop_basic_count == -1) { @@ -235,14 +221,6 @@ void WM_operatortype_props_advanced_begin(wmOperatorType *ot) } } -/** - * Tags all operator-properties of \a ot defined since the first - * #WM_operatortype_props_advanced_begin call, - * or the last #WM_operatortype_props_advanced_end call, with #OP_PROP_TAG_ADVANCED. - * - * \note This is called for all operators during registration (see #wm_operatortype_append__end). - * So it does not need to be explicitly called in operator-type definition. - */ void WM_operatortype_props_advanced_end(wmOperatorType *ot) { PointerRNA struct_ptr; @@ -266,9 +244,6 @@ void WM_operatortype_props_advanced_end(wmOperatorType *ot) ot_prop_basic_count = -1; } -/** - * Remove memory of all previously executed tools. - */ void WM_operatortype_last_properties_clear_all(void) { GHashIterator iter; @@ -471,7 +446,6 @@ static void wm_macro_cancel(bContext *C, wmOperator *op) wm_macro_end(op, OPERATOR_CANCELLED); } -/* Names have to be static for now */ wmOperatorType *WM_operatortype_append_macro(const char *idname, const char *name, const char *description, @@ -613,9 +587,6 @@ char *WM_operatortype_description(struct bContext *C, return NULL; } -/** - * Use when we want a label, preferring the description. - */ char *WM_operatortype_description_or_name(struct bContext *C, struct wmOperatorType *ot, struct PointerRNA *properties) diff --git a/source/blender/windowmanager/intern/wm_operator_utils.c b/source/blender/windowmanager/intern/wm_operator_utils.c index 85a0a28de79..dbcfd814692 100644 --- a/source/blender/windowmanager/intern/wm_operator_utils.c +++ b/source/blender/windowmanager/intern/wm_operator_utils.c @@ -44,9 +44,6 @@ /** \name Generic Utilities * \{ */ -/** - * Only finish + pass through for press events (allowing press-tweak). - */ int WM_operator_flag_only_pass_through_on_press(int retval, const struct wmEvent *event) { if ((event->val != KM_PRESS) && @@ -337,10 +334,6 @@ static int op_generic_value_modal(bContext *C, wmOperator *op, const wmEvent *ev return OPERATOR_RUNNING_MODAL; } -/** - * Allow an operator with only and execute function to run modally, - * re-doing the action, using vertex coordinate store/restore instead of operator undo. - */ void WM_operator_type_modal_from_exec_for_object_edit_coords(wmOperatorType *ot) { PropertyRNA *prop; diff --git a/source/blender/windowmanager/intern/wm_operators.c b/source/blender/windowmanager/intern/wm_operators.c index ffdc99152b1..65fc5210c43 100644 --- a/source/blender/windowmanager/intern/wm_operators.c +++ b/source/blender/windowmanager/intern/wm_operators.c @@ -122,7 +122,6 @@ /** \name Operator API * \{ */ -/* SOME_OT_op -> some.op */ void WM_operator_py_idname(char *to, const char *from) { const char *sep = strstr(from, "_OT_"); @@ -143,7 +142,6 @@ void WM_operator_py_idname(char *to, const char *from) } } -/* some.op -> SOME_OT_op */ void WM_operator_bl_idname(char *to, const char *from) { if (from) { @@ -167,10 +165,6 @@ void WM_operator_bl_idname(char *to, const char *from) } } -/** - * Sanity check to ensure #WM_operator_bl_idname won't fail. - * \returns true when there are no problems with \a idname, otherwise report an error. - */ bool WM_operator_py_idname_ok_or_report(ReportList *reports, const char *classname, const char *idname) @@ -219,15 +213,6 @@ bool WM_operator_py_idname_ok_or_report(ReportList *reports, return true; } -/** - * Print a string representation of the operator, - * with the args that it runs so python can run it again. - * - * When calling from an existing wmOperator, better to use simple version: - * `WM_operator_pystring(C, op);` - * - * \note Both \a op and \a opptr may be `NULL` (\a op is only used for macro operators). - */ char *WM_operator_pystring_ex(bContext *C, wmOperator *op, const bool all_args, @@ -308,9 +293,6 @@ char *WM_operator_pystring(bContext *C, wmOperator *op, const bool all_args, con return WM_operator_pystring_ex(C, op, all_args, macro_args, op->type, op->ptr); } -/** - * \return true if the string was shortened - */ bool WM_operator_pystring_abbreviate(char *str, int str_len_max) { const int str_len = strlen(str); @@ -608,9 +590,6 @@ static const char *wm_context_member_from_ptr(const bContext *C, } #endif -/** - * Calculate the path to `ptr` from context `C`, or return NULL if it can't be calculated. - */ char *WM_context_path_resolve_property_full(const bContext *C, const PointerRNA *ptr, PropertyRNA *prop, @@ -711,8 +690,6 @@ void WM_operator_properties_create(PointerRNA *ptr, const char *opstring) } } -/* similar to the function above except its uses ID properties - * used for keymaps and macros */ void WM_operator_properties_alloc(PointerRNA **ptr, IDProperty **properties, const char *opstring) { IDProperty *tmp_properties = NULL; @@ -763,14 +740,6 @@ void WM_operator_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 operators here. - * This could be made a general function. - */ bool WM_operator_properties_default(PointerRNA *ptr, const bool do_update) { bool changed = false; @@ -798,7 +767,6 @@ bool WM_operator_properties_default(PointerRNA *ptr, const bool do_update) return changed; } -/* remove all props without PROP_SKIP_SAVE */ void WM_operator_properties_reset(wmOperator *op) { if (op->ptr->data) { @@ -945,13 +913,6 @@ bool WM_operator_last_properties_store(wmOperator *UNUSED(op)) /** \name Default Operator Callbacks * \{ */ -/** - * Helper to get select and tweak-transform to work conflict free and as desired. See - * #WM_operator_properties_generic_select() for details. - * - * To be used together with #WM_generic_select_invoke() and - * #WM_operator_properties_generic_select(). - */ int WM_generic_select_modal(bContext *C, wmOperator *op, const wmEvent *event) { PropertyRNA *wait_to_deselect_prop = RNA_struct_find_property(op->ptr, @@ -1012,13 +973,6 @@ int WM_generic_select_modal(bContext *C, wmOperator *op, const wmEvent *event) return OPERATOR_RUNNING_MODAL | OPERATOR_PASS_THROUGH; } -/** - * Helper to get select and tweak-transform to work conflict free and as desired. See - * #WM_operator_properties_generic_select() for details. - * - * To be used together with #WM_generic_select_modal() and - * #WM_operator_properties_generic_select(). - */ int WM_generic_select_invoke(bContext *C, wmOperator *op, const wmEvent *event) { RNA_int_set(op->ptr, "mouse_x", event->mval[0]); @@ -1063,7 +1017,6 @@ int WM_operator_smooth_viewtx_get(const wmOperator *op) return (op->flag & OP_IS_INVOKE) ? U.smooth_viewtx : 0; } -/* invoke callback, uses enum property named "type" */ int WM_menu_invoke_ex(bContext *C, wmOperator *op, wmOperatorCallContext opcontext) { PropertyRNA *prop = op->type->prop; @@ -1184,10 +1137,6 @@ static uiBlock *wm_enum_search_menu(bContext *C, ARegion *region, void *arg) return block; } -/** - * Similar to #WM_enum_search_invoke, but draws previews. Also, this can't - * be used as invoke callback directly since it needs additional info. - */ int WM_enum_search_invoke_previews(bContext *C, wmOperator *op, short prv_cols, short prv_rows) { static struct EnumSearchMenu search_menu; @@ -1210,7 +1159,6 @@ int WM_enum_search_invoke(bContext *C, wmOperator *op, const wmEvent *UNUSED(eve return OPERATOR_INTERFACE; } -/* Can't be used as an invoke directly, needs message arg (can be NULL) */ int WM_operator_confirm_message_ex(bContext *C, wmOperator *op, const char *title, @@ -1255,7 +1203,6 @@ int WM_operator_confirm_or_exec(bContext *C, wmOperator *op, const wmEvent *UNUS return op->type->exec(C, op); } -/* op->invoke, opens fileselect if path property not set, otherwise executes */ int WM_operator_filesel(bContext *C, wmOperator *op, const wmEvent *UNUSED(event)) { if (RNA_struct_property_is_set(op->ptr, "filepath")) { @@ -1280,7 +1227,6 @@ bool WM_operator_filesel_ensure_ext_imtype(wmOperator *op, const struct ImageFor return false; } -/* op->poll */ bool WM_operator_winactive(bContext *C) { if (CTX_wm_window(C) == NULL) { @@ -1289,7 +1235,6 @@ bool WM_operator_winactive(bContext *C) return 1; } -/* return false, if the UI should be disabled */ bool WM_operator_check_ui_enabled(const bContext *C, const char *idname) { wmWindowManager *wm = CTX_wm_manager(C); @@ -1327,9 +1272,6 @@ void WM_operator_last_properties_ensure(wmOperatorType *ot, PointerRNA *ptr) RNA_pointer_create(G_MAIN->wm.first, ot->srna, props, ptr); } -/** - * Use for drag & drop a path or name with operators invoke() function. - */ ID *WM_operator_drop_load_path(struct bContext *C, wmOperator *op, const short idcode) { Main *bmain = CTX_data_main(C); @@ -1633,20 +1575,11 @@ static int wm_operator_props_popup_ex(bContext *C, return OPERATOR_RUNNING_MODAL; } -/** - * Same as #WM_operator_props_popup but don't use operator redo. - * just wraps #WM_operator_props_dialog_popup. - */ int WM_operator_props_popup_confirm(bContext *C, wmOperator *op, const wmEvent *UNUSED(event)) { return wm_operator_props_popup_ex(C, op, false, false); } -/** - * Same as #WM_operator_props_popup but call the operator first, - * This way - the button values correspond to the result of the operator. - * Without this, first access to a button will make the result jump, see T32452. - */ int WM_operator_props_popup_call(bContext *C, wmOperator *op, const wmEvent *UNUSED(event)) { return wm_operator_props_popup_ex(C, op, true, true); @@ -3999,7 +3932,6 @@ static void gesture_zoom_border_modal_keymap(wmKeyConfig *keyconf) WM_modalkeymap_assign(keymap, "IMAGE_OT_view_zoom_border"); } -/* default keymap for windows and screens, only call once per WM */ void wm_window_keymap(wmKeyConfig *keyconf) { WM_keymap_ensure(keyconf, "Window", 0, 0); @@ -4067,7 +3999,8 @@ static const EnumPropertyItem *rna_id_itemf(bool *r_free, return item; } -/* can add more as needed */ +/* Can add more ID types as needed. */ + const EnumPropertyItem *RNA_action_itemf(bContext *C, PointerRNA *UNUSED(ptr), PropertyRNA *UNUSED(prop), diff --git a/source/blender/windowmanager/intern/wm_panel_type.c b/source/blender/windowmanager/intern/wm_panel_type.c index 24508c377a6..609bb55e075 100644 --- a/source/blender/windowmanager/intern/wm_panel_type.c +++ b/source/blender/windowmanager/intern/wm_panel_type.c @@ -69,7 +69,6 @@ void WM_paneltype_remove(PanelType *pt) UNUSED_VARS_NDEBUG(ok); } -/* called on initialize WM_init() */ void WM_paneltype_init(void) { /* reserve size is set based on blender default setup */ diff --git a/source/blender/windowmanager/intern/wm_stereo.c b/source/blender/windowmanager/intern/wm_stereo.c index 16a17484f4f..a62ced1a4bf 100644 --- a/source/blender/windowmanager/intern/wm_stereo.c +++ b/source/blender/windowmanager/intern/wm_stereo.c @@ -177,10 +177,6 @@ bool WM_stereo3d_enabled(wmWindow *win, bool skip_stereo3d_check) return true; } -/** - * If needed, adjust \a r_mouse_xy - * so that drawn cursor and handled mouse position are matching visually. - */ void wm_stereo3d_mouse_offset_apply(wmWindow *win, int r_mouse_xy[2]) { if (!WM_stereo3d_enabled(win, false)) { diff --git a/source/blender/windowmanager/intern/wm_subwindow.c b/source/blender/windowmanager/intern/wm_subwindow.c index 0cb76404258..524580ac88f 100644 --- a/source/blender/windowmanager/intern/wm_subwindow.c +++ b/source/blender/windowmanager/intern/wm_subwindow.c @@ -116,7 +116,6 @@ static void wmOrtho2_offset(const float x, const float y, const float ofs) wmOrtho2(ofs, x + ofs, ofs, y + ofs); } -/* Default pixel alignment for regions. */ void wmOrtho2_region_pixelspace(const ARegion *region) { wmOrtho2_offset(region->winx, region->winy, -0.01f); diff --git a/source/blender/windowmanager/intern/wm_toolsystem.c b/source/blender/windowmanager/intern/wm_toolsystem.c index 3ac1a7c0be1..7b8feac45b4 100644 --- a/source/blender/windowmanager/intern/wm_toolsystem.c +++ b/source/blender/windowmanager/intern/wm_toolsystem.c @@ -251,7 +251,6 @@ void WM_toolsystem_reinit(bContext *C, WorkSpace *workspace, const bToolKey *tke } } -/* Operate on all active tools. */ void WM_toolsystem_unlink_all(struct bContext *C, struct WorkSpace *workspace) { LISTBASE_FOREACH (bToolRef *, tref, &workspace->tools) { @@ -362,12 +361,6 @@ void WM_toolsystem_ref_set_from_runtime(struct bContext *C, } } -/** - * Sync the internal active state of a tool back into the tool system, - * this is needed for active brushes where the real active state is not stored in the tool system. - * - * \see #toolsystem_ref_link - */ void WM_toolsystem_ref_sync_from_context(Main *bmain, WorkSpace *workspace, bToolRef *tref) { bToolRef_Runtime *tref_rt = tref->runtime; @@ -505,14 +498,6 @@ bool WM_toolsystem_key_from_context(ViewLayer *view_layer, ScrArea *area, bToolK return false; } -/** - * Use to update the active tool (shown in the top bar) in the least disruptive way. - * - * This is a little involved since there may be multiple valid active tools - * depending on the mode and space type. - * - * Used when undoing since the active mode may have changed. - */ void WM_toolsystem_refresh_active(bContext *C) { Main *bmain = CTX_data_main(C); @@ -800,16 +785,12 @@ void WM_toolsystem_update_from_context(bContext *C, } } -/** - * For paint modes to support non-brush tools. - */ bool WM_toolsystem_active_tool_is_brush(const bContext *C) { bToolRef_Runtime *tref_rt = WM_toolsystem_runtime_from_context((bContext *)C); return tref_rt && (tref_rt->data_block[0] != '\0'); } -/* Follow wmMsgNotifyFn spec */ void WM_toolsystem_do_msg_notify_tag_refresh(bContext *C, wmMsgSubscribeKey *UNUSED(msg_key), wmMsgSubscribeValue *msg_val) diff --git a/source/blender/windowmanager/intern/wm_uilist_type.c b/source/blender/windowmanager/intern/wm_uilist_type.c index 82ba4aa6e6f..a2ae42d5ead 100644 --- a/source/blender/windowmanager/intern/wm_uilist_type.c +++ b/source/blender/windowmanager/intern/wm_uilist_type.c @@ -131,7 +131,6 @@ void WM_uilisttype_remove_ptr(Main *bmain, uiListType *ult) UNUSED_VARS_NDEBUG(ok); } -/* called on initialize WM_init() */ void WM_uilisttype_init(void) { uilisttypes_hash = BLI_ghash_str_new_ex("uilisttypes_hash gh", 16); @@ -151,16 +150,6 @@ void WM_uilisttype_free(void) uilisttypes_hash = NULL; } -/** - * The "full" list-ID is an internal name used for storing and identifying a list. It is built like - * this: - * "{uiListType.idname}_{list_id}", whereby "list_id" is an optional parameter passed to - * `UILayout.template_list()`. If it is not set, the full list-ID is just "{uiListType.idname}_". - * - * Note that whenever the Python API refers to the list-ID, it's the short, "non-full" one it - * passed to `UILayout.template_list()`. C code can query that through - * #WM_uilisttype_list_id_get(). - */ void WM_uilisttype_to_full_list_id(const uiListType *ult, const char *list_id, char r_full_list_id[/*UI_MAX_NAME_STR*/]) @@ -169,11 +158,6 @@ void WM_uilisttype_to_full_list_id(const uiListType *ult, BLI_snprintf(r_full_list_id, UI_MAX_NAME_STR, "%s_%s", ult->idname, list_id ? list_id : ""); } -/** - * Get the "non-full" list-ID, see #WM_uilisttype_to_full_list_id() for details. - * - * \note Assumes `uiList.list_id` was set using #WM_uilisttype_to_full_list_id()! - */ const char *WM_uilisttype_list_id_get(const uiListType *ult, uiList *list) { /* Some sanity check for the assumed behavior of #WM_uilisttype_to_full_list_id(). */ diff --git a/source/blender/windowmanager/intern/wm_window.c b/source/blender/windowmanager/intern/wm_window.c index 5f684a752d8..35f971e72e4 100644 --- a/source/blender/windowmanager/intern/wm_window.c +++ b/source/blender/windowmanager/intern/wm_window.c @@ -136,8 +136,6 @@ static struct WMInitStruct { static void wm_window_set_drawable(wmWindowManager *wm, wmWindow *win, bool activate); static bool wm_window_timer(const bContext *C); -/* XXX this one should correctly check for apple top header... - * done for Cocoa : returns window contents (and not frame) max size. */ void wm_get_screensize(int *r_width, int *r_height) { unsigned int uiwidth; @@ -148,7 +146,6 @@ void wm_get_screensize(int *r_width, int *r_height) *r_height = uiheight; } -/* size of all screens (desktop), useful since the mouse is bound by this */ void wm_get_desktopsize(int *r_width, int *r_height) { unsigned int uiwidth; @@ -198,8 +195,6 @@ static void wm_ghostwindow_destroy(wmWindowManager *wm, wmWindow *win) } } -/* including window itself, C can be NULL. - * ED_screen_exit should have been called */ void wm_window_free(bContext *C, wmWindowManager *wm, wmWindow *win) { /* update context */ @@ -260,7 +255,6 @@ static int find_free_winid(wmWindowManager *wm) return id; } -/* don't change context itself */ wmWindow *wm_window_new(const Main *bmain, wmWindowManager *wm, wmWindow *parent, bool dialog) { wmWindow *win = MEM_callocN(sizeof(wmWindow), "window"); @@ -276,7 +270,6 @@ wmWindow *wm_window_new(const Main *bmain, wmWindowManager *wm, wmWindow *parent return win; } -/* part of wm_window.c api */ wmWindow *wm_window_copy(Main *bmain, wmWindowManager *wm, wmWindow *win_src, @@ -307,10 +300,6 @@ wmWindow *wm_window_copy(Main *bmain, return win_dst; } -/** - * A higher level version of copy that tests the new window can be added. - * (called from the operator directly) - */ wmWindow *wm_window_copy_test(bContext *C, wmWindow *win_src, const bool duplicate_layout, @@ -353,13 +342,6 @@ static void wm_confirm_quit(bContext *C) wm_close_file_dialog(C, action); } -/** - * Call the quit confirmation prompt or exit directly if needed. The use can - * still cancel via the confirmation popup. Also, this may not quit Blender - * immediately, but rather schedule the closing. - * - * \param win: The window to show the confirmation popup/window in. - */ void wm_quit_with_optional_confirmation_prompt(bContext *C, wmWindow *win) { wmWindow *win_ctx = CTX_wm_window(C); @@ -387,7 +369,6 @@ void wm_quit_with_optional_confirmation_prompt(bContext *C, wmWindow *win) /** \} */ -/* this is event from ghost, or exit-blender op */ void wm_window_close(bContext *C, wmWindowManager *wm, wmWindow *win) { wmWindow *win_other; @@ -679,19 +660,6 @@ static void wm_window_ghostwindow_ensure(wmWindowManager *wm, wmWindow *win, boo ED_screen_global_areas_refresh(win); } -/** - * Initialize #wmWindow without ghostwin, open these and clear. - * - * window size is read from window, if 0 it uses prefsize - * called in #WM_check, also inits stuff after file read. - * - * \warning - * After running, 'win->ghostwin' can be NULL in rare cases - * (where OpenGL driver fails to create a context for eg). - * We could remove them with #wm_window_ghostwindows_remove_invalid - * but better not since caller may continue to use. - * Instead, caller needs to handle the error case and cleanup. - */ void wm_window_ghostwindows_ensure(wmWindowManager *wm) { BLI_assert(G.background == false); @@ -715,10 +683,6 @@ void wm_window_ghostwindows_ensure(wmWindowManager *wm) } } -/** - * Call after #wm_window_ghostwindows_ensure or #WM_check - * (after loading a new file) in the unlikely event a window couldn't be created. - */ void wm_window_ghostwindows_remove_invalid(bContext *C, wmWindowManager *wm) { BLI_assert(G.background == false); @@ -756,14 +720,6 @@ static bool wm_window_update_size_position(wmWindow *win) return false; } -/** - * \param space_type: SPACE_VIEW3D, SPACE_INFO, ... (eSpace_Type) - * \param toplevel: Not a child owned by other windows. A peer of main window. - * \param dialog: whether this should be made as a dialog-style window - * \param temp: whether this is considered a short-lived window - * \param alignment: how this window is positioned relative to its parent - * \return the window or NULL in case of failure. - */ wmWindow *WM_window_open(bContext *C, const char *title, int x, @@ -952,7 +908,6 @@ int wm_window_new_main_exec(bContext *C, wmOperator *op) return OPERATOR_FINISHED; } -/* fullscreen operator callback */ int wm_window_fullscreen_toggle_exec(bContext *C, wmOperator *UNUSED(op)) { wmWindow *window = CTX_wm_window(C); @@ -1083,7 +1038,6 @@ void wm_window_make_drawable(wmWindowManager *wm, wmWindow *win) } } -/* Reset active the current window opengl drawing context. */ void wm_window_reset_drawable(void) { BLI_assert(BLI_thread_is_main()); @@ -1585,10 +1539,6 @@ void wm_window_process_events(const bContext *C) /** \name Ghost Init/Exit * \{ */ -/** - * \note #bContext can be null in background mode because we don't - * need to event handling. - */ void wm_ghost_init(bContext *C) { if (!g_system) { @@ -1627,7 +1577,6 @@ void wm_ghost_exit(void) /** \name Event Timer * \{ */ -/* to (de)activate running timers temporary */ void WM_event_timer_sleep(wmWindowManager *wm, wmWindow *UNUSED(win), wmTimer *timer, @@ -1769,19 +1718,11 @@ static char *wm_clipboard_text_get_ex(bool selection, int *r_len, bool firstline return newbuf; } -/** - * Return text from the clipboard. - * - * \note Caller needs to check for valid utf8 if this is a requirement. - */ char *WM_clipboard_text_get(bool selection, int *r_len) { return wm_clipboard_text_get_ex(selection, r_len, false); } -/** - * Convenience function for pasting to areas of Blender which don't support newlines. - */ char *WM_clipboard_text_get_firstline(bool selection, int *r_len) { return wm_clipboard_text_get_ex(selection, r_len, true); @@ -1890,9 +1831,6 @@ void wm_window_raise(wmWindow *win) /** \name Window Buffers * \{ */ -/** - * \brief Push rendered buffer to the screen. - */ void wm_window_swap_buffers(wmWindow *win) { GHOST_SwapWindowBuffers(win->ghostwin); @@ -2034,7 +1972,6 @@ uint *WM_window_pixels_read(wmWindowManager *wm, wmWindow *win, int r_size[2]) /** \name Initial Window State API * \{ */ -/* called whem no ghost system was initialized */ void WM_init_state_size_set(int stax, int stay, int sizx, int sizy) { wm_init_state.start_x = stax; /* left hand pos */ @@ -2044,7 +1981,6 @@ void WM_init_state_size_set(int stax, int stay, int sizx, int sizy) wm_init_state.override_flag |= WIN_OVERRIDE_GEOM; } -/* for borderless and border windows set from command-line */ void WM_init_state_fullscreen_set(void) { wm_init_state.windowstate = GHOST_kWindowStateFullScreen; @@ -2097,7 +2033,6 @@ void WM_init_tablet_api(void) } } -/* This function requires access to the GHOST_SystemHandle (g_system) */ void WM_cursor_warp(wmWindow *win, int x, int y) { if (win && win->ghostwin) { @@ -2114,9 +2049,6 @@ void WM_cursor_warp(wmWindow *win, int x, int y) } } -/** - * Set x, y to values we can actually position the cursor to. - */ void WM_cursor_compatible_xy(wmWindow *win, int *x, int *y) { float f = GHOST_GetNativePixelSize(win->ghostwin); @@ -2132,11 +2064,6 @@ void WM_cursor_compatible_xy(wmWindow *win, int *x, int *y) /** \name Window Size (public) * \{ */ -/** - * Support for native pixel size - * - * \note macOS retina opens window in size X, but it has up to 2 x more pixels. - */ int WM_window_pixels_x(const wmWindow *win) { float f = GHOST_GetNativePixelSize(win->ghostwin); @@ -2150,17 +2077,10 @@ int WM_window_pixels_y(const wmWindow *win) return (int)(f * (float)win->sizey); } -/** - * Get boundaries usable by all window contents, including global areas. - */ void WM_window_rect_calc(const wmWindow *win, rcti *r_rect) { BLI_rcti_init(r_rect, 0, WM_window_pixels_x(win), 0, WM_window_pixels_y(win)); } -/** - * Get boundaries usable by screen-layouts, excluding global areas. - * \note Depends on U.dpi_fac. Should that be outdated, call #WM_window_set_dpi first. - */ void WM_window_screen_rect_calc(const wmWindow *win, rcti *r_rect) { rcti window_rect, screen_rect; @@ -2210,11 +2130,6 @@ bool WM_window_is_maximized(const wmWindow *win) /** \name Window Screen/Scene/WorkSpaceViewLayer API * \{ */ -/** - * Some editor data may need to be synced with scene data (3D View camera and layers). - * This function ensures data is synced for editors - * in visible workspaces and their visible layouts. - */ void WM_windows_scene_data_sync(const ListBase *win_lb, Scene *scene) { LISTBASE_FOREACH (wmWindow *, win, win_lb) { @@ -2261,9 +2176,6 @@ Scene *WM_window_get_active_scene(const wmWindow *win) return win->scene; } -/** - * \warning Only call outside of area/region loops - */ void WM_window_set_active_scene(Main *bmain, bContext *C, wmWindow *win, Scene *scene) { wmWindowManager *wm = CTX_wm_manager(C); @@ -2376,9 +2288,6 @@ void WM_window_set_active_layout(wmWindow *win, WorkSpace *workspace, WorkSpaceL BKE_workspace_active_layout_set(win->workspace_hook, win->winid, workspace, layout); } -/** - * Get the active screen of the active workspace in \a win. - */ bScreen *WM_window_get_active_screen(const wmWindow *win) { const WorkSpace *workspace = WM_window_get_active_workspace(win); diff --git a/source/blender/windowmanager/message_bus/intern/wm_message_bus.c b/source/blender/windowmanager/message_bus/intern/wm_message_bus.c index 86a106462c3..81ef8c881f5 100644 --- a/source/blender/windowmanager/message_bus/intern/wm_message_bus.c +++ b/source/blender/windowmanager/message_bus/intern/wm_message_bus.c @@ -147,16 +147,6 @@ void WM_msgbus_handle(struct wmMsgBus *mbus, struct bContext *C) // printf("msgbus: keys=%u values=%u\n", a, b); } -/** - * \param msg_key_test: Needs following #wmMsgSubscribeKey fields filled in: - * - msg.params - * - msg.head.type - * - msg.head.id - * .. other values should be zeroed. - * - * \return The key for this subscription. - * note that this is only needed in rare cases when the key needs further manipulation. - */ wmMsgSubscribeKey *WM_msg_subscribe_with_key(struct wmMsgBus *mbus, const wmMsgSubscribeKey *msg_key_test, const wmMsgSubscribeValue *msg_val_params) @@ -239,9 +229,6 @@ void WM_msg_id_remove(struct wmMsgBus *mbus, const struct ID *id) * \note While we could have a separate type for ID's, use RNA since there is enough overlap. * \{ */ -/** - * \note #wmMsgBus.messages_tag_count isn't updated, caller must handle. - */ void wm_msg_subscribe_value_free(wmMsgSubscribeKey *msg_key, wmMsgSubscribeValueLink *msg_lnk) { if (msg_lnk->params.free_data) { diff --git a/source/blender/windowmanager/message_bus/intern/wm_message_bus_intern.h b/source/blender/windowmanager/message_bus/intern/wm_message_bus_intern.h index 24c0192fe14..18df17c3d1c 100644 --- a/source/blender/windowmanager/message_bus/intern/wm_message_bus_intern.h +++ b/source/blender/windowmanager/message_bus/intern/wm_message_bus_intern.h @@ -30,6 +30,9 @@ struct wmMsgBus { uint messages_tag_count; }; +/** + * \note #wmMsgBus.messages_tag_count isn't updated, caller must handle. + */ void wm_msg_subscribe_value_free(struct wmMsgSubscribeKey *msg_key, struct wmMsgSubscribeValueLink *msg_lnk); diff --git a/source/blender/windowmanager/message_bus/wm_message_bus.h b/source/blender/windowmanager/message_bus/wm_message_bus.h index f923947c883..7ee2e5b6ee6 100644 --- a/source/blender/windowmanager/message_bus/wm_message_bus.h +++ b/source/blender/windowmanager/message_bus/wm_message_bus.h @@ -124,6 +124,16 @@ void WM_msg_dump(struct wmMsgBus *mbus, const char *info); void WM_msgbus_handle(struct wmMsgBus *mbus, struct bContext *C); void WM_msg_publish_with_key(struct wmMsgBus *mbus, wmMsgSubscribeKey *msg_key); +/** + * \param msg_key_test: Needs following #wmMsgSubscribeKey fields filled in: + * - `msg.params` + * - `msg.head.type` + * - `msg.head.id` + * .. other values should be zeroed. + * + * \return The key for this subscription. + * note that this is only needed in rare cases when the key needs further manipulation. + */ wmMsgSubscribeKey *WM_msg_subscribe_with_key(struct wmMsgBus *mbus, const wmMsgSubscribeKey *msg_key_test, const wmMsgSubscribeValue *msg_val_params); diff --git a/source/blender/windowmanager/wm.h b/source/blender/windowmanager/wm.h index cfef70b7dcc..e67b1581875 100644 --- a/source/blender/windowmanager/wm.h +++ b/source/blender/windowmanager/wm.h @@ -43,49 +43,98 @@ typedef struct wmPaintCursor { short region_type; } wmPaintCursor; +/** + * Cause a delayed #WM_exit() + * call to avoid leaking memory when trying to exit from within operators. + */ void wm_exit_schedule_delayed(const bContext *C); +/** + * Context is allowed to be NULL, do not free wm itself (lib_id.c). + */ extern void wm_close_and_free(bContext *C, wmWindowManager *); extern void wm_close_and_free_all(bContext *C, ListBase *); +/** + * On startup, it adds all data, for matching. + */ extern void wm_add_default(struct Main *bmain, bContext *C); extern void wm_clear_default_size(bContext *C); /* register to windowmanager for redo or macro */ + +/** + * Called on event handling by `event_system.c`. + * + * All operations get registered in the windowmanager here. + */ void wm_operator_register(bContext *C, wmOperator *op); /* wm_operator.c, for init/exit */ + void wm_operatortype_free(void); +/** + * Called on initialize #WM_init(). + */ void wm_operatortype_init(void); +/** + * Default key-map for windows and screens, only call once per WM. + */ void wm_window_keymap(wmKeyConfig *keyconf); void wm_operatortypes_register(void); /* wm_gesture.c */ +/* called in wm_draw.c */ + void wm_gesture_draw(struct wmWindow *win); +/** + * Tweak and line gestures. + */ int wm_gesture_evaluate(wmGesture *gesture, const struct wmEvent *event); void wm_gesture_tag_redraw(struct wmWindow *win); /* wm_gesture_ops.c */ + +/** + * Standard tweak, called after window handlers passed on event. + */ void wm_tweakevent_test(bContext *C, const wmEvent *event, int action); /* wm_jobs.c */ + +/** + * Hard-coded to event #TIMERJOBS. + */ void wm_jobs_timer(wmWindowManager *wm, wmTimer *wt); +/** + * Kill job entirely, also removes timer itself. + */ void wm_jobs_timer_end(wmWindowManager *wm, wmTimer *wt); /* wm_files.c */ + +/** + * Run the auto-save timer action. + */ void wm_autosave_timer(struct Main *bmain, wmWindowManager *wm, wmTimer *wt); void wm_autosave_timer_begin(struct wmWindowManager *wm); void wm_autosave_timer_end(wmWindowManager *wm); void wm_autosave_delete(void); /* wm_splash_screen.c */ + void WM_OT_splash(wmOperatorType *ot); void WM_OT_splash_about(wmOperatorType *ot); /* wm_stereo.c */ + void wm_stereo3d_draw_sidebyside(wmWindow *win, int view); void wm_stereo3d_draw_topbottom(wmWindow *win, int view); +/** + * If needed, adjust \a r_mouse_xy + * so that drawn cursor and handled mouse position are matching visually. + */ void wm_stereo3d_mouse_offset_apply(wmWindow *win, int r_mouse_xy[2]); int wm_stereo3d_set_exec(bContext *C, wmOperator *op); int wm_stereo3d_set_invoke(bContext *C, wmOperator *op, const wmEvent *event); @@ -93,7 +142,9 @@ void wm_stereo3d_set_draw(bContext *C, wmOperator *op); bool wm_stereo3d_set_check(bContext *C, wmOperator *op); void wm_stereo3d_set_cancel(bContext *C, wmOperator *op); -/* init operator properties */ +/** + * Initialize operator properties. + */ void wm_open_init_load_ui(wmOperator *op, bool use_prefs); void wm_open_init_use_scripts(wmOperator *op, bool use_prefs); diff --git a/source/blender/windowmanager/wm_event_system.h b/source/blender/windowmanager/wm_event_system.h index 9b0f128d071..925be8ab183 100644 --- a/source/blender/windowmanager/wm_event_system.h +++ b/source/blender/windowmanager/wm_event_system.h @@ -144,20 +144,36 @@ typedef struct wmEventHandler_Dropbox { } wmEventHandler_Dropbox; /* wm_event_system.c */ + void wm_event_free_all(wmWindow *win); void wm_event_free(wmEvent *event); void wm_event_free_handler(wmEventHandler *handler); -/* goes over entire hierarchy: events -> window -> screen -> area -> region */ +/** + * Goes over entire hierarchy: events -> window -> screen -> area -> region. + * + * \note Called in main loop. + */ void wm_event_do_handlers(bContext *C); +/** + * Windows store own event queues #wmWindow.event_queue (no #bContext here). + */ void wm_event_add_ghostevent(wmWindowManager *wm, wmWindow *win, int type, void *customdata); #ifdef WITH_XR_OPENXR void wm_event_add_xrevent(wmWindow *win, struct wmXrActionData *actiondata, short val); #endif void wm_event_do_depsgraph(bContext *C, bool is_after_open_file); +/** + * Was part of #wm_event_do_notifiers, + * split out so it can be called once before entering the #WM_main loop. + * This ensures operators don't run before the UI and depsgraph are initialized. + */ void wm_event_do_refresh_wm_and_depsgraph(bContext *C); +/** + * Called in main-loop. + */ void wm_event_do_notifiers(bContext *C); void wm_event_handler_ui_cancel_ex(bContext *C, @@ -166,17 +182,36 @@ void wm_event_handler_ui_cancel_ex(bContext *C, bool reactivate_button); /* wm_event_query.c */ + +/** + * Applies the global tablet pressure correction curve. + */ float wm_pressure_curve(float raw_pressure); void wm_tablet_data_from_ghost(const struct GHOST_TabletData *tablet_data, wmTabletData *wmtab); -/* wm_keymap.c */ - /* wm_dropbox.c */ + void wm_dropbox_free(void); +/** + * Additional work to cleanly end dragging. Additional because this doesn't actually remove the + * drag items. Should be called whenever dragging is stopped + * (successful or not, also when canceled). + */ void wm_drags_exit(wmWindowManager *wm, wmWindow *win); void wm_drop_prepare(bContext *C, wmDrag *drag, wmDropBox *drop); +/** + * Called in inner handler loop, region context. + */ void wm_drags_check_ops(bContext *C, const wmEvent *event); +/** + * The operator of a dropbox should always be executed in the context determined by the mouse + * coordinates. The dropbox poll should check the context area and region as needed. + * So this always returns #WM_OP_INVOKE_DEFAULT. + */ wmOperatorCallContext wm_drop_operator_context_get(const wmDropBox *drop); +/** + * Called in #wm_draw_window_onscreen. + */ void wm_drags_draw(bContext *C, wmWindow *win); #ifdef __cplusplus diff --git a/source/blender/windowmanager/wm_files.h b/source/blender/windowmanager/wm_files.h index 135f31cf8ac..e63afb2ed2f 100644 --- a/source/blender/windowmanager/wm_files.h +++ b/source/blender/windowmanager/wm_files.h @@ -33,6 +33,7 @@ extern "C" { #endif /* wm_files.c */ + void wm_history_file_read(void); struct wmHomeFileRead_Params { @@ -62,6 +63,16 @@ struct wmHomeFileRead_Params { const char *app_template_override; }; +/** + * Called on startup, (context entirely filled with NULLs) + * or called for 'New File' both `startup.blend` and `userpref.blend` are checked. + * + * \param r_params_file_read_post: Support postponed initialization, + * needed for initial startup when only some sub-systems have been initialized. + * When non-null, #wm_file_read_post doesn't run, instead it's arguments are stored + * in this return argument. + * The caller is responsible for calling #wm_homefile_read_post with this return argument. + */ void wm_homefile_read_ex(struct bContext *C, const struct wmHomeFileRead_Params *params_homefile, struct ReportList *reports, @@ -70,15 +81,26 @@ void wm_homefile_read(struct bContext *C, const struct wmHomeFileRead_Params *params_homefile, struct ReportList *reports); +/** + * Special case, support deferred execution of #wm_file_read_post, + * Needed when loading for the first time to workaround order of initialization bug, see T89046. + */ void wm_homefile_read_post(struct bContext *C, const struct wmFileReadPost_Params *params_file_read_post); void wm_file_read_report(bContext *C, struct Main *bmain); void wm_close_file_dialog(bContext *C, struct wmGenericCallback *post_action); +/** + * \return True if the dialog was created, the calling operator should return #OPERATOR_INTERFACE + * then. + */ bool wm_operator_close_file_dialog_if_needed(bContext *C, wmOperator *op, wmGenericCallbackFn exec_fn); +/** + * Check if there is data that would be lost when closing the current file without saving. + */ bool wm_file_or_session_data_has_unsaved_changes(const Main *bmain, const wmWindowManager *wm); void WM_OT_save_homefile(struct wmOperatorType *ot); @@ -99,6 +121,7 @@ void WM_OT_save_as_mainfile(struct wmOperatorType *ot); void WM_OT_save_mainfile(struct wmOperatorType *ot); /* wm_files_link.c */ + void WM_OT_link(struct wmOperatorType *ot); void WM_OT_append(struct wmOperatorType *ot); diff --git a/source/blender/windowmanager/wm_window.h b/source/blender/windowmanager/wm_window.h index f205f923ec8..e44a39ecf1a 100644 --- a/source/blender/windowmanager/wm_window.h +++ b/source/blender/windowmanager/wm_window.h @@ -30,41 +30,93 @@ extern "C" { #endif /* *************** internal api ************** */ + +/** + * \note #bContext can be null in background mode because we don't + * need to event handling. + */ void wm_ghost_init(bContext *C); void wm_ghost_exit(void); +/** + * This one should correctly check for apple top header... + * done for Cocoa: returns window contents (and not frame) max size. + */ void wm_get_screensize(int *r_width, int *r_height); +/** + * Size of all screens (desktop), useful since the mouse is bound by this. + */ void wm_get_desktopsize(int *r_width, int *r_height); +/** + * Don't change context itself. + */ wmWindow *wm_window_new(const struct Main *bmain, wmWindowManager *wm, wmWindow *parent, bool dialog); +/** + * Part of `wm_window.c` API. + */ wmWindow *wm_window_copy(struct Main *bmain, wmWindowManager *wm, wmWindow *win_src, const bool duplicate_layout, const bool child); +/** + * A higher level version of copy that tests the new window can be added. + * (called from the operator directly). + */ wmWindow *wm_window_copy_test(bContext *C, wmWindow *win_src, const bool duplicate_layout, const bool child); +/** + * Including window itself. + * \param C: can be NULL. + * \note #ED_screen_exit should have been called. + */ void wm_window_free(bContext *C, wmWindowManager *wm, wmWindow *win); +/** + * This is event from ghost, or exit-Blender operator. + */ void wm_window_close(bContext *C, wmWindowManager *wm, wmWindow *win); void wm_window_title(wmWindowManager *wm, wmWindow *win); +/** + * Initialize #wmWindow without `ghostwin`, open these and clear. + * + * Window size is read from window, if 0 it uses prefsize + * called in #WM_check, also initialize stuff after file read. + * + * \warning After running, `win->ghostwin` can be NULL in rare cases + * (where OpenGL driver fails to create a context for eg). + * We could remove them with #wm_window_ghostwindows_remove_invalid + * but better not since caller may continue to use. + * Instead, caller needs to handle the error case and cleanup. + */ void wm_window_ghostwindows_ensure(wmWindowManager *wm); +/** + * Call after #wm_window_ghostwindows_ensure or #WM_check + * (after loading a new file) in the unlikely event a window couldn't be created. + */ void wm_window_ghostwindows_remove_invalid(bContext *C, wmWindowManager *wm); void wm_window_process_events(const bContext *C); void wm_window_clear_drawable(wmWindowManager *wm); void wm_window_make_drawable(wmWindowManager *wm, wmWindow *win); +/** + * Reset active the current window opengl drawing context. + */ void wm_window_reset_drawable(void); void wm_window_raise(wmWindow *win); void wm_window_lower(wmWindow *win); void wm_window_set_size(wmWindow *win, int width, int height); void wm_window_get_position(wmWindow *win, int *r_pos_x, int *r_pos_y); +/** + * \brief Push rendered buffer to the screen. + */ void wm_window_swap_buffers(wmWindow *win); void wm_window_set_swap_interval(wmWindow *win, int interval); bool wm_window_get_swap_interval(wmWindow *win, int *intervalOut); @@ -79,8 +131,19 @@ void wm_window_IME_end(wmWindow *win); #endif /* *************** window operators ************** */ + int wm_window_close_exec(bContext *C, struct wmOperator *op); +/** + * Full-screen operator callback. + */ int wm_window_fullscreen_toggle_exec(bContext *C, struct wmOperator *op); +/** + * Call the quit confirmation prompt or exit directly if needed. The use can + * still cancel via the confirmation popup. Also, this may not quit Blender + * immediately, but rather schedule the closing. + * + * \param win: The window to show the confirmation popup/window in. + */ void wm_quit_with_optional_confirmation_prompt(bContext *C, wmWindow *win) ATTR_NONNULL(); int wm_window_new_exec(bContext *C, struct wmOperator *op); diff --git a/source/blender/windowmanager/xr/intern/wm_xr_actionmap.c b/source/blender/windowmanager/xr/intern/wm_xr_actionmap.c index 8903305adb4..8c38b8f0360 100644 --- a/source/blender/windowmanager/xr/intern/wm_xr_actionmap.c +++ b/source/blender/windowmanager/xr/intern/wm_xr_actionmap.c @@ -85,9 +85,6 @@ static XrActionMapBinding *wm_xr_actionmap_binding_find_except(XrActionMapItem * return NULL; } -/** - * Ensure unique name among all action map bindings. - */ void WM_xr_actionmap_binding_ensure_unique(XrActionMapItem *ami, XrActionMapBinding *amb) { char name[MAX_NAME]; @@ -198,10 +195,6 @@ static void wm_xr_actionmap_item_properties_free(XrActionMapItem *ami) } } -/** - * Similar to #wm_xr_actionmap_item_properties_set() - * but checks for the #eXrActionType and #wmOperatorType having changed. - */ void WM_xr_actionmap_item_properties_update_ot(XrActionMapItem *ami) { switch (ami->type) { @@ -278,9 +271,6 @@ static XrActionMapItem *wm_xr_actionmap_item_find_except(XrActionMap *actionmap, return NULL; } -/** - * Ensure unique name among all action map items. - */ void WM_xr_actionmap_item_ensure_unique(XrActionMap *actionmap, XrActionMapItem *ami) { char name[MAX_NAME]; @@ -411,9 +401,6 @@ static XrActionMap *wm_xr_actionmap_find_except(wmXrRuntimeData *runtime, return NULL; } -/** - * Ensure unique name among all action maps. - */ void WM_xr_actionmap_ensure_unique(wmXrRuntimeData *runtime, XrActionMap *actionmap) { char name[MAX_NAME]; diff --git a/source/blender/windowmanager/xr/intern/wm_xr_draw.c b/source/blender/windowmanager/xr/intern/wm_xr_draw.c index 72d88bb3043..5d0163af5e1 100644 --- a/source/blender/windowmanager/xr/intern/wm_xr_draw.c +++ b/source/blender/windowmanager/xr/intern/wm_xr_draw.c @@ -139,12 +139,6 @@ static void wm_xr_draw_viewport_buffers_to_active_framebuffer( GPU_viewport_draw_to_screen_ex(vp->viewport, 0, &rect, draw_view->expects_srgb_buffer, true); } -/** - * \brief Draw a viewport for a single eye. - * - * This is the main viewport drawing function for VR sessions. It's assigned to Ghost-XR as a - * callback (see GHOST_XrDrawViewFunc()) and executed for each view (read: eye). - */ void wm_xr_draw_view(const GHOST_XrDrawViewInfo *draw_view, void *customdata) { wmXrDrawData *draw_data = customdata; diff --git a/source/blender/windowmanager/xr/intern/wm_xr_intern.h b/source/blender/windowmanager/xr/intern/wm_xr_intern.h index 7de1f254224..e2368901757 100644 --- a/source/blender/windowmanager/xr/intern/wm_xr_intern.h +++ b/source/blender/windowmanager/xr/intern/wm_xr_intern.h @@ -213,6 +213,11 @@ void wm_xr_session_draw_data_update(wmXrSessionState *state, const XrSessionSettings *settings, const GHOST_XrDrawViewInfo *draw_view, wmXrDrawData *draw_data); +/** + * Update information that is only stored for external state queries. E.g. for Python API to + * request the current (as in, last known) viewer pose. + * Controller data and action sets will be updated separately via wm_xr_session_actions_update(). + */ void wm_xr_session_state_update(const XrSessionSettings *settings, const wmXrDrawData *draw_data, const GHOST_XrDrawViewInfo *draw_view, @@ -230,9 +235,16 @@ void wm_xr_session_controller_data_populate(const wmXrAction *grip_action, void wm_xr_session_controller_data_clear(wmXrSessionState *state); /* wm_xr_draw.c */ + void wm_xr_pose_to_mat(const GHOST_XrPose *pose, float r_mat[4][4]); void wm_xr_pose_scale_to_mat(const GHOST_XrPose *pose, float scale, float r_mat[4][4]); void wm_xr_pose_to_imat(const GHOST_XrPose *pose, float r_imat[4][4]); void wm_xr_pose_scale_to_imat(const GHOST_XrPose *pose, float scale, float r_imat[4][4]); +/** + * \brief Draw a viewport for a single eye. + * + * This is the main viewport drawing function for VR sessions. It's assigned to Ghost-XR as a + * callback (see GHOST_XrDrawViewFunc()) and executed for each view (read: eye). + */ void wm_xr_draw_view(const GHOST_XrDrawViewInfo *draw_view, void *customdata); void wm_xr_draw_controllers(const struct bContext *C, struct ARegion *region, void *customdata); diff --git a/source/blender/windowmanager/xr/intern/wm_xr_session.c b/source/blender/windowmanager/xr/intern/wm_xr_session.c index 3224869b04a..3fbf923e7a6 100644 --- a/source/blender/windowmanager/xr/intern/wm_xr_session.c +++ b/source/blender/windowmanager/xr/intern/wm_xr_session.c @@ -154,10 +154,6 @@ void wm_xr_session_toggle(wmWindowManager *wm, } } -/** - * Check if the XR-Session was triggered. - * If an error happened while trying to start a session, this returns false too. - */ bool WM_xr_session_exists(const wmXrData *xr) { return xr->runtime && xr->runtime->context && xr->runtime->session_state.is_started; @@ -168,9 +164,6 @@ void WM_xr_session_base_pose_reset(wmXrData *xr) xr->runtime->session_state.force_reset_to_base_pose = true; } -/** - * Check if the session is running, according to the OpenXR definition. - */ bool WM_xr_session_is_ready(const wmXrData *xr) { return WM_xr_session_exists(xr) && GHOST_XrSessionIsRunning(xr->runtime->context); @@ -354,11 +347,6 @@ void wm_xr_session_draw_data_update(wmXrSessionState *state, } } -/** - * Update information that is only stored for external state queries. E.g. for Python API to - * request the current (as in, last known) viewer pose. - * Controller data and action sets will be updated separately via wm_xr_session_actions_update(). - */ void wm_xr_session_state_update(const XrSessionSettings *settings, const wmXrDrawData *draw_data, const GHOST_XrDrawViewInfo *draw_view, -- cgit v1.2.3