gtksourceviewmm r71 - in trunk: . gtksourceview/src

[dodji svn gnome org]

Author: dodji
Date: Sun Aug 31 23:03:05 2008
New Revision: 71
URL: http://svn.gnome.org/viewvc/gtksourceviewmm?rev=71&view=rev

Log:
Updated API Doc of SourceBuffer and SourceView.


Modified:
   trunk/ChangeLog
   trunk/gtksourceview/src/sourcebuffer.hg
   trunk/gtksourceview/src/sourceview.hg

Modified: trunk/gtksourceview/src/sourcebuffer.hg
==============================================================================
--- trunk/gtksourceview/src/sourcebuffer.hg	(original)
+++ trunk/gtksourceview/src/sourcebuffer.hg	Sun Aug 31 23:03:05 2008
@@ -184,30 +184,123 @@
   /// the list of undo actions is cleared and the undo manager is re-enabled.
   _WRAP_METHOD(void end_not_undoable_action(), gtk_source_buffer_end_not_undoable_action)
 
+  /// \brief Moves iter to the position of the previous GtkSourceMark of the
+  /// given category.
+  ///
+  /// Returns true if iter was moved. If category is NULL, the
+  /// previous source mark can be of any category.
+  ///
+  /// \param iter the iterator to consider.
+  /// \param category the category to search for or NULL.
+  /// \return true if iter moved, false otherwise.
   _WRAP_METHOD(bool backward_iter_to_source_mark(Gtk::TextIter& iter, const Glib::ustring& category), gtk_source_buffer_backward_iter_to_source_mark)
   // overload with category == NULL
   bool backward_iter_to_source_mark(Gtk::TextIter& iter);
 
+  /// \brief Moves iter to the position of the next #SourceMark of the given
+  /// category.
+  ///
+  /// Returns true if iter was moved. If category is NULL, the next
+  /// source mark can be of any category.
+  /// \param iter the iterator to move.
+  /// \param category the category to search for, or NULL.
+  /// \return true if iter moved, false otherwise.
   _WRAP_METHOD(bool forward_iter_to_source_mark(Gtk::TextIter& iter, const Glib::ustring& category), gtk_source_buffer_forward_iter_to_source_mark)
-  // overload with category == NULL
+
+  /// \brief Moves iter to the position of the next #SourceMark
+  ///
+  /// Returns true if iter was moved. The category of the next #SourceMark
+  /// is considered to be NULL so that #SourceMark can be of any category.
+  ///
+  /// \param iter the iterator to move.
+  /// \return true if iter moved, false otherwise.
   bool forward_iter_to_source_mark(Gtk::TextIter& iter);
 
+  /// \brief Forces buffer to analyze and highlight the given area
+  /// synchronously.
+  ///
+  /// \param start start of the area to highlight.
+  /// \param end end of the area to highlight.
   _WRAP_METHOD(void ensure_highlight(const Gtk::TextIter& start, const Gtk::TextIter& end), gtk_source_buffer_ensure_highlight)
+
+  /// \brief Sets style scheme used by the buffer.
+  ///
+  /// \param scheme the style scheme to be used by the buffer
   _WRAP_METHOD(void set_style_scheme(const Glib::RefPtr<SourceStyleScheme>& scheme), gtk_source_buffer_set_style_scheme)
+
+  /// \brief Returns the style scheme currently used by the buffer.
+  ///
+  /// \return the style scheme currently used the buffer.
   _WRAP_METHOD(Glib::RefPtr<SourceStyleScheme> get_style_scheme(), gtk_source_buffer_get_style_scheme, refreturn)
+
+  /// \brief Returns the style scheme currently used by the buffer.
+  ///
+  /// This method is const and returns a const value.
   _WRAP_METHOD(Glib::RefPtr<const SourceStyleScheme> get_style_scheme() const, gtk_source_buffer_get_style_scheme, constversion, refreturn)
+
+  /// \brief Creates a source mark in the buffer of category #category.
+  ///
+  /// A source mark is a Gtk::TextMark but organised into categories. Depending on
+  /// the category a pixbuf can be specified that will be displayed along the
+  /// line of the mark.
+  /// Like a Gtk::TextMark, a #SourceMark can be anonymous if the passed name is
+  /// NULL.
+  ///
+  /// Note that the buffer owns the marks.
+  ///
+  /// Marks always have left gravity and are moved to the beginning of the line
+  /// when the user deletes the line they were in.
+  /// Typical uses for a source mark are bookmarks, breakpoints, current executing
+  /// instruction indication in a source file, etc..
+  ///
+  /// \param name the name of the mark, can be "".
+  /// \param category a string defining the mark category.
+  /// \param where location where to place the mark.
+  /// \return the newly created #SourceMark
   _WRAP_METHOD(Glib::RefPtr<SourceMark> create_source_mark(const Glib::ustring& name, const Glib::ustring& category, const Gtk::TextIter& where), gtk_source_buffer_create_source_mark)
 
 #m4 _CONVERSION(`GSList*',`Glib::SListHandle<Glib::RefPtr<SourceMark> >', `$2($3, Glib::OWNERSHIP_SHALLOW)')
 #m4 _CONVERSION(`GSList*',`Glib::SListHandle<Glib::RefPtr<const SourceMark> >', `$2($3, Glib::OWNERSHIP_SHALLOW)')
