Document an abstract class for editor-specific text document editing classes

Inherits from: Object

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. While it is an abstract class, you still use it to create a new Document. It simply passes on new to the appropriate document implementation, e.g. CocoaDocument.

See also: CocoaDocument

Some Important Issues Regarding Document

Different text-editing environments can be used with SuperCollider. Therefore Document is an abstract class, meaning it doesn't provide all the functionality itself, but relies on subclasses to complete the functionality. Calls to Document.new or Document.open are actually passed down to the relevant class for the editor you're using, such as CocoaDocument (for most Mac users) or ScelDocument (containing an EmacsDocument).

Setting the Environment

By defualt 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.

Creation / Class Methods

*new (title, string, makeListener, envir)

title - An instance of String or Symbol. Default value is "Untitled".

string - An instance of String . Default value is "". The contents of the document.

makeListener - Makes this document the lisenter, i.e. the place where SC-lang posts messages. Default value is false. .

envir - An instance of Environment. The Environment to be used by the interpreter of the document window. By defualt, it is set to the current Environment.

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

*open (path, selectionStart, selectionLength, envir)

Open a document from a path.

path - The file system path to the document. An instance of String.

selectionStart -The beginning of the cursor seleciton of the file content. Default value is 0.

selectionLength - The length of the cursor seleciton of the file content. Default value is 0.

envir - An instance of Environment. The Environment to be used by the interpreter of the document window. By defualt, it is set to the current Environment.

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

*openDocuments

Returns an Array of all open documents.

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

*hasEditedDocuments

Returns true if there are edited Documents.

*closeAll (leavePostWindowOpen)

CAUTION Closes all open Documents, whether edited or not.

leavePostWindowOpen - An instance of Boolean. Default is true.

*closeAllUnedited (leavePostWindowOpen)

Closes all unedtited Documents.

leavePostWindowOpen - An instance of Boolean. Default is true.

*current

*current_(arg1)

Gets/sets the current Document.

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

*listener

Returns the current Document which is the listener, i.e. the Document where interpreter messages are posted.

*storePostWin (path)

Stores the conteng of Document.listener.

path - The file system path. An instance of String.

*allDocuments

A class variable. Returns all documents

Default value is defaultValue.

*globalKeyDownAction

*globalKeyDownAction_(arg1)

A class variable. Get/set A global action to be performed when a key is pressed.

arg1 - An instance of Function or FunctionList.

*globalKeyUpAction

*globalKeyUpAction_(arg1)

A class variable. Get/set A global action to be performed when a key is released.

arg1 - An instance of Function or FunctionList.

*initAction

*initAction_(arg1)

A class variable. Get/set A an action to be performed up openning or creating a Document.

arg1 - An instance of Function or FunctionList.

*autoRun

*autoRun_

A class variable. If a document begins with the String, "/*RUN*/", then the code following it int he file will be exectued on opening the file, if autorun is set to true.

arg1 - An instance of Boolean. Default value is true.

*wikiBrowse

*wikiBrowse_(arg1)

A class variable. If set to true, underlining text will create a wiki link.

arg1 - An instance of Boolean. Default value is true.

*implementationClass

*implementationClass_(arg1)

A class variable. The editor implementation specific class which will handle Documents.

arg1 - A class for implementing Document, e.g. CocoaDocument

*setTheme(arg1)

Sets the theme for syntax colorization. The Document class has a preset theme called 'default',

which is set as follows (default SC colors):

themes = (

default: (

classColor: Color(0, 0, 0.75, 1),

textColor: Color(0, 0, 0, 1),

stringColor: Color(0.375, 0.375, 0.375, 1),

commentColor: Color(0.75, 0, 0, 1),

symbolColor: Color(0, 0.45, 0, 1),

numberColor: Color(0, 0, 0, 1)

)

);

If you want to have your own themes for syntax colorization, you need to put your color set into

Document.themes first (preferably in startup.rtf file) and call setTheme by giving it the name of

the theme you've added to "themes" earlier:

//putting a custom color theme into Document.themes

Document.themes.put

(\myTheme,

(

classColor: Color.new255(53, 74, 187),

textColor: Color.new255(0, 0, 0),

stringColor: Color.new255(96, 129, 158),

commentColor: Color.new255(206, 27, 28),

symbolColor: Color.new255(57, 154, 20),

numberColor: Color.new255(157, 80, 65)

)

);

