Document:
Filter:
Classes | Frontends

Document : Object

Editor-specific text document editing
Source: ScIDE.sc
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:

Document.openDocuments

From implementing class

Returns an Array of all open documents.

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 Document: 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.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.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.closeAllHelp

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

Document.closeNoPath

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

Document.closeObsolete

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

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

Document.wordBins(docs, minLengthOfWords: 2, stopList)

From extension in /home/stefan/.local/share/SuperCollider/downloaded-quarks/lfsaw.de/wordBins.sc

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 Document: title).

Arguments:

aname

An instance of String.

Discussion:

.title

.title = newTitle

From implementing class

Get / set the title (same as Document: 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.

.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 Document: toFrontAction.

.didResignKey

From implementing class

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

Controlling Document

.close

From implementing class

Close a document.

.front

From implementing class

Bring a document to the 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 Document: 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 Document: 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.

.keyDownAction

.keyDownAction = action

From implementing class

Get/set the action to be performed on Document: 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 Document: 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.

.selectionSize

From implementing class

Returns the size of a current selection.

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

.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, Document: -getText and Document: -string may be unreliable. Windows users are recommended to use Document: -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.

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

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