diff options
Diffstat (limited to 'source/blender/editors/include/UI_view2d.h')
| -rw-r--r-- | source/blender/editors/include/UI_view2d.h | 187 |
1 files changed, 171 insertions, 16 deletions
diff --git a/source/blender/editors/include/UI_view2d.h b/source/blender/editors/include/UI_view2d.h index 122e5a7d839..c38c4dc1156 100644 --- a/source/blender/editors/include/UI_view2d.h +++ b/source/blender/editors/include/UI_view2d.h @@ -118,21 +118,46 @@ typedef struct View2DScrollers View2DScrollers; /* ----------------------------------------- */ /* Prototypes: */ -/* refresh and validation (of view rects) */ +/** + * Refresh and validation (of view rects). + * + * Initialize all relevant View2D data (including view rects if first time) + * and/or refresh mask sizes after view resize. + * + * - For some of these presets, it is expected that the region will have defined some + * additional settings necessary for the customization of the 2D viewport to its requirements + * - This function should only be called from region init() callbacks, where it is expected that + * this is called before #UI_view2d_size_update(), + * as this one checks that the rects are properly initialized. + */ void UI_view2d_region_reinit(struct View2D *v2d, short type, int winx, int winy); void UI_view2d_curRect_validate(struct View2D *v2d); +/** + * Restore 'cur' rect to standard orientation (i.e. optimal maximum view of tot). + * This does not take into account if zooming the view on an axis + * will improve the view (if allowed). + */ void UI_view2d_curRect_reset(struct View2D *v2d); bool UI_view2d_area_supports_sync(struct ScrArea *area); +/** + * Called by menus to activate it, or by view2d operators + * to make sure 'related' views stay in synchrony. + */ void UI_view2d_sync(struct bScreen *screen, struct ScrArea *area, struct View2D *v2dcur, int flag); -/* Perform all required updates after `v2d->cur` as been modified. +/** + * Perform all required updates after `v2d->cur` as been modified. * This includes like validation view validation (#UI_view2d_curRect_validate). * - * Current intent is to use it from user code, such as view navigation and zoom operations. */ + * Current intent is to use it from user code, such as view navigation and zoom operations. + */ void UI_view2d_curRect_changed(const struct bContext *C, struct View2D *v2d); void UI_view2d_totRect_set(struct View2D *v2d, int width, int height); +/** + * Change the size of the maximum viewable area (i.e. 'tot' rect). + */ void UI_view2d_totRect_set_resize(struct View2D *v2d, int width, int height, bool resize); void UI_view2d_mask_from_win(const struct View2D *v2d, struct rcti *r_mask); @@ -140,13 +165,37 @@ void UI_view2d_mask_from_win(const struct View2D *v2d, struct rcti *r_mask); void UI_view2d_zoom_cache_reset(void); /* view matrix operations */ +/** + * Set view matrices to use 'cur' rect as viewing frame for View2D drawing. + */ void UI_view2d_view_ortho(const struct View2D *v2d); +/** + * Set view matrices to only use one axis of 'cur' only + * + * \param xaxis: if non-zero, only use cur x-axis, + * otherwise use cur-yaxis (mostly this will be used for x). + */ void UI_view2d_view_orthoSpecial(struct ARegion *region, struct View2D *v2d, const bool xaxis); +/** + * Restore view matrices after drawing. + */ void UI_view2d_view_restore(const struct bContext *C); /* grid drawing */ + +/** + * Draw a multi-level grid in given 2d-region. + */ void UI_view2d_multi_grid_draw( const struct View2D *v2d, int colorid, float step, int level_size, int totlevels); +/** + * Draw a multi-level grid of dots, with a dynamic number of levels based on the fading. + * + * \param grid_color_id: The theme color used for the points. Faded dynamically based on zoom. + * \param min_step: The base size of the grid. At different zoom levels, the visible grid may have + * a larger step size. + * \param grid_levels: The maximum grid depth. Larger grid levels will subdivide the grid more. + */ void UI_view2d_dot_grid_draw(const struct View2D *v2d, int grid_color_id, float step, @@ -171,7 +220,9 @@ float UI_view2d_grid_resolution_x__frames_or_seconds(const struct View2D *v2d, bool display_seconds); float UI_view2d_grid_resolution_y__values(const struct View2D *v2d); -/* scale indicator text drawing */ +/** + * Scale indicator text drawing. + */ void UI_view2d_draw_scale_y__values(const struct ARegion *region, const struct View2D *v2d, const struct rcti *rect, @@ -193,13 +244,33 @@ void UI_view2d_draw_scale_x__frames_or_seconds(const struct ARegion *region, bool display_seconds, int colorid); -/* scrollbar drawing */ +/* Scroll-bar drawing. */ + +/** + * Calculate relevant scroller properties. + */ void UI_view2d_scrollers_calc(struct View2D *v2d, const struct rcti *mask_custom, struct View2DScrollers *r_scrollers); +/** + * Draw scroll-bars in the given 2D-region. + */ void UI_view2d_scrollers_draw(struct View2D *v2d, const struct rcti *mask_custom); -/* list view tools */ +/* List view tools. */ + +/** + * Get the 'cell' (row, column) that the given 2D-view coordinates + * (i.e. in 'tot' rect space) lie in. + * + * \param columnwidth, rowheight: size of each 'cell' + * \param startx, starty: coordinates (in 'tot' rect space) that the list starts from. + * This should be (0,0) for most views. However, for those where the starting row was offsetted + * (like for Animation Editor channel lists, to make the first entry more visible), these will be + * the min-coordinates of the first item. + * \param viewx, viewy: 2D-coordinates (in 2D-view / 'tot' rect space) to get the cell for + * \param r_column, r_row: the 'coordinates' of the relevant 'cell' + */ void UI_view2d_listview_view_to_cell(float columnwidth, float rowheight, float startx, @@ -209,9 +280,16 @@ void UI_view2d_listview_view_to_cell(float columnwidth, int *column, int *row); -/* coordinate conversion */ +/* Coordinate conversion. */ + float UI_view2d_region_to_view_x(const struct View2D *v2d, float x); float UI_view2d_region_to_view_y(const struct View2D *v2d, float y); +/** + * Convert from screen/region space to 2d-View space + * + * \param x, y: coordinates to convert + * \param r_view_x, r_view_y: resultant coordinates + */ void UI_view2d_region_to_view( const struct View2D *v2d, float x, float y, float *r_view_x, float *r_view_y) ATTR_NONNULL(); void UI_view2d_region_to_view_rctf(const struct View2D *v2d, @@ -220,9 +298,24 @@ void UI_view2d_region_to_view_rctf(const struct View2D *v2d, float UI_view2d_view_to_region_x(const struct View2D *v2d, float x); float UI_view2d_view_to_region_y(const struct View2D *v2d, float y); +/** + * Convert from 2d-View space to screen/region space + * \note Coordinates are clamped to lie within bounds of region + * + * \param x, y: Coordinates to convert. + * \param r_region_x, r_region_y: Resultant coordinates. + */ bool UI_view2d_view_to_region_clip( const struct View2D *v2d, float x, float y, int *r_region_x, int *r_region_y) ATTR_NONNULL(); +/** + * Convert from 2d-view space to screen/region space + * + * \note Coordinates are NOT clamped to lie within bounds of region. + * + * \param x, y: Coordinates to convert. + * \param r_region_x, r_region_y: Resultant coordinates. + */ void UI_view2d_view_to_region( const struct View2D *v2d, float x, float y, int *r_region_x, int *r_region_y) ATTR_NONNULL(); void UI_view2d_view_to_region_fl(const struct View2D *v2d, @@ -238,21 +331,64 @@ bool UI_view2d_view_to_region_rcti_clip(const struct View2D *v2d, const struct rctf *rect_src, struct rcti *rect_dst) ATTR_NONNULL(); -/* utilities */ +/* Utilities. */ + +/** + * View2D data by default resides in region, so get from region stored in context. + */ struct View2D *UI_view2d_fromcontext(const struct bContext *C); +/** + * Same as above, but it returns region-window. Utility for pull-downs or buttons. + */ struct View2D *UI_view2d_fromcontext_rwin(const struct bContext *C); +/** + * Get scrollbar sizes of the current 2D view. + * The size will be zero if the view has its scrollbars disabled. + */ void UI_view2d_scroller_size_get(const struct View2D *v2d, float *r_x, float *r_y); +/** + * Calculate the scale per-axis of the drawing-area + * + * Is used to inverse correct drawing of icons, etc. that need to follow view + * but not be affected by scale + * + * \param r_x, r_y: scale on each axis + */ void UI_view2d_scale_get(const struct View2D *v2d, float *r_x, float *r_y); float UI_view2d_scale_get_x(const struct View2D *v2d); float UI_view2d_scale_get_y(const struct View2D *v2d); +/** + * Same as `UI_view2d_scale_get() - 1.0f / x, y`. + */ void UI_view2d_scale_get_inverse(const struct View2D *v2d, float *r_x, float *r_y); +/** + * Simple functions for consistent center offset access. + * Used by node editor to shift view center for each individual node tree. + */ void UI_view2d_center_get(const struct View2D *v2d, float *r_x, float *r_y); void UI_view2d_center_set(struct View2D *v2d, float x, float y); +/** + * Simple pan function + * (0.0, 0.0) bottom left + * (0.5, 0.5) center + * (1.0, 1.0) top right. + */ void UI_view2d_offset(struct View2D *v2d, float xfac, float yfac); +/** + * Check if mouse is within scrollers + * + * \param x, y: Mouse coordinates in screen (not region) space. + * \param r_scroll: Mapped view2d scroll flag. + * + * \return appropriate code for match. + * - 'h' = in horizontal scroller. + * - 'v' = in vertical scroller. + * - 0 = not in scroller. + */ char UI_view2d_mouse_in_scrollers_ex(const struct ARegion *region, const struct View2D *v2d, const int xy[2], @@ -268,13 +404,18 @@ char UI_view2d_rect_in_scrollers(const struct ARegion *region, const struct View2D *v2d, const struct rcti *rect) ATTR_NONNULL(1, 2, 3); -/* cached text drawing in v2d, to allow pixel-aligned draw as post process */ +/** + * Cached text drawing in v2d, to allow pixel-aligned draw as post process. + */ void UI_view2d_text_cache_add(struct View2D *v2d, float x, float y, const char *str, size_t str_len, const unsigned char col[4]); +/** + * No clip (yet). + */ void UI_view2d_text_cache_add_rectf(struct View2D *v2d, const struct rctf *rect_view, const char *str, @@ -282,10 +423,15 @@ void UI_view2d_text_cache_add_rectf(struct View2D *v2d, const unsigned char col[4]); void UI_view2d_text_cache_draw(struct ARegion *region); -/* operators */ +/* Operators. */ + void ED_operatortypes_view2d(void); void ED_keymap_view2d(struct wmKeyConfig *keyconf); +/** + * Will start timer if appropriate. + * the arguments are the desired situation. + */ void UI_view2d_smooth_view(struct bContext *C, struct ARegion *region, const struct rctf *cur, @@ -294,13 +440,16 @@ void UI_view2d_smooth_view(struct bContext *C, #define UI_MARKER_MARGIN_Y (42 * UI_DPI_FAC) #define UI_TIME_SCRUB_MARGIN_Y (23 * UI_DPI_FAC) -/* Gizmo Types */ +/* Gizmo Types. */ /* view2d_gizmo_navigate.c */ -/* Caller passes in own idname. */ + +/** + * Caller defines the name for gizmo group. + */ void VIEW2D_GGT_navigate_impl(struct wmGizmoGroupType *gzgt, const char *idname); -/* Edge pan */ +/* Edge pan. */ /** * Custom-data for view panning operators. @@ -361,11 +510,15 @@ void UI_view2d_edge_pan_init(struct bContext *C, void UI_view2d_edge_pan_reset(struct View2DEdgePanData *vpd); -/* Apply transform to view (i.e. adjust 'cur' rect). */ +/** + * Apply transform to view (i.e. adjust 'cur' rect). + */ void UI_view2d_edge_pan_apply(struct bContext *C, struct View2DEdgePanData *vpd, const int xy[2]) ATTR_NONNULL(1, 2, 3); -/* Apply transform to view using mouse events. */ +/** + * Apply transform to view using mouse events. + */ void UI_view2d_edge_pan_apply_event(struct bContext *C, struct View2DEdgePanData *vpd, const struct wmEvent *event); @@ -382,7 +535,9 @@ void UI_view2d_edge_pan_operator_properties_ex(struct wmOperatorType *ot, float delay, float zoom_influence); -/* Initialize panning data with operator settings. */ +/** + * Initialize panning data with operator settings. + */ void UI_view2d_edge_pan_operator_init(struct bContext *C, struct View2DEdgePanData *vpd, struct wmOperator *op); |