5. Cssed python API

cssed is the python module containing this API. It should be imported before to use cssed's python API.

5.1. Methods (grouped)

5.1.1. Text retrieval and modification

Those are some functions to add or get text on cssed. All those actions take place in the current document.

GTK will always expect UTF-8 text, so ensure to ever use this encoding when dealing with cssed output. Most Python builds already have Unicode support, others not. On Linux and OsX no problems are expected if you use an UTF-8 aware language environment.

The best way to avoid problems, is to use UTF-8 always.

If the current document is in other encoding, you should deal with encoding conversion on the python level. Cssed will make no attempt to convert any text passed to it

You can not define with "Defining Python Source Code Encodings" the file encoding.

see also:

5.1.2. Selection

Those functions performs actions regarding text selected on the current document. Most of them just makes a request that will be performed when possible.

5.1.4. Line and position

Internally cssed uses always 0 based indexes on line and character counts. Those functions that returns a count on lines or characters will be indexed this way and will have no meaning for the user. If you'd like to show this kind of data to the user add 1 to the returned value.

5.1.5. Autocompletion

Auto-completion can be accesed through python by the functions below. With auto-completion I mean a feature that let you show a floating list of choices for the user to complete a word - or to add a word to current document - from a user's selection on the list.

The are two kinds of lists for such purpose: the auto-completion list, and the user's list. Auto-completion lists are meant to complete a word that is being written - add part of the word's text - meanwhile user's list, are meant to add one entire word to the text, without completing anything.

The functions show_autocompletion_list and show_user_list creates a list of each of the mentioned types, and the functions autocompletion_cancel, autocompletion_select and is_autocompletion_active works with either one or another kind of list, but only while the list is visible on screen.

5.1.6. Call tips

Call tips are floating windows usefull for displaying information such as a function's signature or the value of a variable on a debugger.

Call tips an auto completion windows can not be shown at the same time on a document.

The call tip definition should be one or more lines separated by '\n' - line feed ASCII character 10.

5.1.7. Markers and bookmarks

Right now cssed implements three kinds of marks on the left margin: the "bookmark", the "arrow marker" and the "marker".

The "arrow marker" is a speciall kind of mark used to get user's attention on one line. Only one "arrow marker" can be at once on screen and once you set one of them, you deletes all other ones that may have been added. It's meant to be used to debuggers or error reporting functions. This marker is represented by a red arrow - hence its name - on the left margin. When you set the arrow marker on one line, the view is scrolled to this line, and the caret is place on it.

Bookmarks are marks on the margin set by the user, it can be set or unset by clicking in the margin, and the best is to let the user deal with them. Bookmarks are represented by a rounded square with white background.

Markers are exactly as bookmarks but the user can not set nor unset them from cssed's controls. They have been implemented to be used programatically and if you need the markers feature you should use them. You can add as many markers as you wish, and you can move to them with marker_next and marker_prev methods. Markers are represented by a circle with white bakground and red border.

5.1.8. Undo redo cut copy and paste

Those functions are a way to access programatically to those common text editor functions. I suposse there's no need to explain them.

5.1.9. Folding

Folding is a feature that hiddes part of the text on user's request. It's meant to be used with programming language or representation languages with an structured syntax, that let you know what code is bounded to a parent gramatical notation.

As example in HTML you can close a fold point located on a tag to hide all its children tags from the users view.

The following functions let you deal programatically with this feature.

5.1.10. Documents and files

The scope of most functions in the cssed's python API is the current document. Those functions let you deal with documents, switching from one to other or opening/saving/creating them.

5.1.11. Output to cssed

Those functions are used to show output to the user, with a dialog and on cssed's output window located on the cssed's footer notebook.

Most of them expect Pango markup, so you can style the message with markup as <span color='red'>text</span>. In the other hand if you feed random text to those functions - such as external program output, or html/xml - you must escape the text to html entities.

GTK will always expect UTF-8 text, so ensure to ever use this encoding when dealing with cssed output. Most Python builds already have Unicode support, others not. On Linux and OsX no problems are expected if you use an UTF-8 aware language environment, on UTF-8 documents.

If the current document is in other encoding, you should deal with encoding conversion at the python level. Cssed will make no attempt to convert any text passed to it.

You can not uset "Defining Python Source Code Encodings" to define the file encoding.

5.1.12. Zooming

Those functions increase or decrease the text size without modifying the configured one.

5.2. Methods (alphabetic)

5.2.1. add_text()

Signature: None add_text(str)

Parameter: string - the text to add to current document.

Return: None

The add_text() method adds the string passed as parameter to cssed's current document.


import cssed

cssed.add_text("Hi from python")
				

5.2.2. autocompletion_cancel()

Signature: None autocompletion_cancel(None)

Parameter: None.

Return: None

Cancel an auto completion action. It hides the auto-completion list if any.


import cssed

if cssed.is_autocompletion_active():
		cssed.autocompletion_cancel()
				

