HelpSource/Classes/TextView.schelp

   1 CLASS:: TextView
   2 redirect:: implClass
   3 summary:: A view displaying editable formatted text
   4 categories:: GUI>Views
   5
   6 DESCRIPTION::
   7
   8 TextView consists of an area where strong::multi-line text:: can be typed in and edited.
   9
  10 Using the view's methods, the text can be formatted: different strong::font:: and strong::text color:: can be applied to parts of the text. Text can also be inserted, removed, and selected programmatically.
  11
  12 The view can strong::open text documents:: and load from them both strong::plain text::, as well as formatted text in strong::HTML::, although it can not save the text back to files. However, you can get the contents of the view using the link::#-string:: method and then implement saving on your own, but the -string method will only return plain text, regardless of how the contents of the view are formatted.
  13
  14 note:: strong::Cocoa GUI:: can also load files in the strong::Rich Text Format::. ::
  15
  16 CLASSMETHODS::
  17
  18 PRIVATE:: key
  19
  20
  21
  22 INSTANCEMETHODS::
  23
  24 SUBSECTION:: Text and Formatting
  25
  26 METHOD:: open
  27         Opens a file at code::path:: and loads text from it.
  28
  29         The file can be in plain text or HTML (or RTF, in Cocoa GUI) format. Note however that saving formatted text in the view is not supported.
  30
  31         If loading the text from the file succeeds, it will replace any current contents of the view.
  32
  33         argument:: path
  34                 A String.
  35
  36 METHOD:: string
  37         The entire displayed contents of the view, as plain text.
  38
  39         Setting this variable will replace any current contents of the view.
  40
  41         argument::
  42                 A String.
  43
  44 METHOD:: setString
  45         Inserts the code::string:: at code::rangeStart:: position, replacing code::rangeSize:: amount of following characters. If code::rangeSize:: is 0, the text will be inserted without any characters being removed.
  46
  47         argument:: string
  48                 A String - the text to insert.
  49         argument:: rangeStart
  50                 An Integer position within the text, in characters.
  51         argument:: rangeSize
  52                 An Integer amount of characters.
  53
  54 METHOD:: setFont
  55         Applies the code::font:: to code::rangeSize:: amount of characters following the code::rangeStart:: position.
  56
  57         argument:: font
  58                 A Font to apply to the desired range of text.
  59         argument:: rangeStart
  60                 An Integer position within the text, in characters.
  61         argument:: rangeSize
  62                 An Integer amount of characters.
  63
  64 METHOD:: setStringColor
  65         Applies the code::color:: to code::rangeSize:: amount of characters following the code::rangeStart:: position.
  66
  67         argument:: color
  68                 A Color to apply to the desired range of text.
  69         argument:: rangeStart
  70                 An Integer position within the text, in characters.
  71         argument:: rangeSize
  72                 An Integer amount of characters.
  73
  74 METHOD:: syntaxColorize
  75         Applies colors to text throughout the entire contents of the view, according to the SuperCollider language syntax highlighting scheme.
  76
  77
  78
  79
  80 SUBSECTION:: Text Selection
  81
  82 METHOD:: selectedString
  83         The plain text contained in the current selection.
  84
  85         argument::
  86                 A String. Setting this variable will replace text in the selection with the argument, or do nothing if there is no selection.
  87         returns::
  88                 A String. If no text is currently selected, an empty String is returned.
  89
  90
  91 METHOD:: selectionStart
  92         The starting position of the selection. If no text is selected this variable represents the cursor position.
  93
  94         returns::
  95                 An Integer position within the text, in characters.
  96
  97 METHOD:: selectionSize
  98         The size of the current selection.
  99
 100         returns::
 101                 An Integer amount of characters - 0 if no text is selected.
 102
 103 METHOD:: select
 104
 105         note:: Not available in strong::Cocoa GUI::. ::
 106
 107         Selects code::size:: amount of characters following the code::start:: position. The cursor will remain at the end of the new selection.
 108
 109         argument:: start
 110                 An Integer position within the text, in characters.
 111         argument:: size
 112                 An Integer amount of characters.
 113
 114
 115
 116
 117 SUBSECTION:: Appearance
 118
 119 METHOD:: font
 120         The default font of the entire text. This font applies to any text to which a font has not been applied using link::#-setFont::.
 121
 122         argument::
 123                 A Font.
 124
 125 METHOD:: stringColor
 126         The default color of the entire text. This color applies to any text to which a color has not been applied using link::#-setStringColor::.
 127
 128 METHOD:: tabWidth
 129         The width of tab characters as they are displayed.
 130
 131
 132
 133
 134 SUBSECTION:: Interaction
 135
 136 METHOD:: editable
 137         Whether the contents of the view are editable, i.e. the text can be typed in and deleted by the user.
 138
 139         argument::
 140                 A Boolean.
 141
 142 METHOD:: enterInterpretsSelection
 143         Whether the selection will be interpreted and invoked as SuperCollider code when Ctrl/Cmd/Shift + Enter key combination is pressed.
 144
 145         Defaults to code::false::.
 146
 147         argument::
 148                 A Boolean.
 149
 150 METHOD:: usesTabToFocusNextView
 151         Whether the tab key will - instead of inserting a tab character into the text - switch focus to the next view (as usual for other views).
 152
 153         Defaults to code::false::.
 154
 155         argument::
 156                 A Boolean.
 157
 158 METHOD:: hasHorizontalScroller
 159         Whether the horizontal scroller is shown.
 160
 161         Note that if link::#-autohidesScrollers:: is code::true:: the scroller may be hidden despite this variable being set to code::true::. Since the TextView typically wraps text into the next line when a line reaches the edge of the view, the horizontal scroller may never be shown, unless link::#-autohidesScrollers:: is code::false::.
 162
 163         Defaults to code::true::.
 164
 165         argument::
 166                 A Boolean.
 167
 168 METHOD:: hasVerticalScroller
 169         Whether the vertical scroller is shown.
 170
 171         Note that if link::#-autohidesScrollers:: is code::true:: the scroller may be hidden despite this variable being set to code::true::.
 172
 173         Defaults to code::true::.
 174
 175         argument::
 176                 A Boolean.
 177
 178 METHOD:: autohidesScrollers
 179         Whether each of the scrollers will be automatically hidden if there is no use for it, i.e. the content is not scrollable in the direction of the scroller.
 180
 181         If link::#-hasHorizontalScroller:: or link::#-hasVerticalScroller:: is code::false::, the respective scroller will always be hidden, regardless of this variable.
 182
 183         Defaults to code::true::.
 184
 185         argument::
 186                 A Boolean.
 187
 188
 189
 190 SUBSECTION:: Drag and Drop
 191
 192 note:: Default drag-and-drop behavior of TextView is not defined in standard SC methods (see link::Classes/View#subclassing::), but in the view implementation instead (except for link::#-defaultGetDrag:: in Qt GUI). It may or may not be overridable by adding your own handlers (see link::Classes/View#drag_and_drop::), depending on the GUI kit in use.
 193 ::
 194
 195 Dragging from TextView will give the selected text in a String as drag data, while dropping will accept any object and insert it link::Classes/Object#-asString#as String:: at the drop location.
 196
 197 You can also drag files from outside SuperCollider onto a TextView, and it will insert their URLs at the drop location.
 198
 199 METHOD:: defaultGetDrag
 200         note:: Only present in strong::Qt GUI:: ::
 201
 202         returns::
 203                 The link::#-selectedString::.
 204
 205
 206
 207 EXAMPLES::
 208
 209 code::
 210 (
 211 w = Window.new("Text View Example",Rect(100,Window.screenBounds.height-400, 520,300)).front;
 212 t = TextView(w.asView,Rect(10,10, 500,200))
 213     .focus(true);
 214 )
 215
 216 // Using the Window you just created, try these in succession, and test how the text view responds
 217 t.mouseUpAction_{|it, x, y, modifiers, buttonNumber, clickCount, pos| [pos].postln};
 218 t.autohidesScrollers_(false);
 219 t.hasVerticalScroller_(false);
 220 t.hasVerticalScroller_(true);
 221 t.hasHorizontalScroller_(false);
 222 t.hasHorizontalScroller_(true);
 223 t.autohidesScrollers_(true);
 224
 225 t.open("Help/GUI/Main-GUI/Button.html"); // load an html file
 226
 227 // selective editing and formatting
 228 t.setStringColor (Color.red, 5, 5);
 229 t.setFont (Font("Courier",12), 5, 10);
 230 t.setString ("\nA replacement String\n", 12, 6);
 231
 232 // compare with these methods, which change everything
 233 t.font_(Font("Courier",14));
 234 t.stringColor_(Color.blue);
 235 ::