Class orion.textview.TextView

A TextView is a user interface for editing text.
Defined in: </shared/eclipse/e4/orion/I201301232230/plugins/org.eclipse.orion.client.editor/web/orion/textview/textView.js>.

Class Summary
Constructor Attributes	Constructor Name and Description
	orion.textview.TextView(options) Constructs a new text view.

Method Summary
Method Attributes	Method Name and Description
	addEventListener(type, listener, useCapture) Adds an event listener to this event target.
	addRuler(ruler, index) Adds a ruler to the text view at the specified position.
	computeSize()
	convert(rect, from, to) Converts the given rectangle from one coordinate spaces to another.
	destroy() Destroys the text view.
	dispatchEvent(evt) Dispatches the given event to the listeners added to this event target.
	focus() Gives focus to the text view.
	getActionDescription(actionID) Returns the action description for a given action ID.
	getActions(defaultAction) Returns all action IDs defined in the text view.
	getBottomIndex(fullyVisible) Returns the bottom index.
	getBottomPixel() Returns the bottom pixel.
	getCaretOffset() Returns the caret offset relative to the start of the document.
	getClientArea() Returns the client area.
	getHorizontalPixel() Returns the horizontal pixel.
	getKeyBindings(actionID) Returns all the key bindings associated to the given action ID.
	getLineHeight(lineIndex) Returns the line height for a given line index.
	getLineIndex(y) Returns the line index for a given line pixel position relative to the document.
	getLinePixel(lineIndex) Returns the top pixel position of a given line index relative to the beginning of the document.
	getLocationAtOffset(offset) Returns the {x, y} pixel location of the top-left corner of the character bounding box at the specified offset in the document.
	getModel() Returns the text model of the text view.
	getOffsetAtLocation(x, y) Returns the character offset nearest to the given pixel location.
	getOptions(options) Returns the specified view options.
	getRulers() Get the view rulers.
	getSelection() Returns the text view selection.
	getText(start, end) Returns the text for the given range.
	getTopIndex(fullyVisible) Returns the top index.
	getTopPixel() Returns the top pixel.
	hasFocus() Check if the text view has focus.
	invokeAction(actionID, defaultAction) Executes the action handler associated with the given action ID.
	isDestroyed() Returns if the view is destroyed.
	onDrag(dragEvent)
	onDragEnd(dragEvent)
	onDragEnter(dragEvent)
	onDragLeave(dragEvent)
	onDragOver(dragEvent)
	onDragStart(dragEvent)
	onDrop(dragEvent)
	onMouseDown(mouseEvent)
	onMouseMove(mouseEvent)
	onMouseOut(mouseEvent)
	onMouseOver(mouseEvent)
	onMouseUp(mouseEvent)
	redraw() Redraws the entire view, including rulers.
	redrawLines(startLine, endLine, ruler) Redraws the text in the given line range.
	redrawRange(start, end) Redraws the text in the given range.
	redrawRulers(startLine, endLine)
	removeEventListener(type, listener, useCapture) Removes an event listener from the event target.
	removeRuler(ruler) Removes a ruler from the text view.
	resize()
	setAction(actionID, handler, actionDescription) Associates an application defined handler to an action ID.
	setCaretOffset(caret, show) Sets the caret offset relative to the start of the document.
	setHorizontalPixel(pixel) Sets the horizontal pixel.
	setKeyBinding(keyBinding, actionID) Associates a key binding with the given action ID.
	setModel(model) Sets the text model of the text view.
	setOptions(options) Sets the view options for the view.
	setRedraw(redraw) Sets whether the view should update the DOM.
	setSelection(start, end, show) Sets the text view selection.
	setText(text, start, end) Replaces the text in the given range with the given text.
	setTopIndex(topIndex) Sets the top index.
	setTopPixel(pixel) Sets the top pixel.
	showSelection() Scrolls the selection into view if needed.
	update(styleChanged, sync)

Event Summary
Event Attributes	Event Name and Description
	onBlur(blurEvent) This event is sent when the text view goes out of focus.
	onContextMenu(contextMenuEvent) This event is sent when the user invokes the view context menu.
	onDestroy(destroyEvent) This event is sent when the text view has been destroyed.
	onFocus(focusEvent) This event is sent when the text view is focused.
	onLineStyle(lineStyleEvent) This event is sent when the text view needs the style information for a line.
	onModelChanged(modelChangedEvent) This event is sent when the text in the model has changed.
	onModelChanging(modelChangingEvent) This event is sent when the text in the model is about to change.
	onModify(modifyEvent) This event is sent when the text view has changed text in the model.
	onScroll(scrollEvent) This event is sent when the text view scrolls vertically or horizontally.
	onSelection(selectionEvent) This event is sent when the text view selection has changed.
	onVerify(verifyEvent) This event is sent when the text view is about to change text in the model.