5.2.3. autocompletion_select()

Signature: None autocompletion_select(str)

Parameter: string - The item to select on the auto-completion list.

Return: None

Selects an item in an auto-completion list.


import cssed

if cssed.is_autocompletion_active():
		cssed.autocompletion_select("string")
				

5.2.4. bookmark_next()

Signature: None bookmark_next(None)

Parameter: None.

Return: None

Goes to next bookmark in current document.


import cssed

cssed.bookmark_next()
				

5.2.5. bookmark_prev()

Signature: None bookmark_prev(None)

Parameter: None.

Return: None

Goes to the previous next bookmark in current document.


import cssed

cssed.bookmark_prev()
				

5.2.6. calltip_get_pos_start()

Signature: int calltip_get_pos_start(None)

Parameter: None.

Return: an integer with the document's position of the calltip's start position.

Returns an integer with the document's position of the call tip when it started to be displayed on screen.


import cssed

if cssed.is_calltip_active():
	start = cssed.calltip_get_pos_start()
				

5.2.7. can_redo()

Signature: boolean can_redo(None)

Parameter: None.

Return: boolean.

This function returns a value indicating if there are actions in the redo list.


import cssed

if cssed.can_redo():
	cssed.redo()
				

5.2.8. can_undo()

Signature: boolean can_undo(None)

Parameter: None.

Return: boolean.

This function returns a value indicating if there are actions in the undo list.


import cssed

if cssed.can_undo():
	cssed.undo()
				

5.2.9. cancel_calltip()

Signature: None cancel_calltip(None)

Parameter: None.

Return: None.

This function cancels the active calltip.


import cssed

if cssed.is_calltip_active():
	cssed.cancel_calltip()
				

5.2.10. clear_arrow_marker()

Signature: None clear_arrow_marker(None)

Parameter: None.

Return: None.

It clears all "arrow" type markers.


import cssed

cssed.clear_arrow_marker()
				

5.2.11. clear_sel()

Signature: None clear_sel(None)

Parameter: None.

Return: None.

It deletes the text selected in current document.


import cssed

if cssed.get_selection_start() > cssed.get_selection_end():
	cssed.clear_sel()
				

5.2.12. copy()

Signature: None copy(None)

Parameter: None.

Return: None.

It copies the selected text to the system clipboard. The exact meaning of it depends on the platform you're using.


import cssed

if cssed.get_selection_end() > cssed.get_selection_start():
	cssed.copy()
				

5.2.13. cut()

Signature: None cut(None)

Parameter: None.

Return: None.

It copies the selected text to the system clipboard and deletes the selection. The exact meaning of it depends on the platform you're using.


import cssed

if cssed.get_selection_end() > cssed.get_selection_start():
	cssed.cut()
				

5.2.14. document_grab_focus()

Signature: None document_grab_focus(None)

Parameter: None.

Return: None.

IT makes the current document editor to grab the focus..


import cssed

cssed.document_grab_focus()
				

5.2.15. ensure_line_is_visible()

Signature: boolean ensure_line_is_visible(int)

Parameter: Integer with the line number (0 based index).

Return: Boolean indicating if the line is visible for the user.

It returns the visibility state of current line. Lines can be visible or not, as example when one fold point is closed, all lines in the given fold depth or greater are hidden to the user.


import cssed

if cssed.is_folding_enabled():
	cssed.ensure_line_is_visible(10)

cssed.set_current_line(10)
				

5.2.16. error_message()

Signature: None error_message(str [,str])

Parameter: string - Error detailed description.

Parameter: string (optional) - Error short description.

Return: None.

It shows an error dialog. It consists in a label with the error's short description in large bold font, and a detailed description is medium normal font below the short description. This dialog is not modal.


import cssed

name = cssed.get_filename()
if name != None:
	cssed.error_message("Filename:%s" % name)
else:
	cssed.error_message("This file is untitled, and is not saved on disk", "File have no name")
				

5.2.17. fold_all()

Signature: None fold_all(None)

Parameter:None.

Return: None.

Closes all fold points in the document, if folding is enabled and the file type is capable of folding - not all file types can fold.


import cssed

if cssed.get_folding_enabled():
	cssed.fold_all()
				

5.2.18. get_current_line()

Signature: int get_current_line(None)

Parameter: None.

Return: An integer indicating the line number (0 based index).

This functions returns the line number where the caret is at current document. This index have no human meaning and starts at 0 - the first line on text is line 0, the second line 1 and so on. To show it to users add one to the line number.


import cssed

cssed.output_write("You're at line %i" % cssed.get_current_line() + 1)
				

5.2.19. get_current_position()

Signature: int get_current_position(None)

Parameter:None.

Return: An integer indicating the character position (0 based index).