+
+   /// \brief Returns the list of marks of the given category at line.
+   ///
+   /// If category is NULL, all marks at line are returned.
+   ///
+   /// \param line the line number to consider.
+   /// \param category category to search for or NULL.
+   /// \param a newly allocated GSList.
+   /// \return the list of marks.
   _WRAP_METHOD(Glib::SListHandle<Glib::RefPtr<SourceMark> > get_source_marks_at_line(int line, const Glib::ustring& category) const, gtk_source_buffer_get_source_marks_at_line)
 
-  // overloaded with category == NULL
+   /// \brief Returns all source marks marks at line.
+   ///
+   /// \param line the line number to consider.
+   /// \param a newly allocated GSList.
+   /// \return the list of marks.
   Glib::SListHandle<Glib::RefPtr<SourceMark> > get_source_marks_at_line(int line) const;
+
+  /// \brief returns the list of marks of the given category at a given
+  /// itertor.
+  ///
+  /// If category is NULL it returns all marks at iter.
+  ///
+  /// \param iter the iterator to consider.
+  /// \param category the category to search for, or NULL.
   _WRAP_METHOD(Glib::SListHandle<Glib::RefPtr<SourceMark> > get_source_marks_at_iter(Gtk::TextIter& iter, const Glib::ustring& category) const, gtk_source_buffer_get_source_marks_at_iter)
-  // overloaded with category == NULL
+
+  /// \brief returns all the marks at a given iterator.
+  ///
+  /// \param iter the iterator to consider.
   Glib::SListHandle<Glib::RefPtr<SourceMark> > get_source_marks_at_iter(Gtk::TextIter& iter) const;
 
+  /// \brief Remove all marks of a given category, from a given region of the
+  //// buffer
+  ///
+  /// If category is NULL, all marks in the range will be removed.
+  ///
+  /// \param start the begining of the region to consider
+  /// \param end the end of the region to consider.
+  /// \param category the category of the marks to consider.
   _WRAP_METHOD(void remove_source_marks(const Gtk::TextIter& start, const Gtk::TextIter& end, const Glib::ustring& category), gtk_source_buffer_remove_source_marks)
 
   /// \name signals

Modified: trunk/gtksourceview/src/sourceview.hg
==============================================================================
--- trunk/gtksourceview/src/sourceview.hg	(original)
+++ trunk/gtksourceview/src/sourceview.hg	Sun Aug 31 23:03:05 2008
@@ -152,31 +152,137 @@
   /// \return true if HOME and END keys will move to the first/last non space character of the line before moving to the start/end, false otherwise
   _WRAP_METHOD(SourceSmartHomeEndType get_smart_home_end() const, gtk_source_view_get_smart_home_end)
 
+  /// \brief if true line marks will be displayed beside the text.
+  ///
+  /// \param show whether line marks should be displayed.
   _WRAP_METHOD(void set_show_line_marks(bool show = true), gtk_source_view_set_show_line_marks)
+
+  /// \brief Returns whether line marks are displayed beside the text.
+  ///
+  /// \return true if the line marks are displayed.
   _WRAP_METHOD(bool get_show_line_marks() const, gtk_source_view_get_show_line_marks)
+
+  /// If true, when the tab key is pressed and there is a
+  /// selection, the selected text is indented of one level instead of being
+  /// replaced with the \t characters. Shift+Tab unindents the selection.
+  /// \param show true if the selection is indented when tab is pressed.
   _WRAP_METHOD(void set_indent_on_tab(bool show = true), gtk_source_view_set_indent_on_tab)
+
+  /// Returns whether when the tab key is pressed the current selection
+  /// should get indented instead of replaced with the \t character.
+  ///
+  /// \return true if the selection is indented when tab is pressed.
   _WRAP_METHOD(bool get_indent_on_tab() const, gtk_source_view_get_indent_on_tab)
