[Bf-blender-cvs] [ea17a92cd70] master: Cleanup: interface_intern.h doc-strings
Campbell Barton
noreply at git.blender.org
Fri Apr 30 08:18:15 CEST 2021
Commit: ea17a92cd7040c0d63a4ed3a8a60cd8f0a3cb77e
Author: Campbell Barton
Date: Fri Apr 30 16:15:22 2021 +1000
Branches: master
https://developer.blender.org/rBea17a92cd7040c0d63a4ed3a8a60cd8f0a3cb77e
Cleanup: interface_intern.h doc-strings
Also clarify some vague comments & add doxygen section for menu-memory.
===================================================================
M source/blender/editors/interface/interface_intern.h
M source/blender/editors/interface/interface_region_menu_popup.c
===================================================================
diff --git a/source/blender/editors/interface/interface_intern.h b/source/blender/editors/interface/interface_intern.h
index 0e465be5bf6..333dc1beb22 100644
--- a/source/blender/editors/interface/interface_intern.h
+++ b/source/blender/editors/interface/interface_intern.h
@@ -62,7 +62,7 @@ struct wmTimer;
#define UI_MENU_PADDING (int)(0.2f * UI_UNIT_Y)
#define UI_MENU_WIDTH_MIN (UI_UNIT_Y * 9)
-/* some extra padding added to menus containing submenu icons */
+/** Some extra padding added to menus containing sub-menu icons. */
#define UI_MENU_SUBMENU_PADDING (6 * UI_DPI_FAC)
/* menu scrolling */
@@ -74,7 +74,7 @@ struct wmTimer;
#define UI_PANEL_MINX 100
#define UI_PANEL_MINY 70
-/* popover width (multiplied by 'U.widget_unit') */
+/** Popover width (multiplied by #U.widget_unit) */
#define UI_POPOVER_WIDTH_UNITS 10
/** #uiBut.flag */
@@ -93,12 +93,12 @@ enum {
/* WARNING: rest of #uiBut.flag in UI_interface.h */
};
-/* uiBut->dragflag */
+/** #uiBut.dragflag */
enum {
UI_BUT_DRAGPOIN_FREE = (1 << 0),
};
-/* but->pie_dir */
+/** #uiBut.pie_dir */
typedef enum RadialDirection {
UI_RADIAL_NONE = -1,
UI_RADIAL_N = 0,
@@ -129,13 +129,13 @@ extern const short ui_radial_dir_to_angle[8];
#define UI_BITBUT_ROW(min, max) \
(((max) >= 31 ? 0xFFFFFFFF : (1 << ((max) + 1)) - 1) - ((min) ? ((1 << (min)) - 1) : 0))
-/* split numbuts by ':' and align l/r */
+/** Split number-buttons by ':' and align left/right. */
#define USE_NUMBUTS_LR_ALIGN
-/* Use new 'align' computation code. */
+/** Use new 'align' computation code. */
#define USE_UIBUT_SPATIAL_ALIGN
-/* PieMenuData->flags */
+/** #PieMenuData.flags */
enum {
/** pie menu item collision is detected at 90 degrees */
UI_PIE_DEGREES_RANGE_LARGE = (1 << 0),
@@ -155,13 +155,13 @@ enum {
#define PIE_CLICK_THRESHOLD_SQ 50.0f
-/* max amount of items a radial menu (pie menu) can contain */
+/** The maximum number of items a radial menu (pie menu) can contain. */
#define PIE_MAX_ITEMS 8
struct uiBut {
struct uiBut *next, *prev;
- /* Pointer back to the layout item holding this button. */
+ /** Pointer back to the layout item holding this button. */
uiLayout *layout;
int flag, drawflag;
eButType type;
@@ -238,10 +238,10 @@ struct uiBut {
short modifier_key;
short iconadd;
- /* UI_BTYPE_BLOCK data */
+ /** #UI_BTYPE_BLOCK data */
uiBlockCreateFunc block_create_func;
- /* UI_BTYPE_PULLDOWN/UI_BTYPE_MENU data */
+ /** #UI_BTYPE_PULLDOWN / #UI_BTYPE_MENU data */
uiMenuCreateFunc menu_create_func;
uiMenuStepFunc menu_step_func;
@@ -255,9 +255,11 @@ struct uiBut {
struct wmOperatorType *optype;
struct PointerRNA *opptr;
short opcontext;
- uchar menu_key; /* 'a'-'z', always lower case */
- ListBase extra_op_icons; /* uiButExtraOpIcon */
+ /** When non-zero, this is the key used to activate a menu items (`a-z` always lower case). */
+ uchar menu_key;
+
+ ListBase extra_op_icons; /** #uiButExtraOpIcon */
/* Draggable data, type is WM_DRAG_... */
char dragtype;
@@ -266,10 +268,10 @@ struct uiBut {
struct ImBuf *imb;
float imb_scale;
- /* active button data */
+ /** Active button data (set when the user is hovering or interacting with a button). */
struct uiHandleButtonData *active;
- /* Custom button data. */
+ /** Custom button data (borrowed, not owned). */
void *custom_data;
char *editstr;
@@ -432,7 +434,7 @@ struct PieMenuData {
float alphafac;
};
-/* uiBlock.content_hints */
+/** #uiBlock.content_hints */
enum eBlockContentHints {
/** In a menu block, if there is a single sub-menu button, we add some
* padding to the right to put nicely aligned triangle icons there. */
@@ -466,7 +468,8 @@ struct uiBlock {
struct Panel *panel;
uiBlock *oldblock;
- ListBase butstore; /* UI_butstore_* runtime function */
+ /** Used for `UI_butstore_*` runtime function. */
+ ListBase butstore;
ListBase button_groups; /* #uiButtonGroup. */
@@ -482,7 +485,8 @@ struct uiBlock {
rctf rect;
float aspect;
- uint puphash; /* popup menu hash for memory */
+ /** Unique hash used to implement popup menu memory. */
+ uint puphash;
uiButHandleFunc func;
void *func_arg1;
@@ -497,10 +501,10 @@ struct uiBlock {
uiBlockHandleFunc handle_func;
void *handle_func_arg;
- /* custom extra handling */
+ /** Custom extra event handling. */
int (*block_event_func)(const struct bContext *C, struct uiBlock *, const struct wmEvent *);
- /* extra draw function for custom blocks */
+ /** Custom extra draw function for custom blocks. */
void (*drawextra)(const struct bContext *C, void *idv, void *arg1, void *arg2, rcti *rect);
void *drawextra_arg1;
void *drawextra_arg2;
@@ -510,7 +514,7 @@ struct uiBlock {
/** Hints about the buttons of this block. Used to avoid iterating over
* buttons to find out if some criteria is met by any. Instead, check this
* criteria when adding the button and set a flag here if it's met. */
- short content_hints; /* eBlockContentHints */
+ short content_hints; /* #eBlockContentHints */
char direction;
/** UI_BLOCK_THEME_STYLE_* */
@@ -524,11 +528,11 @@ struct uiBlock {
const char *lockstr;
bool lock;
- /** to keep blocks while drawing and free them afterwards */
+ /** To keep blocks while drawing and free them afterwards. */
bool active;
- /** to avoid tooltip after click */
+ /** To avoid tool-tip after click. */
bool tooltipdisabled;
- /** UI_block_end done? */
+ /** True when #UI_block_end has been called. */
bool endblock;
/** for doing delayed */
@@ -538,12 +542,12 @@ struct uiBlock {
/** for doing delayed */
int bounds, minbounds;
- /** pull-downs, to detect outside, can differ per case how it is created. */
+ /** Pull-downs, to detect outside, can differ per case how it is created. */
rctf safety;
- /** uiSafetyRct list */
+ /** #uiSafetyRct list */
ListBase saferct;
- uiPopupBlockHandle *handle; /* handle */
+ uiPopupBlockHandle *handle;
/** use so presets can find the operator,
* across menus and from nested popups which fail for operator context. */
@@ -558,10 +562,12 @@ struct uiBlock {
/** \note only accessed by color picker templates. */
ColorPickerData color_pickers;
- bool is_color_gamma_picker; /* Block for color picker with gamma baked in. */
+ /** Block for color picker with gamma baked in. */
+ bool is_color_gamma_picker;
- /** display device name used to display this block,
- * used by color widgets to transform colors from/to scene linear
+ /**
+ * Display device name used to display this block,
+ * used by color widgets to transform colors from/to scene linear.
*/
char display_device[64];
@@ -674,9 +680,9 @@ void ui_block_cm_to_display_space_v3(uiBlock *block, float pixel[3]);
/* interface_regions.c */
struct uiKeyNavLock {
- /* Set when we're using key-input. */
+ /** Set when we're using keyboard-input. */
bool is_keynav;
- /* only used to check if we've moved the cursor */
+ /** Only used to check if we've moved the cursor. */
int event_xy[2];
};
@@ -692,7 +698,7 @@ struct uiPopupBlockCreate {
int event_xy[2];
- /* when popup is initialized from a button */
+ /** Set when popup is initialized from a button. */
struct ARegion *butregion;
uiBut *but;
};
@@ -701,7 +707,7 @@ struct uiPopupBlockHandle {
/* internal */
struct ARegion *region;
- /* use only for 'UI_BLOCK_MOVEMOUSE_QUIT' popups */
+ /** Use only for #UI_BLOCK_MOVEMOUSE_QUIT popups. */
float towards_xy[2];
double towardstime;
bool dotowards;
@@ -711,9 +717,9 @@ struct uiPopupBlockHandle {
void (*cancel_func)(struct bContext *C, void *arg);
void *popup_arg;
- /* store data for refreshing popups */
+ /** Store data for refreshing popups. */
struct uiPopupBlockCreate popup_create_vars;
- /* true if we can re-create the popup using 'popup_create_vars' */
+ /** True if we can re-create the popup using #uiPopupBlockHandle.popup_create_vars. */
bool can_refresh;
bool refresh;
@@ -733,7 +739,7 @@ struct uiPopupBlockHandle {
int retvalue;
float retvec[4];
- /* menu direction */
+ /** Menu direction. */
int direction;
/* Previous values so we don't resize or reposition on refresh. */
diff --git a/source/blender/editors/interface/interface_region_menu_popup.c b/source/blender/editors/interface/interface_region_menu_popup.c
index f234f0fbbf5..6906309fd30 100644
--- a/source/blender/editors/interface/interface_region_menu_popup.c
+++ b/source/blender/editors/interface/interface_region_menu_popup.c
@@ -86,6 +86,17 @@ int ui_but_menu_step(uiBut *but, int direction)
return 0;
}
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Popup Menu Memory
+ *
+ * Support menu-memory, a feature that positions the cursor
+ * over the previously used menu item.
+ *
+ * \note This is stored for each unique menu title.
+ * \{ */
+
static uint ui_popup_string_hash(const char *str, const bool use_sep)
{
/* sometimes button contains hotkey, sometimes not, strip for proper compare */
More information about the Bf-blender-cvs
mailing list