gtksourceview::SourceBuffer Class Reference

The model for SourceView widgets. More...

#include <sourcebuffer.h>

List of all members.

Public Types

typedef SourceBuffer CppObjectType
typedef SourceBuffer_Class CppClassType
typedef GtkSourceBuffer BaseObjectType
typedef GtkSourceBufferClass BaseClassType

Public Member Functions

virtual ~SourceBuffer ()
GtkSourceBuffergobj ()
 Provides access to the underlying C GObject.
const GtkSourceBuffergobj () const
 Provides access to the underlying C GObject.
GtkSourceBuffergobj_copy ()
 Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
bool get_check_brackets () const
 Determines whether bracket match highlighting is activated for the source buffer.
void set_check_brackets (bool check_brackets=true)
 controls the bracket match highlighting function in the buffer.
void set_bracket_match_style (const SourceTagStyle &style)
 Sets the style used for highlighting matching brackets.
bool get_highlight () const
 Determines whether text highlighting is activated in the source buffer.
void set_highlight (bool highlight=true)
 controls whether text is highlighted in the buffer.
int get_max_undo_levels () const
 Determines the number of undo levels the buffer will track for buffer edits.
void set_max_undo_levels (int max_undo_levels)
 Sets the number of undo levels for user actions the buffer will track.
Glib::RefPtr< SourceLanguageget_language ()
 Determines the GtkSourceLanguage used by the buffer.
Glib::RefPtr< const SourceLanguageget_language () const
 Determines the GtkSourceLanguage used by the buffer.
void set_language (Glib::RefPtr< SourceLanguage > language)
 Sets the GtkSourceLanguage the source buffer will use.
gunichar get_escape_char () const
 Determines the escaping character used by the source buffer highlighting engine.
void set_escape_char (gunichar escape_char)
 Sets the escape character to be used by the highlighting engine.
bool can_undo () const
 Determines whether a source buffer can undo the last action.
bool can_redo () const
 Determines whether a source buffer can redo the last action.
void undo ()
 Undoes the last user action which modified the buffer.
void redo ()
 redoes the last undo operation.
void begin_not_undoable_action ()
 Marks the beginning of a not undoable action on the buffer, disabling the undo manager.
void end_not_undoable_action ()
 Marks the end of a not undoable action on the buffer.
Glib::RefPtr< SourceMarkercreate_marker (const Glib::ustring &name, const Glib::ustring &type, const Gtk::TextIter &where)
 Creates a marker in the buffer of type type.
void move_marker (Glib::RefPtr< SourceMarker > &marker, const Gtk::TextIter &where)
 Moves marker to the a new location.
void delete_marker (Glib::RefPtr< SourceMarker > &marker)
 Deletes marker from the source buffer. The same conditions as for Gtk::TextMark apply here. The marker is no longer accessible from the buffer, but if you held a reference to it, it will not be destroyed.
Glib::RefPtr< SourceMarkerget_marker (const Glib::ustring &name)
 Looks up the GtkSourceMarker named name in buffer, returning NULL if it doesn't exists.
Glib::RefPtr< const SourceMarkerget_marker (const Glib::ustring &name) const
 Looks up the GtkSourceMarker named name in buffer, returning NULL if it doesn't exists.
Glib::SListHandle< Glib::RefPtr<
SourceMarker > > 
get_markers_in_region (const Gtk::TextIter &begin, const Gtk::TextIter &end)
 get an ordered (by position) list of SourceMarker objects inside the region delimited by the GtkTextIter begin and end.
Glib::RefPtr< SourceMarkerget_first_marker ()
 get an ordered (by position) list of SourceMarker objects inside the region delimited by the GtkTextIter begin and end.gets the first (nearest to the top of the buffer) marker in buffer.
Glib::RefPtr< const SourceMarkerget_first_marker () const
 gets the first (nearest to the top of the buffer) marker in buffer.
Glib::RefPtr< SourceMarkerget_last_marker ()
 returns the last (nearest to the bottom of the buffer) marker in buffer.
Glib::RefPtr< const SourceMarkerget_last_marker () const
 returns the last (nearest to the bottom of the buffer) marker in buffer.
Gtk::TextIter get_iter_at_marker (const Glib::RefPtr< SourceMarker > &marker)
 gets an iterator pointing at the location of a given marker.
Glib::RefPtr< SourceMarkerget_next_marker (Gtk::TextIter &iter)
 gets the nearest marker to the right of iter.
Glib::RefPtr< const SourceMarkerget_next_marker (Gtk::TextIter &iter) const
 gets the nearest marker to the right of iter.