This functions returns the character position where the caret is at current document. This index have no human meaning and starts at 0 - the first line on text is line 0 , the second line 1 and so on. When using multi-byte character sets - such as UTF-8 - the editor control will attemp to place always the caret on a legal place, so if you request to place it in the middle of a multy-byte character it will skip to the end of it, the same apply if you try to place the caret at the middle of a CR LF line terminator (windows).


import cssed

cssed.output_write("You're at position %i" % cssed.get_current_position() + 1)
				

5.2.20. get_document_index()

Signature: int get_document_index(None)

Parameter:None.

Return: An integer indicating position of current document on the document's list - hence in the document's notebook (0 based index).

This functions returns the position where current document is at document's notebook. This index have no human meaning and starts at 0 - the first document is number 0, the second number 1 and so on.


import cssed

ndocs = cssed.get_num_docs()
index = cssed.get_document_index()

# go to next doc or first if we're in the last one
if index < ndocs:
	cssed.set_document_by_index(index+1)
else:
	cssed.set_document_by_index(0)
				

5.2.21. get_filename()

Signature: (None|str) get_filename(None)

Parameter: None.

Return: string or None.

Gets the name - full path - of the file, if it's saved, or None otherwise. If this function returns None, it indicates the document is a cssed buffer not saved to, nor opened from disk.


import cssed

name = cssed.get_filename()
if name != None:
	cssed.output_write(name)
else:
	cssed.output_write("File is untitled, and is not saved on disk")
				

5.2.22. get_fold_depth()

Signature: int get_fold_depth(int)

Parameter: An integer with the line where to get the fold depth (0 based index).

Return: An integer indicating how many fold point there're on current line.

This functions returns how many fold point there're on current line. This depends on the language. As example for CSS code, the fold point will be marked by a parentheses, but in python it will be marked by white spaces as tabs and spaces have a meaning for python syntax, meanwhile it have no meaning for CSS syntax.


import cssed

current_line = cssed.get_current_line()
cssed.output_write("Fold depth at current line: %d" % cssed.get_fold_depth(current_line))
				

5.2.23. get_fold_level()

Signature: int get_fold_level(int)

Parameter: An integer with the line where to get the fold level (0 based index).

Return: An integer indicating the fold level.

This functions fold level on current line. This depends on the language. This value only have a meaning for the scintilla control. If you want to know on how many fold points is nested current line, use get_fold_depth instead.


import cssed

current_line = cssed.get_current_line()
cssed.output_write("Fold level at current line: %d" % cssed.get_fold_level(current_line))
				

5.2.24. get_folding_enabled()

Signature: boolean get_folding_enabled(None)

Parameter: None.

Return: A boolean indicating if the user enabled folding.

This functions returns a boolean (True or False) telling if the user have choose to enable folding. Folding may be enabled and the language could have no folding capabilities. Not all languages support folding.


import cssed

if cssed.get_folding_enabled():
	current_line = cssed.get_current_line()
	cssed.output_write("Fold level at current line: %d" % cssed.get_fold_level(current_line))
				

5.2.25. get_folding_margin_visible()

Signature: boolean get_folding_margin_visible(None)

Parameter: None.

Return: A boolean indicating if the folding margin is visible.

This functions returns a boolean (True or False) telling if the folding margin is visible for the user.


import cssed

if cssed.get_folding_enabled() and cssed.get_folding_margin_visible():
	current_line = cssed.get_current_line()
	cssed.output_write("Fold level at current line: %d" % cssed.get_fold_level(current_line))
				

5.2.26. get_global_python_directory()

Signature: str get_global_python_directory(None)

Parameter: None.

Return: An string with the full path to the global - system wide - python directory.

This functions returns an string with the full path to the global - system wide - python directory. Read the section Environment setup to learn more about this.


import cssed

globaldir = cssed.get_global_python_directory()
userdir = cssed.get_user_python_directory()
cssed.output_write("Cssed will search for script on %s and %s" % (globaldir, userdir))
				

5.2.27. get_length()

Signature: int get_length(None)

Parameter: None.

Return: A integer indicating the byte length of currently opened document.

This function returns the bytes count on current document. It may be or not the same as the character count. When using multi-byte characters on cssed, could be needed more than one byte for a single char. To know the character length use len(cssed.get_text()) instead cssed.get_length().


import cssed

cssed.output_write("Current document length %d" % cssed.get_length())
				

5.2.28. get_line_count()

Signature: int get_line_count(None)

Parameter: None.

Return: A integer indicating how many lines have the current document.

This function returns the number of text lines on current document.


import cssed

cssed.output_write("Current document lines %d" % cssed.get_line_count())
				

5.2.29. get_line_end_from_position()

Signature: int get_line_end_from_position(int)

Parameter: A integer with the position.

Return: A integer indicating where is the end of the line at a given position.

This function returns where the line end is at a given position. This function is a bit buggy right now, and is not recommended to use it.


import cssed
pos = cssed.get_current_position()
cssed.output_write("Line end is at %d" % cssed.get_line_end_from_position(pos))
				

