<html><head><title> POO Editors </title></head><body><center><h1> Custom POO Editors </h1></center> <p><hr><h2>Introduction</h2> POO provides a very simple built-in editor. This is the editor invoked by commands such as @edit or @newfunc, if your ".editor" property is undefined or cannot be executed as a custom editor. <p>However, if you set your ".editor" property to a properly written custom editing function, that function will be used instead of the built-in editor. Since it requires wiz privs to set a reference to a function you do not own, non-wizards will have to change their editor with a command such as the following: <p><center> @editor notvi </center> This command (if <a href="lib/editors.html">installed</a> on your POO) will set your editor to the function stored as $pub.editors.notvi -- to return to the default editor, use "@editor default". <p><hr><h2>Creating Custom Editors</h2> <b>WARNING</b>: <i>Creating custom POO editors is Big Magic. If you do doubt your skill or your courage, go no further, for frustration awaits you with big nasty pointy teeth!</i> <p>An editor function has the form: <p><center><b>myEditor( self, buffer, msg, state )</b></center> <ul> <li><b>self</b>: the object on which the editor is being invoked <li><b>buffer</b>: a list of strings -- the lines being edited <li><b>msg</b>: the line typed by the user at the "edit>" prompt <li><b>state</b>: editor-defined state variable; initially <tt>None</tt> </ul><p> The editor function must examine the msg and state parameters to decide how to process the buffer. It must then return a new state, which will be passed back upon the next entry by the user. "state" may be any datatype, but two return values have special meaning to the POO engine: <p><ul> <li><b>"DONE"</b>: exit the editor and save changes <li><b>"ABORT"</b>: exit the editor, discard changes </ul> You must return one of these two strings to end the editing session. Any other return value will be passed back to you as the state parameter. <p><b>Note</b>: if <b>msg</b> is '.x' you must exit with "DONE", and if it is '.q' you must exit with "ABORT". These are enforced by the POO engine; if you don't interpret these messages, the normal save/abort behavior will be invoked regardless. This is to prevent users from getting "stuck" in a custom editor and unable to exit. <p>If your code raises an exception, it will be caught silently and the built-in editor will be invoked instead. This makes debugging difficult; the only way to debug is to manually invoke your editor, e.g., <p><center><tt> ;me.myEditor(['line one','line two'], '.x', "OK") </tt></center> <p><hr><h2>Sample Editor</h2> The code below can be executed by a wizard to create a minimal custom editor. To restore the default editor, use <tt>@delprop me.editor</tt>. <pre> @newfunc me.testEditor( self, buffer, msg, state ) print "in " + str(self) + "'s editor, with ", \ "buffer: ", buffer, "msg: ", msg, "state: ", state # for this ultra-simple editor, the only command we recognize # is "." to exit; anything else is text to append to the buffer. if not state: print "[Cheezy line-entry editor -- enter a period when done.]" return "OK" # we'll use "OK" to mean "ready to accept input" if msg == ".": return "DONE" # <-- special keyword, indicates we're done editing else: buffer.append(msg) print "new buffer:", buffer return "OK" .x @set me.editor = me.testEditor </pre> <p><hr><h2>Cautions</h2> Nonwizards cannot assign functions they do not own to properties. So to make an editor publicly available, something like <a href="lib/editors.html">$pub.editors</a> should be used. <p>Python objects don't die as long as any references to them exist. So if you recreate your editor with @newfunc, and other players have references to it, they will continue to use the old code. To avoid this mess, always update an editor function with @edit rather than @newfunc. <p><hr><h2>Summary</h2> Custom editors are a powerful feature of POO that allow the simple built-in editor to be replaced with a variety of more sophisticated ones, automatically invoked for each user according to his preference. Writing a custom editor is difficult, but once done, the functionality of POO can be significantly enhanced without modifying the engine code. <p><hr><address> http://www.strout.net/python/poo/editors.html <br>Last Updated: 8/14/97 . . . . . . <a href="http://www.strout.net/">Joe Strout</a> </address></body></html>