Glib::RefPtr< SourceMarkerget_prev_marker (Gtk::TextIter &iter)
 gets the nearest marker to the left of iter.
Glib::RefPtr< const SourceMarkerget_prev_marker (Gtk::TextIter &iter) const
 gets the nearest marker to the left of iter.
signals
Glib::SignalProxy1< void,
bool > 
signal_can_redo ()
 Emitted whenever there is a change in the buffer's ability to redo an operation.
Glib::SignalProxy1< void,
bool > 
signal_can_undo ()
 Emitted whenever there is a change in the buffer's ability to undo an operation.
Glib::SignalProxy2< void,
Gtk::TextIter &, Gtk::TextIter & > 
signal_highlight_updated ()
 Emitted whenever the syntax highlighting information has been updated, so that views can request a redraw if the region changed is visible.
Glib::SignalProxy1< void,
Gtk::TextIter & > 
signal_marker_updated ()
 Emitted whenever a marker of sourcebuffer has changed and needs to be redisplayed by the view.

Static Public Member Functions

static GType get_type () G_GNUC_CONST
static GType get_base_type () G_GNUC_CONST
static Glib::RefPtr< SourceBuffercreate (Glib::RefPtr< SourceTagTable > &tagtable)
 create a new SourceBuffer, from a SourceTagTable.
static Glib::RefPtr< SourceBuffercreate (Glib::RefPtr< SourceLanguage > &language)

Protected Member Functions

 SourceBuffer (const Glib::ConstructParams &construct_params)
 SourceBuffer (GtkSourceBuffer *castitem)
 SourceBuffer ()
 SourceBuffer (Glib::RefPtr< SourceTagTable > &tagtable)
 SourceBuffer (Glib::RefPtr< SourceLanguage > &language)

Friends

class SourceBuffer_Class

Related Functions

(Note that these are not member functions.)

Glib::RefPtr< gtksourceview::SourceBufferwrap (GtkSourceBuffer *object, bool take_copy=false)


Detailed Description

The model for SourceView widgets.

It extends the TextBuffer object by adding features necessary to display and edit source code: syntax highlighting, bracket matching and markers. It also implements support for undo/redo operations. To create a SourceBuffer use SourceBuffer::create(). By default highlighting is enabled, but you can disable it with SourceBuffer::set_highlight(). This can be useful if you're not using SourceLanguage objects to set the highlighting patterns, and instead you're manually adding SourceTag objects to the buffer's tag table.


Member Typedef Documentation

typedef SourceBuffer gtksourceview::SourceBuffer::CppObjectType

typedef SourceBuffer_Class gtksourceview::SourceBuffer::CppClassType

typedef GtkSourceBuffer gtksourceview::SourceBuffer::BaseObjectType

typedef GtkSourceBufferClass gtksourceview::SourceBuffer::BaseClassType


Constructor & Destructor Documentation

gtksourceview::SourceBuffer::SourceBuffer ( const Glib::ConstructParams &  construct_params  )  [explicit, protected]

gtksourceview::SourceBuffer::SourceBuffer ( GtkSourceBuffer castitem  )  [explicit, protected]

virtual gtksourceview::SourceBuffer::~SourceBuffer (  )  [virtual]

gtksourceview::SourceBuffer::SourceBuffer (  )  [protected]

gtksourceview::SourceBuffer::SourceBuffer ( Glib::RefPtr< SourceTagTable > &  tagtable  )  [explicit, protected]

gtksourceview::SourceBuffer::SourceBuffer ( Glib::RefPtr< SourceLanguage > &  language  )  [explicit, protected]


Member Function Documentation

static GType gtksourceview::SourceBuffer::get_type (  )  [static]

static GType gtksourceview::SourceBuffer::get_base_type (  )  [static]

GtkSourceBuffer* gtksourceview::SourceBuffer::gobj (  )  [inline]

Provides access to the underlying C GObject.

const GtkSourceBuffer* gtksourceview::SourceBuffer::gobj (  )  const [inline]

Provides access to the underlying C GObject.

GtkSourceBuffer* gtksourceview::SourceBuffer::gobj_copy (  ) 

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

static Glib::RefPtr<SourceBuffer> gtksourceview::SourceBuffer::create ( Glib::RefPtr< SourceTagTable > &  tagtable  )  [static]

create a new SourceBuffer, from a SourceTagTable.

Parameters:
tagtable a tag table to be taken in account
Returns:
a new SourceBuffer

static Glib::RefPtr<SourceBuffer> gtksourceview::SourceBuffer::create ( Glib::RefPtr< SourceLanguage > &  language  )  [static]