5.2.30. get_line_from_position()

Signature: int get_line_from_position(int)

Parameter: A integer with the position.

Return: A integer indicating where is the end of the line at a given position.

This function returns where the line end is at a given position. This function is a bit buggy right now, and is not recommended to use it.


import cssed
pos = cssed.get_current_position()
cssed.output_write("Current line is %d" % cssed.get_line_from_position(pos))
				

5.2.31. get_line_is_visible()

Signature: boolean get_line_is_visible(int)

Parameter: A integer with the line.

Return: A boolean indicating whereif the line is visible for the user or not.

Lines in the text buffer may not the same as in the document's view, if folding is enabled and there are fold points closed. In this case, some lines are hidden to the user and when you move the caret to those lines it will not be seen by the user leading in confusion.


import cssed

if !cssed.get_line_is_visible(3):
	cssed.ensure_line_is_visible(3)

cssed.set_current_line(3)
				

5.2.32. get_line_length()

Signature: int get_line_length(int)

Parameter: The line where to extract its length.

Return: An integer with the character length of the given line. The line number is a 0 based index (first line is 0).

This methods returns the character length of any given line. If the line does not exists this function will return 0.


import cssed

cssed.output_write( "Current line have length %d" % cssed.get_line_length(cssed.get_current_line()) )
				

5.2.33. get_modified()

Signature: boolean get_modified(None)

Parameter: None.

Return: A boolean indicating the modification flag.

This methods returns a boolean indicating if current document have been modified on cssed. When you save a file it's flagged as non modified, and when you change it into cssed is flagged as modified,


import cssed

if cssed.get_modified():
	cssed.error_message("File is modified, remember to save it")
else:
	cssed.error_message("File is not modified. It's safe to close this file")
				

5.2.34. get_num_docs()

Signature: int get_num_docs(None)

Parameter: None.

Return: An integer indicating the number of documents opened on cssed

This methods returns integer indicating the number of documents opened on cssed, this can be used to switch from one document to other as most actions will take place in the current document. There'll be allways at least one document opened on cssed so the minimum return value is 1.


import cssed

ndocs = cssed.get_num_docs()
cssed.error_message("There are %d documents opened" % ndocs)
				

5.2.35. get_position_from_line()

Signature: int get_position_from_line(int)

Parameter: An integer with the line number (0 based index).

Return: An integer indicating the character position at start of the given line or -1 on error.

This methods is used to know what character position is at the start of the given line. If the line does not exists -1 is returned.


import cssed

lpos = cssed.get_position_from_line(2)
cssed.error_message("Line 3 is at position %d" % lpos)
				

5.2.36. get_selected_text()

Signature: (None|str) get_selected_text(None)

Parameter: None.

Return: An string with the text selected on current document or None if there is no selection.

If there's text selected in the current document, this function will return a string containing the text, if there's no text selected this function will return None.


import cssed

text = cssed.get_selected_text()
if text != None:
	cssed.error_message("You selected:\n%s" % text)
else:
	cssed.error_message("No text selected")
				

5.2.37. get_selection_end()

Signature: int get_selection_end(None)

Parameter: None.

Return: An integer with the character position at the end of selected text.

This method returns an iteger with the character position at the end of selected text if there's some text selected, or the caret position otherwise. In this case - no selection - cssed.get_selection_end() will return the same value as cssed.get_selection_start().


import cssed

end = cssed.get_selection_end()
cssed.error_message("The end of current selected text is at %d" % end)
				

5.2.38. get_selection_start()

Signature: int get_selection_start(None)

Parameter: None.

Return: An integer with the character position at the start of selected text.

This method returns an iteger with the character position at the start of selected text if there's some text selected, or the caret position otherwise. In this case - no selection - cssed.get_selection_start() will return the same value as cssed.get_selection_end().


import cssed

start = cssed.get_selection_start()
cssed.error_message("The start of current selected text is at %d" % end)
				

5.2.39. get_style_at()

Signature: int get_style_at(int)

Parameter: An integer containing the character position where to get the style.

Return: An integer with the style at the given position.

This method returns an integer with the style at the given position. This value only have a meaning for the scintilla control. You can get the valid style values from SciLexer.h in the scintilla module on cssed's source tree.


import cssed

stylr = cssed.get_style_at(0)
cssed.error_message("The style at position 0 is %d" % style)
				

5.2.40. get_text()

Signature: str get_text(None)

Parameter: None.

Return: An string with the document's text.

This method returns an istring with the whole document's text.


import cssed

text = cssed.get_text()
cssed.set_current_position(cssed.get_length())
cssed.add_text("\n\nCOPY:\n\n")
cssed.add_text(text)
				

5.2.41. get_text_line()

Signature: (None|str) get_text_line(int)

Parameter: An integer with the liene number (0 based index).

Return: An string with the line's text or None on error (line does not exists).

This method returns an string with the given line's text, or None if the line number is out of range - does not exists at current document.


