SF.net SVN: geany:[2819] trunk - Commits

25 Jul 2008

Revision: 2819
          http://geany.svn.sourceforge.net/geany/?rev=2819&view=rev
Author:   ntrel
Date:     2008-07-25 14:18:49 +0000 (Fri, 25 Jul 2008)
Log Message:
-----------
Add dox for ScintillaFuncs.
Modified Paths:
--------------
    trunk/ChangeLog
    trunk/src/plugindata.h
    trunk/src/sciwrappers.c
Modified: trunk/ChangeLog
===================================================================

--- trunk/ChangeLog	2008-07-25 11:28:30 UTC (rev 2818)
+++ trunk/ChangeLog	2008-07-25 14:18:49 UTC (rev 2819)
@@ -3,6 +3,8 @@
  * src/interface.c, src/ui_utils.c, geany.glade:
    Revert editor popup menu Current Word submenu changes. See
    http://lists.uvena.de/geany-devel/2008-July/000101.html.
+ * src/sciwrappers.c, src/plugindata.h:
+   Add dox for ScintillaFuncs.
2008-07-25  Enrico Tröger  <enrico(dot)troeger(at)uvena(dot)de>
Modified: trunk/src/plugindata.h
===================================================================
--- trunk/src/plugindata.h	2008-07-25 11:28:30 UTC (rev 2818)
+++ trunk/src/plugindata.h	2008-07-25 14:18:49 UTC (rev 2819)
@@ -225,9 +225,11 @@
struct _ScintillaObject;
-/* See sciwrappers.h */
+/** See sciwrappers.h. */
 typedef struct ScintillaFuncs
 {
+	/** Send Scintilla a message.
+	 * @see http://scintilla.org for the documentation. */
    long int (*send_message) (struct _ScintillaObject* sci, unsigned int iMessage,
    		long unsigned int wParam, long int lParam);
    void	(*send_command) (struct _ScintillaObject* sci, gint cmd);
Modified: trunk/src/sciwrappers.c
===================================================================
--- trunk/src/sciwrappers.c	2008-07-25 11:28:30 UTC (rev 2818)
+++ trunk/src/sciwrappers.c	2008-07-25 14:18:49 UTC (rev 2819)
@@ -20,9 +20,12 @@
  * $Id$
  */
-/*
- * Wrappers for the SCI_* Scintilla messages.
- * Originally from the cssed project (http://cssed.sf.net).
+/** @file sciwrappers.h
+ * Wrapper functions for the Scintilla editor widget @c SCI_* messages.
+ * You should also check the http://scintilla.org documentation, as it is more detailed.
+ * @note These functions were originally from the cssed project
+ * (http://cssed.sf.net, thanks).
+ * @see ScintillaFuncs::send_message().
  */
#include <string.h>
@@ -35,9 +38,6 @@
 #define SSM(s, m, w, l) scintilla_send_message(s, m, w, l)
-/* stolen from cssed (http://cssed.sf.net), thanks */
-
-
 /* line numbers visibility */
 void sci_set_line_numbers(ScintillaObject * sci, gboolean set, gint extra_width)
 {
@@ -196,6 +196,7 @@
    }
 }
