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

Cleanup: use doxygen formatting in UI_interface.h, DNA_screen_types.h

Browse Source 
Also use doxygen type references & correct some typos.
This commit is contained in:
Campbell Barton
2023-07-26 15:23:24 +10:00
parent fcacebbfb1
commit cf49cbde45
2 changed files with 111 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
source/blender/editors/include/UI_interface.h
View File

@@ -96,8 +96,10 @@ typedef struct uiViewItemHandle uiViewItemHandle;
*/
#define UI_VALUE_INDETERMINATE_CHAR BLI_STR_UTF8_EM_DASH
/* Separator for text in search menus (right pointing arrow).
* keep in sync with `string_search.cc`. */
/**
* Separator for text in search menus (right pointing arrow).
* keep in sync with `string_search.cc`.
*/
#define UI_MENU_ARROW_SEP BLI_STR_UTF8_BLACK_RIGHT_POINTING_SMALL_TRIANGLE
/* names */
@@ -113,7 +115,7 @@ typedef struct uiViewItemHandle uiViewItemHandle;
*/
#define UI_REGION_OVERLAP_MARGIN (U.widget_unit / 3)
/* use for clamping popups within the screen */
/** Use for clamping popups within the screen. */
#define UI_SCREEN_MARGIN 10
/** #uiBlock.emboss and #uiBut.emboss */
@@ -131,7 +133,7 @@ typedef enum eUIEmbossType {
UI_EMBOSS_UNDEFINED = 255, /* For layout engine, use emboss from block. */
} eUIEmbossType;
/* uiBlock->direction */
/** #uiBlock::direction */
enum {
UI_DIR_UP = 1 << 0,
UI_DIR_DOWN = 1 << 1,
@@ -161,10 +163,10 @@ enum {
UI_BLOCK_OUT_1 = 1 << 10,
UI_BLOCK_SEARCH_MENU = 1 << 11,
UI_BLOCK_POPUP_MEMORY = 1 << 12,
/* Stop handling mouse events. */
/** Stop handling mouse events. */
UI_BLOCK_CLIP_EVENTS = 1 << 13,
/* block->flag bits 14-17 are identical to but->drawflag bits */
/* #uiBlock::flags bits 14-17 are identical to #uiBut::drawflag bits. */
UI_BLOCK_POPUP_HOLD = 1 << 18,
UI_BLOCK_LIST_ITEM = 1 << 19,
@@ -201,6 +203,7 @@ enum {
/** #uiBut.flag general state flags. */
enum {
/* WARNING: the first 8 flags are internal (see #UI_SELECT definition). */
UI_BUT_ICON_SUBMENU = 1 << 8,
UI_BUT_ICON_PREVIEW = 1 << 9,
@@ -262,10 +265,10 @@ enum {
UI_BUT_DRAGPOIN_FREE = (1 << 1),
};
/* Default font size for normal text. */
/** Default font size for normal text. */
#define UI_DEFAULT_TEXT_POINTS 11.0f
/* Larger size used for title text. */
/** Larger size used for title text. */
#define UI_DEFAULT_TITLE_POINTS 11.0f
#define UI_PANEL_WIDTH 340
@@ -274,11 +277,11 @@ enum {
#define UI_NAVIGATION_REGION_WIDTH UI_COMPACT_PANEL_WIDTH
#define UI_NARROW_NAVIGATION_REGION_WIDTH 100
/* The width of one icon column of the Toolbar. */
/** The width of one icon column of the Toolbar. */
#define UI_TOOLBAR_COLUMN (1.25f * ICON_DEFAULT_HEIGHT_TOOLBAR)
/* The space between the Toolbar and the area's edge. */
/** The space between the Toolbar and the area's edge. */
#define UI_TOOLBAR_MARGIN (0.5f * ICON_DEFAULT_HEIGHT_TOOLBAR)
/* Total width of Toolbar showing one icon column. */
/** Total width of Toolbar showing one icon column. */
#define UI_TOOLBAR_WIDTH UI_TOOLBAR_MARGIN + UI_TOOLBAR_COLUMN
#define UI_PANEL_CATEGORY_MARGIN_WIDTH (U.widget_unit * 1.0f)
@@ -288,19 +291,23 @@ enum {
#define UI_PANEL_MARGIN_X (U.widget_unit * 0.4f)
#define UI_PANEL_MARGIN_Y (U.widget_unit * 0.1f)
/* but->drawflag - these flags should only affect how the button is drawn. */
/* NOTE: currently, these flags *are not passed* to the widget's state() or draw() functions
* (except for the 'align' ones)!
/**
* #uiBut::drawflag, these flags should only affect how the button is drawn.
*
* \note currently, these flags *are not passed* to the widgets state() or draw() functions
* (except for the 'align' ones)!
*/
enum {
/** Text and icon alignment (by default, they are centered). */
UI_BUT_TEXT_LEFT = 1 << 1,
UI_BUT_ICON_LEFT = 1 << 2,
UI_BUT_TEXT_RIGHT = 1 << 3,
/** Prevent the button to show any tooltip. */
/** Prevent the button to show any tool-tip. */
UI_BUT_NO_TOOLTIP = 1 << 4,
/** Show a quick tooltip label, that is, a short tooltip that appears faster than the full one
* and only shows the label. After a short delay the full toolitp is shown if any. */
/**
* Show a quick tool-tip label, that is, a short tool-tip that appears faster than the full one
* and only shows the label. After a short delay the full tool-tip is shown if any.
*/
UI_BUT_HAS_TOOLTIP_LABEL = 1 << 5,
/** Do not add the usual horizontal padding for text drawing. */
UI_BUT_NO_TEXT_PADDING = 1 << 6,
@@ -318,7 +325,8 @@ enum {
* Warning - HACK!
* Needed for buttons which are not TOP/LEFT aligned,
* but have some top/left corner stitched to some other TOP/LEFT-aligned button,
* because of 'corrective' hack in widget_roundbox_set()... */
* because of "corrective" hack in #widget_roundbox_set().
*/
UI_BUT_ALIGN_STITCH_TOP = 1 << 18,
UI_BUT_ALIGN_STITCH_LEFT = 1 << 19,
UI_BUT_ALIGN_ALL = UI_BUT_ALIGN | UI_BUT_ALIGN_STITCH_TOP | UI_BUT_ALIGN_STITCH_LEFT,
@@ -337,10 +345,10 @@ enum {
/** Value is animated, but the current value differs from the animated one. */
UI_BUT_ANIMATED_CHANGED = 1 << 24,
/* Draw the checkbox buttons inverted. */
/** Draw the checkbox buttons inverted. */
UI_BUT_CHECKBOX_INVERT = 1 << 25,
/* Drawn in a way that indicates that the state/value is unknown. */
/** Drawn in a way that indicates that the state/value is unknown. */
UI_BUT_INDETERMINATE = 1 << 26,
};
@@ -362,10 +370,13 @@ typedef enum {
UI_BUT_POIN_BIT = 256, /* OR'd with a bit index. */
} eButPointerType;
/* requires (but->poin != NULL) */
/** \note requires `but->poin != NULL`. */
#define UI_BUT_POIN_TYPES (UI_BUT_POIN_FLOAT | UI_BUT_POIN_SHORT | UI_BUT_POIN_CHAR)
/* assigned to but->type, OR'd with the flags above when passing args */
/**
* #uiBut::type
* OR'd with #eButPointerType when passing as an argument.
*/
typedef enum {
UI_BTYPE_BUT = 1 << 9,
UI_BTYPE_ROW = 2 << 9,
@@ -429,7 +440,7 @@ typedef enum {
/** Resize handle (resize UI-list). */
UI_BTYPE_GRIP = 57 << 9,
UI_BTYPE_DECORATOR = 58 << 9,
/* An item a view (see #ui::AbstractViewItem). */
/** An item a view (see #ui::AbstractViewItem). */
UI_BTYPE_VIEW_ITEM = 59 << 9,
} eButType;
@@ -512,10 +523,10 @@ void UI_draw_widget_scroll(struct uiWidgetColors *wcol,
* \note in case this middle clipping would just remove a few chars,
* it rather clips right, which is more readable.
*
* If rpart_sep is not Null, the part of str starting to first occurrence of rpart_sep
* If `rpart_sep` is not null, the part of `str` starting to first occurrence of `rpart_sep`
* is preserved at all cost.
* Useful for strings with shortcuts
* (like 'AVeryLongFooBarLabelForMenuEntry|Ctrl O' -> 'AVeryLong...MenuEntry|Ctrl O').
* (like `A Very Long Foo Bar Label For Menu Entry|Ctrl O' -> 'AVeryLong...MenuEntry|Ctrl O`).
*/
float UI_text_clip_middle_ex(const struct uiFontStyle *fstyle,
char *str,
@@ -525,9 +536,9 @@ float UI_text_clip_middle_ex(const struct uiFontStyle *fstyle,
char rpart_sep);
/**
* Callbacks
* Callbacks.
*
* UI_block_func_handle_set/ButmFunc are for handling events through a callback.
* #UI_block_func_handle_set/ButmFunc are for handling events through a callback.
* HandleFunc gets the retval passed on, and ButmFunc gets a2. The latter is
* mostly for compatibility with older code.
*
@@ -574,7 +585,7 @@ typedef struct ARegion *(*uiButSearchTooltipFn)(struct bContext *C,
void *active);
typedef void (*uiButSearchListenFn)(const struct wmRegionListenerParams *params, void *arg);
/* Must return allocated string. */
/** Must return an allocated string. */
typedef char *(*uiButToolTipFunc)(struct bContext *C, void *argN, const char *tip);
typedef void (*uiBlockHandleFunc)(struct bContext *C, void *arg, int event);
@@ -851,7 +862,7 @@ void UI_block_lock_clear(uiBlock *block);
void UI_block_align_begin(uiBlock *block);
void UI_block_align_end(uiBlock *block);
/* block bounds/position calculation */
/** Block bounds/position calculation. */
typedef enum {
UI_BLOCK_BOUNDS_NONE = 0,
UI_BLOCK_BOUNDS = 1,
@@ -1279,7 +1290,7 @@ uiBut *uiDefIconButO_ptr(uiBlock *block,
uiBut *uiDefButImage(
uiBlock *block, void *imbuf, int x, int y, short width, short height, const uchar color[4]);
uiBut *uiDefButAlert(uiBlock *block, int icon, int x, int y, short width, short height);
/* Button containing both string label and icon */
/** Button containing both string label and icon. */
uiBut *uiDefIconTextBut(uiBlock *block,
int type,
int retval,
@@ -1382,7 +1393,7 @@ uiBut *uiDefIconTextButO_ptr(uiBlock *block,
short height,
const char *tip);
/* for passing inputs to ButO buttons */
/** For passing inputs to ButO buttons. */
struct PointerRNA *UI_but_operator_ptr_get(uiBut *but);
void UI_but_context_ptr_set(uiBlock *block,
@@ -1421,9 +1432,11 @@ typedef struct uiStringInfo {
char *strinfo;
} uiStringInfo;
/* NOTE: Expects pointers to uiStringInfo structs as parameters.
* Will fill them with translated strings, when possible.
* Strings in uiStringInfo must be MEM_freeN'ed by caller. */
/**
* \note Expects pointers to #uiStringInfo structs as parameters.
* Will fill them with translated strings, when possible.
* Strings in #uiStringInfo must be MEM_freeN'ed by caller.
*/
void UI_but_string_info_get(struct bContext *C, uiBut *but, ...) ATTR_SENTINEL(0);
void UI_but_extra_icon_string_info_get(struct bContext *C, uiButExtraOpIcon *extra_icon, ...)
ATTR_SENTINEL(0);
@@ -1605,21 +1618,21 @@ uiBut *uiDefSearchButO_ptr(uiBlock *block,
float a2,
const char *tip);
/* For uiDefAutoButsRNA */
/** For #uiDefAutoButsRNA. */
typedef enum {
/* Keep current layout for aligning label with property button. */
/** Keep current layout for aligning label with property button. */
UI_BUT_LABEL_ALIGN_NONE,
/* Align label and property button vertically. */
/** Align label and property button vertically. */
UI_BUT_LABEL_ALIGN_COLUMN,
/* Split layout into a column for the label and one for property button. */
/** Split layout into a column for the label and one for property button. */
UI_BUT_LABEL_ALIGN_SPLIT_COLUMN,
} eButLabelAlign;
/* Return info for uiDefAutoButsRNA */
/** Return info for uiDefAutoButsRNA. */
typedef enum eAutoPropButsReturn {
/* Returns when no buttons were added */
/** Returns when no buttons were added */
UI_PROP_BUTS_NONE_ADDED = 1 << 0,
/* Returned when any property failed the custom check callback (check_prop) */
/** Returned when any property failed the custom check callback (check_prop) */
UI_PROP_BUTS_ANY_FAILED_CHECK = 1 << 1,
} eAutoPropButsReturn;
@@ -2538,13 +2551,13 @@ void uiTemplateCacheFileLayers(uiLayout *layout,
const struct bContext *C,
struct PointerRNA *fileptr);
/* Default UIList class name, keep in sync with its declaration in bl_ui/__init__.py */
/** Default UIList class name, keep in sync with its declaration in `bl_ui/__init__.py`. */
#define UI_UL_DEFAULT_CLASS_NAME "UI_UL_list"
enum uiTemplateListFlags {
UI_TEMPLATE_LIST_FLAG_NONE = 0,
UI_TEMPLATE_LIST_SORT_REVERSE = (1 << 0),
UI_TEMPLATE_LIST_SORT_LOCK = (1 << 1),
/* Don't allow resizing the list, i.e. don't add the grip button. */
/** Don't allow resizing the list, i.e. don't add the grip button. */
UI_TEMPLATE_LIST_NO_GRIP = (1 << 2),
/** Do not show filtering options, not even the button to expand/collapse them. Also hides the
* grip button. */
@@ -3157,10 +3170,14 @@ int UI_fontstyle_height_max(const struct uiFontStyle *fs);
*/
void UI_draw_icon_tri(float x, float y, char dir, const float[4]);
/* XXX: read a style configure */
/**
* Read a style (without any scaling applied).
*/
const struct uiStyle *UI_style_get(void); /* use for fonts etc */
/* for drawing, scaled with DPI setting */
const struct uiStyle *UI_style_get_dpi(void); /* DPI scaled settings for drawing */
/**
* Read a style (with the current DPI applied).
*/
const struct uiStyle *UI_style_get_dpi(void);
/* linker workaround ack! */
void UI_template_fix_linking(void);
@@ -3301,10 +3318,10 @@ void UI_style_init_default(void);
void UI_interface_tag_script_reload(void);
/* Special drawing for toolbar, mainly workarounds for inflexible icon sizing. */
/** Special drawing for toolbar, mainly workarounds for inflexible icon sizing. */
#define USE_UI_TOOLBAR_HACK
/* Support click-drag motion which presses the button and closes a popover (like a menu). */
/** Support click-drag motion which presses the button and closes a popover (like a menu). */
#define USE_UI_POPOVER_ONCE
/**

79
source/blender/makesdna/DNA_screen_types.h
View File

@@ -305,10 +305,10 @@ typedef struct uiList { /* some list UI data need to be saved in file */
int filter_flag;
int filter_sort_flag;
/* Custom sub-classes properties. */
/** Custom sub-classes properties. */
IDProperty *properties;
/* Dynamic data (runtime). */
/** Dynamic data (runtime). */
uiListDyn *dyn_data;
} uiList;
@@ -331,13 +331,16 @@ typedef struct uiPreview {
} uiPreview;
typedef struct ScrGlobalAreaData {
/* Global areas have a non-dynamic size. That means, changing the window
* size doesn't affect their size at all. However, they can still be
* 'collapsed', by changing this value. Ignores DPI (ED_area_global_size_y
* and winx/winy don't) */
/**
* Global areas have a non-dynamic size. That means, changing the window size doesn't
* affect their size at all. However, they can still be 'collapsed', by changing this value.
* Ignores DPI (#ED_area_global_size_y and winx/winy don't).
*/
short cur_fixed_height;
/* For global areas, this is the min and max size they can use depending on
* if they are 'collapsed' or not. */
/**
* For global areas, this is the min and max size they can use depending on
* if they are 'collapsed' or not.
*/
short size_min, size_max;
/** GlobalAreaAlign. */
short align;
@@ -405,19 +408,21 @@ typedef struct ScrArea {
/** Callbacks for this space type. */
struct SpaceType *type;
/* Non-NULL if this area is global. */
/** Non-NULL if this area is global. */
ScrGlobalAreaData *global;
/* A list of space links (editors) that were open in this area before. When
/**
* #SpaceLink.
* A list of space links (editors) that were open in this area before. When
* changing the editor type, we try to reuse old editor data from this list.
* The first item is the active/visible one.
*/
/** #SpaceLink. */
ListBase spacedata;
/* NOTE: This region list is the one from the active/visible editor (first item in
/**
* #ARegion.
* \note This region list is the one from the active/visible editor (first item in
* spacedata list). Use SpaceLink.regionbase if it's inactive (but only then)!
*/
/** #ARegion. */
ListBase regionbase;
/** #wmEventHandler. */
ListBase handlers;
@@ -429,7 +434,7 @@ typedef struct ScrArea {
} ScrArea;
typedef struct ARegion_Runtime {
/* Panel category to use between 'layout' and 'draw'. */
/** Panel category to use between 'layout' and 'draw'. */
const char *category;
/**
@@ -442,7 +447,7 @@ typedef struct ARegion_Runtime {
/* The offset needed to not overlap with window scroll-bars. Only used by HUD regions for now. */
int offset_x, offset_y;
/* Maps uiBlock->name to uiBlock for faster lookups. */
/** Maps #uiBlock::name to uiBlock for faster lookups. */
struct GHash *block_name_map;
} ARegion_Runtime;
@@ -457,8 +462,10 @@ typedef struct ARegion {
rcti drawrct;
/** Size. */
short winx, winy;
/* This is a Y offset on the panel tabs that represents pixels, where zero represents no scroll -
* the first category always shows first at the top. */
/**
* This is a Y offset on the panel tabs that represents pixels,
* where zero represents no scroll - the first category always shows first at the top.
*/
int category_scroll;
char _pad0[4];
@@ -558,8 +565,10 @@ enum {
/** #bScreen.state */
enum {
SCREENNORMAL = 0,
SCREENMAXIMIZED = 1, /* one editor taking over the screen */
SCREENFULL = 2, /* one editor taking over the screen with no bare-minimum UI elements */
/** One editor taking over the screen. */
SCREENMAXIMIZED = 1,
/** One editor taking over the screen with no bare-minimum UI elements. */
SCREENFULL = 2,
};
/** #bScreen.redraws_flag */
@@ -592,7 +601,7 @@ enum {
PNL_INSTANCED_LIST_ORDER_CHANGED = (1 << 7),
};
/* Fallback panel category (only for old scripts which need updating) */
/** Fallback panel category (only for old scripts which need updating). */
#define PNL_CATEGORY_FALLBACK "Misc"
/** #uiList.layout_type */
@@ -605,11 +614,11 @@ enum {
/** #uiList.flag */
enum {
/* Scroll list to make active item visible. */
/** Scroll list to make active item visible. */
UILST_SCROLL_TO_ACTIVE_ITEM = 1 << 0,
};
/* Value (in number of items) we have to go below minimum shown items to enable auto size. */
/** Value (in number of items) we have to go below minimum shown items to enable auto size. */
#define UI_LIST_AUTO_SIZE_THRESHOLD 1
/* uiList filter flags (dyn_data) */
@@ -668,13 +677,13 @@ typedef enum eRegion_Type {
#define RGN_TYPE_NUM (RGN_TYPE_XR + 1)
} eRegion_Type;
/* use for function args */
/** Use for function args. */
#define RGN_TYPE_ANY -1
/* Region supports panel tabs (categories). */
/** Region supports panel tabs (categories). */
#define RGN_TYPE_HAS_CATEGORY_MASK (1 << RGN_TYPE_UI)
/* Check for any kind of header region. */
/** Check for any kind of header region. */
#define RGN_TYPE_IS_HEADER_ANY(regiontype) \
(((1 << (regiontype)) & \
((1 << RGN_TYPE_HEADER) | 1 << (RGN_TYPE_TOOL_HEADER) | (1 << RGN_TYPE_FOOTER))) != 0)
@@ -735,22 +744,26 @@ enum {
/** #ARegion.do_draw */
enum {
/* Region must be fully redrawn. */
/** Region must be fully redrawn. */
RGN_DRAW = 1,
/* Redraw only part of region, for sculpting and painting to get smoother
* stroke painting on heavy meshes. */
/**
* Redraw only part of region, for sculpting and painting to get smoother
* stroke painting on heavy meshes.
*/
RGN_DRAW_PARTIAL = 2,
/* For outliner, to do faster redraw without rebuilding outliner tree.
/**
* For outliner, to do faster redraw without rebuilding outliner tree.
* For 3D viewport, to display a new progressive render sample without
* while other buffers and overlays remain unchanged. */
* while other buffers and overlays remain unchanged.
*/
RGN_DRAW_NO_REBUILD = 4,
/* Set while region is being drawn. */
/** Set while region is being drawn. */
RGN_DRAWING = 8,
/* For popups, to refresh UI layout along with drawing. */
/** For popups, to refresh UI layout along with drawing. */
RGN_REFRESH_UI = 16,
/* Only editor overlays (currently gizmos only!) should be redrawn. */
/** Only editor overlays (currently gizmos only!) should be redrawn. */
RGN_DRAW_EDITOR_OVERLAYS = 32,
};