import cssed

text = cssed.get_text_line(30)
cssed.set_current_position(cssed.get_length())
if text != None:
	cssed.output_write("Line 30 %s\n" % text)
else:
	cssed.error_message("Line 31 does not exists")
				

5.2.42. get_user_python_directory()

Signature: str get_user_python_directory(None)

Parameter: None.

Return: An string with the full path to the user's python directory.

This functions returns an string with the full path to the user's python directory. Read the section Environment setup to learn more about this.


import cssed

globaldir = cssed.get_global_python_directory()
userdir = cssed.get_user_python_directory()
cssed.output_write("Cssed will search for script on %s and %s" % (globaldir, userdir))
				

5.2.43. interpreter_decref()

Signature: int interpreter_decref(None)

Parameter: None.

Return: An integer with the interpreter reference count.

This method decrease the interpreter reference count. Read the section "Interpreter Reference count" for more information.


import cssed

if cssed.interpreter_refcount() > 0:
	cssed.interpreter_decref() # Never do this !!! 
				

5.2.44. interpreter_init_script()

Signature: (None|str) interpreter_init_script(None)

Parameter: None.

Return: An string with the interpreter init script or None.

Your version may be compiled with support to load an initial script on each interpreter initialization or not. If your cssed python script build have no support for this feature this method will return None, if it have such support it will return a string with the file's name of the initial script to load. Read Environment setup sction for more information on this.


import cssed
import os

initscript = cssed.interpreter_init_script()
if initscript == None:
	cssed.output_write("There's no support for initial script on this build")
else:
	cssed.output_write("The interpreter will load\n%s\non initiallization if it exists.", initscript)
	if os.path.exists(initscript):
		cssed.output_write("This file exists on this system")
	else:
		cssed.output_write("This file does not exists on this system")
				

5.2.45. interpreter_ref()

Signature: int interpreter_ref(None)

Parameter: None.

Return: An integer with the interpreter reference count.

This method increase the interpreter reference count. Read the section "Interpreter Reference count" for more information.


import cssed

cssed.interpreter_ref() # Next script will run in the same environment
				

5.2.46. interpreter_refcount()

Signature: int interpreter_refcount(None)

Parameter: None.

Return: An integer with the interpreter reference count.

This method returns the interpreter reference count. Read the section "Interpreter Reference count" for more information.


import cssed

cssed.output_write("Reference count %d" % cssed.interpreter_refcount())
				

5.2.47. is_autocompletion_active()

Signature: boolean is_autocompletion_active(None)

Parameter: None.

Return: An boolean indicating if the user activated auto-completion.

This method returns boolean indicating if the user activated auto-completion.


import cssed

if cssed.is_autocompletion_active():
	cssed.output_write("Auto-completion active for the current document")
				

5.2.48. is_bookmark_set_at_line()

Signature: boolean is_bookmark_set_at_line(int)

Parameter: An integer with the line number (0 based index).

Return: A boolean indicating if there's a bookmark in a given line.

This method returns a boolean indicating if there's a bookmark at the given line, bookmarks are a user choice so it's much better to avoid to change them.


import cssed

if cssed.is_bookmark_set_at_line(cssed.get_current_line()):
	cssed.output_write("There's a bookmark at current line")
				

5.2.49. is_calltip_active()

Signature: boolean is_calltip_active(None)

Parameter: None

Return: A boolean indicating if there's a calltip being shown on screen.

This method returns a boolean indicating if there's a calltip being shown on screen, this is usefull as some functions may require an active calltip such as cancel_calltip or calltip_get_pos_start.


import cssed

if cssed.is_calltip_active():
	cssed.cancel_calltip()
				

5.2.50. is_file_opened()

Signature: boolean is_file_opened(str)

Parameter: An string with the file's full path.

Return: A boolean indicating if the given file is opened on cssed.

This method returns a boolean indicating if the given file name is opened on cssed. If this function returns True, cssed will switch to this document.


import cssed
import os

if not cssed.is_file_opened(os.path.expanduser("~/filename")):
	cssed.output_write("File is not opened")
				

5.2.51. is_folding_enabled()

Signature: boolean is_folding_enabled(None)

Parameter: None.

Return: A boolean indicating if the user enabled folding.

This method returns a boolean indicating if the user enabled folding. Some languages have no folding support and documents of those language types can't enable folding even while the user selected it.


import cssed
import os

if cssed.is_folding_enabled():
	cssed.output_write("Folding is enabled for this document")
				

5.2.52. is_marker_set_at_line()

Signature: boolean is_marker_set_at_line(int)

Parameter: An integer with the line number (0 based index).

Return: A boolean indicating if there is a marker at the given line.

This method returns a boolean indicating if there's a marker at the given line. Markers are always programatically added - not as bookmarks that are added by the user - and it's OK to change them as you wish.


import cssed

