Document | SuperCollider 3.14.0-dev Help

Implementing class: 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

Document.new(title: "untitled", string: "", envir)

From implementing class

Arguments:

title	An instance of String or Symbol.
string	An instance of String. The contents of the document.
envir	An instance of Environment. The Environment to be used by the interpreter of the document window. By default, it is set to the current Environment.

Discussion:

Document.open(path, selectionStart: 0, selectionLength: 0, envir)

From implementing class

Open a document from a path.

Arguments:

path	The file system path to the document. An instance of String.
selectionStart	The beginning of the cursor selection of the file content.
selectionLength	The length of the cursor selection of the file content.
envir	An instance of Environment. The Environment to be used by the interpreter of the document window. By default, it is set to the current Environment.

Discussion:

See also Document: save below.Document.open("README", 292,253); // notice the selected text in the open document

Document.openDocuments

From implementing class

Returns an Array of all open documents.d = Document.openDocuments.do{ |doc| doc.name.postln };

Document.hasEditedDocuments

From implementing class

Returns true if there are edited Documents.

Document.closeAll

From implementing class

WARNING: Closes all open Documents, whether edited or not.

Arguments:

(leavePostWindowOpen)

An instance of Boolean.

Document.closeAllUnedited

From implementing class

Closes all unedited Documents.

Arguments:

(leavePostWindowOpen)

An instance of Boolean.

Document.current

Document.current = value

From implementing class

Gets/sets the current Document.

Arguments:

(value)

A Document.

Discussion:

Document.allDocuments

From implementing class

Returns all documents.

Document.globalKeyDownAction

Document.globalKeyDownAction = action

From implementing class

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

Arguments:

action

An instance of Function or FunctionList.

Document.globalKeyUpAction

Document.globalKeyUpAction = action

From implementing class

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

Arguments:

action

An instance of Function or FunctionList.

Document.initAction

Document.initAction = value

From implementing class

Get/set A an action to be performed up opening or creating a Document.

Arguments:

(action)

An instance of Function or FunctionList.

Document.autoRun

Document.autoRun = value

From implementing class

If autoRun is set to true, documents beginning with the comment /*RUN*/ will be executed immediately after being opened, and also when the class library is recompiled with the document already open in the IDE.

Arguments:

(value)

An instance of Boolean. Default value is true.

Document.implementationClass

From implementing class

The editor implementation specific class which will handle Documents.

Arguments:

(value)

A class for implementing Document.

Path Utilities

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

Document.dir

Document.dir = path

From implementing class

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

Arguments:

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

Discussion:

In Main-startUp you can set this to a more practical directory:Document.dir = "~/Documents/SuperCollider";

Document.standardizePath(p)

From implementing class

Arguments:

p	The file system path to the directory. An instance of 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.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

Document.abrevPath(path)

From implementing class

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

Arguments:

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

Inherited class methods

Undocumented class methods

Document.asyncActions

From implementing class

Document.executeAsyncResponse(funcID ... args)

From implementing class

Document.findByQUuid(quuid)

From implementing class

Document.makeCleanerWindow

From extension in /home/stefan/.local/share/SuperCollider/downloaded-quarks/adclib/Classes/GUI/extStringCleaning.sc

Document.openStartup

From extension in /home/stefan/.local/share/SuperCollider/downloaded-quarks/wslib/wslib-classes/Lang/Workflow/extDocument-openStartup.sc

Document.prCurrent = newCurrent

From implementing class

Document.setActiveDocByQUuid(quuid)

From implementing class

Document.syncDocs(docInfo)

From implementing class

Document.syncFromIDE(quuid, title, chars, isEdited, path, selStart, selSize)

From implementing class

Instance Methods

General Document Properties

.path

.path = apath

From implementing class

Get / set the Document's path.

Arguments:

apath

An instance of String. A files system path.

Discussion:

.dir

From implementing class

Returns the directory of a Document.

Discussion:

==(that)

From implementing class

A binary operator.

Arguments:

that	An instance of Document.

Discussion:

.editable

.editable = bool: true

From implementing class

Get / set the document is editable.

Arguments:

bool	An instance of Boolean.

.name

.name = aname

From implementing class

Get / set the title (same as -title).

Arguments:

aname

An instance of String.

