xstatebutton docs missing support for refs

[lgeggleston]

>>> h.xpanel('Button')
0.0
>>> foo = h.ref(0)
>>> h.xstatebutton('button', foo)
0.0
>>> h.xpanel()
0.0
>>> foo[0]
1.0
>>> foo[0] = 0

[nrnhines]

Thanks. You are correct that xstatebutton and all the other widgets will accept an h._ref_var variable in place of the hoc &var variable. I have to admit it is a bit of a surprise to me that h.ref((0) is also acceptable and I thought it was not valid for persistent references within a function call but only for call by reference in the context of returning a changed argument. I will have to review the implementation with a view toward understanding if this is really safe with regard to persistence after return from the function. (of course, it is assumed that foo is persistent in python over the lifetime of the xstatebutton). @ramcdougal do you care to weigh in on this with regard to pythonicity as to whether it should be mentioned in the Syntax section or whether it should be mentioned in a Note further on. In some ways it is implied by the hoc documentation. ie. any place hoc refers to &x, one can use an h.ref(0)

[ramcdougal]

I absolutely think this should be mentioned in the syntax section.

Lookup by class/module and name is more cumbersome to write and I assume slower to evaluate than using a ref.

I don't see why there would be a problem with persistent references, but I've never looked too deeply into that either. The perhaps more common example of this is with using a ref for an xvarlabel.

[nrnhines]

It is clear on review of the implementation that h.ref(0) can be used anywhere a double* is stored.
It is only necessary that the h.ref object persist in the python world as long as the double* is stored
to prevent python from freeing the double* while there is still a chance that it may be used by c or c++ internal code.