Architecture: operators

*** Overview
Operators (wmOperatorType*) manage tools, so by defining a new wmOperatorType you create a new tool. Check out [1] for more info (and conventions) and [2] for a tutorial/more details.
* Example 1: http://pastebin.com/uMfBNvZj
* Example 2: http://pastebin.com/XUutURAc

*** Members
* name
e.g. ot->name = "(De)select All"

Human readable name for the UI. Capitalized.

* idname
e.g. ot->idname = "MESH_OT_select_all"

It's an unique identifier; set it identical to the method name
Format: <PREFIX>_OT_<action>_<details> (e.g. MESH_OT_select_all)

* description
e.g. ot->description = "(De)select all vertices, edges or faces";

* srna
e.g. PropertyRNA *prop = RNA_def_int(ot->srna, ...)

Operators can define a number of RNA properties (see [0]->N1).
These can be set by the user and used by the operator to modify its behaviour.

* exec, invoke, modal, cancel
e.g. ot->exec = edbm_select_all_exec

Every operator must define either exec or invoke.
exec:	Provided to run the operator without user interaction.
	Only if this is provided can the ot be recorded for a macro.
invoke:	Will execute after an event (e.g. getting mouse coordinates).
modal:	From the invoke callback, the ot can add itself as a handler,
	and receive further events in the modal callback.
cancel:	If the ot is cancelled (e.g. program quitting), this callback is called.

Return for exec, invoke and cancel:
pass through: Means the operator passes on the event to other operators,
	as if the callback did not run.
running modal: Indicates that the ot is still running and has registered
	itself to receive modal callbacks.
cancelled, finished: Mean the execution of the ot has ended, successfully or not.
	The operator will be registered only for 'finished'.

* poll
e.g. ot->poll= ED_operator_editmesh

Used to verify the ot can be executed in the current context. It's often shared for multiple operators. It's always called before executing the ot, so it may be used to gray out or hide UI elements that use this ot automatically.

*** Caveats:
* Note the distinction between RNA properties and customdata. The properties should only store public parameters as seen by the user, these are saved as part of macro's and written to file. The customdata is an arbitrary pointer, typically to a C struct, that should only exist while the operator is running, an so it is not written to file.

* The invoke callback also takes properties as inputs and should take those into account. For example a transform operator might have a mode=rotate input, and should then start in rotation mode.

Home:
[0] http://wiki.blender.org/index.php/User:Ansimionescu
Reference:
[1] http://wiki.blender.org/index.php/Dev:2.5/Source/Architecture/Operators
[2] http://wiki.blender.org/index.php/Dev:2.5/Source/Architecture/Operators/Tutorial