Discussion:

.title

.title = newTitle

From implementing class

Get / set the title (same as -name).

Arguments:

newTitle

An instance of String.

.promptToSave

.promptToSave = bool

From implementing class

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

Arguments:

bool	An instance of Boolean.

.closed

From implementing class

Returns true if the document has been closed.

.isEdited

From implementing class

Returns true if the document has been edited.Document.current.isEdited.postln;

.isFront

From implementing class

Returns true if the document is in front.

.didBecomeKey

From implementing class

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

.didResignKey

From implementing class

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

Controlling Document

.close

From implementing class

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

.save(docPath)

From implementing class

Save this Document.

Arguments:

path

An optional instance of String indicating the path to save the Document. If a path is not provided, the current path (if it has been previously saved or read) is used. After a successful save, this Document's path will be updated if needed. See also Document: *open above.d = Document.new("testSave", "foo"); d.save(Platform.defaultTempDir ++ "foo.scd"); // saved in the temp dir d.string_("foobar", 0, 3); d.save; // save at previous path d.string_("save as now", 0, 6); d.save(Platform.defaultTempDir ++ "savedAs.scd"); d.path;

.front

From implementing class

Bring a document to the front.Document.listener.front;

.onClose

.onClose = value

From implementing class

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

Arguments:

(value)

An instance of Function or FunctionList.

.endFrontAction

.endFrontAction = value

From implementing class

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

Arguments:

(value)

An instance of Function or FunctionList.

.toFrontAction

.toFrontAction = value

From implementing class

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

Arguments:

(value)

An instance of Function or FunctionList.

.mouseDownAction

.mouseDownAction = action

From implementing class

Get/set the action to be performed on -mouseDown.

Arguments:

action

An instance of Function or FunctionList. The arguments passed to the function are: document, x, y, modifiers, buttonNumber, clickCount.

.mouseUpAction

.mouseUpAction = action

From implementing class

Get/set the action to be performed on -mouseUp.

Arguments:

action

An instance of Function or FunctionList. The arguments passed to the function are: document, x, y, modifiers, buttonNumber.

Discussion:

Test here and click in front of the numbers: 17 and 23.Document.current.mouseUpAction = nil; // clear mouseUpAction

.keyDownAction

.keyDownAction = action

From implementing class

Get/set the action to be performed on -keyDown.

Arguments:

action

An instance of Function or FunctionList. The arguments passed to the function are: document, char, modifiers, unicode, keycode. See View: Key actions for details on these arguments.

Discussion:

.keyUpAction

.keyUpAction = action

From implementing class

Get/set the action to be performed on -keyUp.

Arguments:

action

An instance of Function or FunctionList. The arguments passed to the function are: document, char, modifiers, unicode, keycode. See View: Key actions for details on these arguments.

Discussion:

Accessing and Editing Content

.selectLine(line)

From implementing class

Select a line of the document by number.

Arguments:

line	An Integer.

Discussion:

.selectRange(start: 0, length: 0)

From implementing class

Select a text range in the string of the document.

Arguments:

start	The start index.
length	The length of the selection.

Discussion:

.selectionStart

From implementing class

Returns the start of a current selection.Document.current.selectionStart.postln;

.selectionSize

From implementing class

Returns the size of a current selection.( var doc; doc = Document.current; doc.selectRange(doc.selectionStart - 40, 10); doc.selectionSize.postln; )

.selectedString

.selectedString = txt

From implementing class

Gets/sets the selected string.

Arguments:

txt	An instance of String.

Discussion:

.currentLine

From implementing class

Returns the current line as a String.( var doc; doc = Document.current; doc.selectRange(doc.selectionStart - 40, 10); doc.currentLine.postln; )

.getSelectedLines(rangestart: -1, rangesize: 0)

From implementing class

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

Discussion:

.string

.string_(string, rangestart: -1, rangesize: 1)

From implementing class

Gets or sets the string within a certain range.

Arguments:

string	A String.
rangestart	An Integer.
rangesize	An Integer.

Discussion:

.getText(start: 0, range: -1)

From implementing class

Get a range of text from the document. Synchronous. The text is directly returned.

Arguments:

start	An Integer for the starting position to access.
range	An Integer for the number of characters to retrieve. -1 retrieves to the end of the document.

