class:: Document redirect:: implementationClass summary:: Editor-specific text document editing categories:: Frontends related:: Classes/EmacsDocument, Classes/ScelDocument description:: The Document class represents a text document within the context of your text editing environment. You can use the class to programmatically create, modify, and query these documents. Document used to be an abstract class, meaning it didn't provide all the functionality itself, but instead relied on subclasses to complete the functionality. One such subclass was CocoaDocument. Although CocoaDocument was available only to macOS and had an ad hoc interface, it possessed many additional features like code animation and rich text. In SuperCollider 3.6, Document changed a bit and now the "abstract class" descriptor is only partially true. The SuperCollider IDE provides its own version of the Document class. The Emacs editor still supplies link::Classes/ScelDocument:: (which links to link::Classes/EmacsDocument::) as a subclass of Document. As an unfortunate byproduct of the history of Document, there are inconsistencies in the APIs of SCIDE's Document and Emacs' ScelDocument. This help file describes that of SCIDE. Future versions of SuperCollider will aim to fix these API inconsistencies and restore the functionality of CocoaDocument. subsection:: Setting the Environment By default code::envir:: it is set to the current link::Classes/Environment::. However, you can make it use its own link::Classes/Environment:: also. Thus, e.g., if you were to set the link::Classes/Environment:: variable code::~myVar = 12:: in the current link::Classes/Environment::, you can create a new Document window in which that link::Classes/Environment:: variable is not set. classmethods:: private:: prGetLast, prSetSyntaxColorTheme, prnumberOfOpen, prBasicNew, prGetIndexOfListener, prDefaultUsesAutoInOutdent, initClass method:: new argument:: title An instance of link::Classes/String:: or link::Classes/Symbol::. argument:: string An instance of link::Classes/String::. The contents of the document. argument:: envir An instance of link::Classes/Environment::. The link::Classes/Environment:: to be used by the interpreter of the document window. By default, it is set to the current link::Classes/Environment::. discussion:: code:: Document.new("this is the title", "this is the text"); :: method:: open Open a document from a path. argument:: path The file system path to the document. An instance of link::Classes/String::. argument:: selectionStart The beginning of the cursor selection of the file content. argument:: selectionLength The length of the cursor selection of the file content. argument:: envir An instance of link::Classes/Environment::. The Environment to be used by the interpreter of the document window. By default, it is set to the current link::Classes/Environment::. discussion:: code:: Document.open("README", 292,253); // notice the selected text in the open document :: method:: openDocuments Returns an Array of all open documents. code:: d = Document.openDocuments.do{ |doc| doc.name.postln }; :: method:: hasEditedDocuments Returns true if there are edited Documents. method:: closeAll warning:: Closes all open Documents, whether edited or not. :: argument:: leavePostWindowOpen An instance of link::Classes/Boolean::. method:: closeAllUnedited Closes all unedited Documents. argument:: leavePostWindowOpen An instance of link::Classes/Boolean::. method:: current Gets/sets the current Document. argument:: value A Document. discussion:: code:: Document.current.name.postln; // Prints "Document.html" :: method:: allDocuments Returns all documents. method:: globalKeyDownAction Get/set A global action to be performed when a key is pressed. argument:: action An instance of link::Classes/Function:: or link::Classes/FunctionList::. method:: globalKeyUpAction Get/set A global action to be performed when a key is released. argument:: action An instance of link::Classes/Function:: or link::Classes/FunctionList::. method:: initAction Get/set A an action to be performed up opening or creating a Document. argument:: action An instance of link::Classes/Function:: or link::Classes/FunctionList::. method:: autoRun If a document begins with the link::Classes/String::, code::"/*RUN*/"::, then the code following it int he file will be executed on opening the file, if autorun is set to true. argument:: value An instance of link::Classes/Boolean::. Default value is code::true::. method:: implementationClass The editor implementation specific class which will handle Documents. argument:: value A class for implementing Document. subsection:: Path Utilities Utilities and settings for dealing with documents such as SuperCollider code files. By default the document directory is SuperCollider's application directory. method:: dir Get/set the default document directory. The default is dependent on link::Classes/Document#implementationClass::. argument:: path The file system path to the directory. An instance of link::Classes/String::. discussion:: In Main-startUp you can set this to a more practical directory: code:: Document.dir = "~/Documents/SuperCollider"; :: method:: standardizePath argument:: p The file system path to the directory. An instance of link::Classes/String::. discussion:: If it is a relative path, expand it to an absolute path relative to your document directory. Expand tildes in path (your home directory), resolve symbolic links (but not aliases). Also converts from Mac OS 9 path format. See PathName for more complex needs. code:: Document.standardizePath("~/"); // This will print your home directory Document.standardizePath(":Patches:newfoots:fastRuckAndTuck"); // Returns: /Volumes/Macintosh HD/Users/cruxxial/Documents/SC3docs/Patches/newfoots/fastRuckAndTuck Document.standardizePath("~/Documents/SC3docs/Patches/newfoots/fastRuckAndTuck"); // Returns: Patches/newfoots/fastRuckAndTuck Document.standardizePath("Patches/newfoots/fastRuckAndTuck") // Returns: Patches/newfoots/fastRuckAndTuck :: method:: abrevPath Returns a path relative to Document.dir, if the path is inside Document.dir. argument:: path The file system path to the directory. An instance of link::Classes/String::. instancemethods:: private:: prGetBackgroundColor, prGetBounds, prIsEditable, propen, prGetTitle, prinitByString, prGetLastIndex, prSetBackgroundColor, prSetFileName, prUsesAutoInOutdent, prclose, prGetSelectedBackgroundColor, prGetFileName, prSetSelectedBackgroundColor, prSelectLine, prinitByIndex, prAdd, prSetBounds, prinsertText, prSetTitle, initFromPath, initByString subsection:: General Document Properties method:: path Get / set the the Document's path. argument:: apath An instance of link::Classes/String::. A files system path. discussion:: code:: Document.current.path.postln; :: method:: dir Returns the directory of a Document. discussion:: code:: Document.current.dir.postln; :: method:: == A binary operator. argument:: that An instance of Document. discussion:: code:: Document.current == Document.listener; // presumably returns false :: method:: editable Get / set the the document is editable. argument:: bool An instance of link::Classes/Boolean::. method:: name Get / set the title (same as link::Classes/Document#title::). argument:: aname An instance of link::Classes/String::. discussion:: code:: Document.current.name.postln; :: method:: title Get / set the title (same as link::Classes/Document#name::). argument:: newTitle An instance of link::Classes/String::. method:: promptToSave Get/set whether a document is prompts to save if it has been changed. Use this with caution. argument:: bool An instance of link::Classes/Boolean::. method:: closed Returns code::true:: if the document has been closed. method:: isEdited Returns code::true:: if the document has been edited. code:: Document.current.isEdited.postln; :: method:: isFront Returns code::true:: if the document is in front. method:: didBecomeKey Saves the current link::Classes/Environment::, makes the document current, and performs its link::Classes/Document#toFrontAction::. method:: didResignKey Performs the Document's link::Classes/Document#endFrontAction:: and restores the current link::Classes/Environment::. subsection:: Controlling Document method:: close Close a document. code:: ( Task({ var doc; doc = Document("background", "closing in 2 seconds"); doc.stringColor_(Color.blue); 1.wait; doc.background_(Color.blue(alpha:0.8)); 1.wait; doc.close; }).play(AppClock); ) :: method:: front Bring a document to the front. code:: Document.listener.front; :: method:: onClose Get/set the action to be performed on closing the document. argument:: value An instance of link::Classes/Function:: or link::Classes/FunctionList::. method:: endFrontAction Get/set the action to be performed when the document becomes no longer the front document. argument:: value An instance of link::Classes/Function:: or link::Classes/FunctionList::. method:: toFrontAction Get / set the action to be performed when the document become the front document. argument:: value An instance of link::Classes/Function:: or link::Classes/FunctionList::. method:: mouseDownAction Get/set the action to be performed on link::Classes/Document#mouseDown::. argument:: action An instance of link::Classes/Function:: or link::Classes/FunctionList::. The arguments passed to the function are: code::document::, code::x::, code::y::, code::modifiers::, code::buttonNumber::, code::clickCount::, code::clickPos::. method:: mouseUpAction Get/set the action to be performed on link::Classes/Document#mouseUp::. argument:: action An instance of link::Classes/Function:: or link::Classes/FunctionList::. The arguments passed to the function are: code::document::, code::x::, code::y::, code::modifiers::, code::buttonNumber::, code::clickCount::, code::clickPos::. discussion:: code:: ( //add a mouse action to this document: //example: easy button: //when you click in front of a 17 a SinOsc will start up; s.waitForBoot({ Document.current.mouseUpAction_({arg doc; var char; char = doc.rangeText(doc.selectionStart, 2); if(char == "17",{ {EnvGen.kr(Env.perc, doneAction: Done.freeSelf) * SinOsc.ar([600,720,300].choose, 0, 0.5)}.play; }); if(char == "23",{ {EnvGen.kr(Env.perc, doneAction: Done.freeSelf) * PinkNoise.ar(0.2)}.play; }); }) }); ) :: Test here and click in front of the numbers: 17 and 23. code:: Document.current.mouseUpAction = nil; // clear mouseUpActiont :: method:: keyDownAction Get/set the action to be performed on link::Classes/Document#keyDown::. argument:: action An instance of link::Classes/Function:: or link::Classes/FunctionList::. The arguments passed to the function are: code::document::, code::char::, code::modifiers::, code::unicode::, code::keycode::. See link::Classes/View#Key actions:: for details on these arguments. discussion:: code:: Document.current.keyDownAction = { arg ...args; args.postln }; // now type some text Document.current.keyDownAction = nil; :: method:: keyUpAction Get/set the action to be performed on link::Classes/Document#keyUp::. argument:: action An instance of link::Classes/Function:: or link::Classes/FunctionList::. The arguments passed to the function are: code::document::, code::char::, code::modifiers::, code::unicode::, code::keycode::. See link::Classes/View#Key actions:: for details on these arguments. discussion:: code:: Document.current.keyUpAction = { arg ...args; args.postln }; // now type some text Document.current.keyUpAction = nil; :: subsection:: Editing Content method:: selectLine Select a line of the document by number. argument:: line An link::Classes/Integer::. discussion:: code:: Document.current.selectLine(390); :: method:: selectRange Select a text range in the string of the document. argument:: start The start index. argument:: length The length of the selection. discussion:: code:: ( Document.current.selectRange(Document.current.selectedRangeLocation + 3, 150); ) :: method:: selectionStart Returns the start of a current selection. code:: Document.current.selectionStart.postln; :: method:: selectionSize Returns the size of a current selection. code:: ( var doc; doc = Document.current; doc.selectRange(doc.selectionStart - 40, 10); doc.selectionSize.postln; ) :: method:: selectedString Gets/sets the selected string. argument:: txt An instance of link::Classes/String::. discussion:: code:: ( var doc; doc = Document.current; doc.selectRange(doc.selectionStart - 40, 10); doc.selectedString.postln; ) :: method:: currentLine Returns the current line as a link::Classes/String::. code:: ( var doc; doc = Document.current; doc.selectRange(doc.selectionStart - 40, 10); doc.currentLine.postln; ) :: method:: getSelectedLines Returns all full lines from before code::rangestart:: to after code::rangestart + rangesize:: as a link::Classes/String::. discussion:: code:: ( var doc; doc = Document.current; doc.selectRange(doc.selectionStart - 40, 10); doc.getSelectedLines(doc.selectionStart - 40, 130).postln; ) :: method:: string Gets or sets the string within a certain range. argument:: string A link::Classes/String::. argument:: rangestart An link::Classes/Integer::. argument:: rangesize An link::Classes/Integer::. discussion:: code:: // Select the following code in parentheses and execute it ( Document.current.string_(": test test test test test ", Document.current.selectedRangeLocation + 12, 18); ) // Watch me change content :: subsection:: Subclassing and Internal Methods The following methods are usually not used directly or are called by a primitive. Programmers can still call or override these as needed. code:: *startup *numberOfOpen mouseUp (x, y, modifiers, buttonNumber, clickCount, clickPos) keyDown (character, modifiers, unicode, keycode) keyUp (character, modifiers, unicode, keycode) getIdentifierCoordFromEnd (endPos) dataptr Private. Used only internally: *newFromIndex (idx) *prnumberOfOpen *prGetLast *prGetIndexOfListener *prBasicNew prAdd prGetLastIndex setFont (font, rangeStart, rangeSize) setTextColor (color, rangeStart, rangeSize) propen (path, selectionStart, selectionLength) rangeText (rangestart, rangesize) insertTextRange (string, rangestart, rangesize) prinitByString (title, str, makeListener) prSetBackgroundColor (color) prGetBackgroundColor (color) prSelectLine (line) prIsEditable_ (editable) prSetTitle (argName) prGetTitle prGetFileName prSetFileName (apath) prGetBounds (argBounds) prSetBounds (argBounds) prclose prinsertText (dataPtr, txt) prinitByIndex (idx) envir envir_ (ev) text removeUndo selectedText selectUnderlinedText (clickPos) linkAtClickPos (clickPos) selectedRangeLocation selectedRangeSize restoreCurrentEnvironment saveCurrentEnvironment initByIndex (idx) initLast initFromPath (path, selectionStart, selectionLength) initByString (argTitle, str, makeListener) :: examples:: code:: //unfocusedFront_ ( Document.allDocuments.at(0).unfocusedFront ) ( var doc; doc = Document("", "||"); doc.background_(Color.blue(alpha: 1.0.rand)); Task({ 1000.do({ doc.setFont(rangeSize: [7, 8, 9, 24].choose); 0.08.wait; }) }).play(AppClock); Task({ 100.do({ 1.01.wait; doc.stringColor_([Color.red(alpha: 1.0.rand), Color.green(alpha: 1.0.rand)].choose); }) }).play(AppClock); Task({ 100.do({ 1.01.wait; doc.selectedString_(["\"\n#", "||", "-", "--"].choose); }) }).play(AppClock); Task({ var co, mul; co = 0.1; mul = 1.02; 100.do({ 0.16.wait; co = co * mul; if(co > 0.99, { co = 0.1 }); doc.background_(Color.blue(alpha: co)); }); doc.close; }).play(AppClock) ) :: A simple implementation of TBT (time based text) http://tbt.dyne.org/?info=download code:: // record: type some text ( var time = Main.elapsedTime; a = List.new; r = Routine { |char| loop { a = a.add([char, Main.elapsedTime - time]); char = 0.yield; } }; Document.new("type some text") .bounds_(Rect(100,SCWindow.screenBounds.height - 250, 400, 200)) .keyDownAction = { |doc, key| r.value(key) ; time = Main.elapsedTime}; ) // play back text in time ( d = Document.new("type some text") .bounds_(Rect(550,SCWindow.screenBounds.height-250,400,200)); fork({ a.do { |pair| d.string = d.string ++ pair[0]; pair[1].wait; } }, AppClock) ) :: Changing the default look of documents can be done with the help of the link::#*initAction:: method. Run the following example once. Afterwards all newly created documents will have a dark grey background. To make this change happen every time you start SuperCollider, put the code inside your startup.scd file (and optionally wrap it in a code::{}.defer(0.1):: ). code:: ( Document.listener.background = Color.red; //a special color for post document Document.listener.bounds = Rect(1, 461, 620, 567); //move and resize post document Document.initAction = {|doc| //function to run for every new document doc.background = Color.grey(0.1, 0.9); doc.bounds = Rect(0, 119, 1280, 659); doc.selectedBackground = Color(0.4, 0.05, 0.18); doc.stringColor = Color.grey(0.9); }; ) ::