Deprecate sci_get_text(), sci_get_selected_text() and sci_get_text_range().

Add sci_get_contents(), sci_get_contents_range() and sci_get_selection_contents() as replacement functions to provide an easier and cleaner API (initial patch by Frank).

git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@3647 ea778897-0a13-0410-b9d1-a72fbfd435f5

ChangeLog

@@ -3,6 +3,13 @@
  * src/callbacks.c:
    Delay disk file checks when switching between documents a little
    bit to avoid fast, unintentional page switching in some cases.
+ * plugins/geanyfunctions.h, src/plugindata.h, src/plugins.c,
+   src/sciwrappers.c, src/sciwrappers.h:
+   Deprecate sci_get_text(), sci_get_selected_text() and
+   sci_get_text_range().
+   Add sci_get_contents(), sci_get_contents_range() and
+   sci_get_selection_contents() as replacement functions to provide
+   an easier and cleaner API (initial patch by Frank).
 
 
 2009-03-22  Enrico Tröger  <enrico(dot)troeger(at)uvena(dot)de>

plugins/geanyfunctions.h

@@ -138,6 +138,12 @@
 	geany_functions->p_sci->indicator_clear
 #define sci_indicator_set \
 	geany_functions->p_sci->indicator_set
+#define sci_get_contents \
+	geany_functions->p_sci->get_contents
+#define sci_get_contents_range \
+	geany_functions->p_sci->get_contents_range
+#define sci_get_selection_contents \
+	geany_functions->p_sci->get_selection_contents
 #define templates_get_template_fileheader \
 	geany_functions->p_templates->get_template_fileheader
 #define utils_str_equal \

src/plugindata.h

@@ -45,7 +45,7 @@
 enum {
 	/** The Application Programming Interface (API) version, incremented
 	 * whenever any plugin data types are modified or appended to. */
-	GEANY_API_VERSION = 135,
+	GEANY_API_VERSION = 136,
 
 	/** The Application Binary Interface (ABI) version, incremented whenever
 	 * existing fields in the plugin data types have to be changed or reordered. */
@@ -316,6 +316,9 @@ typedef struct SciFuncs
 	gint	(*get_tab_width) (struct _ScintillaObject *sci);
 	void	(*indicator_clear) (struct _ScintillaObject *sci, gint start, gint end);
 	void	(*indicator_set) (struct _ScintillaObject *sci, gint indic);
+	gchar*	(*get_contents) (struct _ScintillaObject *sci, gint len);
+	gchar*	(*get_contents_range) (struct _ScintillaObject *sci, gint start, gint end);
+	gchar*	(*get_selection_contents) (struct _ScintillaObject *sci);
 }
 SciFuncs;
 

src/plugins.c

@@ -196,7 +196,10 @@ static SciFuncs sci_funcs = {
 	&sci_has_selection,
 	&sci_get_tab_width,
 	&sci_indicator_clear,
-	&sci_indicator_set
+	&sci_indicator_set,
+	&sci_get_contents,
+	&sci_get_contents_range,
+	&sci_get_selection_contents
 };
 
 static TemplateFuncs template_funcs = {

src/sciwrappers.c

@@ -542,7 +542,6 @@ gint sci_get_line_length(ScintillaObject* sci,gint line)
 }
 
 
-/* TODO: rename/change to use buffer? Otherwise inconsistent with sci_get_text*(). */
 /** Get line contents.
  * @param sci Scintilla widget.
  * @param line_num Line number.
@@ -559,6 +558,9 @@ gchar *sci_get_line(ScintillaObject* sci, gint line_num)
 
 
 /** Get all text.
+ * @deprecated sci_get_text is deprecated and should not be used in newly-written code.
+ * Use sci_get_contents() instead.
+ *
  * @param sci Scintilla widget.
  * @param len Length of @a text buffer, usually sci_get_length() + 1.
  * @param text Text buffer; must be allocated @a len + 1 bytes for null-termination. */
@@ -567,8 +569,25 @@ void sci_get_text(ScintillaObject* sci, gint len, gchar* text)
 	SSM( sci, SCI_GETTEXT, len, (sptr_t) text );
 }
 
