Page MenuHome

UI API Code Refactor
Closed, ResolvedPublicDESIGN

Description

First of all - this design task has no user visible changes.

Motivation

Currently there are some rough edges to the UI API (interface_*.c/h)

  • uiBut struct stores members for all buttons, making some logic highly confusing (below), so I propose to use a polymorphic struct, as we do already with ID and Modifier types. (so we would have uiBut_ColorBand, uiBut_Text, uiBut_Number... etc, as well as uiBut which would only store values common to all buttons).

    /* both these values use depends on the button type
    • (polymorphic struct or union would be nicer for this stuff) */

      /* (type == HSVCUBE), Use UI_GRAD_* values.
    • (type == NUM), Use to store RNA 'step' value, for dragging and click-step.
    • (type == LABEL), Use (a1 == 1.0f) to use a2 as a blending factor (wow, this is imaginative!).
    • (type == SCROLL) Use as scroll size.
    • (type == SEARCH_MENU) Use as number or rows.
    • (type == COLOR) Use as indication of color palette */ float a1;

      /* (type == HSVCIRCLE ), Use to store the luminosity.
    • (type == NUM), Use to store RNA 'precision' value, for dragging and click-step.
    • (type == LABEL), If (a1 == 1.0f) use a2 as a blending factor.
    • (type == SEARCH_MENU) Use as number or columns.
    • (type == COLOR) Use as indication of active palette color */ float a2;
  • API has become inconsistent, eg: ui_is_but_float, ui_but_is_editable, ui_button_is_active.
  • Button types have inconsistent naming (and a bit ambiguous)
BUT, BUTM, ROW, TOG, BUT_NORMAL, OPTION, OPTIONN.

Scope

To ensure this is completed in a reasonable time and not breaking code, this is mainly a cleanup/refactor, larger changes can be done after.

Out of Scope (for now)

  • Re-organizing files
  • Moving functions between files.
  • Rewriting functionality.

Timeframe

This branch will be reviewed and merged after 2.72 release to avoid conflicts from having many small changes.

Changes

This is to keep track of the changes which will eventually be applied to a branch.

Rename API Functions & Enum's

See: ui_api_refactor.py

This script contains a replacement table for proposed API changes.

Struct's

TODO

Event Timeline

Sounds good to me! Even not being too familiar with the API the above changes are much more readable and the consistency goes a longs ways towards making it easier to learn.

Since you said it could be done after 2.72 I have added it to the new UI Roadmap: http://wiki.blender.org/index.php/Dev:Doc/Projects/UI#Projects

Sorry that I didn't comment earlier. Was quite busy and tried to spend the time left with coding, rather than commenting ;).
The proposed changes seem good to me mostly, but I have a few more ideas to share:

Rename and reorganize button flags (but->flag)

  • Rename states UI_ACTIVE and UI_SELECT to be more descriptive (see below)
  • Add a new state UI_BUT_ACTIVE which can be used for radio buttons, checkboxes, tabs, etc.
  • UI_BUT_DISABLED and UI_BUT_INACTIVE seem to be the same (or at least can be made the same), so we could delete UI_BUT_INACTIVE
  • Same with UI_HIDDEN and UI_SCROLLED. They are more or less the same. UI_HIDDEN would be enough
  • Split flags into but->flag and but->state. Both should be in UI_interface.h
  • Rename flags to "UI_BUT_xxx" and states to "UI_BUT_STATE_xxx"

So this is how but->state could look like:

/* but->state */
enum {
    /* general states */
    UI_BUT_STATE_HOVER     /* was “UI_ACTIVE” */
    UI_BUT_STATE_PUSHED    /* was “UI_SELECT” */
    UI_BUT_STATE_ACTIVE

    /* more specific states */
    UI_BUT_STATE_TEXTINPUT
    UI_BUT_STATE_DISABLED
    UI_BUT_STATE_HIDDEN
    UI_BUT_STATE_ANIMATED
    UI_BUT_STATE_ANIMATED_KEY
    UI_BUT_STATE_DRIVEN
    UI_BUT_STATE_REDALERT
    UI_BUT_STATE_DRAG_MULTI
    UI_BUT_STATE_SCA_LINK_GREY
};

The rest can stay in but->flag.

Correct “wrongly” placed functions

Move functions to interface_utils.c
Afaik the purpose of “_utils.c” files is to collect functions that are useful in various places, providing something like a “function-toolset API”. Looking at the code, we have a lot of functions matching this scheme spread over all the editors/interface files. interface.c almost looks like a replacement for interface_utils.c, but interface_handlers.c has a lot of them, too.
Candidates for this are:

  • ui_fontscale
  • ui_get_but_val, ui_set_but_val, ui_set_but_hsv, …
  • ui_get_but_string
  • ui_convert_to_unit_alt_name
  • ui_is_but_float, ui_is_but_bool, …
  • ui_but_find_activated, ui_but_find_old, …
  • ...

Other functions

  • ui_but_menu (the right click menu) - from interface_handlers.c to interface_regions.c or interface_blocks.c (see below)
  • ui_handler_panel - from interface_panel.c to interface_handlers.c
  • uiDefAutoButR and uiDefAutoButsRNA - from interface_utils.c to interface.c
  • ...

Rename button types

  • OPTION and OPTIONN to CHECKBOX and CHECKBOXN (we should change this in the GUI, too – opinion from @Jonathan Williamson (carter2422) and @venomgfx?)
  • Swap MENU and PULLDOWN - they've already been interchanged for years

Add moarz files

Add more files to /editors/interface making already existing ones cleaner and more compact and providing a better organization
E.g. interface_blocks.c or interface_buttons.c

  • +1 for UI_BUT_STATE_*** changes.
  • Id like to postpone moving functions for now (or do as second step, since it may involve header reorganization).
  • 1+ for OPTION -> CHECKBOX
  • not sure about swapping MENU/PULLDOWN. but this could indeed use some clarification.
  • further organization I rather postpone a bit.
Campbell Barton (campbellbarton) changed the task status from Unknown Status to Resolved.EditedNov 11 2014, 5:30 PM