User:Quorn/SummerOfCode2008/UserManual

From BlenderWiki

Text Editor and Python Plugins

The editor has a number of new features both immediately available as editor functions, and via Python scripting.

Header Buttons

The text editor header has the following toggle buttons:

Fullscreen

Toggles the text area to full screen size and back (nothing new here)

Line numbers

After enabling line numbers, typing digits with the mouse cursor over the line numbers will jump to the typed line.

Word wrap

Word wrap is immediately available allowing more extensive text documents to be edited with ease.

Syntax highlighting

Syntax highlighting has been rewritten to be much faster and accurate.

Python text plugins

See the section on Plugins below.

Next comes the font size, tab size and finally the file name and information section:

• Text: Internal indicates the text is not associated with any file on disk
• Text: External indicates the text has been linked from a library .blend file
• File: <filename> indicates the text has been saved to/loaded from <filename>
• File: * <filename> (unsaved) indicates changes in the text have not yet been saved

If the text is associated with a file and that file is modified outside of Blender, a menu of options is presented:

A text object may also be disassociated from its file by choosing:

File → Make Internal

Editing

Aside from the typical editing functions you may also hold the Alt key and use the cursor keys, AltDel and Alt← Backspace to operate on whole words or chunks of symbols at a time.

The Ins key does what it should by toggling between insert (default) and overwrite mode. The RMB menu also now puts Cut, Copy and Paste operations to hand.

Find and Replace

The previous find box has been upgraded to a new Find and Replace panel. The panel offers a number of new options and remains visible as a reusable tool.

Two buttons on the right allow selected text to be brought into the appropriate field without the need to copy and paste.

The Wrap Around option will loop the search back to the top of the current text. If deselected, searching will work forward only and stop at the bottom.

Replace/Find will replace the selected occurrence and move forward to the next. Mark All is described in the Markers section.

Markers

A feature of the Find and Replace panel is the Mark All option. This places markers in the text area to indicate all occurrences of the sought word. By editing within one of these markers, all matching occurrences will be edited at the same time.

To clear markers simply press Esc. Markers are also used by the template completion plugin (see Plugins).

Suggestions

Suggestions are displayed by plugin scripts. They allow these scripts to present a list of words to be inserted. You can select an item from the list with the LMB , cursor keys or mouse wheel. Confirm with ↵ Enter or MMB . The list is updated as you type to narrow down the suggested entries.

The list is cancelled by pressing Esc or scrolled with the mouse wheel, cursor keys and page up/down keys.

Plugins

The following features are available via plugins which are enabled by clicking the Python icon in the text area header. To see how they work, see the section on How Plugins Work.

Import Complete

Shortcut: Space

Aids importing by displaying a list of modules available on the system after import or from is typed.

Member Suggest

Shortcut: . (Period)

Lists members of a module, class or builtin type.

Suggest All

Shortcut: CtrlSpace

Suggests imports or members if appropriate or otherwise lists global variables, defs, classes and modules both imported and present in the local script.

Script Outline

Shortcut: CtrlT

Provides a menu for navigating to definitions in the current script. It also allows a quick jump to the definition of the item under the cursor.

Function Documentation

Shortcut: CtrlI

Lists documentation for the function under the cursor (or before the cursor if inside its parentheses).

Template Completion

Shortcut: ⇆ Tab

If the word preceding the cursor is one of the trigger words it is expanded to a template. Use ⇆ Tab again to navigate between markers within the template or Esc to clear the markers. To edit templates or create your own, edit the textplugin_templates.py file found in the Blender scripts directory to your needs.

How Plugins Work

Text plugins work almost exactly like other Python scripts in Blender and register themselves in the TextPlugin menu. The difference is that they also register a shortcut:

 #!BPY
 """
 Name: 'Suggest All | Ctrl Space'
 Blender: 246
 Group: 'TextPlugin'
 Shortcut: 'Ctrl+Space'
 Tooltip: 'Performs suggestions based on the context of the cursor'
 """

A list of valid key names may be found in Appendix.

Once registered, a script is called every time the specified combination is pressed. That is, provided plugins are enabled in the active text space. Plugin scripts must therefore execute quickly, especially if the assigned shortcut is a commonly used key.

The active text object may be accessed via the bpy module:

 import bpy
 txt = bpy.data.text.active

There are then a number of methods available for positioning the cursor, reading text, selecting and marking text. Other utilities are available via the BPyTextPlugin module.

The BPyTextPlugin module uses a cached parsing system to provide information about a given text object. It is recommended to use the following method for extracting the required information:

 import BPyTextPlugin, bpy
 txt = bpy.data.text.active
 desc = BPyTextPlugin.get_cached_descriptor(txt) # A ScriptDesc instance
 desc.classes    # A dictionary of class names mapping to ClassDesc instances
 desc.defs       # A dictionary of functions in the global scope (FunctionDesc)
 desc.vars       # A dictionary of variables in the global scope (VarDesc)
 desc.imports    # A dictionary mapping module names to imported modules

The further descriptor objects ClassDesc and FunctionDesc also have defs and vars fields if appropriate. The lineno field is present in all but the ScriptDesc objects to indicate the line on which the symbol is first defined. For full details, see the BPyTextPlugin.py file in your scripts directory under bpymodules.

Appendix

Key combinations may start with an optional qualifier:

• Ctrl+
• Alt+
• Shift+

followed by further qualifiers (if required) and finally a key name (some variations also exist):

• A - Z (AKEY - ZKEY)
• 0 - 9
• PAD0 - PAD9
• F1 - F12
• Period
• Comma
• ...

Each item may be separated by a space + or -. For example 'Ctrl+Space'.

Note that some combinations are reserved and will not work. Others may be used by the text area (eg. CtrlC) but will still function as plugin shortcuts. Be careful which keys you decide to use.

Use symbol keys with care as they may or may not require ⇧ Shift to be pressed. This may also change across keyboard layouts.