+/** Get all text inside a given text length.
+ * @param sci Scintilla widget.
+ * @param len Length of the text to retrieve from the start of the document,
+ *            usually sci_get_length() + 1.
+ * @return A copy of the text. Should be freed when no longer needed.
+ *
+ * @since 0.17
+ */
+gchar *sci_get_contents(ScintillaObject *sci, gint len)
+{
+	gchar *text = g_malloc(len);
+	SSM(sci, SCI_GETTEXT, len, (sptr_t) text);
+	return text;
+}
 
 /** Get selected text.
+ * @deprecated sci_get_selected_text is deprecated and should not be used in newly-written code.
+ * Use sci_get_selection_contents() instead.
+ *
  * @param sci Scintilla widget.
  * @param text Text buffer; must be allocated sci_get_selected_text_length() + 1 bytes
  * for null-termination. */
@@ -577,6 +596,22 @@ void sci_get_selected_text(ScintillaObject* sci, gchar* text)
 	SSM( sci, SCI_GETSELTEXT, 0, (sptr_t) text);
 }
 
+/** Get selected text.
+ * @param sci Scintilla widget.
+ *
+ * @return The selected text. Should be freed when no longer needed.
+ *
+ * @since 0.17
+ */
+gchar *sci_get_selection_contents(ScintillaObject *sci)
+{
+	gint len = sci_get_selected_text_length(sci);
+	gchar *selection = g_malloc(len + 1);
+
+	SSM(sci, SCI_GETSELTEXT, 0, (sptr_t) selection);
+
+	return selection;
+}
 
 /** Get selected text length.
  * @param sci Scintilla widget.
@@ -586,7 +621,6 @@ gint sci_get_selected_text_length(ScintillaObject* sci)
 	return SSM( sci, SCI_GETSELTEXT, 0, 0);
 }
 
-
 gint sci_get_position_from_xy(ScintillaObject* sci, gint x, gint y, gboolean nearby)
 {
 	/* for nearby return -1 if there is no character near to the x,y point. */
@@ -842,6 +876,9 @@ void sci_clear_cmdkey(ScintillaObject *sci, gint key)
 
 
 /** Get text between @a start and @a end.
+ * @deprecated sci_get_text_range is deprecated and should not be used in newly-written code.
+ * Use sci_get_contents_range() instead.
+ *
  * @param sci Scintilla widget.
  * @param start Start.
  * @param end End.
@@ -855,6 +892,22 @@ void sci_get_text_range(ScintillaObject *sci, gint start, gint end, gchar *text)
 	SSM(sci, SCI_GETTEXTRANGE, 0, (long) &tr);
 }
 
+/** Get text between @a start and @a end.
+ *
+ * @param sci Scintilla widget.
+ * @param start Start.
+ * @param end End.
+ * @return The text inside the given range. Should be freed when no longer needed.
+ *
+ * @since 0.17
+ */
+gchar *sci_get_contents_range(ScintillaObject *sci, gint start, gint end)
+{
+	gchar *text = g_malloc((end - start) + 1);
+	sci_get_text_range(sci, start, end, text);
+	return text;
+}
+
 
 void sci_line_duplicate(ScintillaObject *sci)
 {

src/sciwrappers.h

@@ -86,8 +86,10 @@ void				sci_set_selection_end		(ScintillaObject* sci, gint position);
 
 gint				sci_get_length				(ScintillaObject* sci);
 void				sci_get_text				(ScintillaObject* sci,gint len,gchar* text);
+gchar*				sci_get_contents			(ScintillaObject* sci, gint len);
 void				sci_get_selected_text		(ScintillaObject* sci, gchar* text);
 gint				sci_get_selected_text_length(ScintillaObject* sci);
+gchar*				sci_get_selection_contents	(ScintillaObject* sci);
 gchar*				sci_get_line				(ScintillaObject* sci, gint line_num);
 gint 				sci_get_line_length			(ScintillaObject* sci, gint line);
 gint				sci_get_line_count			(ScintillaObject* sci);
@@ -139,6 +141,7 @@ void				sci_set_codepage			(ScintillaObject * sci, gint cp);
 void				sci_clear_cmdkey			(ScintillaObject * sci, gint key);
 void				sci_assign_cmdkey			(ScintillaObject * sci, gint key, gint command);
 void				sci_get_text_range			(ScintillaObject * sci, gint start, gint end, gchar *text);
+gchar*				sci_get_contents_range		(ScintillaObject * sci, gint start, gint end);
 void				sci_selection_duplicate		(ScintillaObject * sci);
 void				sci_line_duplicate			(ScintillaObject * sci);
 void				sci_insert_text				(ScintillaObject * sci, gint pos, const gchar *text);