Writer/API/Text cursor

A text cursor can only move within the text range of the text object in which it was created. Thus a text cursor that is created for the main document's text range can not move inside a table.

Creating a text cursor

A common thing to do is to create a text cursor which has the same location as the view cursor, as follows:

oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)

NOTE: You can have many non-visible Text Cursors (oCursor) as you want but there is only ONE View Cursor (oVC) per document.

If you want a cursor for the text in the main document:

oCursor = thisComponent.getText.createTextCursor
'or
oText = thisComponent.getText
oCursor = oText.createTextCursorByRange(oText.getStart)

Start and End of a text cursor

A cursor has the methods getStart, and getEnd. Which is the Start end and which is the End end of the selection is determined by the direction in which the selection was made.

However, the methods collapseToStart and collapseToEnd are relative to the start and end of the document.

Moving a cursor

A cursor has a number of gotoXXX methods, where XXX is some relative location. In each case the method has a boolean parameter for "extending the selection". When this parameter is set to true the selection is extended from the current selection to the new location.

There is no method for adding to the selection. While the view cursor can have more than one selection, text cursors only have one selection.

The gotoXXX methods return true if they were able to execute the movement, false otherwise.

bExtend = false
oCursor.goLeft(5, bExtend)   'go left 5 characters
oCursor.goRight(10, bExtend) 'go right 10 characters
oCursor.goUp(1, bExtend)     'go up one line
oCursor.goDown(2, bExtend)   'go down two lines
oCursor.gotoStart(bExtend)   'go to the start of the text range
oCursor.gotoEnd(bExtend)     'go to the end of the text range
oCursor.gotoRange(oVC, false)'go to the same range as the view cursor (error if oVC not in same text range)
 
oCursor.gotoNextWord(bExtend)
oCursor.gotoPreviousWord(bExtend)
oCursor.gotoEndOfWord(bExtend)
oCursor.gotoStartOfWord(bExtend)
 
oCursor.gotoNextSentence(bExtend)
oCursor.gotoPreviousSentence(bExtend)
oCursor.gotoStartOfSentence(bExtend)
oCursor.gotoEndOfSentence(bExtend)
 
oCursor.gotoStartOfParagraph(bExtend)
oCursor.gotoEndOfParagraph(bExtend)
oCursor.gotoNextParagraph(bExtend)
oCursor.gotoPreviousParagraph(bExtend)

oCursor.JumpToFirstPage(bExtend)
oCursor.JumpToLastPage(bExtend)
oCursor.JumpToPage(5,bExtend)   'go to page 5
oCursor.JumpToPreviousPage(bExtend)
oCursor.JumpToNextPage(bExtend)
oCursor.JumpToStartOfPage(bExtend)   
oCursor.JumpToEndOfPage(bExtend)   

oCursor.ScreenUp(bExtend)   
oCursor.ScreenDown(bExtend)

Checking a cursor

To check if the text cursor is at the beginning or the end of a line.

If oCursor.isAtStartOfLine() then print "Text cursor is at the Start of the line"
If oCursor.isAtEndOfLine() then print "Text cursor is at the End of the line"
If oCursor.IsVisible() then print "This text cursor is visible (aka the View Cursor)"

Getting text from a cursor

If you manage to select text with the Text Cursor, you can see what you have selected

Print oCursor.string

To see a full list of a Text Cursor's methods.

MsgBox oCursor.DBG_methods

Working sample code

'Author: JohnV (2003)
'Source: http://www.oooforum.org/forum/viewtopic.phtml?t=89740
'Purpose: Saves each page of a Writer Document to a separate File
Sub PagesToSeparateFiles				'Will overwrite an existing file without warning!
	dim oDoc,oVC,NewDoc,filename,url,oTC,oNewDocVC,newname,newurl,n

	filename = InputBox("Entry a filename.","What filename to save to?")

	url = "C:\VideoOutput"				 	'Insert your desired url here.
	oDoc = ThisComponent
	oVC = oDoc.CurrentController.getViewCursor		'Create View Cursor oVC
	oVC.gotoStart(false)					'Make oVC position itself to the start of the document
	NewDoc = StarDesktop.loadComponentFromURL("private:factory/swriter","_blank",0,Array())	'Open blank Writer doc
	oNewDocVC = NewDoc.CurrentController.getViewCursor	'Create another View Cursor for this new document

	Do
		oTC = oDoc.Text.createTextCursorByRange(oVC)	'Create Text Cursor by cloning the View Cursor (both have same position in doc)
		oVC.jumpToEndOfPage			'Move View Cursor oVC to EndOfPage
		oTC.gotoRange(oVC,true)			'Move Text Cursor to same location as oVC while selecting text in between (True)
		oNewDocVC.String = oTC.String		'make oNewDocVC in newdoc get what Text Cursor is selecting (copy w/o clipboard!)
		n = n+1					'increment page counter n
		newname = filename & "_" & n & ".odt"	'generate unique filename based on page number
		newurl = ConvertToURL(url & "/" & newname)
		NewDoc.StoreToURL(newurl,Array())	' 
		oNewDocVC.String = ""							
	Loop While oVC.jumpToNextPage
	NewDoc.dispose					'Close NewDoc
End Sub