rsc3/doc-schelp/HelpSource/Classes/Document.schelp

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