Yamyam: 1版をインポートしました

2018-06-28T17:54:29Z

1版をインポートしました

wiki>Mindrones bot: Robot: Changing template: K

2010-04-12T18:28:15Z

Robot: Changing template: K

新規ページ

==Improving Python Editing In Blender==
This project enables users to develop Python scripts with greater ease by including a number of new features to the text editor and improving upon the existing functionality.

For information on the changes made to Blender and the way it fits in with current development see the [http://docs.google.com/Doc?id=d5scbjf_12ffjnqqgn Integration Document]

Or for information on using the new system, see the [[User:Quorn/SummerOfCode2008/UserManual|User Manual]]

===Current Status===
<div class="floatright"><vimeo>1376152</vimeo></div>
<div class="floatright"><vimeo>1478608</vimeo></div>

The key aspect of this project has been the text plug-in system. This system allows Python scripts to be created that interact directly with the user, and the text on which the user is working. For information on how to write a text plug-in, see the section on [[User:Quorn/SummerOfCode2008#Writing a Text Plug-in|Writing a Text Plug-in]] below.

These videos demonstrate the features introduced by this project. For a more complete list see below.

{{clr}}

===Features Completed===
The following list outlines the features brought to Blender by this project:
* Code/member suggestion and completion ['''[http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=15583 done]''']
* Scrollable documentation access panel ['''[http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=15635 done]''']
* Whole word operations ['''[http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=15127 done]''']
* Insert/overwrite support ['''[http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=15115 done]''']
* Header lists active file (or "Internal") and modified status (*) ['''[http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=15148 done]''']
* External modifications are checked for and reported with options ['''[http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=15364 done]''']
* Word wrap

It will also fix the following issues:
* Library linked Text can be edited ['''[http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=15162 fixed]''']
* Backspace at top of file inserted blank line on undo ['''[http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=15119 fixed]''']

====Additional====
Additional features that are being considered or would be good extensions to the project:
* Better search: all text search, find and replace ['''[http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=15721 done]''']
* Interaction between Blender clipboard and text clipboard ['''[https://projects.blender.org/tracker/index.php?func=detail&aid=17370&group_id=9&atid=127 done]''']
* Additional line and positional markers, which would then allow... ['''[http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=15960 done]''']
* Code templates and snippets<sup>[[User:Quorn/SummerOfCode2008#References|1]]</sup> ['''[http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=15982 done]''']
* Mindrones' Wishlist<sup>[[User:Quorn/SummerOfCode2008#References|2]]</sup>
* Better support for other languages
* Script output redirect

Other issues found:
* Redo fails when re-deleting backward-selected text ['''[http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=15713 fixed]''']
* Pressing up at the top or down at the bottom breaks undo ['''[http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=15789 fixed]''']

===Feature Descriptions===
====Code Completion====
When editing Python scripts it is often desirable to have a list of functions and variables defined in the current script. It is also useful to have the ability to list the various functions and fields of a given object.

The code completion section of this project brings both of these to the user and provides a platform for further completion methods (such as snippets or tags) to be implemented.

The actual ''completion'' comes from the ability to type only a few (if any) of the characters of the method or field before invoking the suggestions list. For template-like completion the system makes it very easy to add. A script can be written with the shortcut {{Shortcut|Tab}} that strips out at the word preceding the cursor, looks it up in some template dict and <code>insert()</code>s the template into the code positioning the cursor in the right place with <code>setCursorPos()</code>. If time allows I will produce such a script and a tutorial on its creation at the end of the project.

To invoke completion simply enable syntax highlighting and press {{shortcut|ctrl|Space}}. This will list all modules, functions and variables available or defined in the script. Additional scripts work to complete import statements:
<pre>import |</pre>
...and member fields:
<pre>import Blender
Blender.|</pre>
Where <code>|</code> marks the cursor position. The last period or space typed will invoke these context sensitive scripts. {{shortcut|ctrl|Space}} may also be used here.

====Documentation Listings====
On similar lines to code completion a quick view of the documentation for an object is displayable. This aims to reduce the need for using external documentation by bringing it into the interface.

Currently, whilst inside a function:
<pre>print somefunc(somevar, | )</pre>
Pressing {{shortcut|ctrl|I}} will list the <code>somefunc</code> function's documentation text. If the cursor is not inside a function's parentheses it will attempt to display the documentation string for the name preceding it:
<pre>import Blender|</pre>
will display the text "The main Blender module"

====Editing Methods====
Editors typically have a set of operations that users have come to expect yet Blender lacked a number of these.

Text overwrite support. Before this project you could only insert text and the {{Shortcut|Ins}} key had little use. Now the {{Shortcut|Ins}} toggles insert/overwrite modes and changes the cursor to reflect this.

Whole word operations (implemented in some editors as {{shortcut|ctrl|Left}}, {{shortcut|ctrl|Del}}, {{shortcut|ctrl|Backspace}}, etc.) have been added. Unfortunately, {{shortcut|ctrl|Left/Right}} are reserved for screen switching so {{Shortcut|Alt}} equivalents have been substituted where appropriate:
{| border=1
|{{shortcut|alt|Left/Right}}
| Moves the cursor left/right by one word or group of symbols.
|-
|{{shortcut|ctrl|Backspace/Del}} <br> {{shortcut|alt|Backspace/Del}}
| Deletes the word to the left/right of the cursor.
|}
Word wrap is another missing feature and is very useful for writing text that is not part of a script. Word wrap will have a toggle button associated with it but is not yet implemented.

===Writing a Text Plug-in===
To write your own text plug-in take a look at the template under '''File → Script Templates → Text Plugin'''. The BPy module, together with the new Text object functions allow a variety of useful tools
to be created.

====The BPyTextPlugin Module====
The central component of many text plug-ins is the python module BPyTextPlugin. This module provides tools for parsing and obtaining useful information about a given Text object. Here is a short description of how it works and the interface for using it in your own scripts.

The method of most use is <code>get_cached_descriptor(txtobj)</code> which returns an instance of <code>ScriptDesc</code> when passed a Blender Text object. If the text has not been previously parsed or for whatever reason, it is decided to reparse the text, <code>parse_text(txtobj)</code> is called. This method can also be used to force a re-parse.

<pre>import BPyTextPlugin, bpy

txt = bpy.data.texts.active
desc = BPyTextPlugin.get_cached_descriptor(txt)

BPyTextPlugin.print_cache_for(txt)</pre>

The best way to understand the <code>ScriptDesc</code> instance is to look at the BPyTextPlugin module itself. Its <code>vars</code> and <code>defs</code> fields provide lists of <code>VarDesc</code> and <code>FuncDesc</code> instances which further describe the text. The <code>classes</code> field provides access to classes with their own <code>vars</code> and <code>defs</code> lists.

Each descriptor has a <code>lineno</code> field for accessing the number of the line on which it is first defined, and a <code>name</code> field for obtaining the symbol name.

====Changes To The Text Object====
Once a script has obtained the information it requires it can feed this information to the user by two new methods:
{| border="1"
| <code>txt.showDoc(doc)</code>
| Displays word-wrapped documentation in an easily dismissable panel
|-
| <code>txt.suggest(list, prefix)</code>
| Displays suggestions list limited to show items with the specified prefix.
|}

It may also create markers (see below) by calling
{| border="1"
| <code>txt.markSelection(group, (r,g,b), flags)</code>
| Marks the current selection with the specified group, colour and behaviour flags. Use <code>Text.TMARK_EDITALL</code> to indicate that all markers of the same group should be edited together*
|}

<sub>* Markers with this flag must be of the same length and mark equal text</sub>

Example using the suggestion and documentation tools:

<pre>import bpy
from BPyTextPlugin import suggest_cmp

txt = bpy.data.texts.active
sugs = [('suggest_me', 'v'), # v for variable
('suggest_this', 'f') # f for function
]
sugs.sort(cmp=suggest_cmp)

txt.showDocs('Some kind of documentation string, automatically word-wrapped')
txt.suggest(sugs, 'suggest_')</pre>

'''Note:''' It is no longer necessary to sort the suggestions list but it is still recommended. Use <code>sort(cmp=BPyTextPlugin.suggest_cmp)</code> for sorting.

Other additions to the Blender Text object (<code>txt</code>):
{| border="1"
| <code>row, col = txt.getCursorPos()</code>
| Returns the cursor position (row, col). Note that line numbers are usually 1-based in python, whereas row is 0-based here.
|-
| <code>txt.setCursorPos(row, col)</code>
| Sets the position of the cursor in the Text object (or as close as possible). Selections are cleared.
|-
| <code>row, col = txt.getSelectPos()</code>
| Returns the selection cursor position (row, col). Note that line numbers are usually 1-based in python, whereas row is 0-based here.
|-
| <code>txt.setSelectPos(row, col)</code>
| Sets the position of the selection cursor in the Text object (or as close as possible). Selections are extended to this point, use <code>setCursorPos</code> first to base the selection.
|-
| <code>txt.insert(string)</code>
| Inserts <code>string</code> at the current cursor position.
|-
| <code>txt.readline()</code>
| Reads a line from the Text object in accordance with other readline methods.
|-
| <code>txt.reset()</code>
| Resets the IO pointer to the beginning (for reading).
|}

With these tools, many plug-ins can be produced, from class browsers to template completion scripts.

===Markers===
Markers provide a neat way to jump around text and edit repeated portions in one go. They allow templates to be constructed where certain bits must be filled in and expand on the find and replace options.

To see markers in action see the video above or take a look at my template script:

https://svn.blender.org/svnroot/bf-blender/branches/soc-2008-quorn/release/scripts/textplugin_templates.py

The template syntax used in this script is based on GEdit's snippets<sup>[[User:Quorn/SummerOfCode2008#References|1]]</sup>

===Project Schedule===
During the first week, I shall learn as much as possible about the current implementation and outline the possibilities. Some of the simpler features and fixes may be carried out here. The remainder of the time will be split as follows:

Stage 1: Implement the back end functions for code completion, documentation and other features. Output is generally directed at the console at this stage.

Stage 2: Create UI elements for displaying the requested information. Output is fed to these on request.

Stage 3: Implement advanced UI features and interaction (scrollable documentation panel, member selection). Also allow the user to enable/disable these features, possibly adding options to User Preferences although this should be limited.

Stage 4: Seemless integration: enabling context sensitive pop-up without specific user request (eg. when the user types a . after a valid variable or pressing tab for snippet completion).

Stage 5: Final testing, debugging and tidy-up. Optimizing the code for best possible performance.

On completion of the project, changes merged with the trunk will be documented for the general public. The wiki page at [[Manual/Python_Scripting#The_Text_Editor]] will be updated.

===About Me===
I am a 21 year old Mathematics student who has just finished his final year. I am about to embark on a Masters degree in Computer Animation. I have been developing software since an early age and have experience in many languages including Pascal, Java, C, C++ and Python. I have worked on the development of an open source renderfarm for Blender<sup>[[User:Quorn/SummerOfCode2008#References|3]]</sup> and make use of many open source tools in my daily life.

I love the idea of making something useful for all and hope that this project will do just that.

===References===
# [http://live.gnome.org/Gedit/Plugins/Snippets GEdit Snippets]
# [http://blender.mindrones.com/wishlist/text-editor Mindrones' Wishlist]
# [http://netblend.sourceforge.net Distriblend]

← 古い版	2018年6月28日 (木) 17:54時点における版
(相違点なし)

利用者:Quorn/SummerOfCode2008 - 版の履歴

Yamyam: 1版 をインポートしました

wiki>Mindrones bot: Robot: Changing template: K

Yamyam: 1版をインポートしました