Class Detail

orion.textview.TextView(options)

Constructs a new text view.

Parameters:
{orion.textview.TextViewOptions} options: the view options.

Method Detail

addEventListener(type, listener, useCapture)

Adds an event listener to this event target.
Defined in: </shared/eclipse/e4/orion/I201301232230/plugins/org.eclipse.orion.client.editor/web/orion/textview/eventTarget.js>.

Parameters:
{String} type: The event type.
{Function|EventListener} listener: The function or the EventListener that will be executed when the event happens.
{Boolean} useCapture Optional, Default: false: true if the listener should be trigged in the capture phase.

See:: #removeEventListener

addRuler(ruler, index)

Adds a ruler to the text view at the specified position.

The position is relative to the ruler location.

Parameters:
{orion.textview.Ruler} ruler: the ruler.
{Number} index Optional, Default: length: the ruler index.

computeSize()

convert(rect, from, to)

Converts the given rectangle from one coordinate spaces to another.

The supported coordinate spaces are:

"document" - relative to document, the origin is the top-left corner of first line
"page" - relative to html page that contains the text view

All methods in the view that take or return a position are in the document coordinate space.

Parameters:
rect: the rectangle to convert.
rect.x: the x of the rectangle.
rect.y: the y of the rectangle.
rect.width: the width of the rectangle.
rect.height: the height of the rectangle.
{String} from: the source coordinate space.
{String} to: the destination coordinate space.

See:: #getLocationAtOffset; #getOffsetAtLocation; #getTopPixel; #setTopPixel

destroy()

Destroys the text view.

Removes the view from the page and frees all resources created by the view. Calling this function causes the "Destroy" event to be fire so that all components attached to view can release their references.

See:: #onDestroy

dispatchEvent(evt)

Dispatches the given event to the listeners added to this event target.
Defined in: </shared/eclipse/e4/orion/I201301232230/plugins/org.eclipse.orion.client.editor/web/orion/textview/eventTarget.js>.

Parameters:
{Event} evt: The event to dispatch.

focus()

Gives focus to the text view.

{orion.textview.ActionDescrition} getActionDescription(actionID)

Returns the action description for a given action ID.

Parameters:
actionID

Returns:: {orion.textview.ActionDescrition} the action description

{String[]} getActions(defaultAction)

Returns all action IDs defined in the text view.

There are two types of actions, the predefined actions of the view and the actions added by application code.

The predefined actions are:

Navigation actions. These actions move the caret collapsing the selection.

"lineUp" - moves the caret up by one line
"lineDown" - moves the caret down by one line
"lineStart" - moves the caret to beginning of the current line
"lineEnd" - moves the caret to end of the current line
"charPrevious" - moves the caret to the previous character
"charNext" - moves the caret to the next character
"pageUp" - moves the caret up by one page
"pageDown" - moves the caret down by one page
"wordPrevious" - moves the caret to the previous word
"wordNext" - moves the caret to the next word
"textStart" - moves the caret to the beginning of the document
"textEnd" - moves the caret to the end of the document

Selection actions. These actions move the caret extending the selection.

"selectLineUp" - moves the caret up by one line
"selectLineDown" - moves the caret down by one line
"selectLineStart" - moves the caret to beginning of the current line
"selectLineEnd" - moves the caret to end of the current line
"selectCharPrevious" - moves the caret to the previous character
"selectCharNext" - moves the caret to the next character
"selectPageUp" - moves the caret up by one page
"selectPageDown" - moves the caret down by one page
"selectWordPrevious" - moves the caret to the previous word
"selectWordNext" - moves the caret to the next word
"selectTextStart" - moves the caret to the beginning of the document
"selectTextEnd" - moves the caret to the end of the document
"selectAll" - selects the entire document

Edit actions. These actions modify the text view text

"deletePrevious" - deletes the character preceding the caret
"deleteNext" - deletes the charecter following the caret
"deleteWordPrevious" - deletes the word preceding the caret
"deleteWordNext" - deletes the word following the caret
"tab" - inserts a tab character at the caret
"shiftTab" - noop
"toggleTabMode" - toggles tab mode.
"toggleWrapMode" - toggles wrap mode.
"enter" - inserts a line delimiter at the caret

Clipboard actions.

"copy" - copies the selected text to the clipboard
"cut" - copies the selected text to the clipboard and deletes the selection
"paste" - replaces the selected text with the clipboard contents

