[Bf-python] Blender.Registry

[Willian Padovani Germano]

Hi again,

Second part of the changes.

[ But first: the previous email was big enough, so I didn't mention
there that with the new Scripts window it's already possible to have
more than one script with gui running at the same time at the same
window.  If you have more than one running at the same time, you can
choose which one to use on the window header's datablock pulldown list,
just like you select a text in the Text Editor window. ]

Since Blender 2.28, every script uses its own global dictionary
(namespace), so there's no need to worry about name clashes and leftover
data, since as soon as the script goes away, its global dict is also
freed.

But in some cases it is useful to have persistent data, that can be
accesseed by another script or by the same one on a later call.  There
was a method to allow this, called Blender.ReleaseGlobalDict(bool):
http://www.blender.org/modules/documentation/231PythonDoc/Blender-module
.html#ReleaseGlobalDict

but this was not good and doesn't work anymore.  There's a better way in
the form of a new module, Blender.Registry, that was introduced some
months ago but is still undocumented.  The idea is that you can register
a dictionary with some data that won't be deleted from Blender until it
is shut down.  This persistent data can then be accessed and changed by
other scripts or the same one on a later execution.  It's highly
recommended that you don't store big chunks of data (write to a file if
you need that) and don't store blender objects (save their name strings
instead).  Only Python types should be saved (numbers, strings, lists,
dictionaries, etc).

Straight to an usage example: let's say the user pushed some buttons and
defined some strings in your script's gui.  You can save this data to
the "registry" and if your script is executed again, you can get that
data (the state) again and put the buttons in the same form they were
left by the user:

#----------------------------
Example "MyScript":

# in your script you initialize this global data related to buttons:
TOGGLE = 1
DIR = ""
VALUE = 0

# then you check if there's a key already for your script
# Looking for a saved key in Blender.Registry dict:
reg = Blender.Registry.GetKey('MyScript')
if reg:
  TOGGLE = reg['TOGGLE']
  DIR = reg['DIR']
  VALUE = reg['VALUE']

# better also define a function to do the saving when needed:
def update_RegistryInfo():
  d = {}
  d['TOGGLE'] = TOGGLE
  d['DIR'] = DIR
  d['VALUE'] = VALUE
  Blender.Registry.SetKey('MyScript', d)

# ... here goes your script ...

# Before exiting use the function you wrote:
  update_RegistryInfo()
#----------------------------------

Here are the currently available functions in the Blender.Registry
module:

Registry.Keys()  # gets all registered keys
Registry.SetKey(keyname, dict) # set a new key
Registry.GetKey(keyname) # try to get a key by name
Registry.RemoveKey(keyname) # remove a key from the registry

After you GetKey an existing key, it'll be automatically updated when
you change its dict, no need to call SetKey on it again.  A single key
should be enough for a script, since it holds a dictionary where you can
store all data you need to.

Later we'll add a way to save to a file (or Blender Text) a piece or the
whole Registry dict.  Note that then it will be checked if every dict
entry is of an acceptable type (only python types are ok, don't store a
Blender obj, store its name instead).

This was just an intro to the module.  The next version of the Blender
Python API Reference will include documentation for it.

--
Willian, wgermano at ig.com.br