Chapter 7. Programming CUTE

The most important feature of CUTE is the built-in python interpreter. It is responsible for configuring and extending CUTE. There are tasks which a user will wish to automate in a text editor. One way to do this is to record a macro once and execute it several times. The alternative is to write a python script using CUTE functions.

The CUTE/python API

General Functions

General functions are defined in the cute python module.

load(filename)

Load a file into the editor.

inputInteger(text)

Get an integer value from the user via a dialog.

inputText(text)

Get a string from the user via a dialog.

message(text)

Show a message dialog.

question(text)

Show a message dialog asking a question with yes and no button.

getOpenFileName()

Show an open file dialog and returns file name. You can also use a filter. For example: getOpenFileName(“*.cpp”).

getExistingDirectory()

Show an open dir dialog and returns dir name.

loadSession(filename)

Load a previously-saved session called filename.

viewList()

Retrieve list containing all views.

activateView(view)

The given view will become the current one.

Configuration Functions

These functions are defined in the config module.

addRecentFile(filename)

Add an item to the recent file menu.

addBookmark(name,line_number)

Add an item to the bookmark menu.

addTool(name,command)

Add an item to the tools menu.

addPythonTool(command)

Add an item to the tools menu, after the command has been created with createCommand()

setCurrentDir()

Set working directory.

setMainWidgetGeometry(x,y,width,height)

Set main window geometry: width, height and position.

map(command,shortcut)

Map an action to a shortcut.

createCommand(function,name)

creates a new command implemented in function with the given name; it can be bound to a shortcut and inserted into a menu

Color(red,green,blue)

Construct new color object.

Scintilla Functions

Scintilla functions are defined in the cute module.

These functions can be called with or without a view object: for example it is possible to call my_view.clear() in order to clear a certain view or just clear() in order to clear the current view.

clear()

Deletes all the text in the text edit.

copy()

Copies selected text to the clipboard.

cut()

Copies selected text to the clipboard and then deletes the text.

foldAll()

If any lines are currently folded then they are all unfolded. Otherwise all lines are folded. This has the same effect as clicking in the fold margin with the shift and control keys pressed.

paste()

Pastes text from the clipboard into the text edit at the current cursor position.

undo()

Undo the last change or sequence of changes.

redo()

Redo previously-Undone changes or sequences of changes.

selectToMatchingBrace()

If the cursor is either side of a brace character then move it to the position of the corresponding brace and select the text between the braces.

zoomIn()

Zooms in on the text by making the base font size one point larger and recalculating all font sizes.

zoomOut()

Zooms out on the text by making the base font size range points smaller and recalculating all font sizes.

beginUndoAction()

Mark the beginning of a sequence of actions that can be undone by a single call to undo().

endUndoAction()

Mark the end of a sequence of actions that can be undone by a single call to undo().

autoIndent()

Returns 1 if auto-indentation is enabled.

backspaceUnindents()

Returns 1 if the backspace key unindents a line instead of deleting a character.

braceMatching()

Returns the brace matching mode.

eolMode()

Returns the end-of-line mode.

eolVisibility()

Returns the visibility of end-of-lines.

findNext()

Find the next occurrence of the string found using findFirst().

folding()

Returns the current folding style.

hasSelectedText()

Returns 1 if some text is selected.

indentationGuides()

Returns 1 if the display of indentation guides is enabled.

indentationsUseTabs()

Returns 1 if indentations are created using tabs and spaces, rather than just spaces.

indentationWidth()

Returns the indentation width in characters. The default is 0 which means that the value returned by tabWidth() is actually used.

isModified()

Returns 1 if the text has been modified.

isReadOnly()

Returns 1 if the text edit is read-only.

isRedoAvailable()

Returns 1 if there is something that can be redone.

isUndoAvailable()

Returns 1 if there is something that can be undone.

isUtf8()

Returns 1 if text is interpreted as being UTF8 encoded. The default is to interpret the text as Latin1 encoded.

lines()

Returns the number of lines of text.

length()

Returns the length of the text edit's text.

tabIndents()

Returns 1 if the tab key indents a line instead of inserting a tab character.

tabWidth()

Returns the tab width in characters.

whitespaceVisibility()

Returns the visibility of whitespace.

ensureLineVisible()

Ensures that the line number line is visible.

setAutoIndent(bool)

If autoindent is 1 then auto-indentation is enabled.

setBackspaceUnindents(bool)

If bool is 1, the backspace key will unindent a line rather then delete a character.