# This will toggle a marker at current line
line = cssed.get_current_line()
cssed.set_marker_at_line(line, not cssed.is_marker_set_at_line(line))
				

5.2.53. marker_next()

Signature: boolean marker_next(None)

Parameter: None.

Return: A boolean indicating if the marker exists.

This method returns a boolean indicating if there's a marker below the current line. If this function returns True the caret will move to the marker's line.


import cssed

if not cssed.marker_next():
	cssed.error_message ("No next marker")
				

5.2.54. marker_prev()

Signature: boolean marker_prev(None)

Parameter: None.

Return: A boolean indicating if the marker exists.

This method returns a boolean indicating if there's a marker above the current line. If this function returns True the caret will move to the marker's line.


import cssed

if not cssed.marker_prev():
	cssed.error_message ("No previous marker")
				

5.2.55. new_document()

Signature: boolean new_document(None)

Parameter: None.

Return: A boolean indicating if the new document have been created.

This method will open a new empty document on cssed.If this function returns True, the blank new document will be the current one.


import cssed

if cssed.new_document():
	cssed.add_text ("Document created from python")
				

5.2.56. open_file()

Signature: None open_file(str)

Parameter: An string with the full path to the file.

Return: None.

This method will open a given file on cssed.An error message will be shown to the user on error. Use is_file_opened to know if this function succeed.


import cssed
import os

cssed.open_file(os.path.expanduser("~/test.file"))
				

5.2.57. output_clear()

Signature: None output_clear(None)

Parameter: None.

Return: None.

This method will "clean" the output window - erase all contents on it.


import cssed

cssed.output_clear():
cssed.output_write("Hi")
				

5.2.58. output_write()

Signature: None output_write(str)

Parameter: The string to write to output.

Return: None.

This method will write the text passed on cssed's output window. This window will take the text passed as Pango markup so you can use colors and fonts on it easily. If you'll feed random text to the program output you must first clean up all "<" and ">"characters as in the example below.

A pattern with the form "/full/path/to/file:line_number: text" will be taken as a link, if the user double clicks on it, in the output window. The file will be opened - if it's not opened it will be selected - and the caret will be moved to the line number.


import cssed
import os

def clean_markup(str):
	str = str.replace("&", "&amp;")
	str = str.replace("<", "&lt;")
	str = str.replace(">", "&gt;")
	return str

cssed.output_write ("<span color='navy'>Hi</span>")
cssed.output_write (clean_markup("<span color='navy'>Hi</span>"))
cssed.output_write ("%s:2: your bashrc line 2, double click here" % os.path.expanduser("~/.bashrc"))
				

5.2.59. paste()

Signature: None paste(str)

Parameter: None.

Return: None.

This method is used to paste the clipboard contents on current document.


import cssed

if cssed.get_selection_end() > cssed.get_selection_start():
	cssed.copy()
	for i in range(10):
		cssed.paste()
				

5.2.60. prompt_for_directory_to_create()

Signature: (str|None) prompt_for_directory_to_create(str [,str])

Parameter: A string with the dialog title.

Parameter: (Optional) The base directory.

Return: A string with the path to the selected directory, or None on cancel.

This method shows a file selector dialog, suited to return a directory name that may exists or not. It will return a string containing the full path to the directory, or None on cancel. If the optional parameter is passed with a string containing the path to an existing directory, it will be opened on dialog startup.


import cssed
import os

dir = cssed.prompt_for_directory_to_create("Dialog's title", os.path.expanduser("~/")):
if dir not None:
	cssed.output_write(dir)
				

5.2.61. prompt_for_directory_to_open()

Signature: (str|None) prompt_for_directory_to_open(str [,str])

Parameter: A string with the dialog title.

Parameter: (Optional) The base directory.

Return: A string with the path to the selected directory, or None on cancel.

This method shows a file selector dialog, suited to return a directory name that must exists. It will return a string containing the full path to the directory, or None on cancel. If the optional parameter is passed with a string containing the path to an existing directory, it will be opened on dialog startup.


import cssed
import os

dir = cssed.prompt_for_directory_to_open("Dialog's title", os.path.expanduser("~/")):
if dir not None:
	cssed.output_write(dir)
				

5.2.62. prompt_for_file_to_open()

Signature: (str|None) prompt_for_file_to_open(str [,str])

Parameter: A string with the dialog title.

Parameter: (Optional) The base directory.

Return: A string with the path to the selected file, or None on cancel.

This method shows a file selector dialog, suited to return a file name that must exists. It will return a string containing the full path to the directory, or None on cancel. If the optional parameter is passed with a string containing the path to an existing directory, it will be opened on dialog startup.


import cssed
import os

dir = cssed.prompt_for_file_to_open("Dialog's title", os.path.expanduser("~/")):
if dir not None:
	cssed.output_write(dir)
				

5.2.63. prompt_for_file_to_save()

Signature: (str|None) prompt_for_file_to_save(str [,str])

