[Bf-blender-cvs] [7e927174396] master: Cleanup: move public doc-strings into headers for 'windowmanager'
Campbell Barton
noreply at git.blender.org
Wed Dec 8 07:15:54 CET 2021
Commit: 7e927174396443cdc4c5544dad13faca7299d183
Author: Campbell Barton
Date: Wed Dec 8 17:12:41 2021 +1100
Branches: master
https://developer.blender.org/rB7e927174396443cdc4c5544dad13faca7299d183
Cleanup: move public doc-strings into headers for 'windowmanager'
Ref T92709
===================================================================
M source/blender/windowmanager/WM_api.h
M source/blender/windowmanager/WM_keymap.h
M source/blender/windowmanager/WM_toolsystem.h
M source/blender/windowmanager/gizmo/WM_gizmo_api.h
M source/blender/windowmanager/gizmo/intern/wm_gizmo.c
M source/blender/windowmanager/gizmo/intern/wm_gizmo_group.c
M source/blender/windowmanager/gizmo/intern/wm_gizmo_group_type.c
M source/blender/windowmanager/gizmo/intern/wm_gizmo_intern.h
M source/blender/windowmanager/gizmo/intern/wm_gizmo_map.c
M source/blender/windowmanager/gizmo/intern/wm_gizmo_target_props.c
M source/blender/windowmanager/gizmo/intern/wm_gizmo_type.c
M source/blender/windowmanager/gizmo/wm_gizmo_wmapi.h
M source/blender/windowmanager/intern/wm.c
M source/blender/windowmanager/intern/wm_cursors.c
M source/blender/windowmanager/intern/wm_dragdrop.c
M source/blender/windowmanager/intern/wm_event_query.c
M source/blender/windowmanager/intern/wm_event_system.c
M source/blender/windowmanager/intern/wm_files.c
M source/blender/windowmanager/intern/wm_files_link.c
M source/blender/windowmanager/intern/wm_gesture.c
M source/blender/windowmanager/intern/wm_gesture_ops.c
M source/blender/windowmanager/intern/wm_init_exit.c
M source/blender/windowmanager/intern/wm_jobs.c
M source/blender/windowmanager/intern/wm_keymap.c
M source/blender/windowmanager/intern/wm_keymap_utils.c
M source/blender/windowmanager/intern/wm_menu_type.c
M source/blender/windowmanager/intern/wm_operator_props.c
M source/blender/windowmanager/intern/wm_operator_type.c
M source/blender/windowmanager/intern/wm_operator_utils.c
M source/blender/windowmanager/intern/wm_operators.c
M source/blender/windowmanager/intern/wm_panel_type.c
M source/blender/windowmanager/intern/wm_stereo.c
M source/blender/windowmanager/intern/wm_subwindow.c
M source/blender/windowmanager/intern/wm_toolsystem.c
M source/blender/windowmanager/intern/wm_uilist_type.c
M source/blender/windowmanager/intern/wm_window.c
M source/blender/windowmanager/message_bus/intern/wm_message_bus.c
M source/blender/windowmanager/message_bus/intern/wm_message_bus_intern.h
M source/blender/windowmanager/message_bus/wm_message_bus.h
M source/blender/windowmanager/wm.h
M source/blender/windowmanager/wm_event_system.h
M source/blender/windowmanager/wm_files.h
M source/blender/windowmanager/wm_window.h
M source/blender/windowmanager/xr/intern/wm_xr_actionmap.c
M source/blender/windowmanager/xr/intern/wm_xr_draw.c
M source/blender/windowmanager/xr/intern/wm_xr_intern.h
M source/blender/windowmanager/xr/intern/wm_xr_session.c
===================================================================
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,
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list