利用者:Kesten/Projects/TextEditorWiki Proposal

Text Editor

There are a few “gotchas” when working with the Text Editor, which can make it seem like your scripts are not being saved, or old versions are being run instead of what is shown in the Text Editor Window. Apart from this, the text editor alows for excellent workflow as a small testbed for python scripts. For larger scripting projects, you will probably want to consider an IDE such as Eclipse with PyDev support as demonstrated in Witold Jaworkski's | airplane demo.

First of all, if you are re-starting blender frequently, you need to take care that you are always working on the same .blend file session. Just below “User Preferences” in the File Drop-Down menu in Fig 1. you can select “Save User Setting”. This saves the current .blend file as the default. Unfortunately, the default filename is not displayed in the “.blend loaded file” so care must be taken if you are using internal files that you are working on the correct .blend file or it will seem that your changes are not being saved. If you wish to have the default loaded .blend file be your current project and you are using “make internal” scripts, you will have to remember to “Save User Settings” before closing every time. It's probably safer to manually load the .blend file for your project beginning every session.

Make Internal

Suppose that you want to send a .blend file to a friend along with several scripts. You could send a folder with several files in it, but it is much more convenient to tell blender to “make internal” the scripts. However, this presents several challenges to the development work-flow.

The main problem is that the Active Text Block is positioned so that unless you have a very short path and have toggled the View->Toggle Full Screen (Fig. 3) you cannot see what the active file is. The “Filename field” is much more prominent, but it is unreliable (see tests below). It does not always indicate the name of the file shown in the Text Editor Windor, nor is it always the Active File. All sorts of confusion can occur if you are learning the Text Editor but cannot see the Active Text File.

A naive workflow would be to create a new text-block file, save it and then make it internal. One way to do this would be Text->Create Text Block, Text->Save As and when the File Browser pops up Save As test1.py for this example. If you now click Text->Make Internal, you dissociate the text buffer from the file on disk, creating a data chunk in the .blend file. Now for the “gotcha”. Unless you do a “File->Save” in the blender main menu, the data chunk will not be saved. You must also take care because now you have an internal test1.py and a disk test1.py and unless you can see the Active Text Block, it is easy to confuse the two.

Working with scripts on-disk only

Unless you need to bundle scripts with a .blend file, it is recommended that you do not use the “Make Internal” feature as it allows for mis-match between disk and internal copies of a file. The little red “life-preserver” icon above indicates a mismatch or change on disk of a loaded file.

Working with internal-only scripts

It is possible to create scripts that only exist in a .blend file by Text->Create Text Block followed by a File->Save from the main blender menu. Save, Save As and Reload in the Text menu seem to only apply to disk files.

Keeping disk and internal copies synchronized

Choose to use either the internal or disk version as your primary version for developing. If you choose the internal version, your workflow is - Text->Create Text Block, make changes, File-Save, Run Script. To update the disk file at the end of a session, Text->Save As. If the disk copy is your primary, then the workflow is Text->Open Text Block, make changes, Text->Save, Run Script. To update the internal copy at the end of a session, Text->Make Internal, File->Save.

Why Can't I find files in the File Browser?

The “File Browser” has a large number of options for filtering files. If you can't find a file you think should be there, toggle off the “File Filters” icon. Note that many blender features require that python scripts are named with a .py extension. Check your directory with an external file browser if necessary.

Some Python Specifics

A python module is a file that has some functions defined which you can call via an import statement. Another “gotcha” for new python scripters is trying to include your own python module in another file. This may work the first time, but thereafter, changes made to the imported module will not be reflected when you run the executing script. This is because python only imports the symbol table, which amounts to your function definitions, the first time the script is run. To force changes made to yourModule.py to be honored in a calling script you must add the following to the calling script.

import imp 
imp.reload(yourModule)

Note that you drop the .py extension when importing modules. Also note that when you call myFunction() defined in yourModule, you access it as yourModule.myFunction(). An imported module must be in the same directory as the calling script, in a location recognized by blender such as ../blender/../scripts/addons or in the PYTHONPATH environment variable.

Some Blender-Python Specifics

Console vs. Text Editor

Blender offers you two ways to interact with python, via the Text Editor, or with the Python Console. An important distinction is that the Python Console loads some “Convenience Imports” like mathutils and bpy. If some things work in the Python Console but give errors using “Run Script” in the Text Editor, it may be because the Text Editor does not load any convenience imports.

BGE modules

Blender Game Engine (BGE) modules can only be accessed when blender is in Game Engine mode after the “P” for “play” key is hit. Once it is hit, you cannot use any of blender's features outside the game until you press the “Esc” key. To test a bge-dependent script, you must trigger it to execute from a game-logic node.

Errors

Getting error messages from python can be a bit of a trick. In windows, go to the main blender menu and choose Help->System Console. In linux, the easiest way is to find the directory where the blender executable lives and type “./blender” at the command prompt ie, assuming blender is in /bin,

blender/build/linux/bin$ ./blender

Errors will then show up in the terminal that you launched blender from. Another possible aid is the “Info Window”. It echos many (but not all) blender commands generated by the user and some error messages. To access the info-window, hover the mouse pointer above the main menu panel and pull down.

Code Completion

In the Python Console, type “bpy.” and then “ctrl+spacebar”

Python API Exposure

With the mouse pointer in the 3d Viewport press “spacebar”.

Notes

• Text->Reload reloads a file from disk discarding any changes made in the Text Editor Window. It does not seem to be related to imp.reload() in any way.

• “Run Script” will execute unsaved changes, but does not autosave the file. If you close without saving, the latest changes will be lost.

• If you want to run a script on start-up check the “Register” check-box.

A few tests:

1. Type a few lines in test1.py . Click “save as” . File Browser menu opens. In File Browser type over filename to test2.py . Click save as. Blender returns to text-block view but the name in filename field is still test1.py . Restart blender. test1.py doesn't containt the changes. test2.py does. Expected Result: the filename field should reflect the active file and this should always be the file open in the text window.

2. Make changes to test2.py internal and test3.py disk files. Blender File->Save to textTesting.blend. Restart Blender. Changes were saved to test2.py . The changes to test3.py seem to have been stored in the .blend file, but changes to disk were not made. A “*” by the filename indicates they are out of synch.

3. With test3.py open, add a line and rename it test4.py in the filename field. Click Text->Save. test3.py saves the changes. test4.py is not saved. Expect that changing the name in the filename field would change the active file being worked on and create a new file if it doesn't exist (at least when Text->save is clicked). If this is not the behavior then the filename field should be read-only.

4. Make file test13.py internal, then click the “x” button to unlink the file. It is removed from the drop-up text-buffers menu.

5. Make some changes to a file, then Run Script. The changes are run in the script, but if you quit without saving, those changes were not autosaved. I believe most applications would either autosave upon running, or execute the un-saved text buffer.