+/** Set all text. */
 void sci_set_text(ScintillaObject* sci, const gchar* text)
 {
    if( text != NULL ){ /* if null text is passed to scintilla will segfault */
@@ -247,12 +248,18 @@
 }
+/** Begin grouping a set of edits together as one Undo action.
+ * You must call sci_end_undo_action() after making your edits.
+ * @param sci Scintilla @c GtkWidget. */
 void sci_start_undo_action( ScintillaObject* sci )
 {
    SSM( sci,SCI_BEGINUNDOACTION,0,0 );
 }
+/** End grouping a set of edits together as one Undo action.
+ * @param sci Scintilla @c GtkWidget.
+ * @see sci_start_undo_action(). */
 void sci_end_undo_action( ScintillaObject* sci )
 {
    SSM( sci, SCI_ENDUNDOACTION,0,0);
@@ -362,30 +369,35 @@
 }
+/** Get line number from character index. */
 gint sci_get_line_from_position(ScintillaObject* sci, gint position )
 {
    return SSM(sci, SCI_LINEFROMPOSITION, position, 0);
 }
+/** Get column number relative to the start of the line that @a position is on. */
 gint sci_get_col_from_position(ScintillaObject* sci, gint position )
 {
    return SSM(sci, SCI_GETCOLUMN, position, 0);
 }
+/** Get character index for the start of @a line. */
 gint sci_get_position_from_line(ScintillaObject* sci, gint line )
 {
    return SSM(sci, SCI_POSITIONFROMLINE, line, 0);
 }
+/** Get cursor position. */
 gint sci_get_current_position(ScintillaObject* sci )
 {
    return SSM(sci, SCI_GETCURRENTPOS, 0, 0);
 }
+/** Set the cursor position. */
 void sci_set_current_position(ScintillaObject* sci, gint position, gboolean scroll_to_caret)
 {
    if (scroll_to_caret)
@@ -408,18 +420,21 @@
 }
+/** Get total number of lines. */
 gint sci_get_line_count( ScintillaObject* sci )
 {
    return SSM(sci, SCI_GETLINECOUNT, 0, 0);
 }
+/** Set selection start position. */
 void sci_set_selection_start(ScintillaObject* sci, gint position)
 {
    SSM(sci, SCI_SETSELECTIONSTART, position, 0);
 }
+/** Set selection end position. */
 void sci_set_selection_end(ScintillaObject* sci, gint position)
 {
    SSM(sci, SCI_SETSELECTIONEND, position, 0);
@@ -456,24 +471,28 @@
 }
+/** Get position of selection start. */
 gint sci_get_selection_start(ScintillaObject* sci)
 {
    return SSM(sci, SCI_GETSELECTIONSTART,0,0);
 }
+/** Get position of selection end. */
 gint sci_get_selection_end(ScintillaObject* sci)
 {
    return SSM(sci, SCI_GETSELECTIONEND,0,0);
 }
+/** Replace selection. */
 void sci_replace_sel(ScintillaObject* sci, const gchar* text)
 {
    SSM(sci, SCI_REPLACESEL,0, (sptr_t) text);
 }
+/** Get length of all text. */
 gint sci_get_length(ScintillaObject* sci)
 {
    return SSM(sci,SCI_GETLENGTH,0,0);
@@ -486,13 +505,14 @@
 }
+/** Get line length. */
 gint sci_get_line_length(ScintillaObject* sci,gint line)
 {
    return SSM(sci,SCI_LINELENGTH, line,0);
 }
-/* Returns: a NULL-terminated copy of the line text */
+/** Returns: a NULL-terminated copy of the line text. */
 gchar *sci_get_line(ScintillaObject* sci, gint line_num)
 {
    gint len = sci_get_line_length(sci, line_num);
@@ -504,14 +524,15 @@
 }
-/* the last char will be null terminated */
+/** The last char will be null terminated, so ensure @a text has been allocated @a len + 1
+ * bytes. */
 void sci_get_text(ScintillaObject* sci, gint len, gchar* text)
 {
    SSM( sci, SCI_GETTEXT, len, (sptr_t) text );
 }
-/* Text must be allocated sci_get_selected_text_length() + 1, because
+/** Text must be allocated sci_get_selected_text_length() + 1, because
  * the selection will be NULL-terminated. */
 void sci_get_selected_text(ScintillaObject* sci, gchar* text)
 {
@@ -519,6 +540,7 @@
 }
+/** Get selected text length. */
 gint sci_get_selected_text_length(ScintillaObject* sci)
 {
    return SSM( sci, SCI_GETSELTEXT, 0, 0);
@@ -539,13 +561,14 @@
 }
-/* folding */
+/** Returns: whether @a line should be drawn on the screen (folding may have hidden it). */
 gboolean sci_get_line_is_visible(ScintillaObject* sci, gint line)
 {
    return SSM(sci,SCI_GETLINEVISIBLE, line,0);
 }
+/** Make the @a line visible (folding may have hidden it). */
 void sci_ensure_line_is_visible(ScintillaObject* sci, gint line)
 {
    SSM(sci,SCI_ENSUREVISIBLE,line,0);
@@ -620,6 +643,7 @@
 }
+/** Get character. */
 gchar sci_get_char_at(ScintillaObject *sci, gint pos)
 {
    return (gchar) SSM(sci, SCI_GETCHARAT, pos, 0);
@@ -644,7 +668,7 @@
 }
-/* you can also call this has_selection */
+/** You can also call this has_selection. */
 gboolean sci_can_copy(ScintillaObject *sci)
 {
    if (SSM(sci, SCI_GETSELECTIONEND,0,0) - SSM(sci, SCI_GETSELECTIONSTART,0,0))
@@ -673,6 +697,7 @@
 }
+/** Scroll the cursor in view. */
 void sci_scroll_caret(ScintillaObject *sci)
 {
    SSM(sci, SCI_SCROLLCARET, 0, 0);
@@ -723,6 +748,7 @@
 }
+/** Get style number for @a position. */
 gint sci_get_style_at(ScintillaObject *sci, gint position)
 {
    return SSM(sci, SCI_GETSTYLEAT, position, 0);
@@ -747,7 +773,7 @@
 }
-/* text will be zero terminated and must be allocated (end - start + 1) bytes */
+/** Text will be zero terminated and must be allocated (end - start + 1) bytes. */
 void sci_get_text_range(ScintillaObject *sci, gint start, gint end, gchar *text)
 {
    struct TextRange tr;
@@ -770,6 +796,7 @@
 }
+/** Insert text. */
 void sci_insert_text(ScintillaObject *sci, gint pos, const gchar *text)
 {
    SSM(sci, SCI_INSERTTEXT, pos, (sptr_t) text);
@@ -827,13 +854,17 @@
    return SSM(sci, SCI_GETREADONLY, 0, 0);
 }
-/* a simple convenience function to not have SSM() in the outside of this file */
- void sci_cmd(ScintillaObject * sci, gint cmd)
+/** A simple convenience function for sending Scintilla commands without any parameters.
+ * @param sci The Scintilla @c GtkWidget.
+ * @param cmd @c SCI_COMMAND.
+ * @see http://scintilla.org for the documentation. */
+void sci_cmd(ScintillaObject * sci, gint cmd)
 {
    SSM(sci, cmd, 0, 0);
 }
+/** Get current line number. */
 gint sci_get_current_line(ScintillaObject *sci)
 {
    return SSM(sci, SCI_LINEFROMPOSITION, SSM(sci, SCI_GETCURRENTPOS, 0, 0), 0);
@@ -886,6 +917,7 @@
    SSM(sci, SCI_AUTOCSETMAXHEIGHT, val, 0);
 }
+/** Find a matching brace at @a pos. */
 gint sci_find_bracematch(ScintillaObject *sci, gint pos)
 {
    return SSM(sci, SCI_BRACEMATCH, pos, 0);
@@ -916,11 +948,13 @@
    return SSM(sci, SCI_GETLINESELENDPOSITION, line, 0);
 }
+/** Get selection mode. */
 gint sci_get_selection_mode(ScintillaObject *sci)
 {
    return SSM(sci, SCI_GETSELECTIONMODE, 0, 0);
 }
+/** Set selection mode. */
 void sci_set_selection_mode(ScintillaObject *sci, gint mode)
 {
    SSM(sci, SCI_SETSELECTIONMODE, mode, 0);
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

    