class:: Document
redirect:: implementationClass
summary:: An abstract class for editor-specific text document editing classes
categories:: Frontends
related:: Classes/CocoaDocument, 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. While it is an abstract class, you still use it to create a code::new:: Document. It simply passes on code::new:: to the appropriate document implementation, e.g. link::Classes/CocoaDocument::.

subsection:: 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 code::Document.new:: or code::Document.open:: are actually passed down to the relevant class for the editor you're using, such as link::Classes/CocoaDocument:: (for most Mac users) or link::Classes/ScelDocument:: (containing an link::Classes/EmacsDocument::).

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:: makeListener
Makes this document the listener, i.e. the place where SC-lang posts messages.
argument:: envir
An instance of link::Classes/Environment::. The link::Classes/Environment:: to be used by the interpreter of the document window. By defualt, 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 defualt, 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:: listener
Returns the current Document which is the listener, i.e. the Document where interpreter messages are posted.

method:: allDocuments
Returns all documents.

method:: globalKeyDownAction
Get/set A global action to be performed when a key is pressed.
argument:: value
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:: value
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:: value
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 exectued 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, e.g. link::Classes/CocoaDocument::.

subsection:: Path Utilities

Utilities and settings for dealing with documents such as super collider 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 OS9 macintosh 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:: bounds
Get/set the bounds of the document.
argument:: argBounds
An instance of link::Classes/Rect::.

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:: doc
An instance of Document.
discussion::
code::
Document.current == Document.listener; // presumaably returns false
::

method:: editable
Get / set the the document is editable.
argument:: abool
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:: argName
An instance of link::Classes/String::.

method:: alwaysOnTop
Get/set whether a document is always on top.
argument:: boolean
An instance of link::Classes/Boolean::.

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:: isListener
Returns if the document is the listener.

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:: unfocusedFront
Bring a document to the front without focusing it.
code::
Document.listener.unfocusedFront;
::

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::.
note::
The Mac OSX built-in editor does not supports this feature. A mouseDownAction that you supply will be ignored.
::
argument:: value
An instance of link::Classes/Function:: or link::Classes/FunctionList::. The arguments passed to the function are: 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:: value
An instance of link::Classes/Function:: or link::Classes/FunctionList::. The arguments passed to the function are: 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: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 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:: value
An instance of link::Classes/Function:: or link::Classes/FunctionList::. The arguments passed to the function are: code::char::, code::modifiers::, code::unicode::, code::keycode::.
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:: value
An instance of link::Classes/Function:: or link::Classes/FunctionList::. The arguments passed to the function are: code::char::, code::modifiers::, code::unicode::, code::keycode::.
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
::

method:: font
Gets or sets the font within a certain range.
argument:: font
An instance of link::Classes/Font::.
argument:: rangestart
An link::Classes/Integer::. Default value is -1. If code::rangestart = -1::, the whole document is selected.
argument:: rangesize
An link::Classes/Integer::. Default value is 0.
discussion::
code::
// Select the following code in parentheses and execute it
(
Document.current.font_(Font("Impact", 14),
	Document.current.selectedRangeLocation + 12,
	18);
)
// Watch me change font
::

method:: underlineSelection
Underlines the current selection of a Document.


subsection:: Auto-Completion

note::
OSX version only, currently. See link::Reference/DocumentAutoCompletion::.
::
code::
	*allowAutoComp
	*autoCompAll
	*autoComplete
	*autoCompleteKeyAction
	*openFileAutoComplete (path)
	*openAutoComplete
	autoComplete
::

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