Parameter: A string with the dialog title.

Parameter: (Optional) The base directory.

Return: A string with the path to the selected file, or None on cancel.

This method shows a file selector dialog, suited to return a file name that may exists or not. It will return a string containing the full path to the directory, or None on cancel. If the optional parameter is passed with a string containing the path to an existing directory, it will be opened on dialog startup.


import cssed
import os

dir = cssed.prompt_for_file_to_save("Dialog's title", os.path.expanduser("~/")):
if dir not None:
	cssed.output_write(dir)
				

5.2.64. redo()

Signature: None redo(None)

Parameter: None.

Return: None.

This method returns the document to a state that have previously reverted by "undoing" the effects of one or more actions. If there are actions in the "redo" queue - "undo" have been called one or more times - this method will change the document to the former state by reverting the first action in the redo queue.


import cssed

if cssed.can_redo():
	cssed.redo()
				

5.2.65. replace_sel()

Signature: None replace_sel(str)

Parameter: A string to replace the selected text.

Return: None.

This function replaces the text selected on current document, with the string passed as parameter.


import cssed

text = cssed.get_selected_text()
if text != None:
	cssed.replace_sel(text.title())
else:
	cssed.error_message("Select some text to convert to 'title case'")
				

5.2.66. save_document()

Signature: boolean save_document(None)

Parameter: None.

Return: A boolean indicating sucess or failure.

This function saves the current document. If it's unnamed a file selector dialog is shown to select a file name. Returns True on success, False on failure.


import cssed

if cssed.get_modified():
	cssed.save_document()
				

5.2.67. save_document_as()

Signature: boolean save_document_as(str)

Parameter: A string with the new file name (full path).

Return: A boolean indicating sucess or failure.

This function saves the current document in other location.


import cssed

if cssed.get_modified():
	cssed.save_document_as()
				

5.2.68. search_next()

Signature: None search_next(str)

Parameter: A string to search for.

Return: None.

This method searches the given text forwards. If it's found the caret is moved to the matching text, and it's selected.


import cssed

cssed.search_next("a")
				

5.2.69. search_prev()

Signature: None search_prev(str)

Parameter: A string to search for.

Return: None.

This method searches the given text backwards. If it's found the caret is moved to the matching text, and it's selected.


import cssed

cssed.search_prev("a")
				

5.2.70. select_text_range()

Signature: None select_text_range(int, int)

Parameter: A integer with the start position.

Parameter: A integer with the start position.

Return: None.

This method selects - if possible - the range of text given as parameter to the function.

Warning

This function is deprecated and should not be used in newly written code. Use set_selection_range instead.


import cssed

if cssed.get_length() > 10:
	cssed.select_text_range(0, 9)
				

5.2.71. set_arrow_marker_at_line()

Signature: None set_arrow_marker_at_line(int)

Parameter: A integer with the line number.

Return: None.

This moves the arrow marker to the given line if it exists. The caret is scrolled into the view if the arrow marker is not visible on screen.


import cssed

cssed.set_arrow_marker_at_line(0)
				

5.2.72. set_bookmark_at_line()

Signature: None set_bookmark_at_line(int, boolean)

Parameter: A integer with the line number.

Return: A boolean indicating if the bookmark will be set or unset.

This method is used to set/unset a bookmark at a given line. Bookmarks are user defined and is better not to play with them. In most cases is better to use set_marker_at_line.


import cssed

# this wil toggle a bookmark at current line
line = cssed.get_current_line()
cssed.set_bookmark_at_line(line, not cssed.is_bookmark_set_at_line(line))
				

5.2.73. set_current_line()

Signature: None set_current_line(int)

Parameter: A integer with the line number.

Return: None.

This method will move the caret to the given line number if possible. The caret is scrolled into view, if the line is not visible on screen.


import cssed

# move to document's start
cssed.set_current_line(0)
				

5.2.74. set_current_position()

Signature: None set_current_position(int)

Parameter: A integer with the character position.

Return: None.

This method will move the caret to the given position if possible. The caret is scrolled into view, if the line is not visible on screen.


import cssed

# move to document's start
cssed.set_current_position(0)
				

5.2.75. set_document_by_index()

Signature: None set_document_by_index(int)

Parameter: A integer with document's index.

Return: None.

This method will set the given document's index as the current document if possible.


import cssed

# move to first document in the document's tab
cssed.set_document_by_index(0)
				

5.2.76. set_folding_margin_visible()

Signature: None set_folding_margin_visible(boolean)

Parameter: A boolean with the value of the "visible" property.

Return: None.

This method will set the folding margin visible or not, depending on the value of the boolean pased as parameter.


import cssed

# hide folding margin
cssed.set_folding_margin_visible(False)
				

5.2.77. set_marker_at_line()

Signature: None set_marker_at_line(int, boolean)

Parameter: A integer with the line number.

Parameter: A boolean indicating if the marker will be set or unset.