setEolMode(eolMode)

Sets the end-of-line mode to eolMode.

setEolVisibility(eolVisibility)

If eolVisibility is 1 then ends-of-lines are made visible.

setFolding(bool)

Sets the folding style for margin 2 to fold.

setIndentationGuidesBackgroundColor(color)

Set the background color of indentation guides.

setIndentationGuidesForegroundColor(color)

Set the foreground color of indentation guides.

setMarginsForegroundColor(color)

Set the foreground color of all margins.

setMarginsBackgroundColor(color)

Set the background color of all margins.

setMarkerBackgroundColor(color,mnr)

Set the background color of the marker mnr. If mnr is -1 then the color of all markers is set.

setMarkerForegroundColor(color,mnr)

Set the foreground color of the marker mnr. If mnr is -1 then the color of all markers is set.

setMatchedBraceBackgroundColor(color)

Set the background color used to display matched braces.

setMatchedBraceForegroundColor(color)

Set the foreground color used to display matched braces.

setUnmatchedBraceBackgroundColor(color)

Set the background color used to display unmatched braces.

setUnmatchedBraceForegroundColor(color)

Set the foreground color used to display unmatched braces.

setIndentationGuides(indentationsGuides)

Enables or disables the display of indentation guides.

setIndentationsUseTabs(bool)

If bool is 1 then indentations are created using tabs and spaces, rather than just spaces.

setIndentationWidth(width)

Sets the indentation width. If width is 0 then the value returned by tabWidth() is used.

setModified(bool)

Sets the modified state of the text edit. Note that it is only possible to clear the modified state. Attempts to set the modified state are ignored.

setReadOnly(bool)

Sets the read-only state of the text edit.

setTabIndents(bool)

If bool is 1 then the tab key will indent a line rather then insert a tab character.

setTabWidth(width)

Sets the tab width.

setUtf8(bool)

Sets the current text encoding. If bool is 1 then UTF8 is used, otherwise Latin1 is used.

setWhitespaceVisibility(bool)

Sets the visibility of whitespace.

unindent(line_number)

Decreases the indentation of line line_number.

zoomTo(percentage)

Zooms the text by making the base font size given points and recalculating all font sizes.

convertEol(eolMode)

All the lines of the text have their end-of-lines converted to given mode.

markerDeleteHandle(int_handle)

Delete the marker instance with the given marker handle.

indentation(line_number)

Returns the number of characters by which the given line is indented.

lineLength(line_number)

Returns the length of the given line, or -1 if there is no such line.

marginLineNumbers(margin_number)

Returns 1 if line numbers are enabled for the given margin.

marginSensitivity(margin_number)

Returns 1 if the given margin is sensitive to mouse clicks.

marginWidth(margin_number)

Returns the width in pixels of the given margin.

markerDefine(symbol,margin_number)

Define a marker using the given symbol with the given marker number. If mnr is -1 then the marker number is automatically allocated.

markerLine(marker_handle)

Return the line number that contains the marker instance with the given marker handle.

setCursorPosition(line,index)

Sets the cursor to the given line at the given position index.

setIndentation(line_number,string)

Sets the indentation of line line_number to match the given string.

setMarginLineNumbers(margin_number,bool)

Enables or disables, according to second arg, the display of line numbers in the given margin.

setMarginSensitivity(margin_number,bool)

Enables or disables, according to second arg, the sensitivity of the given margin to mouse clicks.

setMarginWidth(margin_number,width)

Sets the width of the given margin to the given pixels. If the width of a margin is 0 then it is not displayed.

insert(string,line,index)

Inserts text at the given position, or at the current position if none is supplied. The function must be given at least 1 argument.

find(string,isRegExp,isCaseSensitive,isWholeWord,wrap,forward,line,index)

Finds a string in the current view. The function must be given at least 1 argument.

currentLine()

Returns current line.

currentColumn()

Returns current index.

selection()

Returns current selection as Selection object. A selection object has four attributes: lineFrom, lineTo, columnFrom and columnTo.

selectedText()

Returns selected text.

moveCursor(int left, int down)

Moves cursor, negative values can also be used.

line(line_number)

Returns line at the given line number.

setMarginStringWidth(margin_number,string)

Sets the margin margin_number's width with the given string.

setSelection(from_line,from_index,to_line,to_index)

Sets selection.

insertCommand(shell_command)

Inserts output of a shell command.

filter(shell_command)

Filters selection with a shell command.

fileName()

Retrieves the file name of the view.