[Bf-taskforce25] RNA groups proposal, first alpha + patch

[vekoon]

Uff, stupid google code has problems updating the file so I uploaded 
another one: 
http://vekoon.googlecode.com/files/rna_groups_complete_0.1a.patch


vekoon wrote, on 15/02/2009 0.04:
> Sorry, there was a mistake in the readfile code that crashed the 
> application. I updated the patch (same link).
>
> vekoon wrote, on 14/02/2009 22.39:
>> Hey guys,
>> The API refactor is more or less finished. This is a first *working* 
>> version of the entire implementation of RNA groups and everything 
>> that was depending on them and followed. This includes almost 
>> everything I suggested in my initial proposal with the exception of 
>> group filters which are only partially implemented and so disabled in 
>> this first release. I really wanted to include them already in this 
>> first patch but couldn't find the time but I decided to release this 
>> first alpha anyway so that there's at least some time span for people 
>> to try out before next sunday meeting (tomorrow) which I'm not sure 
>> I'll be able to attend but it's still relevant so there can be some 
>> discussion about the whole thing.
>>
>> Now, keep in mind this is a _real_ alpha, meaning in the moment I 
>> finished it I created the patch so it could be instable in some 
>> circumstances and crash (for instance I think it could for objects 
>> with material nodes? not quite sure though). Also for the same reason 
>> there could be various glitches and misbehaviors and I already 
>> noticed there are maybe some leaks that I'll hack down later on.
>> The API modules themselves are pretty clean/polished (except some 
>> places where I recycled code from the old implementation that are not 
>> as clean) and although of course they're still in their alpha stage 
>> so they're surely not perfect I tried to make them workable and sane 
>> in term of readability. A part of the code that'll surely need to be 
>> checked is the readfile/writefile one which I'm not sure I did 
>> correctly and maybe I forgot something. Also some places because they 
>> were just demo code in the end I really didn't pay much attention so 
>> the code is not that nice especially in space_buttons where I left 
>> some unused code like buttons_selection, that was the selection 
>> region where it shows the selected objects: I didn't put that in as 
>> it was really irrelevant in terms of my proposal, you can put it in 
>> back if you want. Oh and I also noticed the area should be refreshed 
>> when the window is created but these are all very small tweaks I can 
>> think of later.
>>
>> What we have now:
>> An API divided into 3 levels each of one depends on the levels it's 
>> preceded by. The first level is the group cache, accessible through 
>> editors/include/PG_cache.h and implemented in 
>> editors/interface/pg_cache. This is just a big object where all the 
>> groups are cached in relation to their properties so that groups -> 
>> subgroups -> properties type of access is highly optimized and lowers 
>> down the overhead of having groups as attributes for properties 
>> (which makes RNA api a lot easier to work with). This first level 
>> only depends on RNA which means the cache can be at the application 
>> level (which is the same as RNA's).
>> The second level is called group state. This maintains "state" 
>> information for every group you want it to, like collapsed state etc. 
>> and it's generally at the space level or deeper in the chain (and can 
>> be persisted on file so that this state information is kept). This is 
>> again dependent only on RNA but would probably be advisable to 
>> consider it dependent on group cache for future purposes.
>> The third and last level is group UI. This level is obviously 
>> targeted at generating automatic UI for groups. Various options 
>> include the idea of having also automatic layout where groups are 
>> displaced in an automatic way (this is optional though). As of now 
>> they get broken up in rows or columns at the height or width of the 
>> window (see code below). This level depends on both group cache and 
>> group state.
>> An example of how the API is used (taken from the space_buttons code):
>>
>> ------------------ CODE ----------------------
>>
>>    gui= PG_ui_create(sbuts->gc, sbuts->gs);
>>    block= uiBeginBlock(C, ar, "buttons-block", UI_EMBOSS, UI_HELV);
>>
>>    PG_ui_init(gui, C, ar);
>>    PG_ui_area_set(gui, 0, 0, winw, winh);
>>
>>     if (winw >= winh+PG_ui_max_size_get(gui))
>>        PG_ui_flow_set(gui, PG_UI_FLOW_HOR);
>>    else
>>        PG_ui_flow_set(gui, PG_UI_FLOW_VER);
>>
>>    PG_CACHE_BEGIN_ROOT(sbuts->gc, ritem)
>>    {
>>        group= PG_cache_group(sbuts->gc, ritem);
>>        if (RNA_grouprna_type(group)==GROUP_ROOT) {
>>            state= PG_state_item(sbuts->gs, group, 0);
>>            if (state && state->flag & PG_STATE_USE)
>>                if (buttons_data_for_group(C, group, &ptr))
>>                    PG_ui_draw_children(gui, ritem, &ptr, block);
>>        }
>>    }
>>    PG_CACHE_END
>>
>>    uiEndBlock(C, block);
>>    uiDrawBlock(C, block);
>>
>>    PG_ui_total_area_get(gui, NULL, NULL, &w, &h);
>>
>>    /* update size of tot-rect (extents of data/viewable area) */
>>    if (PG_ui_flow_get(gui)==PG_UI_FLOW_HOR)
>>        UI_view2d_totRect_set(v2d, w?w:winw, winh);
>>    else
>>        UI_view2d_totRect_set(v2d, winw, h?h:winh);
>>
>>    PG_ui_free(gui);
>>
>> ------------------ CODE ----------------------
>>
>>
>> Now to complete this e-mail I'd like to share my "vision" on how a 
>> possible final API could work. Note this is pseudo-code to make it 
>> easier to understand. All of this is actually already possible with 
>> my API although of course there are no py bindings for it.
>>
>> group1 = rna.def_group('ObjectUserinfo', rna.Group_Object, 
>> GROUP_FLAGS, 'User Info')
>> group2 = rna.def_group('ObjectUserinfoData', group1, GROUP_FLAGS, 
>> 'Custom Data')
>>
>> rna.def_prop('some_flag', 'bool', group=group1, ..., 'Some Flag');
>> rna.def_prop('some_name1', 'int', group=group2, ..., 'Some Name 1');
>> rna.def_prop('some_name2', 'int', group=group2, ..., 'Some Name 2');
>> rna.def_prop('some_name3', 'int', group=group2, ..., 'Some Name 3');
>>
>> item = pg.cache_item(group2);
>> item.draw = draw_userinfo_data
>>
>> def draw_userinfo_data( gui, item, stage, block, x, y, w, h):
>>    ...draw...
>>    #return this to skip default drawing for the group
>>    return pg.UI_STAGE_SKIP
>>
>>
>> And this is about it. I was thinking about making smaller patches but 
>> was too much time consuming so instead I made a single big patch. You 
>> can find it here: 
>> http://vekoon.googlecode.com/files/rna_groups_complete_0.1.patch
>> I tried it with scons/minngw and cmake/msvc8 and it worked fine, then 
>> I tried scons/msvc9 and it crashed but as of now I don't have time to 
>> check why this happens so I suggest you use one of the other methods 
>> (scons/mingw I'm pretty sure should work).
>> Try the code out and also have fun exporting some more groups like 
>> for materials etc. in rna_*.c files and see how it works out for you. 
>> In the moment you export some group they should automatically show up 
>> in the buttons window/properties editor (unless you set the group 
>> flag GROUP_INTERNAL) and under the correct context (not all contexts 
>> are handled yet though, like radiosity or sound). As I said there are 
>> probably still various glitches or weird things you'll see but this 
>> is mostly to get a feel on how it works and if it's actually usable 
>> and blend nicely in the workflow. Then of course, after winter camp, 
>> when all the new UI paradigms will be defined I'll rewrite the UI 
>> part of this code accordingly and later we'll think about ways of 
>> beautifying the display and drawing of groups.
>> I think it's all, impressions and comments are welcome.
>>
>>
>>
>