Return: None.

This method is used to set/unset a marker at a given line.


import cssed

# this wil toggle a marker at current line
line = cssed.get_current_line()
cssed.set_marker_at_line(line, not cssed.is_marker_set_at_line(line))
				

5.2.78. set_selection_end()

Signature: None set_selection_end(int)

Parameter: A integer with the position.

Return: None.

This sets the text selected on screen from the caret position to the given position, if the later is greater than the former.


import cssed

cssed.set_current_position(0)
cssed.set_selection_end(10)
				

5.2.79. set_selection_range()

Signature: None set_selection_range(int, int)

Parameter: A integer with the start position.

Parameter: A integer with the end position.

Return: None.

This method selects - if possible - the range of text given as parameter to the function.


import cssed

if cssed.get_length() > 10:
	cssed.set_selection_range(0, 9)
				

5.2.80. set_selection_start()

Signature: None set_selection_start(int)

Parameter: A integer with the position.

Return: None.

This sets the the caret position to the given position to start a selection range, use set_selection_end to select the end of the selection. You can set the whole selection with a single call to select_text_range.


import cssed

cssed.set_selection_start(0)
cssed.set_selection_end(10)
				

5.2.81. show_autocompletion_list()

Signature: None show_autocompletion_list(int, str)

Parameter: An integer with the length of the word to complete, that's written on screen.

Parameter: A string with the auto-completion list items.

Return: None.

This method will show on screen a auto-completion list at caret position. The word will be automatically completed if the user selects an item on the list. The first parameter must be an integer with the length of text that's already written on scree. This amount of text will be discarded by the auto-completion mechanism. As example if you'd like to autocomplete the word "set_" you must pass a length of 4 characters to be discarded and not written as they're already written on screen.

The word list to show must be contained on the string passed as second parameter, with the format of a space character delimited list of sorted words. As example "felicitate felicitated felicitates felicitating" is a valid word list.


import cssed
import os

# you need the "look" command on your system to run this script

start = cssed.get_selection_start()
end = cssed.get_selection_end()

if start == end:
	cssed.error_message("Select text to complete","No selection")
else:
	text = cssed.get_selected_text()
	cssed.set_current_position(end)
	output = os.popen("look %s" % text).read()
	list = output.split("\n")
	list.sort()
	if len(output) > 0:
		cssed.show_autocompletion_list(len(text), " ".join(list))
				

5.2.82. show_calltip()

Signature: None show_calltipshow_calltip(int, str)

Parameter: An integer with calltip start character position.

Parameter: A string with the call tip definition.

Return: None.

This method will show on screen a call tip at the given position.

The call tip definition should have one or more lines separated by '\n' line feed.


import cssed

pos = cssed.get_current_position()
cssed.show_calltip(pos, "show_calltipshow_calltip(int, str)")
				

5.2.83. show_user_list()

Signature: None show_user_list(str)

Parameter: A string with the list items.

Return: None.

This method will show on screen a list of words at caret position. The word will be automatically added to the current document. The main difference between user list and auto completion lists - on cssed - is the former does not auto-complete the a word but shows the user a set of options.

The word list to show must be contained on the string passed as second parameter, with the format of a space character delimited list of sorted words. As example "felicitate felicitated felicitates felicitating" is a valid word list.


import cssed

options = "felicitate felicitated felicitates felicitating"
cssed.show_user_list(options)
				

5.2.84. toggle_fold_at_line()

Signature: None toggle_fold_at_line(int)

Parameter: An integer with the line where to toggle the folding.

Return: None.

This method will toggle a fold point at a given line. If it's closed it'll unfold it, if it's opened it will fold it.


import cssed

cssed.toggle_fold_at_line(2)
				

5.2.85. undo()

Signature: None undo(None)

Parameter: None.

Return: None.

This method returns the document to a previous state by "undoing" the effects of one or more actions. . If there are actions in the "undo" queue this method will change the document to a later state by reverting the first action in the undo queue.


import cssed

if cssed.can_undo():
	cssed.undo()
				

5.2.86. unfold_all()

Signature: None unfold_all(None)

Parameter: None.

Return: None.

This method will unfold all foild points closed in the current document if any.


import cssed

cssed.unfold_all()
				

5.2.87. zoom_in()

Signature: None zoom_in(None)

Parameter: None.

Return: None.

This method will "zoom in" the text - increase its size - on current document.


import cssed

cssed.zoom_in()
				

5.2.88. zoom_off()

Signature: None zoom_off(None)

Parameter: None.

Return: None.

This method will revert all previous "zoom" commands by reverting the text to its normal state.


import cssed

cssed.zoom_off()
				

5.2.89. zoom_out()

Signature: None zoom_out(None)

Parameter: None.

Return: None.

This method will "zoom out" the text - decrease its size - on current document.


import cssed

cssed.zoom_out()
				

5.3. Undocumented functions

Those functions are not documented yet.