diff options
author | Campbell Barton <ideasman42@gmail.com> | 2015-05-31 07:20:03 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2015-05-31 07:20:03 +0300 |
commit | 67bebc42f4a789487583b7e2c7f1174910ab67f9 (patch) | |
tree | 79d86ed9e28bf82543107ec6b4c3d07cf0ea31d0 /source/blender | |
parent | 28ef76d0f01788bd909fc5d854a494575d1c0017 (diff) |
UI: comments (doxygen tweaks)
Diffstat (limited to 'source/blender')
-rw-r--r-- | source/blender/editors/interface/interface.c | 39 | ||||
-rw-r--r-- | source/blender/editors/interface/interface_eyedropper.c | 14 | ||||
-rw-r--r-- | source/blender/editors/interface/interface_handlers.c | 29 | ||||
-rw-r--r-- | source/blender/editors/interface/interface_layout.c | 3 | ||||
-rw-r--r-- | source/blender/editors/interface/interface_ops.c | 8 | ||||
-rw-r--r-- | source/blender/editors/interface/interface_panel.c | 11 | ||||
-rw-r--r-- | source/blender/editors/interface/interface_style.c | 2 | ||||
-rw-r--r-- | source/blender/editors/interface/interface_templates.c | 26 | ||||
-rw-r--r-- | source/blender/editors/interface/interface_widgets.c | 32 | ||||
-rw-r--r-- | source/blender/editors/interface/resources.c | 5 | ||||
-rw-r--r-- | source/blender/editors/interface/view2d.c | 14 | ||||
-rw-r--r-- | source/blender/editors/interface/view2d_ops.c | 79 |
12 files changed, 142 insertions, 120 deletions
diff --git a/source/blender/editors/interface/interface.c b/source/blender/editors/interface/interface.c index 1eadd259295..4a48c9a967d 100644 --- a/source/blender/editors/interface/interface.c +++ b/source/blender/editors/interface/interface.c @@ -83,11 +83,11 @@ #define B_NOP -1 -/* - * a full doc with API notes can be found in bf-blender/trunk/blender/doc/guides/interface_API.txt +/** + * a full doc with API notes can be found in 'blender/doc/guides/interface_API.txt' * - * uiBlahBlah() external function - * ui_blah_blah() internal function + * `uiBlahBlah()` external function. + * `ui_blah_blah()` internal function. */ static void ui_but_free(const bContext *C, uiBut *but); @@ -1100,13 +1100,16 @@ static bool ui_but_event_property_operator_string(const bContext *C, uiBut *but, return found; } -/* this goes in a seemingly weird pattern: +/** + * This goes in a seemingly weird pattern: * + * <pre> * 4 * 5 6 * 1 2 * 7 8 * 3 + * </pre> * * but it's actually quite logical. It's designed to be 'upwards compatible' * for muscle memory so that the menu item locations are fixed and don't move @@ -3098,13 +3101,13 @@ void ui_block_cm_to_scene_linear_v3(uiBlock *block, float pixel[3]) /** * \brief ui_def_but is the function that draws many button types * - * \param x,y The lower left hand corner of the button (X axis) - * \param width,height The size of the button. + * \param x, y: The lower left hand corner of the button (X axis) + * \param width, height: The size of the button. * * for float buttons: - * - \a a1 Click Step (how much to change the value each click) - * - \a a2 Number of decimal point values to display. 0 defaults to 3 (0.000) - * 1,2,3, and a maximum of 4, all greater values will be clamped to 4. + * \param a1: Click Step (how much to change the value each click) + * \param a2: Number of decimal point values to display. 0 defaults to 3 (0.000) + * 1,2,3, and a maximum of 4, all greater values will be clamped to 4. */ static uiBut *ui_def_but( uiBlock *block, int type, int retval, const char *str, @@ -4321,8 +4324,11 @@ uiBut *uiDefSearchBut(uiBlock *block, void *arg, int retval, int icon, int maxle } -/* arg is user value, searchfunc and handlefunc both get it as arg */ -/* if active set, button opens with this item visible and selected */ +/** + * \param sfunc, bfunc: both get it as \a arg. + * \param arg: user value, + * \param active: when set, button opens with this item visible and selected. + */ void UI_but_func_search_set(uiBut *but, uiButSearchFunc sfunc, void *arg, uiButHandleFunc bfunc, void *active) { but->search_func = sfunc; @@ -4391,8 +4397,10 @@ static void operator_enum_call_cb(struct bContext *UNUSED(C), void *but, void *a } } -/* Same parameters as for uiDefSearchBut, with additional operator type and properties, used by callback - * to call again the right op with the right options (properties values). */ +/** + * Same parameters as for uiDefSearchBut, with additional operator type and properties, used by callback + * to call again the right op with the right options (properties values). + */ uiBut *uiDefSearchButO_ptr( uiBlock *block, wmOperatorType *ot, IDProperty *properties, void *arg, int retval, int icon, int maxlen, int x, int y, @@ -4415,7 +4423,8 @@ uiBut *uiDefSearchButO_ptr( return but; } -/* push a new event onto event queue to activate the given button +/** + * push a new event onto event queue to activate the given button * (usually a text-field) upon entering a popup */ void UI_but_focus_on_enter_event(wmWindow *win, uiBut *but) diff --git a/source/blender/editors/interface/interface_eyedropper.c b/source/blender/editors/interface/interface_eyedropper.c index 44e06bab4ab..4f77185fb8f 100644 --- a/source/blender/editors/interface/interface_eyedropper.c +++ b/source/blender/editors/interface/interface_eyedropper.c @@ -379,12 +379,11 @@ void UI_OT_eyedropper_color(wmOperatorType *ot) /* -------------------------------------------------------------------- */ -/* Data Dropper - * - * note: datadropper is only internal name to avoid confusion in this file - */ +/* Data Dropper */ /** \name Eyedropper (ID data-blocks) + * + * \note: datadropper is only internal name to avoid confusion in this file. * \{ */ typedef struct DataDropper { @@ -653,12 +652,11 @@ void UI_OT_eyedropper_id(wmOperatorType *ot) /* -------------------------------------------------------------------- */ -/* Depth Dropper - * - * note: depthdropper is only internal name to avoid confusion in this file - */ +/* Depth Dropper */ /** \name Eyedropper (Depth) + * + * \note: depthdropper is only internal name to avoid confusion in this file. * \{ */ typedef struct DepthDropper { diff --git a/source/blender/editors/interface/interface_handlers.c b/source/blender/editors/interface/interface_handlers.c index 4548c09080b..8c81ae071a7 100644 --- a/source/blender/editors/interface/interface_handlers.c +++ b/source/blender/editors/interface/interface_handlers.c @@ -198,7 +198,7 @@ static void ui_selectcontext_apply( #define IS_ALLSELECT_EVENT(event) ((event)->alt != 0) -/* just show a tinted color so users know its activated */ +/** just show a tinted color so users know its activated */ #define UI_BUT_IS_SELECT_CONTEXT UI_BUT_NODE_ACTIVE #endif /* USE_ALLSELECT */ @@ -206,15 +206,18 @@ static void ui_selectcontext_apply( #ifdef USE_DRAG_MULTINUM -/* how far to drag before we check for gesture direction (in pixels), +/** + * how far to drag before we check for gesture direction (in pixels), * note: half the height of a button is about right... */ #define DRAG_MULTINUM_THRESHOLD_DRAG_X (UI_UNIT_Y / 4) -/* how far to drag horizontally before we stop checking which buttons the gesture spans (in pixels), +/** + * how far to drag horizontally before we stop checking which buttons the gesture spans (in pixels), * locking down the buttons so we can drag freely without worrying about vertical movement. */ #define DRAG_MULTINUM_THRESHOLD_DRAG_Y (UI_UNIT_Y / 4) -/* how strict to be when detecting a vertical gesture, [0.5 == sloppy], [0.9 == strict], (unsigned dot-product) +/** + * how strict to be when detecting a vertical gesture, [0.5 == sloppy], [0.9 == strict], (unsigned dot-product) * note: we should be quite strict here, since doing a vertical gesture by accident should be avoided, * however with some care a user should be able to do a vertical movement without *missing*. */ #define DRAG_MULTINUM_THRESHOLD_VERTICAL (0.75f) @@ -2350,15 +2353,17 @@ static void ui_but_copy_paste(bContext *C, uiBut *but, uiHandleButtonData *data, } } -/* ************************ password text ****************************** +/** + * Password Text + * ============= * * Functions to convert password strings that should not be displayed - * to asterisk representation (e.g. mysecretpasswd -> *************) + * to asterisk representation (e.g. 'mysecretpasswd' -> '*************') * * It converts every UTF-8 character to an asterisk, and also remaps * the cursor position and selection start/end. * - * Note: remaping is used, because password could contain UTF-8 characters. + * \note: remaping is used, because password could contain UTF-8 characters. * */ @@ -2558,7 +2563,8 @@ static void ui_textedit_set_cursor_select(uiBut *but, uiHandleButtonData *data, ui_but_update(but); } -/* this is used for both utf8 and ascii, its meant to be used for single keys, +/** + * This is used for both utf8 and ascii, its meant to be used for single keys, * notice the buffer is either copied or not, so its not suitable for pasting in * - campbell */ static bool ui_textedit_type_buf( @@ -8397,13 +8403,14 @@ static void ui_handle_button_return_submenu(bContext *C, const wmEvent *event, u /* ************************* menu handling *******************************/ -/* function used to prevent loosing the open menu when using nested pulldowns, +/** + * Function used to prevent loosing the open menu when using nested pulldowns, * when moving mouse towards the pulldown menu over other buttons that could * steal the highlight from the current button, only checks: * * - while mouse moves in triangular area defined old mouse position and - * left/right side of new menu - * - only for 1 second + * left/right side of new menu. + * - only for 1 second. */ static void ui_mouse_motion_towards_init_ex(uiPopupBlockHandle *menu, const int xy[2], const bool force) diff --git a/source/blender/editors/interface/interface_layout.c b/source/blender/editors/interface/interface_layout.c index f6e0273560e..279d72819be 100644 --- a/source/blender/editors/interface/interface_layout.c +++ b/source/blender/editors/interface/interface_layout.c @@ -2729,7 +2729,8 @@ uiLayout *uiLayoutBox(uiLayout *layout) return (uiLayout *)ui_layout_box(layout, UI_BTYPE_ROUNDBOX); } -/* Check all buttons defined in this layout, and set any button flagged as UI_BUT_LIST_ITEM as active/selected. +/** + * Check all buttons defined in this layout, and set any button flagged as UI_BUT_LIST_ITEM as active/selected. * Needed to handle correctly text colors of active (selected) list item. */ void ui_layout_list_set_labels_active(uiLayout *layout) diff --git a/source/blender/editors/interface/interface_ops.c b/source/blender/editors/interface/interface_ops.c index 6549042c324..23b20591275 100644 --- a/source/blender/editors/interface/interface_ops.c +++ b/source/blender/editors/interface/interface_ops.c @@ -759,10 +759,12 @@ static void UI_OT_editsource(wmOperatorType *ot) } /* ------------------------------------------------------------------------- */ -/* EditTranslation utility funcs and operator, - * Note: this includes utility functions and button matching checks. - * this only works in conjunction with a py operator! */ +/** + * EditTranslation utility funcs and operator, + * \note: this includes utility functions and button matching checks. + * this only works in conjunction with a py operator! + */ static void edittranslation_find_po_file(const char *root, const char *uilng, char *path, const size_t maxlen) { char tstr[32]; /* Should be more than enough! */ diff --git a/source/blender/editors/interface/interface_panel.c b/source/blender/editors/interface/interface_panel.c index 4b0585c34b3..81a26258f6f 100644 --- a/source/blender/editors/interface/interface_panel.c +++ b/source/blender/editors/interface/interface_panel.c @@ -210,8 +210,9 @@ static void ui_panel_copy_offset(Panel *pa, Panel *papar) } -/* XXX Disabled paneltab handling for now. Old 2.4x feature, *DO NOT* confuse it with new tool tabs in 2.70. ;) - * See also T41704. +/** + * XXX Disabled paneltab handling for now. Old 2.4x feature, *DO NOT* confuse it with new tool tabs in 2.70. ;) + * See also T41704. */ /* #define UI_USE_PANELTAB */ @@ -737,11 +738,13 @@ typedef struct PanelSort { Panel *pa, *orig; } PanelSort; -/* note about sorting; +/** + * \note about sorting; * the sortorder has a lower value for new panels being added. * however, that only works to insert a single panel, when more new panels get * added the coordinates of existing panels and the previously stored to-be-inserted - * panels do not match for sorting */ + * panels do not match for sorting + */ static int find_leftmost_panel(const void *a1, const void *a2) { diff --git a/source/blender/editors/interface/interface_style.c b/source/blender/editors/interface/interface_style.c index 4b683f3fcc2..10575fcbc54 100644 --- a/source/blender/editors/interface/interface_style.c +++ b/source/blender/editors/interface/interface_style.c @@ -64,7 +64,7 @@ /* style + theme + layout-engine = UI */ -/* +/** * This is a complete set of layout rules, the 'state' of the Layout * Engine. Multiple styles are possible, defined via C or Python. Styles * get a name, and will typically get activated per region type, like diff --git a/source/blender/editors/interface/interface_templates.c b/source/blender/editors/interface/interface_templates.c index 1920250f7cc..b76c168a1e5 100644 --- a/source/blender/editors/interface/interface_templates.c +++ b/source/blender/editors/interface/interface_templates.c @@ -362,7 +362,8 @@ static const char *template_id_browse_tip(StructRNA *type) return N_("Browse ID data to be linked"); } -/* Return a type-based i18n context, needed e.g. by "New" button. +/** + * \return a type-based i18n context, needed e.g. by "New" button. * In most languages, this adjective takes different form based on gender of type name... */ #ifdef WITH_INTERNATIONAL @@ -687,7 +688,8 @@ void uiTemplateIDPreview( /************************ ID Chooser Template ***************************/ -/* This is for selecting the type of ID-block to use, and then from the relevant type choosing the block to use +/** + * This is for selecting the type of ID-block to use, and then from the relevant type choosing the block to use * * - propname: property identifier for property that ID-pointer gets stored to * - proptypename: property identifier for property used to determine the type of ID-pointer that can be used @@ -747,7 +749,8 @@ void uiTemplateAnyID( /* ---------- */ -/* This is creating/editing RNA-Paths +/** + * This is creating/editing RNA-Paths * * - ptr: struct which holds the path property * - propname: property identifier for property that path gets stored to @@ -2478,10 +2481,10 @@ static void handle_layer_buttons(bContext *C, void *arg1, void *arg2) /* see view3d_header.c */ } -/* TODO: - * - for now, grouping of layers is determined by dividing up the length of - * the array of layer bitflags */ - +/** + * \todo for now, grouping of layers is determined by dividing up the length of + * the array of layer bitflags + */ void uiTemplateLayers( uiLayout *layout, PointerRNA *ptr, const char *propname, PointerRNA *used_ptr, const char *used_propname, int active_layer) @@ -2622,10 +2625,11 @@ void uiTemplateGameStates( /************************* List Template **************************/ -static void uilist_draw_item_default(struct uiList *ui_list, struct bContext *UNUSED(C), struct uiLayout *layout, - struct PointerRNA *UNUSED(dataptr), struct PointerRNA *itemptr, int icon, - struct PointerRNA *UNUSED(active_dataptr), const char *UNUSED(active_propname), - int UNUSED(index), int UNUSED(flt_flag)) +static void uilist_draw_item_default( + struct uiList *ui_list, struct bContext *UNUSED(C), struct uiLayout *layout, + struct PointerRNA *UNUSED(dataptr), struct PointerRNA *itemptr, int icon, + struct PointerRNA *UNUSED(active_dataptr), const char *UNUSED(active_propname), + int UNUSED(index), int UNUSED(flt_flag)) { PropertyRNA *nameprop = RNA_struct_name_property(itemptr->type); diff --git a/source/blender/editors/interface/interface_widgets.c b/source/blender/editors/interface/interface_widgets.c index ec5a204af5e..b3ac22a5971 100644 --- a/source/blender/editors/interface/interface_widgets.c +++ b/source/blender/editors/interface/interface_widgets.c @@ -65,9 +65,9 @@ #define ICON_SIZE_FROM_BUTRECT(rect) (0.8f * BLI_rcti_size_y(rect)) /* ************** widget base functions ************** */ -/* +/** * - in: roundbox codes for corner types and radius - * - return: array of [size][2][x,y] points, the edges of the roundbox, + UV coords + * - return: array of `[size][2][x, y]` points, the edges of the roundbox, + UV coords * * - draw black box with alpha 0 on exact button boundbox * - for every AA step: @@ -107,7 +107,7 @@ typedef struct uiWidgetBase { } uiWidgetBase; -/* uiWidgetType: for time being only for visual appearance, +/** uiWidgetType: for time being only for visual appearance, * later, a handling callback can be added too */ typedef struct uiWidgetType { @@ -929,7 +929,8 @@ static void ui_text_clip_give_next_off(uiBut *but, const char *str) but->ofs += bytes; } -/* Helper. +/** + * Helper. * This func assumes things like kerning handling have already been handled! * Return the length of modified (right-clipped + ellipsis) string. */ @@ -1626,17 +1627,6 @@ static void widget_draw_text_icon(uiFontStyle *fstyle, uiWidgetColors *wcol, uiB /* *********************** widget types ************************************* */ - -/* uiWidgetStateColors - * char inner_anim[4]; - * char inner_anim_sel[4]; - * char inner_key[4]; - * char inner_key_sel[4]; - * char inner_driven[4]; - * char inner_driven_sel[4]; - * float blend; - */ - static struct uiWidgetStateColors wcol_state_colors = { {115, 190, 76, 255}, {90, 166, 51, 255}, @@ -1647,18 +1637,6 @@ static struct uiWidgetStateColors wcol_state_colors = { 0.5f, 0.0f }; -/* uiWidgetColors - * char outline[3]; - * char inner[4]; - * char inner_sel[4]; - * char item[3]; - * char text[3]; - * char text_sel[3]; - * - * short shaded; - * float shadetop, shadedown; - */ - static struct uiWidgetColors wcol_num = { {25, 25, 25, 255}, {180, 180, 180, 255}, diff --git a/source/blender/editors/interface/resources.c b/source/blender/editors/interface/resources.c index ed61518de6b..617a3e1bdc6 100644 --- a/source/blender/editors/interface/resources.c +++ b/source/blender/editors/interface/resources.c @@ -824,8 +824,9 @@ static void ui_theme_space_init_handles_color(ThemeSpace *theme_space) rgba_char_args_set(theme_space->act_spline, 0xdb, 0x25, 0x12, 255); } -/* initialize default theme - * Note: when you add new colors, created & saved themes need initialized +/** + * initialize default theme + * \note: when you add new colors, created & saved themes need initialized * use function below, init_userdef_do_versions() */ void ui_theme_init_default(void) diff --git a/source/blender/editors/interface/view2d.c b/source/blender/editors/interface/view2d.c index 5f7eca5f5b0..04ab50053a2 100644 --- a/source/blender/editors/interface/view2d.c +++ b/source/blender/editors/interface/view2d.c @@ -363,8 +363,9 @@ void UI_view2d_region_reinit(View2D *v2d, short type, int winx, int winy) } -/* Ensure View2D rects remain in a viable configuration - * - cur is not allowed to be: larger than max, smaller than min, or outside of tot +/** + * Ensure View2D rects remain in a viable configuration + * 'cur' is not allowed to be: larger than max, smaller than min, or outside of 'tot' */ // XXX pre2.5 -> this used to be called test_view2d() static void ui_view2d_curRect_validate_resize(View2D *v2d, int resize, int mask_scrollers) @@ -844,7 +845,8 @@ void UI_view2d_sync(bScreen *screen, ScrArea *area, View2D *v2dcur, int flag) } -/* Restore 'cur' rect to standard orientation (i.e. optimal maximum view of tot) +/** + * 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(View2D *v2d) @@ -1100,8 +1102,10 @@ void UI_view2d_view_ortho(View2D *v2d) glLoadIdentity(); } -/* Set view matrices to only use one axis of 'cur' only - * - xaxis = if non-zero, only use cur x-axis, otherwise use cur-yaxis (mostly this will be used for x) +/** + * 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(ARegion *ar, View2D *v2d, const bool xaxis) { diff --git a/source/blender/editors/interface/view2d_ops.c b/source/blender/editors/interface/view2d_ops.c index eafc5c1d24c..6fbe8509188 100644 --- a/source/blender/editors/interface/view2d_ops.c +++ b/source/blender/editors/interface/view2d_ops.c @@ -63,12 +63,13 @@ static int view2d_poll(bContext *C) /* ********************************************************* */ /* VIEW PANNING OPERATOR */ -/* This group of operators come in several forms: - * 1) Modal 'dragging' with MMB - where movement of mouse dictates amount to pan view by - * 2) Scrollwheel 'steps' - rolling mousewheel by one step moves view by predefined amount +/** + * This group of operators come in several forms: + * -# Modal 'dragging' with MMB - where movement of mouse dictates amount to pan view by + * -# Scrollwheel 'steps' - rolling mousewheel by one step moves view by predefined amount * - * In order to make sure this works, each operator must define the following RNA-Operator Props: - * deltax, deltay - define how much to move view by (relative to zoom-correction factor) + * In order to make sure this works, each operator must define the following RNA-Operator Props: + * - `deltax, deltay` - define how much to move view by (relative to zoom-correction factor) */ /* ------------------ Shared 'core' stuff ---------------------- */ @@ -525,15 +526,18 @@ static void VIEW2D_OT_scroll_up(wmOperatorType *ot) /* ********************************************************* */ /* SINGLE-STEP VIEW ZOOMING OPERATOR */ -/* This group of operators come in several forms: - * 1) Scrollwheel 'steps' - rolling mousewheel by one step zooms view by predefined amount - * 2) Scrollwheel 'steps' + alt + ctrl/shift - zooms view on one axis only (ctrl=x, shift=y) // XXX this could be implemented... - * 3) Pad +/- Keys - pressing each key moves the zooms the view by a predefined amount +/** + * This group of operators come in several forms: + * -# Scrollwheel 'steps' - rolling mousewheel by one step zooms view by predefined amount. + * -# Scrollwheel 'steps' + alt + ctrl/shift - zooms view on one axis only (ctrl=x, shift=y). + * XXX this could be implemented... + * -# Pad +/- Keys - pressing each key moves the zooms the view by a predefined amount. * * In order to make sure this works, each operator must define the following RNA-Operator Props: - * zoomfacx, zoomfacy - These two zoom factors allow for non-uniform scaling. - * It is safe to scale by 0, as these factors are used to determine - * amount to enlarge 'cur' by + * + * - zoomfacx, zoomfacy - These two zoom factors allow for non-uniform scaling. + * It is safe to scale by 0, as these factors are used to determine. + * amount to enlarge 'cur' by. */ /* ------------------ 'Shared' stuff ------------------------ */ @@ -872,10 +876,11 @@ static void VIEW2D_OT_zoom_out(wmOperatorType *ot) /* ********************************************************* */ /* DRAG-ZOOM OPERATOR */ -/* MMB Drag - allows non-uniform scaling by dragging mouse +/** + * MMB Drag - allows non-uniform scaling by dragging mouse * - * In order to make sure this works, each operator must define the following RNA-Operator Props: - * deltax, deltay - amounts to add to each side of the 'cur' rect + * In order to make sure this works, each operator must define the following RNA-Operator Props: + * - `deltax, deltay` - amounts to add to each side of the 'cur' rect */ /* apply transform to view (i.e. adjust 'cur' rect) */ @@ -1192,10 +1197,12 @@ static void VIEW2D_OT_zoom(wmOperatorType *ot) /* ********************************************************* */ /* BORDER-ZOOM */ -/* The user defines a rect using standard borderselect tools, and we use this rect to +/** + * The user defines a rect using standard borderselect tools, and we use this rect to * define the new zoom-level of the view in the following ways: - * 1) LEFTMOUSE - zoom in to view - * 2) RIGHTMOUSE - zoom out of view + * + * -# LEFTMOUSE - zoom in to view + * -# RIGHTMOUSE - zoom out of view * * Currently, these key mappings are hardcoded, but it shouldn't be too important to * have custom keymappings for this... @@ -1534,13 +1541,14 @@ static void VIEW2D_OT_smoothview(wmOperatorType *ot) /* ********************************************************* */ /* SCROLLERS */ -/* Scrollers should behave in the following ways, when clicked on with LMB (and dragged): - * 1) 'Handles' on end of 'bubble' - when the axis that the scroller represents is zoomable, - * enlarge 'cur' rect on the relevant side - * 2) 'Bubble'/'bar' - just drag, and bar should move with mouse (view pans opposite) +/** + * Scrollers should behave in the following ways, when clicked on with LMB (and dragged): + * -# 'Handles' on end of 'bubble' - when the axis that the scroller represents is zoomable, + * enlarge 'cur' rect on the relevant side. + * -# 'Bubble'/'bar' - just drag, and bar should move with mouse (view pans opposite). * - * In order to make sure this works, each operator must define the following RNA-Operator Props: - * deltax, deltay - define how much to move view by (relative to zoom-correction factor) + * In order to make sure this works, each operator must define the following RNA-Operator Props: + * - `deltax, deltay` - define how much to move view by (relative to zoom-correction factor) */ /* customdata for scroller-invoke data */ @@ -1562,10 +1570,12 @@ typedef struct v2dScrollerMove { } v2dScrollerMove; -/* View2DScrollers is typedef'd in UI_view2d.h +/** + * #View2DScrollers is typedef'd in UI_view2d.h * This is a CUT DOWN VERSION of the 'real' version, which is defined in view2d.c, as we only need focus bubble info - * WARNING: the start of this struct must not change, so that it stays in sync with the 'real' version - * For now, we don't need to have a separate (internal) header for structs like this... + * + * \warning: The start of this struct must not change, so that it stays in sync with the 'real' version + * For now, we don't need to have a separate (internal) header for structs like this... */ struct View2DScrollers { /* focus bubbles */ @@ -1584,10 +1594,12 @@ enum { /* ------------------------ */ -/* check if mouse is within scroller handle - * - mouse = relevant mouse coordinate in region space - * - sc_min, sc_max = extents of scroller 'groove' (potential available space for scroller) - * - sh_min, sh_max = positions of scrollbar handles +/** + * Check if mouse is within scroller handle. + * + * \param mouse: relevant mouse coordinate in region space. + * \param sc_min, sc_max: extents of scroller 'groove' (potential available space for scroller). + * \param sh_min, sh_max: positions of scrollbar handles. */ static short mouse_in_scroller_handle(int mouse, int sc_min, int sc_max, int sh_min, int sh_max) { @@ -1791,7 +1803,10 @@ static void scroller_activate_apply(bContext *C, wmOperator *op) UI_view2d_sync(CTX_wm_screen(C), CTX_wm_area(C), v2d, V2D_LOCK_COPY); } -/* handle user input for scrollers - calculations of mouse-movement need to be done here, not in the apply callback! */ +/** + * Handle user input for scrollers - calculations of mouse-movement need to be done here, + * not in the apply callback! + */ static int scroller_activate_modal(bContext *C, wmOperator *op, const wmEvent *event) { v2dScrollerMove *vsm = op->customdata; |