.getTextAsync(action, start: 0, range: -1)

From implementing class

Get a range of text from the document. Asynchronous. The text is passed to the action function as an argument.

NOTE: Currently, in Windows, -getText and -string may be unreliable. Windows users are recommended to use -getTextAsync for the time being.

Arguments:

action	A function to evaluate after the request is complete. It is passed one argument, a String, for the retrieved contents.
start	An Integer for the starting position to access.
range	An Integer for the number of characters to retrieve. -1 retrieves to the end of the document.

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)

Inherited instance methods

Undocumented instance methods

.clean(space: true)

From extension in /home/stefan/.local/share/SuperCollider/downloaded-quarks/adclib/Classes/GUI/extStringCleaning.sc

.envir

.envir = newEnvir

From implementing class

.getChar(index: 0)

From implementing class

.hasSavedPreviousEnvironment

From implementing class

.hash

From implementing class

.initFromIDE(id, argtitle, argstring, argisEdited, argPath, selStart, selSize)

From implementing class

.insertText(string, index: 0)

From implementing class

.keyDown(modifiers, unicode, keycode, key)

From implementing class

.keyUp(modifiers, unicode, keycode, key)

From implementing class

.mouseDown(x, y, modifiers, buttonNumber, clickCount)

From implementing class

.mouseUp(x, y, modifiers, buttonNumber)

From implementing class

.prGetSelectionRange(id)

From implementing class

.prGetSelectionStart(id)

From implementing class

.prGetTextFromMirror(id, start: 0, range: -1)

From implementing class

.prReadTextFromFile(path)

From implementing class

.prSetEdited(flag)

From implementing class

.prSetSelectionMirror(quuid, start, size)

From implementing class

.prSetText(text, action, start: 0, range: -1)

From implementing class

.prSetTextMirror(quuid, text, start, range)

From implementing class

.pushLinkedEnvironment

From implementing class

.quuid

From implementing class

.rangeText(rangestart: 0, rangesize: 1)

From implementing class

.removeUndo

From implementing class

.restorePreviousEnvironment

From implementing class

.savedEnvir

From implementing class

.setChar(char, index: 0)

From implementing class

.text

.text = string

From implementing class

.textChanged(index, numCharsRemoved, addedChars)

From implementing class

.textChangedAction

.textChangedAction = action

From implementing class

Examples

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

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

helpfile source: /usr/local/share/SuperCollider/HelpSource/Classes/Document.schelp
link::Classes/Document::

Document : Object

Document.new(title: "untitled", string: "", envir)

Arguments:

Discussion:

Document.open(path, selectionStart: 0, selectionLength: 0, envir)

Arguments:

Discussion:

Document.openDocuments

Document.hasEditedDocuments

Document.closeAll

Arguments:

Document.closeAllUnedited

Arguments:

Document.current

Document.current = value

Arguments:

Discussion:

Document.allDocuments

Document.globalKeyDownAction

Document.globalKeyDownAction = action

Arguments:

Document.globalKeyUpAction

Document.globalKeyUpAction = action

Arguments:

Document.initAction

Document.initAction = value

Arguments:

Document.autoRun

Document.autoRun = value

Arguments:

Document.implementationClass

Arguments:

Document.dir

Document.dir = path

Arguments:

Discussion:

Document.standardizePath(p)

Arguments:

Discussion:

Document.abrevPath(path)

Arguments:

Document.asyncActions

Document.closeAllHelp

Document.closeNoPath

Document.closeObsolete

Document.executeAsyncResponse(funcID ... args)

Document.findByQUuid(quuid)

Document.makeCleanerWindow

Document.openStartup

Document.prCurrent = newCurrent

Document.setActiveDocByQUuid(quuid)

Document.syncDocs(docInfo)

Document.syncFromIDE(quuid, title, chars, isEdited, path, selStart, selSize)

.path

.path = apath

Arguments:

Discussion:

.dir

Discussion:

==(that)

Arguments:

Discussion:

.editable

.editable = bool: true

Arguments:

.name

.name = aname

Arguments:

Discussion:

.title

.title = newTitle

Arguments:

.promptToSave

.promptToSave = bool

Arguments:

.closed

.isEdited

.isFront

.didBecomeKey

.didResignKey