//and then calling setTheme with the name:

Document.setTheme('myTheme');

//to see the current theme:

Document.theme;

You can switch to the default theme anytime by calling:

Document.setTheme('default');

Next time you invoke syntaxColorize, the color theme set by setTheme will be used for syntax

colorization. If you want to change the background color for the document window and selected

text, in order to make them fit with your syntax colorization theme, see the help for the "background" and "selectedBackground" methods for Document.

arg1 - A Symbol, defining the name of the theme that you've put into Document.themes.

Path Utilites

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

*dir

*dir_ (path)

Get/set the default document directory. The default is dependent on Document.implementationClass.

path - The file system path to the directory. An instance of String.

In Main-startUp you can set this to a more practical directory:

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

*wikiDir

*wikiDir_ (path)

Get/set the default wiki directory. The default is dependent on Document.implementationClass.

path - The file system path to the directory. An instance of String.

*standardizePath (p)

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 OS9 macintosh path format. See PathName for more complex needs.

path - The file system path to the directory. An instance of String.

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 (path)

Returns a path relative to Document.dir, if the path is inside Document.dir.

path - The file system path to the directory. An instance of String.

General Document Properties

bounds

bounds_ (argBounds)

Get/set the bounds of the document.

argBounds - an instance of Rect.

path

path_ (apath)

Get / set the the Document's path.

apath - An instance of String. A files system path.

Document.current.path.postln;

dir

Returns the directory of a Document.

Document.current.dir.postln;

== (doc)

A binary operator.

doc - An instance of Document.

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

editable

editable_(abool)

Get / set the the document is editable.

arg1 - An instance of Boolean.

name

name_ (aname)

title

title_ (argName)

Get / set the title.

aname/argName - An instance of String.

Document.current.name.postln

background

background_ (color)

Get / set the the Document's background color.

color - An instance of Color;

(

a = Document("background", "'hardly see anything");

a.background_(Color.blue(alpha:0.8)); // notice that alpha controlls th window transparency

)

postColor

postColor_ (color)

Get / set the listeners pen color.

color - An instance of Color;

Document.postColor; //returns current post color

Document.postColor_(Color.red);

Document.postColor_(Color.green);

Document.postColor_(Color.blue);

Document.postColor_(Color.black);

(

r = Routine({

10.do({

Document.postColor_(Color.rand);

"There is no blue without yellow and without orange.".postln;

0.5.rand.yield;

});

Document.postColor_(Color.black);

});

)

r.play;

r.stop;

alwaysOnTop

alwaysOnTop_ (boolean)

Get/set whether a document is always on top.

boolean - An instance of Boolean.

promptToSave

promptToSave_ (bool)

Get/set whether a document is prompts to save if it has been changed. Use this with caution.

bool - An instance of Boolean.

closed

Returns true if the document has been closed

isEdited

Returns true if the document has been edited.

Document.current.isEdited.postln;

isFront

Returns true if the document is in front.

isListener

Returns if the document is the listener.

didBecomeKey

Saves the current Environment, makes the document current, and performs its toFrontAction.

didResignKey

Performs the Document's endFrontAction and restores the current Environment.

Controlling Document

close

Close a document.

(

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

Bring a document to the front.

Document.listener.front

unfocusedFront

Bring a document to the forn without focusing it.

Document.listener.unfocusedFront

onClose

onClose_(arg1)

Get / set the action to be performed on closing the document.

arg1 - An instance of Function or FunctionList .

endFrontAction

endFrontAction_(arg1)

Get / set the action to be performed when the document becomes no longer the front document.

arg1 - An instance of Function or FunctionList .

toFrontAction

toFrontAction_(arg1)

Get / set the action to be performed when the document become the front document.

arg1 - An instance of Function or FunctionList .

mouseDownAction

mouseDownAction_(arg1)

mouseUpAction

mouseUpAction_(arg1)

Get / set the action to be performed on mouseDown or mouseUp.

Note: The Mac OSX built-in editor supports only mouseUpAction. A mouseDownAction that you supply will be ignored.

arg1 - An instance of Function or FunctionList The arguments passed to the function are.

x, y, modifiers, buttonNumber, clickCount, clickPos

(

//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:2) * SinOsc.ar([600,720,300].choose, 0, 0.5)}.play;

});

