ScriptDocument
Memory category | Instances |
---|
Member index 19
Removed member index 1
History | Member | |
---|---|---|
532 | GetNumLines(): int |
Description
A ScriptDocument instance is a proxy of the document of a Studio Script Editor. It's different from the LuaSourceContainer open in the editor in that it represents the ephemeral state of an open document, and its representation is in a format that's more suited for reading and editing code than executing it. In particular, ScriptDocument reflects any changes that have been made to the open script in Drafts Mode, which the source property doesn't.
The Script Editor itself exists and changes on a different thread than any DataModel, so the ScriptDocument replicates the open Script Editor, but it isn't the open editor. Because of the replication, there's sometimes a slight delay between changing the text in the editor and updating the ScriptDocument. The delay usually occurs because the DataModel is busy, and it's almost always extremely small, but it still exists.
The existence of a ScriptDocument indicates that a document is open in the Script Editor. All ScriptDocument instances have ScriptEditorService as its parent. Each instance adheres to the following encoding conventions:
- All text in ScriptDocument is UTF-8 encoded.
- All line indices are 1-indexed.
- All character indices are 1-indexed and count UTF-8 bytes, not graphemes, so the same warning from TextBox.CursorPosition applies: many Unicode characters take more than one byte.
- All ranges are inclusive of their start position and exclusive of their end position, so start == end implies an empty range.
All APIs for ScriptDocument are at Plugin level security.
History 32
- 649 Add MultiEditTextAsync
- 543 Add CloseAsync
- 541 Add ViewportChanged
- 541 Add GetViewport
- 540 Add RequestSetSelectionAsync
- 540 Add ForceSetSelectionAsync
- 538 Add HasSelectedText
- 538 Add GetSelectionStart
- 538 Add GetSelectionEnd
- 538 Add GetSelectedText
- 536 Change Parameters of GetText from (startLine: int = -1234567, startCharacter: int = -1234567, endLine: int = -1234567, endCharacter: int = -1234567) to (startLine: int? = nil, startCharacter: int? = nil, endLine: int? = nil, endCharacter: int? = nil)
- 536 Change Parameters of GetLine from (lineIndex: int = -1234567) to (lineIndex: int? = nil)
- 534 Add SelectionChanged
- 534 Add GetSelection
- 533 Change Parameters of EditTextAsync from (newText: string, startLine: int, startCharacter: int, endLine: int = -1, endCharacter: int = -1) to (newText: string, startLine: int, startCharacter: int, endLine: int, endCharacter: int)
- 532 Change Security of IsCommandBar from RobloxScriptSecurity to PluginSecurity
- 532 Change Parameters of GetText from () to (startLine: int = -1234567, startCharacter: int = -1234567, endLine: int = -1234567, endCharacter: int = -1234567)
- 532 Change Security of GetText from RobloxScriptSecurity to PluginSecurity
- 532 Change Security of GetScript from RobloxScriptSecurity to PluginSecurity
- 532 Remove GetNumLines
- 532 Add GetLineCount
- 532 Add GetLine
- 532 Change Security of EditTextAsync from RobloxScriptSecurity to PluginSecurity
- 531 Add IsCommandBar
- 531 Add GetInternalUri
- 531 Change ReturnType of EditTextAsync from bool to Tuple
- 531 Change Parameters of EditTextAsync from (newText: string, startLine: int, startCharacter: int, endLine: int, endCharacter: int) to (newText: string, startLine: int, startCharacter: int, endLine: int = -1, endCharacter: int = -1)
- 530 Add EditTextAsync
- 528 Add GetText
- 528 Add GetScript
- 528 Add GetNumLines
- 528 Add ScriptDocument
Members 19
CloseAsync
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
Tuple |
Requests that the editor associated with this document close. Yields the current thread until the editor responds to the request. If the function succeeds, it returns (true, nil). If the function fails, it returns (false, string) as a description of the problem.
This function can't close the command bar.
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
History 1
- 543 Add CloseAsync
EditTextAsync
Parameters (5) | ||
---|---|---|
newText | string | |
startLine | int | |
startCharacter | int | |
endLine | int | |
endCharacter | int | |
Returns (1) | ||
Tuple |
Replaces the text in the specified range from (startLine
, startColumn
)
to (endLine
, endColumn
) with newText
. If the range is empty, then
the function inserts the text at (startLine
, startColumn
). If the text
cursor is within the specified range, the cursor moves to the end position
of the edit. Otherwise, the text cursor doesn't move. This function yields
the current thread until it receives a reply from the editor about the
edit.
If the function succeeds, it returns (true
, nil
).
The function throws an error if:
- The range is invalid.
- The range would slice a unicode character, for example replace only some of the bytes of the unicode character.
- The
newText
itself contains invalid UTF-8.
If the function fails, it returns (false, string). The string is a
description of the problem. The most common failure type is a version
mismatch. This occurs when you try to call EditTextAsync
during the time
when the ScriptDocument is out of sync with the contents of the
editor. If this happens, you can retry the edit.
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
History 5
- 533 Change Parameters of EditTextAsync from (newText: string, startLine: int, startCharacter: int, endLine: int = -1, endCharacter: int = -1) to (newText: string, startLine: int, startCharacter: int, endLine: int, endCharacter: int)
- 532 Change Security of EditTextAsync from RobloxScriptSecurity to PluginSecurity
- 531 Change ReturnType of EditTextAsync from bool to Tuple
- 531 Change Parameters of EditTextAsync from (newText: string, startLine: int, startCharacter: int, endLine: int, endCharacter: int) to (newText: string, startLine: int, startCharacter: int, endLine: int = -1, endCharacter: int = -1)
- 530 Add EditTextAsync
ForceSetSelectionAsync
Parameters (4) | Default | |
---|---|---|
cursorLine | int | |
cursorCharacter | int | |
anchorLine | int? | nil |
anchorCharacter | int? | nil |
Returns (1) | ||
Tuple |
Asks the editor to set its cursor selection to the argument values. Both anchor arguments must be passed, or neither. If neither is passed, then they each default to being the same as the corresponding cursor argument. The editor might decline to update its cursor if the text content of the document has changed. Unlike ScriptDocument:RequestSetSelectionAsync(), the editor will not decline to move its cursor if the cursor has moved since the request was made. Returns (true, nil) if the cursor was updated, and (false, string) with an explanation string if it was not. Yields the current thread until the editor replies.
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
History 1
GetInternalUri
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
string |
Security | RobloxScriptSecurity |
---|---|
Thread safety | Unsafe |
History 1
- 531 Add GetInternalUri
GetLine
Parameters (1) | Default | |
---|---|---|
lineIndex | int? | nil |
Returns (1) | ||
string |
Returns the text of the specified line. When no argument is provided, returns the line of the current cursor position.
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
GetLineCount
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
int |
Returns the number of lines in the active document.
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
History 1
- 532 Add GetLineCount
GetScript
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
LuaSourceContainer |
Returns the underlying LuaSourceContainer instance, if one exists,
otherwise nil
.
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
GetSelectedText
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
string |
Gets the text selected in the editor, or an empty string if there is no selection.
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
History 1
- 538 Add GetSelectedText
GetSelection
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
Tuple |
Returns the last known selection of the Script Editor in the format:
CursorLine, CursorChar, AnchorLine, AnchorChar
. If the Script Editor has
no selection, CursorLine == AnchorLine
and CursorChar == AnchorChar
.
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
History 1
- 534 Add GetSelection
GetSelectionEnd
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
Tuple |
Gets the larger of the cursor position and anchor. If the editor has no selection, they are the same value.
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
History 1
- 538 Add GetSelectionEnd
GetSelectionStart
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
Tuple |
Gets the smaller of the cursor position and anchor. If the editor has no selection, they are the same value.
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
History 1
- 538 Add GetSelectionStart
GetText
Parameters (4) | Default | |
---|---|---|
startLine | int? | nil |
startCharacter | int? | nil |
endLine | int? | nil |
endCharacter | int? | nil |
Returns (1) | ||
string |
Returns text from the open editor. Must be called with 0, 2 or 4 arguments:
- If called with 0 arguments, gets the entire contents of the open editor.
- If called with 2 arguments, gets the text of the document starting at
(
startLine
,startColumn
). - If called with 4 arguments, gets the text of the document starting at
(
startLine
,startColumn
) and ending at (endLine
,endColumn
).
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
History 4
- 536 Change Parameters of GetText from (startLine: int = -1234567, startCharacter: int = -1234567, endLine: int = -1234567, endCharacter: int = -1234567) to (startLine: int? = nil, startCharacter: int? = nil, endLine: int? = nil, endCharacter: int? = nil)
- 532 Change Parameters of GetText from () to (startLine: int = -1234567, startCharacter: int = -1234567, endLine: int = -1234567, endCharacter: int = -1234567)
- 532 Change Security of GetText from RobloxScriptSecurity to PluginSecurity
- 528 Add GetText
GetViewport
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
Tuple |
Returns the currently displayed line numbers in the editor change. The editor displays the lines between startLine and endLine, inclusive. The first and last line might only display partially. For example, only the topmost pixel of the last line might be on screen. Furthermore, code folding might hide lines between startLine and endLine.
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
History 1
- 541 Add GetViewport
HasSelectedText
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
bool |
Returns whether or not the editor has any text selected.
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
History 1
- 538 Add HasSelectedText
IsCommandBar
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
bool |
Returns true if the ScriptDocument represents the Command bar. The command bar has special rules and limitations in this API:
- Studio creates the Command bar before running plugins, so it doesn't always fire the opened event, although it does close and reopen as Studio transitions between DataModels.
- You can't edit the Command bar with
EditTextAsync
for security reasons.
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
History 2
- 532 Change Security of IsCommandBar from RobloxScriptSecurity to PluginSecurity
- 531 Add IsCommandBar
MultiEditTextAsync
Parameters (1) | ||
---|---|---|
edits | Array | |
Returns (1) | ||
Tuple |
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
History 1
RequestSetSelectionAsync
Parameters (4) | Default | |
---|---|---|
cursorLine | int | |
cursorCharacter | int | |
anchorLine | int? | nil |
anchorCharacter | int? | nil |
Returns (1) | ||
Tuple |
Asks the editor to set its cursor selection to the argument values. Both anchor arguments must be passed, or neither. If neither is passed, then they each default to being the same as the corresponding cursor argument. The editor might decline to update its cursor if the text content of the document has changed, or the cursor has moved since the request was made. Returns (true, nil) if the cursor was updated, and (false, string) with an explanation string if it was not. Yields the current thread until the editor replies.
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
History 1
SelectionChanged
Parameters (4) | |
---|---|
positionLine | int64 |
positionCharacter | int64 |
anchorLine | int64 |
anchorCharacter | int64 |
Fires when the ScriptDocument changes, including immediately after a text change.
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
History 1
- 534 Add SelectionChanged
ViewportChanged
Parameters (2) | |
---|---|
startLine | int64 |
endLine | int64 |
Fires when the displayed line numbers in the editor change. See ScriptDocument.GetViewport for details.
Security | PluginSecurity |
---|---|
Thread safety | Unsafe |
History 1
- 541 Add ViewportChanged
Removed members 1
GetNumLines
Parameters (0) | ||
---|---|---|
No parameters. | ||
Returns (1) | ||
int |
Security | RobloxScriptSecurity |
---|---|
Thread safety | Unsafe |
History 2
- 532 Remove GetNumLines
- 528 Add GetNumLines