Parameters:
{Boolean} defaultAction Optional, Default: false: whether or not the predefined actions are included.

Returns:: {String[]} an array of action IDs defined in the text view.

See:: #invokeAction; #setAction; #setKeyBinding; #getKeyBindings

{Number} getBottomIndex(fullyVisible)

Returns the bottom index.

The bottom index is the line that is currently at the bottom of the view. This line may be partially visible depending on the vertical scroll of the view. The parameter fullyVisible determines whether to return only fully visible lines.

Parameters:
{Boolean} fullyVisible Optional, Default: false: if true, returns the index of the last fully visible line. This parameter is ignored if the view is not big enough to show one line.

Returns:: {Number} the index of the bottom line.

See:: #getTopIndex; #setTopIndex

{Number} getBottomPixel()

Returns the bottom pixel.

The bottom pixel is the pixel position that is currently at the bottom edge of the view. This position is relative to the beginning of the document.

Returns:: {Number} the bottom pixel.

See:: #getTopPixel; #setTopPixel; #convert

getCaretOffset()

Returns the caret offset relative to the start of the document.

Returns:: the caret offset relative to the start of the document.

See:: #setCaretOffset; #setSelection; #getSelection

getClientArea()

Returns the client area.

The client area is the portion in pixels of the document that is visible. The client area position is relative to the beginning of the document.

Returns:: the client area rectangle {x, y, width, height}.

See:: #getTopPixel; #getBottomPixel; #getHorizontalPixel; #convert

{Number} getHorizontalPixel()

Returns the horizontal pixel.

The horizontal pixel is the pixel position that is currently at the left edge of the view. This position is relative to the beginning of the document.

Returns:: {Number} the horizontal pixel.

See:: #setHorizontalPixel; #convert

{orion.textview.KeyBinding[]} getKeyBindings(actionID)

Returns all the key bindings associated to the given action ID.

Parameters:
{String} actionID: the action ID.

Returns:: {orion.textview.KeyBinding[]} the array of key bindings associated to the given action ID.

See:: #setKeyBinding; #setAction

{Number} getLineHeight(lineIndex)

Returns the line height for a given line index. Returns the default line height if the line index is not specified.

Parameters:
{Number} lineIndex Optional: the line index.

Returns:: {Number} the height of the line in pixels.

See:: #getLinePixel

{Number} getLineIndex(y)

Returns the line index for a given line pixel position relative to the document.

Parameters:
{Number} y Optional: the line pixel.

Returns:: {Number} the line index for the specified pixel position.

See:: #getLinePixel

{Number} getLinePixel(lineIndex)

Returns the top pixel position of a given line index relative to the beginning of the document.

Clamps out of range indices.

Parameters:
{Number} lineIndex: the line index.

Returns:: {Number} the pixel position of the line.

See:: #setTopPixel; #getLineIndex; #convert

getLocationAtOffset(offset)

Returns the {x, y} pixel location of the top-left corner of the character bounding box at the specified offset in the document. The pixel location is relative to the document.

Clamps out of range offsets.

Parameters:
{Number} offset: the character offset

Returns:: the {x, y} pixel location of the given offset.

See:: #getOffsetAtLocation; #convert

{orion.textview.TextModel} getModel()

Returns the text model of the text view.

Returns:: {orion.textview.TextModel} the text model of the view.

getOffsetAtLocation(x, y)

Returns the character offset nearest to the given pixel location. The pixel location is relative to the document.

Parameters:
x: the x of the location
y: the y of the location

Returns:: the character offset at the given location.

See:: #getLocationAtOffset

{Object|orion.textview.TextViewOptions} getOptions(options)

Returns the specified view options.

The returned value is either a orion.textview.TextViewOptions or an option value. An option value is returned when only one string paremeter is specified. A orion.textview.TextViewOptions is returned when there are no paremeters, or the parameters are a list of options names or a orion.textview.TextViewOptions. All view options are returned when there no paremeters.

Parameters:
{String|orion.textview.TextViewOptions} options Optional: The options to return.

Returns:: {Object|orion.textview.TextViewOptions} The requested options or an option value.

See:: #setOptions

getRulers()

Get the view rulers.

Returns:: the view rulers

See:: #addRuler

{orion.textview.Selection} getSelection()

Returns the text view selection.

The selection is defined by a start and end character offset relative to the document. The character at end offset is not included in the selection.

Returns:: {orion.textview.Selection} the view selection

See:: #setSelection

getText(start, end)

Returns the text for the given range.

The text does not include the character at the end offset.