brief create a new SourceBuffer

Parameters:
language the language to be considered by the SourceBuffer for syntax highlighting.
Returns:
a new SourceBuffer

bool gtksourceview::SourceBuffer::get_check_brackets (  )  const

Determines whether bracket match highlighting is activated for the source buffer.

Returns:
true if the source buffer will highlight matching brackets, false otherwise.

void gtksourceview::SourceBuffer::set_check_brackets ( bool  check_brackets = true  ) 

controls the bracket match highlighting function in the buffer.

If activated, when you position your cursor over a bracket character (a parenthesis, a square bracket, etc.) the matching opening or closing bracket character will be highlighted. You can specify the style with the SourceBuffer::set_bracket_match_style() function.

Parameters:
check_brackets true if you want matching brackets highlighted.

void gtksourceview::SourceBuffer::set_bracket_match_style ( const SourceTagStyle style  ) 

Sets the style used for highlighting matching brackets.

Parameters:
style the SourceTagStyle specifying colors and text attributes

bool gtksourceview::SourceBuffer::get_highlight (  )  const

Determines whether text highlighting is activated in the source buffer.

Returns:
true if highlighting is activated, false otherwise.

void gtksourceview::SourceBuffer::set_highlight ( bool  highlight = true  ) 

controls whether text is highlighted in the buffer.

