HelpSource/Reference/DocumentAutoCompletion.schelp

   1 title:: Document Autocompletion
   2 categories:: OSX, Frontends
   3 summary:: SuperCollider autocompletion on OSX
   4
   5 The autocompletion feature described in this document is available in the OSX version only. It uses the keyDownAction feature of link::Classes/CocoaDocument:: to intercept keystrokes and open the autocompletion interface when specific characters are typed. That feature is not available in all platforms.
   6
   7 The SCEL interface in Linux has its own autocompletion function, accessed by typing <ESC> <TAB>.
   8
   9 Autocompletion is not available in the Windows version as of this writing.
  10
  11 Another way to get information about classes and methods is the class browser, accessed by calling code::.browse:: on a class, e.g. code::Object.browse::. The browser is available in the OSX version, as well as any platform where link::Classes/SwingOSC:: (http://www.sciss.de/swingOSC) is installed.
  12
  13 section:: Usage
  14
  15 To open a text window with the auto-complete feature enabled, execute the following in SuperCollider:
  16 code::
  17 Document.autoComplete
  18 ::
  19
  20 (ac is a shortcut for Auto-complete, to make it easier to type.)
  21
  22 To open a file by pathname:
  23 code::
  24 Document.openFileAutoComplete("myPath.rtf");
  25 Document.openFileAutoComplete("*.sc");  // wildcards are supported
  26 ::
  27
  28 To bring up an open-file dialog:
  29 code::
  30 Document.openAutoComplete
  31 ::
  32
  33 Autocompletion will be integrated more tightly into the code editor.
  34
  35
  36
  37 section:: Summary
  38
  39 While editing code in an auto-complete code window, the following keystrokes initiate special actions:
  40
  41 table::
  42 ## ( || Attempt to match the preceding identifier to method names containing that string, and display a list of methods with their defining classes. Making a selection will insert a method template into your document. "(" Will also match classnames, with the code::.new:: method: code::Rect(:: will show you a method template for Rect-*new.
  43
  44 ## . || Attempt to match the preceding identifier to an exact class name, and present a list of class methods (not instance methods). Your selection will insert a method template into the document.
  45
  46 ## CTRL-. || attempt to match the preceding identifier to class names containing the identifier, and present a list of those class names. Your selection will open a class browser. You can navigate through the class tree to find the method you want, and press enter in the method list to insert a method template.
  47
  48 ## Shortcut in the class browser || Type "^" in the method list to go to the superclass. This allows speedier location of methods inherited from superclasses.
  49
  50 ## Special behavior for CTRL-. || When you choose a method in a class browser, its class will be compared to the class you chose in the opening list. If the initial class responds to the method, the initial class will be put into the document; otherwise, the class from the class browser.
  51 ::
  52
  53
  54
  55 section:: Feature description
  56
  57 When you type a dot, SuperCollider will to check the previous text to see if it refers to a valid class. If so, a window will be presented with all the class methods (not instance methods) of the class.
  58
  59 So, for example, if you type:
  60 code::
  61 SinOsc.
  62 ::
  63
  64 the window will display the options:
  65 code::
  66 ar(freq, phase, mul, add)
  67 buildSynthDef()
  68 buildSynthDef_()
  69 ....
  70 ::
  71
  72 If you type the first few letters into the text box, the list will reduce itself to the matching entries. If you type 'a', then the list will contain only:
  73 code::
  74 ar(freq, phase, mul, add)
  75 ::
  76
  77 Press enter or return, and the method name with all its arguments will be added to your document, leaving the text:
  78 code::
  79 SinOsc.ar(freq, phase, mul, add)
  80 ::
  81
  82 You can also click on the item you want in the list (or move through the list with the up and down arrow keys), and then press return.
  83
  84 Pressing escape or closing the window will cancel the auto-complete. Text typed into the text box prior to canceling will be added to the document--so, if you keep typing while the box comes up and you want to ignore it, your text will not be lost.
  85
  86 Similar behavior for method names: when you type an open parenthesis '(', SuperCollider will display a list of all classes that define this method. Type the first few letters of the class name (don't forget to capitalize) to choose the right one.
  87
  88 This treatment is necessary because variables in SuperCollider are not typed. If you enter 'func.value(', the text editor has no way to know what kind of object will be contained in func at the time of execution. So, it presents you with all possible options and allows you to choose.
  89
  90 note::
  91 strong::New::: The autocompleter now supports partial string matching for methods (triggered by typing open-paren) and classes (not by typing dot, but by typing ctrl-dot). In the case of classes, you will be given a list of classes matching the string typed. After you choose from the list, a full class browser will be opened. When you select a method and press enter, a method template will be dropped into the current document.
  92 ::
  93
  94 Because the class browser does not show methods defined by superclasses, you may press ^ to go to the superclass.
  95
  96
  97
  98 section:: Further configuration
  99
 100 Use the startup file (see link::Guides/Using-the-Startup-File::) to define class names and method names to be excluded from the browsers. I like to exclude the most common flow of control mechanisms (code::while::, code::do::, code::if::, etc.).
 101 code::
 102 AutoCompMethodBrowser.exclude([\if, \do, \while, \loop, \collect, \select, \reject, \detect, \add, \put, \at]);
 103 AutoCompClassBrowser.exclude([... list of classes ...]);
 104 ::
 105
 106
 107
 108 section:: Quirks and caveats
 109
 110 The auto complete features will be lost from all documents when recompiling the class library.
 111
 112 The method browser does not handle inheritance. If you're browsing a method like code::add::, you won't find link::Classes/Array:: in the list (but you will find its superclass link::Classes/ArrayedCollection::).