Document

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 ScelDocument (which links to 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.

Setting the Environment

By default envir it is set to the current Environment. However, you can make it use its own Environment also. Thus, e.g., if you were to set the Environment variable ~myVar = 12 in the current Environment, you can create a new Document window in which that Environment variable is not set.

Class Methods

.new

Document.new("this is the title", "this is the text");

.open

xxxxxxxxxx

Document.open("README", 292,253); // notice the selected text in the open document

.openDocuments

xxxxxxxxxx

d = Document.openDocuments.do{ |doc| doc.name.postln };

.hasEditedDocuments

.closeAll

.closeAllUnedited

.current

xxxxxxxxxx

Document.current.name.postln; // Prints "Document.html"

.allDocuments

.globalKeyDownAction

.globalKeyUpAction

.initAction

.autoRun

.implementationClass

Path Utilities

Utilities and settings for dealing with documents such as SuperCollider code files. By default the document directory is SuperCollider's application directory.

.dir

xxxxxxxxxx

Document.dir = "~/Documents/SuperCollider";

.standardizePath

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

.abrevPath

Inherited class methods

Instance Methods

General Document Properties

.path

xxxxxxxxxx

Document.current.path.postln;

.dir

xxxxxxxxxx

Document.current.dir.postln;

==

xxxxxxxxxx

Document.current == Document.listener; // presumably returns false

.editable

.name

xxxxxxxxxx

Document.current.name.postln;

.title

.promptToSave

.closed

.isEdited

xxxxxxxxxx

Document.current.isEdited.postln;

.isFront

.didBecomeKey

.didResignKey

Controlling Document

.close

xxxxxxxxxx

(

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);

)

.front

xxxxxxxxxx

Document.listener.front;

.onClose

.endFrontAction

.toFrontAction

.mouseDownAction

.mouseUpAction

xxxxxxxxxx

(

​

//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;

        });

    })

});

)

xxxxxxxxxx

Document.current.mouseUpAction = nil; // clear mouseUpAction

.keyDownAction

xxxxxxxxxx

Document.current.keyDownAction = { arg ...args; args.postln };

// now type some text

Document.current.keyDownAction = nil;

.keyUpAction

xxxxxxxxxx

Document.current.keyUpAction = { arg ...args; args.postln };

// now type some text

Document.current.keyUpAction = nil;

Accessing and Editing Content

.selectLine

xxxxxxxxxx

Document.current.selectLine(390);

.selectRange

xxxxxxxxxx

(

Document.current.selectRange(Document.current.selectedRangeLocation + 3, 150);

)

.selectionStart

xxxxxxxxxx

Document.current.selectionStart.postln;

.selectionSize

xxxxxxxxxx

(

var doc;

doc = Document.current;

doc.selectRange(doc.selectionStart - 40, 10);

doc.selectionSize.postln;

)

.selectedString

xxxxxxxxxx

(

var doc;

doc = Document.current;

doc.selectRange(doc.selectionStart - 40, 10);

doc.selectedString.postln;

)

.currentLine

xxxxxxxxxx

(

var doc;

doc = Document.current;

doc.selectRange(doc.selectionStart - 40, 10);

doc.currentLine.postln;

)

.getSelectedLines

xxxxxxxxxx

(

var doc;

doc = Document.current;

doc.selectRange(doc.selectionStart - 40, 10);

doc.getSelectedLines(doc.selectionStart - 40, 130).postln;

)

.string

xxxxxxxxxx

// 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

.getText

.getTextAsync

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. *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)

xxxxxxxxxx

    *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)

Inherited instance methods

Examples

xxxxxxxxxx

//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// 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) )

xxxxxxxxxx

// 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 *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 {}.defer(0.1) ).( 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); }; )

xxxxxxxxxx

(

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);

};

)