If highlight is TRUE, the text will be highlighted according to the patterns installed in the buffer (either set with SourceBuffer::set_language() or by adding individual GtkSourceTag tags to the buffer's tag table). Otherwise, any current highlighted text will be restored to the default buffer style. Tags not of SourceTag type will not be removed by this option, and normal Gtk::TextTag priority settings apply when highlighting is enabled. If not using a SourceLanguage for setting the highlighting patterns in the buffer, it is recommended for performance reasons that you add all the SourceTag tags with highlighting disabled and enable it when finished.

Parameters:
highlight true if you want to activate highlighting

int gtksourceview::SourceBuffer::get_max_undo_levels (  )  const

Determines the number of undo levels the buffer will track for buffer edits.

Returns:
the maximum number of possible undo levels.

void gtksourceview::SourceBuffer::set_max_undo_levels ( int  max_undo_levels  ) 

Sets the number of undo levels for user actions the buffer will track.

If the number of user actions exceeds the limit set by this function, older actions will be discarded. A new action is started whenever the function Gtk::TextBuffer::begin_user_action() is called. In general, this happens whenever the user presses any key which modifies the buffer, but the undo manager will try to merge similar consecutive actions, such as multiple character insertions into one action. But, inserting a newline does start a new action.

Parameters:
max_undo_levels the desired maximum number of undo levels.

Glib::RefPtr<SourceLanguage> gtksourceview::SourceBuffer::get_language (  ) 

Determines the GtkSourceLanguage used by the buffer.

Returns:
the SourceLanguage set by SourceBuffer::set_language(), or nil.

Glib::RefPtr<const SourceLanguage> gtksourceview::SourceBuffer::get_language (  )  const

Determines the GtkSourceLanguage used by the buffer.

Returns:
the SourceLanguage set by SourceBuffer::set_language(), or nil.

void gtksourceview::SourceBuffer::set_language ( Glib::RefPtr< SourceLanguage language  ) 

Sets the GtkSourceLanguage the source buffer will use.

This adds GtkSourceTag tags with the language's patterns and sets the escape character with SourceBuffer::set_escape_char(). Note that this will remove any SourceTag tags currently in the buffer's tag table. The buffer holds a reference to the language set.

Parameters:
language a GtkSourceLanguage to set.

gunichar gtksourceview::SourceBuffer::get_escape_char (  )  const

Determines the escaping character used by the source buffer highlighting engine.

Returns:
the UTF-8 character for the escape character the buffer is using.

void gtksourceview::SourceBuffer::set_escape_char ( gunichar  escape_char  ) 

Sets the escape character to be used by the highlighting engine.

When performing the initial analysis, the engine will discard a matching syntax pattern if it's prefixed with an odd number of escape characters. This allows for example to correctly highlight strings with escaped quotes embedded. This setting affects only syntax patterns (i.e. those defined in GtkSyntaxTag tags).

Parameters:
escape_char the escape character the buffer should use.

bool gtksourceview::SourceBuffer::can_undo (  )  const

Determines whether a source buffer can undo the last action.

Returns:
true if it's possible to undo the last action, false otherwise.

bool gtksourceview::SourceBuffer::can_redo (  )  const

Determines whether a source buffer can redo the last action.

I.E if the last operation was an undo.

Returns:
true if it's possible to redo the last action, false otherwise.

void gtksourceview::SourceBuffer::undo (  ) 

Undoes the last user action which modified the buffer.

Use SourceBuffer::can_undo() to check whether a call to this function will have any effect. Actions are defined as groups of operations between a call to TextBuffer::begin_user_action() and TextBuffer::end_user_action(), or sequences of similar edits (inserts or deletes) on the same line.

void gtksourceview::SourceBuffer::redo (  ) 

redoes the last undo operation.

Use SourceBuffer::can_redo() to check whether a call to this function will have any effect.

void gtksourceview::SourceBuffer::begin_not_undoable_action (  ) 

Marks the beginning of a not undoable action on the buffer, disabling the undo manager.

Typically you would call this function before initially setting the contents of the buffer (e.g. when loading a file in a text editor). You may nest SourceBuffer::begin_not_undoable_action() / SourceBuffer::end_not_undoable_action() blocks.

void gtksourceview::SourceBuffer::end_not_undoable_action (  ) 

Marks the end of a not undoable action on the buffer.

When the last not undoable block is closed through the call to this function, the list of undo actions is cleared and the undo manager is re-enabled.

Glib::RefPtr<SourceMarker> gtksourceview::SourceBuffer::create_marker ( const Glib::ustring &  name,
const Glib::ustring &  type,
const Gtk::TextIter &  where 
)

Creates a marker in the buffer of type type.

A marker is semantically very similar to a GtkTextMark, except it has a type which is used by the SourceView displaying the buffer to show a pixmap on the left margin, at the line the marker is in. Because of this, a marker is generally associated to a line and not a character position. Markers are also accessible through a position or range in the buffer. Markers are implemented using Gtk::TextMark, so all characteristics and restrictions to marks apply to markers too. These includes life cycle issues and "mark-set" and "mark-deleted" signal emissions. Like a Gtk::TextMark, a SourceMarker can be anonymous if the passed name is "". Also, the buffer owns the markers so you shouldn't unreference it. Markers always have left gravity and are moved to the beginning of the line when the user deletes the line they were in. Also, if the user deletes a region of text which contained lines with markers, those are deleted. Typical uses for a marker are bookmarks, breakpoints, current executing instruction indication in a source file, etc..

Parameters:
name the name of the marker.
type a string defining the marker type.
where location to place the marker
Returns:
a newly created SourceMarker, owned by the buffer.

void gtksourceview::SourceBuffer::move_marker ( Glib::RefPtr< SourceMarker > &  marker,
const Gtk::TextIter &  where 
)

Moves marker to the a new location.

Parameters:
marker the marker you want to move in the SourceBuffer.
where the new location you want to move the marker to.

void gtksourceview::SourceBuffer::delete_marker ( Glib::RefPtr< SourceMarker > &  marker  ) 

Deletes marker from the source buffer. The same conditions as for Gtk::TextMark apply here. The marker is no longer accessible from the buffer, but if you held a reference to it, it will not be destroyed.

Parameters:
marker the marker to delete.

Glib::RefPtr<SourceMarker> gtksourceview::SourceBuffer::get_marker ( const Glib::ustring &  name  ) 

Looks up the GtkSourceMarker named name in buffer, returning NULL if it doesn't exists.

Returns:
the SourceMarker whose name is name, or nil.

Glib::RefPtr<const SourceMarker> gtksourceview::SourceBuffer::get_marker ( const Glib::ustring &  name  )  const

Looks up the GtkSourceMarker named name in buffer, returning NULL if it doesn't exists.

Returns:
the SourceMarker whose name is name, or nil.

Glib::SListHandle<Glib::RefPtr<SourceMarker> > gtksourceview::SourceBuffer::get_markers_in_region ( const Gtk::TextIter &  begin,
const Gtk::TextIter &  end 
)

get an ordered (by position) list of SourceMarker objects inside the region delimited by the GtkTextIter begin and end.

The iters may be in any order.

Returns:
the list of SourceMarkers

Glib::RefPtr<SourceMarker> gtksourceview::SourceBuffer::get_first_marker (  ) 

get an ordered (by position) list of SourceMarker objects inside the region delimited by the GtkTextIter begin and end.gets the first (nearest to the top of the buffer) marker in buffer.

Returns:
the first marker in buffer

Glib::RefPtr<const SourceMarker> gtksourceview::SourceBuffer::get_first_marker (  )  const

gets the first (nearest to the top of the buffer) marker in buffer.

Returns:
the first marker in buffer or nil if there are no markers in the buffer.

Glib::RefPtr<SourceMarker> gtksourceview::SourceBuffer::get_last_marker (  ) 

returns the last (nearest to the bottom of the buffer) marker in buffer.

Returns:
a reference to the last SourceMarker, or nil if there are no markers in the buffer.

Glib::RefPtr<const SourceMarker> gtksourceview::SourceBuffer::get_last_marker (  )  const

returns the last (nearest to the bottom of the buffer) marker in buffer.

Returns:
a reference to the last SourceMarker, or nil if there are no markers in the buffer.

Gtk::TextIter gtksourceview::SourceBuffer::get_iter_at_marker ( const Glib::RefPtr< SourceMarker > &  marker  ) 

gets an iterator pointing at the location of a given marker.

Parameters:
marker the marker we want to get the iterator at.
Returns:
the iterator.

Glib::RefPtr<SourceMarker> gtksourceview::SourceBuffer::get_next_marker ( Gtk::TextIter &  iter  ) 

gets the nearest marker to the right of iter.

If there are multiple markers at the same position, this function will always return the first one (from the internal linked list), even if starting the search exactly at its location. You can get the others using SourceMarker::next().

Parameters:
iter an iterator pointing to the location to start searching from.
Returns:
the SourceMarker nearest to the right of iter, or nil if there are no more markers after iter.

Glib::RefPtr<const SourceMarker> gtksourceview::SourceBuffer::get_next_marker ( Gtk::TextIter &  iter  )  const

gets the nearest marker to the right of iter.

If there are multiple markers at the same position, this function will always return the first one (from the internal linked list), even if starting the search exactly at its location. You can get the others using SourceMarker::next().

Parameters:
iter an iterator pointing to the location to start searching from.
Returns:
the SourceMarker nearest to the right of iter, or nil if there are no more markers after iter.

Glib::RefPtr<SourceMarker> gtksourceview::SourceBuffer::get_prev_marker ( Gtk::TextIter &  iter  ) 

gets the nearest marker to the left of iter.

If there are multiple markers at the same position, this function will always return the last one (from the internal linked list), even if starting the search exactly at its location. You can get the others using SourceMarker::prev().

Parameters:
iter an iterator pointing to the location to start searching from.
Returns:
the SourceMarker nearest to the right of iter, or nil if there are no more markers before iter.

Glib::RefPtr<const SourceMarker> gtksourceview::SourceBuffer::get_prev_marker ( Gtk::TextIter &  iter  )  const

gets the nearest marker to the left of iter.

If there are multiple markers at the same position, this function will always return the last one (from the internal linked list), even if starting the search exactly at its location. You can get the others using SourceMarker::prev().

Parameters:
iter an iterator pointing to the location to start searching from.
Returns:
the SourceMarker nearest to the right of iter, or nil if there are no more markers before iter.

Glib::SignalProxy1< void,bool > gtksourceview::SourceBuffer::signal_can_redo (  ) 

Emitted whenever there is a change in the buffer's ability to redo an operation.

parameter can_redo: true if the buffer can now perform a redo, false otherwise.

Glib::SignalProxy1< void,bool > gtksourceview::SourceBuffer::signal_can_undo (  ) 

Emitted whenever there is a change in the buffer's ability to undo an operation.

parameter can_undo: true if the buffer can now perfom an undo, false otherwise.

Glib::SignalProxy2< void,Gtk::TextIter &,Gtk::TextIter & > gtksourceview::SourceBuffer::signal_highlight_updated (  ) 

Emitted whenever the syntax highlighting information has been updated, so that views can request a redraw if the region changed is visible.

Usually only view widgets displaying this buffer will be interested in this signal. parameter start: an iterator at the start of the updated region. parameter end: and iterator at the end of the updated region.

Glib::SignalProxy1< void,Gtk::TextIter & > gtksourceview::SourceBuffer::signal_marker_updated (  ) 

Emitted whenever a marker of sourcebuffer has changed and needs to be redisplayed by the view.

A change in a marker's type or location can trigger this signal. Note that moving a marker causes the emission of this signal twice: one for the old location and one for the new. parameter where: an iterator at the location where the change occurred.


Friends And Related Function Documentation

friend class SourceBuffer_Class [friend]

Glib::RefPtr< gtksourceview::SourceBuffer > wrap ( GtkSourceBuffer object,
bool  take_copy = false 
) [related]

Parameters:
object The C instance
take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns:
A C++ instance that wraps this C instance.


The documentation for this class was generated from the following file:
Generated on Fri May 4 07:53:30 2007 for libgtksourceviewmm by  doxygen 1.5.2