+
+  /// \brief Sets the number of spaces to use for each step of indent.
+  ///
+  /// If width is
+  /// -1, the value of the GtkSourceView::tab-width property will be used.
+  ///
+  /// \param width indent width in characters
   _WRAP_METHOD(void set_indent_width(gint width), gtk_source_view_set_indent_width)
+
+  /// \brief Set Returns the number of spaces to use for each step of indent.
+  ///
+  /// See SourceView::set_indent_width(gint) for details.
+  ///
+  /// \return indent width.
   _WRAP_METHOD(gint get_indent_width() const, gtk_source_view_get_indent_width)
+
+  /// \brief Set the priority for the given mark category.
+  ///
+  /// When there are multiple
+  /// marks on the same line, marks of categories with higher priorities will
+  /// be drawn on top.
+  /// \param category a mark category.
+  /// \param priority the priority of #category
   _WRAP_METHOD(void set_mark_category_priority(const Glib::ustring& category, gint priority), gtk_source_view_set_mark_category_priority)
+
+  /// \brief Gets the priority which is associated with the given category.
+  ///
+  /// \param category a mark category.
+  /// \return the priority or if category exists but no priority was set,
+  /// it defaults to 0.
   _WRAP_METHOD(gint get_mark_category_priority(const Glib::ustring& category) const, gtk_source_view_get_mark_category_priority)
+
+  /// \brief Associates a given pixbuf with a given mark category.
+  /// If pixbuf is NULL, the pixbuf is unset.
+  ///
+  /// \param category a mark category.
+  /// \param pixbuf the pixbuf to associate the mark category to.
   _WRAP_METHOD(void set_mark_category_pixbuf(const Glib::ustring& category, const Glib::RefPtr<Gdk::Pixbuf>& pixbuf), gtk_source_view_set_mark_category_pixbuf)
+  /// \brief Gets the pixbuf which is associated with the given mark category.
+  ///
+  /// \param category a mark category.
+  /// \return the associated GdkPixbuf, or NULL if not found.
   _WRAP_METHOD(Glib::RefPtr<Gdk::Pixbuf> get_mark_category_pixbuf(const Glib::ustring& category), gtk_source_view_get_mark_category_pixbuf, refreturn)
+
+  /// \brief Gets the pixbuf which is associated with the given mark category.
+  ///
+  /// \param category a mark category.
+  /// \return the associated GdkPixbuf, or NULL if not found.
   _WRAP_METHOD(Glib::RefPtr<const Gdk::Pixbuf> get_mark_category_pixbuf(const Glib::ustring& category) const, gtk_source_view_get_mark_category_pixbuf, refreturn, constversion)
 
   _WRAP_SIGNAL(void redo(), "redo")
   _WRAP_SIGNAL(void undo(), "undo")
 
+  /// \brief Whether to display line numbers
+  ///
+  /// default value is false
   _WRAP_PROPERTY("show-line-numbers", bool)
+
+  /// \brief Whether to display line mark pixbufs
+  ///
+  /// default value is false.
   _WRAP_PROPERTY("show-line-marks", bool)
+
+  /// \brief Width of an tab character expressed in number of spaces.
+  ///
+  /// Allowed values are [1,32]
+  /// Default value is 8
   _WRAP_PROPERTY("tab-width", guint)
+
+  /// \brief Width of an indentation step expressed in number of spaces.
+  ///
+  /// Allowed values are [-1,32]
+  /// Default value is -1
   _WRAP_PROPERTY("indent-width", int)
+
+  /// \brief Whether to enable auto indentation.
+  ///
+  /// Default value is false
   _WRAP_PROPERTY("auto_indent", bool)
+
+  /// \brief Whether to insert spaces instead of tabs.
+  ///
+  /// Default value is false
   _WRAP_PROPERTY("insert_spaces_instead_of_tabs", bool)
+
+  /// \brief Whether to display the right margin.
+  ///
+  /// Default value is false
   _WRAP_PROPERTY("show-right-margin", bool)
+
+  /// \brief Position of the right margin.
+  ///
+  /// Allowed values are [1,200]
+  /// Default value is 80
   _WRAP_PROPERTY("right-margin-position", guint)
+
+  /// \brief Set the behavior of the HOME and END keys.
+  ///
+  /// Default value is GTK_SOURCE_SMART_HOME_END_DISABLED
   _WRAP_PROPERTY("smart_home_end", SourceSmartHomeEndType)
+
+  /// \brief Whether to highlight the current line.
+  ///
+  /// Default value is false
   _WRAP_PROPERTY("highlight_current_line", bool)
+
+  /// \brief Whether to indent the selected text when the tab key is
+  /// pressed.
+  ///
+  /// Default value is true.
   _WRAP_PROPERTY("indent_on_tab", bool)
 
 };