[Bf-python] HOWTO have scripts in menus

Willian Padovani Germano wgermano at ig.com.br
Mon Jan 19 04:26:51 CET 2004


Hi,

At last scripts can be registered and appear in Blender's menus.  This
is the main one of a small set of changes that give a few new
possibilities for scripting.  Here and in another email (subject:
Blender.Registry) these changes are described with a little bit more
detail, for those interested.

Scripts in menus:

To register a script in a Blender menu, the author needs to add a simple
header to the top of the script.  Here's an example:

!#BPY

""" Registration info for Blender menus
Name: 'My Exporter'
Blender: 232
Group: 'Export'
"""

The script must then be put in the directory pointed to by the user pref
scripts dir (set it on Blender's Info Window -> File Paths -> Scripts)

and that's enough.  The single-quotes are necessary and each tag (Name,
Blender, Group) should appear in the order given above, but only the
first letter (case independent) of a tag is considered, so you can
simply write:

#!BPY
"""
n 'My Exporter'
b 232
g 'Export'
"""

empty lines are also ignored.  Besides the above tags, two more are
available, but optional:  Submenu and Tooltip.  Here's a full example,
taken from the AC3D Export script:

#!BPY

""" Registration info for Blender menus: <- these words are ignored
Name: 'AC3D'
Blender: 232
Group: 'Export'
Submenu: 'All meshes...' all
Submenu: 'Only selected...' sel
Submenu: 'Configure' config
Tip: 'Export to AC3D (.ac) format.'
"""

Again, the order is to be respected and only the first letter of each
tag is important, so t, T, Tip, Tooltip, Twhatever are all the same.

Tags description:

-> Name: the script name as will appear in the menu.  Should be between
single-quotes and unique *in its group* -- two 'Import' scripts, for
example, can't have exactly the same name.  So script authors may choose
to add the script version to the name: Name: 'My Script 1.0'.

-> Blender: the version number, as given by this Blender Python code:

import Blender
print Blender.Get('version')

This is to define the minimum Blender version a script expects: if
someday you write a script for, say, Blender 2.4, it may have some
bpython API call that was not available in Blender 2.39 and below (down
to the upcoming 2.32, which will be the first version to check for
this).  Before running a script, if its Blender version is newer than
the one the user is running, a msg will be given warning the user about
that.  This tag was suggested by Douglas Bischoff.  Martin Poirier then
pointed that it should be used as a 'minimal version tag', to warn about
the mismatch, but try to run the script anyway.

-> Group

This defines the menu where your script will appear.  Currently there's
'Import', 'Export' and 'Misc'.  Naturally, we'll add more options soon
and whenever it's agreed that they are needed.

Import and export are on the main "File" menu.  Misc appears at the
Scripts Window header, under menu "Scripts", where all other groups will
also be available.

-> Submenu

This is optional, but you can add more than one, as the example above
showed.  After the user clicks on an entry which has submenus, a pop-up
menu is opened with the available submenu options.  The way this works,
then, requires a quick explanation. The syntax is:

Submenu: 'Name' arg

where Name is the string that will be shown to the user and arg is any
single word, a function argument.  Think of arg as the argv[i] arguments
in Python.  But instead of being in sys.argv, arg is stored in a new
dictionary:

__script__ = {'name': 'scriptname', 'arg': arg} , that you can find with
"print dir()" in current cvs Blender and from 2.32 on.

To know which submenu the user chose, just check
__script__['arg'] , it holds the chosen option.

If the script was executed with the old method (ALT+P in the Text Editor
window), __script__['arg'] is None.

So if you register the following submenus for an exporter:

Submenu: 'All...' all
Submenu: 'Selected...' sel
Submenu: 'Configure' config

in your script you can have something like:

a = __script__['arg']
if a == 'all': export_all()
elif a == 'sel': export_selected()
else: # a is 'config' or None (= executed in the text editor)
  Blender.Draw.Register(gui, event, bevent)

to check which submenu was chosen by the user.

-> Tooltip: (optional) simply a string about your script, hopefully with
useful info, that is shown when the user leaves the mouse pointer over
the script's menu entry for a while.  If not given, the script filename
(filename.py) will be shown as tooltip.

-------------------------------------------------------
How the system works:  on start-up Blender checks the user pref
pythondir for scripts with registering info (the header explained above)
and adds them to the menus.

It also writes a file called .Bpymenus to the user's home dir (the
location will maybe change to <Blender install dir>) with the
registration info, for faster access.

Actually, if the file is available and is not older than the dir
(meaning the dir contents were not modified after the file was written),
the file is read on start-up directly.  A menu entry was added to the
Scripts window and also a button to the Info window -> file paths (close
to Scripts entry) to force a re-registration of scripts without having
to restart Blender -- suggested by Kent Mein.

---------------------------------------------------------

That's it.  There are a few more things to be decided and also another
possible dir will be added as a place to look for scripts to be
registered:
<Blender install dir>/.blender/scripts

Comments / questions / criticism are welcome, sorry for the long email.

--
Willian, wgermano at ig.com.br




More information about the Bf-python mailing list