griefith/test
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

UI: comments (doxygen tweaks)

Browse Source
This commit is contained in:
Campbell Barton
2015-05-31 14:20:03 +10:00
parent 28ef76d0f0
commit 67bebc42f4
12 changed files with 142 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
source/blender/editors/interface/interface.c
View File

@@ -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)

14
source/blender/editors/interface/interface_eyedropper.c
View File

@@ -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 {

29
source/blender/editors/interface/interface_handlers.c
View File

@@ -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)

3
source/blender/editors/interface/interface_layout.c
View File

@@ -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)

8
source/blender/editors/interface/interface_ops.c
View File

@@ -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! */

11
source/blender/editors/interface/interface_panel.c
View File

@@ -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)
{

2
source/blender/editors/interface/interface_style.c
View File

@@ -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

26
source/blender/editors/interface/interface_templates.c
View File

@@ -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);

32
source/blender/editors/interface/interface_widgets.c
View File

@@ -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},

5
source/blender/editors/interface/resources.c
View File

@@ -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)

14
source/blender/editors/interface/view2d.c
View File

@@ -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)
{

79
source/blender/editors/interface/view2d_ops.c
View File

@@ -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;