On 31 July 2011 20:18, Matthew Brush mbrush@codebrainz.ca wrote:

Hi,

I'm working on the Python bindings (again) and I had a simple question.  How can we know which struct members in the plugin API are supposed to be settable vs those which should be read-only?

Hi Matthew,

I would treat them *all* as read-only unless something explicitly says you can set it. (and almost nothing does)

Your example readonly is a good one, if you look at callbacks.c/on_set_file_readonly1_toggled() you will see that there are several steps to making it work after modifying the struct member. But it would be dangerous for a plugin to repeat that implementation because it can change at any time.

So unless struct members say you can set them, or they are set by functions accessible in the API, then they are read-only.

At the moment this means that many capabilities are not available to plugins. In some cases this is an oversight (or no one has asked for it yet). In some cases it is to limit how much of the implementation is exposed, so that further internal evolution is not constrained by the need to keep the API constant.

For example, in the GeanyDocument struct there's a member called 'readonly', which no doubt if set directly by plugin developer will not update the read-only status of the document (ie. change GtkMenus in the UI, tab colors, etc).  Are any of the exposed struct members supposed to be settable by the plugin developer or are they all supposed to be read-only?  In some cases in the API there are accessor functions, so can one assume that none of the struct members should be set directly and only ever set through an acessor

If a function to set the member is *documented* as part of the API it is intended to be called from plugins.

function, if available?  Are there any exceptions to this, for example, some of the prefs structs?

IMHO plugins shouldn't set any of the existing Geany prefs, they are there for the user to set via Geany, which knows what to do when they are changed and what the legal combinations are. Plugins can read them but shouldn't mess with them. Plugins should use their own prefs and stash is in the API for that purpose.

Cheers Lex