Request for Comment - Plugin API

[Ron]

Guys, are there any functions in the API at the moment that you think should be changed? If so speak up now before we go into the beta cycle.

[birty]

i havent used it extensively but it all looks ok to me (apart from the documentation :wink: )

[Ron]

Documentation: we now have a doc writer so things should start to change :-) (can't promise when yet)

[Mark F]

I haven't used any of the plugin API.

Having admitted that, the UI part of the API is not intuitive. I'm sure it will become much clearer when documentation is available; but, all of these nodes and types looks very complex. Is there a higher level abstraction that might work for this?

Again, I haven't used the API so I am probably way off base here.

[Ron]

You don't have to worry about any of that. There is a support file called dui.cpp, this will when I have enough time become a support library that handles all the dirty work.

All you need to do is design the DUI with the designer (which will be updated... priorities...). Then load the XML file with the help of dui.cpp and hook it into the interface when asked for. I wish there was a good solution and easy to the UI problem, however I have not yet found it. Using ActiveX objects is very flexible but has it's own problems. So I am more then happy to hear suggestions here. They probably won't make it into 4.0 since that would probably be a big change.

[Mark F]

That sounds like a great start. I look forward to it. :)

[Ron]

Mark here is a project that include the file (actually du.cpp)

http://www.promixis.com/phpBB2/viewtopic.php?p=109600#109600

[Mark F]

I realize the multi-threaded LUA (see this thread (http://www.promixis.com/phpBB2/viewtopic.php?t=10606) for more information) is new as of yesterday; but, we might need to be able to signal/broadcast conditions and lock/unlock mutexes from within a plugin. New lua_* routines would seem the most natural for this.

:D

[Ron]

Help me out here, what function are you thinking :-)

[Ron]

Mark, I was wondering do we need the WaitForMultipleObject functionality? The library has no way of using that now, I would have to gut it.

[Mark F]

What the heck was I thinking? :)

The LUA Thread package exports the mutex and condition objects. I thought a plugin might need to signal one of these conditions to release a LUA thread at some point. In order to do that without compromising the environment, the plugin would need to acquire the mutex that is attached to the condition first.

This is the sample LUA code in the reference to wait for a condition:

-- make sure we are the only currently accessing the predicate
predicate.mutex:lock()
-- while the predicate is not what we want
while unsatisfactory(predicate) do
-- wait until someone changes the predicate
predicate.cond:wait(predicate.mutex)
end
-- at this point, the predicate is valid AND we own it
use(predicate)
-- unlock the mutex, so that other threads can access the predicate
predicate.mutex:unlock()


This is the sample LUA code in the reference to signal a condition (a plugin might need to do this):

-- make sure we are the only currently accessing the predicate
predicate.mutex:lock() -- how would a plugin do this?
-- change the predicate
update(predicate)
-- release one of the threads blocked on cond
predicate.cond:signal() -- how would a plugin do this?
-- unlock the mutex, so that other threads can access the predicate
predicate.mutex:unlock() -- how would a plugin do this?


Thinking about this some more, I'm pretty sure we can get around this with a much more efficient means. Namely, have the thread block in the plugin and only get released after the data is updated.

On the WaitForMultiple... question, I wouldn't worry about it for now. Perhaps in the future but I don't know.

[curtiswren]

You mentioned in a previous post that it was not possible to use DUI for the event dialog at least in this version. Is there another way to show an event dialog? The gir_learn_event function doesn't seem to be available either. I think some plugins will need this.

Also, I would like to see a way to prefill the values of the settings DUI prior to displaying it and be able to get the values after the apply button is pressed. The registry settings will work for most things, but it would be a bit more flexible this way.

Other than those couple small things, I think it looks good. I really like the DUI stuff.

[Ron]

The gir_learn_event should work. (It used to work in G4...) I will check.

About the DUI, the prefilled values you can achieve by using the default value box. I know the designer sometimes doesn't let you sorry, it is a work in progress.

To get a callback after the user hits apply simply listen to the duOnApply event in gir_dynamic_ui.


void * WINAPI gir_dynamic_ui(lua_State * LuaState, PFTree tree, PFTreeNode node, PCommand command,int val1, int val2, void *userdata)
{
switch (val1)
{
case duOnHookConfig:
ConfigInsertDynamicUI(tree, node);
return NULL;
case duOnUnHookConfig:
return ConfigRemoveDynamicUI(tree);
case duOnApply:
NewSettings(val2);
return NULL;
}

return NULL;
}

[Ron]

I forgot to mention for the duOnApply to work you'll need to call SettemCallbacks.


PCHAR fn = GetGirderDirFile("uir.xml");
MyDUITree = LoadDUI(fn);
free(fn);

Config1 = FindItemNode(Config1GUID, MyDUITree, NULL);

if ( ( Config1 == NULL ) )
{
MessageBox(0,"Could not find Page 1 in DUI definition file","UIR Error",MB_ICONERROR);
return GIR_FALSE;
}

SetItemCallbacks(MyDUITree, Config1, gir_dynamic_ui);


Note (1) that you don't have to use the exported gir_dynamic_ui if you prefer you can have girder call a different function. Note (2) apply will only be called if the DUI detected any change, so if your dialog was unchanged apply is not called.

[Mark F]

I have a question about this part of the help file:

The interaction between the plugin and Girder is done through a function called gir_dynamic_ui,

void * WINAPI gir_dynamic_ui(pLuaRec LuaRec, PFTree tree, PFTreeNode node, PBaseNode BaseNode,int val1, int val2, void *userdata);

The first parameter is a structure that contains the Window Handle, Critical Section, the Lua State and a user data parameter.

typedef struct {
HWND hwnd;
void * L; // lua_State *
CRITICAL_SECTION CS;
void * UserData;
} *pLuaRec;


What is the proposed usage of the void *userdata in the gir_dynamic_ui() function?
What is the proposed usage of the void *UserData in the pLuaRec structure?
Are these different? How does a plugin set them?

[Ron]

You can set the userdata by returning your userdata during a duOnGetValues or duOnGetDefaults (=5). However, I am not sure this is too handy.

The userdata pointer in the pLuaRec was really added for convinience. It is a different value from the userdata in the function call. You can set it at any time. Look at the example plugin function: ActionPage3Callback

So yes they are redundant. I am thinking about dropping the functioncall userdata.