if(char == "23",{

{EnvGen.kr(Env.perc, doneAction:2) * PinkNoise.ar(0.2)}.play;

});

})

});

)

test here and click in front of the number:

17

23

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

keyDownAction

keyDownAction_(arg1)

keyUpAction

keyUpAction_(arg1)

Get / set the action to be performed on keyDown or keyUp.

arg1 - An instance of Function or FunctionList The arguments passed to the function are

char, modifiers, unicode,keycode

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

// now type some text

Document.current.keyDownAction=nil;

makeWikiPage (wikiWord, extension, directory)

Creates a wiki page .

wikiWord - An instance of String. The name of the document.

extension - An instance of String. The file extension. Default value is ".rtf".

directory - An instance of String. The directory in which to save the page.

Document.current.makeWikiPage("test1");

openWikiPage

Opens/creates a wiki page out of the currently selected text.

Editing Content

selectLine (line)

Select a line of the document by number.

line - An Integer.

Document.current.selectLine(390);

selectRange (start, length)

Select a text range in the string of the document

start -The start index.

length - The length of the seleciton.

(

Document.current.selectRange(Document.current.selectedRangeLocation+3,

150);

)

balanceParens (level)

Starting from the current selection, increase the selection

until matching parentheses are selected.

level - do this as many times to find ever wider brackets. Set to inf for outmost.

((((

Document.current.balanceParens(1);

Document.current.balanceParens(3);

Document.current.balanceParens(inf);

))))

selectionStart

Returns the start of a current selection.

Document.current.selectionStart.postln;

selectionSize

Returns the size of a current selection.

(

var doc;

doc = Document.current;

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

doc.selectionSize.postln;

)

selectedString_ (txt)

selectedString

Gets/sets the selected string.

txt - An instance of String.

(

var doc;

doc = Document.current;

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

doc.selectedString.postln;

)

currentLine

Returns the current line as a String.

(

var doc;

doc = Document.current;

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

doc.currentLine.postln;

)

getSelectedLines(rangestart, rangesize)

Returns all full lines from before rangestart to after rangestart + rangesize as a String.

(

var doc;

doc = Document.current;

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

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

)

string (rangestart, rangesize)

string_ (string, rangestart, rangesize)

Gets/sets the string within a certain range.

string - Explanation of string. Default value is nil. Other information.

rangestart - An integer. Default value is nil.

rangesize - An integer. Default value is 1.

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

font_ (font, rangestart, rangesize)

Gets/sets the font within a certain range.

font - An instance of Font.

rangestart - An integer. Default value is -1. If rangestart = -1, the whole document is selected.

rangesize - An integer. Default value is 0.

// Select the following code in parentheses and execute it

(

Document.current.font_(Font("Impact",14),

Document.current.selectedRangeLocation+12,

18);

)

// Watch me change font

stringColor

Gets the last color set with stringColor_.

stringColor_ (color, rangeStart, rangeSize)

Sets the string color of a specific range of already printed text. Default is the whole document.

To set the listener text color for posting, see: postColor

color - An instance of Color.

rangeStart - An Integer. Default is -1.

rangeSize - An Integer. Default value is 0

// Select the following code in parentheses and execute it

(

Document.current.stringColor_(Color.rand(0.2,0.8),

Document.current.selectedRangeLocation+13,

16);

)

// Watch me change color

selectedBackground

Gets the document's background color for selected text.

selectedBackground_ (color)

Sets the document's background color for selected text.

Applies to the whole document instance.

color - An instance of Color.

Document.current.selectedBackground; //returns default color

(

w = Document.new("Test", "Here is a selected text...");

w.selectedBackground_(Color.new255(120, 180, 110));

w.selectRange(10, 13);

)

syntaxColorize

Syntax colorize a document.

underlineSelection

Underlines the current selection of a Document.

Auto-Completion

OSX version only, currently. See DocumentAutoCompletion

*allowAutoComp

*autoCompAll

*autoComplete

*autoCompleteKeyAction

*openFileAutoComplete (path)

*openAutoComplete

autoComplete

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)

Examples

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

)