Parameters:
{Number} start Optional, Default: 0: the start offset of text range.
{Number} end Optional, Default: char count: the end offset of text range.

See:: #setText

{Number} getTopIndex(fullyVisible)

Returns the top index.

The top index is the line that is currently at the top of the view. This line may be partially visible depending on the vertical scroll of the view. The parameter fullyVisible determines whether to return only fully visible lines.

Parameters:
{Boolean} fullyVisible Optional, Default: false: if true, returns the index of the first fully visible line. This parameter is ignored if the view is not big enough to show one line.

Returns:: {Number} the index of the top line.

See:: #getBottomIndex; #setTopIndex

{Number} getTopPixel()

Returns the top pixel.

The top pixel is the pixel position that is currently at the top edge of the view. This position is relative to the beginning of the document.

Returns:: {Number} the top pixel.

See:: #getBottomPixel; #setTopPixel; #convert

{Boolean} hasFocus()

Check if the text view has focus.

Returns:: {Boolean} true if the text view has focus, otherwise false.

{Boolean} invokeAction(actionID, defaultAction)

Executes the action handler associated with the given action ID.

The application defined action takes precedence over predefined actions unless the defaultAction paramater is true.

If the application defined action returns false, the text view predefined action is executed if present.

Parameters:
{String} actionID: the action ID.
{Boolean} defaultAction Optional: whether to always execute the predefined action.

Returns:: {Boolean} true if the action was executed.

See:: #setAction; #getActions

{Boolean} isDestroyed()

Returns if the view is destroyed.

Returns:: {Boolean} true if the view is destroyed.

onDrag(dragEvent)

Parameters:
dragEvent

onDragEnd(dragEvent)

Parameters:
dragEvent

onDragEnter(dragEvent)

Parameters:
dragEvent

onDragLeave(dragEvent)

Parameters:
dragEvent

onDragOver(dragEvent)

Parameters:
dragEvent

onDragStart(dragEvent)

Parameters:
dragEvent

onDrop(dragEvent)

Parameters:
dragEvent

onMouseDown(mouseEvent)

Parameters:
mouseEvent

onMouseMove(mouseEvent)

Parameters:
mouseEvent

onMouseOut(mouseEvent)

Parameters:
mouseEvent

onMouseOver(mouseEvent)

Parameters:
mouseEvent

onMouseUp(mouseEvent)

Parameters:
mouseEvent

redraw()

Redraws the entire view, including rulers.

See:: #redrawLines; #redrawRange; #setRedraw

redrawLines(startLine, endLine, ruler)

Redraws the text in the given line range.

The line at the end index is not redrawn.

Parameters:
{Number} startLine Optional, Default: 0: the start line
{Number} endLine Optional, Default: line count: the end line
ruler

See:: #redraw; #redrawRange; #setRedraw

redrawRange(start, end)

Redraws the text in the given range.

The character at the end offset is not redrawn.

Parameters:
{Number} start Optional, Default: 0: the start offset of text range
{Number} end Optional, Default: char count: the end offset of text range

See:: #redraw; #redrawLines; #setRedraw

redrawRulers(startLine, endLine)

Parameters:
startLine
endLine

removeEventListener(type, listener, useCapture)

Removes an event listener from the event target.

All the parameters must be the same ones used to add the listener.

Defined in: </shared/eclipse/e4/orion/I201301232230/plugins/org.eclipse.orion.client.editor/web/orion/textview/eventTarget.js>.

Parameters:
{String} type: The event type
{Function|EventListener} listener: The function or the EventListener that will be executed when the event happens.
{Boolean} useCapture Optional, Default: false: true if the listener should be trigged in the capture phase.

See:: #addEventListener

removeRuler(ruler)

Removes a ruler from the text view.

Parameters:
{orion.textview.Ruler} ruler: the ruler.

resize()

setAction(actionID, handler, actionDescription)

Associates an application defined handler to an action ID.

If the action ID is a predefined action, the given handler executes before the default action handler. If the given handler returns true, the default action handler is not called.

Parameters:
{String} actionID: the action ID.
{Function} handler: the action handler.
{orion.textview.ActionDescription} actionDescription Optional, Default: undefined: the action description.

See:: #getActions; #invokeAction

setCaretOffset(caret, show)

Sets the caret offset relative to the start of the document.

Parameters:
{Number} caret: the caret offset relative to the start of the document.
{Boolean} show Optional, Default: true: if true, the view will scroll if needed to show the caret location.

See:: #getCaretOffset; #setSelection; #getSelection

setHorizontalPixel(pixel)

Sets the horizontal pixel.

The horizontal pixel is the pixel position that is currently at the left edge of the view. This position is relative to the beginning of the document.

Parameters:
{Number} pixel: the horizontal pixel.

See:: #getHorizontalPixel; #convert

setKeyBinding(keyBinding, actionID)

Associates a key binding with the given action ID. Any previous association with the specified key binding is overwriten. If the action ID is null, the association is removed.

Parameters:
{orion.textview.KeyBinding} keyBinding: the key binding
{String} actionID: the action ID

setModel(model)

Sets the text model of the text view.

Parameters:
{orion.textview.TextModel} model: the text model of the view.

setOptions(options)

Sets the view options for the view.

Parameters:
{orion.textview.TextViewOptions} options: the view options.

See:: #getOptions

setRedraw(redraw)

Sets whether the view should update the DOM.

This can be used to improve the performance.

When the flag is set to true, the entire view is marked as needing to be redrawn. Nested calls to this method are stacked.

Parameters:
{Boolean} redraw: the new redraw state

See:: #redraw

setSelection(start, end, show)

Sets the text view selection.

The selection is defined by a start and end character offset relative to the document. The character at end offset is not included in the selection.

The caret is always placed at the end offset. The start offset can be greater than the end offset to place the caret at the beginning of the selection.

Clamps out of range offsets.

Parameters:
{Number} start: the start offset of the selection
{Number} end: the end offset of the selection
{Boolean} show Optional, Default: true: if true, the view will scroll if needed to show the caret location.

See:: #getSelection

setText(text, start, end)

Replaces the text in the given range with the given text.

The character at the end offset is not replaced.

When both start and end parameters are not specified, the text view places the caret at the beginning of the document and scrolls to make it visible.

Parameters:
{String} text: the new text.
{Number} start Optional, Default: 0: the start offset of text range.
{Number} end Optional, Default: char count: the end offset of text range.

See:: #getText

setTopIndex(topIndex)

Sets the top index.

The top index is the line that is currently at the top of the text view. This line may be partially visible depending on the vertical scroll of the view.

Parameters:
{Number} topIndex: the index of the top line.

See:: #getBottomIndex; #getTopIndex

setTopPixel(pixel)

Sets the top pixel.

The top pixel is the pixel position that is currently at the top edge of the view. This position is relative to the beginning of the document.

Parameters:
{Number} pixel: the top pixel.

See:: #getBottomPixel; #getTopPixel; #convert

showSelection()

Scrolls the selection into view if needed.

Returns:: true if the view was scrolled.

See:: #getSelection; #setSelection

update(styleChanged, sync)

Parameters:
styleChanged
sync

Event Detail

onBlur(blurEvent)

This event is sent when the text view goes out of focus.

Parameters:
{orion.textview.BlurEvent} blurEvent: the event

onContextMenu(contextMenuEvent)

This event is sent when the user invokes the view context menu.

Parameters:
{orion.textview.ContextMenuEvent} contextMenuEvent: the event

onDestroy(destroyEvent)

This event is sent when the text view has been destroyed.

Parameters:
{orion.textview.DestroyEvent} destroyEvent: the event

See:: #destroy

onFocus(focusEvent)

This event is sent when the text view is focused.

Parameters:
{orion.textview.FocusEvent} focusEvent: the event

onLineStyle(lineStyleEvent)

This event is sent when the text view needs the style information for a line.

Parameters:
{orion.textview.LineStyleEvent} lineStyleEvent: the event

onModelChanged(modelChangedEvent)

This event is sent when the text in the model has changed.

Parameters:
{orion.textview.ModelChangedEvent} modelChangedEvent: the event

onModelChanging(modelChangingEvent)

This event is sent when the text in the model is about to change.

Parameters:
{orion.textview.ModelChangingEvent} modelChangingEvent: the event

onModify(modifyEvent)

This event is sent when the text view has changed text in the model.

If the text is changed directly through the model API, this event is not sent.

Parameters:
{orion.textview.ModifyEvent} modifyEvent: the event

onScroll(scrollEvent)

This event is sent when the text view scrolls vertically or horizontally.

Parameters:
{orion.textview.ScrollEvent} scrollEvent: the event

onSelection(selectionEvent)

This event is sent when the text view selection has changed.

Parameters:
{orion.textview.SelectionEvent} selectionEvent: the event

onVerify(verifyEvent)

This event is sent when the text view is about to change text in the model.

If the text is changed directly through the model API, this event is not sent.

Listeners are allowed to change these parameters. Setting text to null or undefined stops the change.

Parameters:
{orion.textview.VerifyEvent} verifyEvent: the event

Classes

Class orion.textview.TextView