[gtksourceview/wip/loader-saver] Document some of the GtkSourceFile API
- From: Sébastien Wilmet <swilmet src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtksourceview/wip/loader-saver] Document some of the GtkSourceFile API
- Date: Sat, 28 Dec 2013 22:26:25 +0000 (UTC)
commit 92c07f2cc70dd6c5c9099a400bb12e56f64663e8
Author: Sébastien Wilmet <swilmet gnome org>
Date: Sat Dec 28 22:09:29 2013 +0100
Document some of the GtkSourceFile API
And remove the sync API, it won't be used nor implemented.
docs/reference/gtksourceview-3.0-sections.txt | 58 ++++++++
docs/reference/gtksourceview-docs.xml | 6 +
gtksourceview/gtksourcefile.c | 177 ++++++++++++++++++++----
gtksourceview/gtksourcefile.h | 35 +++---
4 files changed, 229 insertions(+), 47 deletions(-)
---
diff --git a/docs/reference/gtksourceview-3.0-sections.txt b/docs/reference/gtksourceview-3.0-sections.txt
index 0618e46..2418c41 100644
--- a/docs/reference/gtksourceview-3.0-sections.txt
+++ b/docs/reference/gtksourceview-3.0-sections.txt
@@ -207,6 +207,64 @@ gtk_source_completion_words_get_type
</SECTION>
<SECTION>
+<FILE>encoding</FILE>
+<TITLE>GtkSourceEncoding</TITLE>
+GtkSourceEncoding
+<SUBSECTION>
+gtk_source_encoding_get_from_charset
+gtk_source_encoding_get_from_index
+gtk_source_encoding_to_string
+gtk_source_encoding_get_name
+gtk_source_encoding_get_charset
+gtk_source_encoding_get_utf8
+gtk_source_encoding_get_current
+gtk_source_encoding_copy
+gtk_source_encoding_free
+<SUBSECTION Standard>
+GTK_SOURCE_TYPE_ENCODING
+gtk_source_encoding_get_type
+</SECTION>
+
+<SECTION>
+<FILE>file</FILE>
+<TITLE>GtkSourceFile</TITLE>
+GtkSourceFile
+GtkSourceNewlineType
+GtkSourceCompressionType
+GtkSourceFileSaveFlags
+GtkSourceMountOperationFactory
+GTK_SOURCE_FILE_ERROR
+<SUBSECTION>
+gtk_source_file_new
+gtk_source_file_get_location
+gtk_source_file_get_buffer
+gtk_source_file_get_encoding
+gtk_source_file_set_encoding
+gtk_source_file_get_newline_type
+gtk_source_file_set_newline_type
+gtk_source_file_get_compression_type
+gtk_source_file_set_compression_type
+gtk_source_file_get_ensure_trailing_newline
+gtk_source_file_set_ensure_trailing_newline
+gtk_source_file_set_mount_operation_factory
+gtk_source_file_load_async
+gtk_source_file_load_finish
+gtk_source_file_save_async
+gtk_source_file_save_finish
+<SUBSECTION Standard>
+GTK_SOURCE_FILE
+GTK_SOURCE_FILE_CLASS
+GTK_SOURCE_FILE_GET_CLASS
+GTK_SOURCE_IS_FILE
+GTK_SOURCE_IS_FILE_CLASS
+GTK_SOURCE_TYPE_FILE
+GtkSourceFileClass
+GtkSourceFilePrivate
+gtk_source_file_error_quark
+gtk_source_file_get_type
+</SECTION>
+
+<SECTION>
<FILE>gutter</FILE>
<TITLE>GtkSourceGutter</TITLE>
GtkSourceGutter
diff --git a/docs/reference/gtksourceview-docs.xml b/docs/reference/gtksourceview-docs.xml
index 658ada7..6dc1d31 100644
--- a/docs/reference/gtksourceview-docs.xml
+++ b/docs/reference/gtksourceview-docs.xml
@@ -24,6 +24,8 @@
<xi:include href="xml/completionproposal.xml"/>
<xi:include href="xml/completionprovider.xml"/>
<xi:include href="xml/completionwords.xml"/>
+ <xi:include href="xml/encoding.xml"/>
+ <xi:include href="xml/file.xml"/>
<xi:include href="xml/gutter.xml"/>
<xi:include href="xml/gutterrenderer.xml"/>
<xi:include href="xml/gutterrendererpixbuf.xml"/>
@@ -80,6 +82,10 @@
<title>Index of new symbols in 3.12</title>
<xi:include href="xml/api-index-3.12.xml"><xi:fallback /></xi:include>
</index>
+ <index id="api-index-3-14" role="3.14">
+ <title>Index of new symbols in 3.14</title>
+ <xi:include href="xml/api-index-3.14.xml"><xi:fallback /></xi:include>
+ </index>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
diff --git a/gtksourceview/gtksourcefile.c b/gtksourceview/gtksourcefile.c
index 0e01bd2..1470b3a 100644
--- a/gtksourceview/gtksourcefile.c
+++ b/gtksourceview/gtksourcefile.c
@@ -227,7 +227,7 @@ gtk_source_file_class_init (GtkSourceFileClass *klass)
g_object_class_install_property (object_class, PROP_ENSURE_TRAILING_NEWLINE,
g_param_spec_boolean ("ensure-trailing-newline",
"Ensure trailing newline",
- "Ensure the buffer ends with a trailing
newline",
+ "Ensure the file ends with a trailing newline",
TRUE,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT |
@@ -253,6 +253,14 @@ gtk_source_file_error_quark (void)
return quark;
}
+/**
+ * gtk_source_file_new:
+ * @location: a #GFile.
+ * @buffer: a #GtkSourceBuffer.
+ *
+ * Returns: a new #GtkSourceFile object.
+ * Since: 3.14
+ */
GtkSourceFile *
gtk_source_file_new (GFile *location,
GtkSourceBuffer *buffer)
@@ -266,6 +274,14 @@ gtk_source_file_new (GFile *location,
NULL);
}
+/**
+ * gtk_source_file_get_location:
+ * @file: a #GtkSourceFile.
+ *
+ * Returns: (transfer full): the location. Call g_object_unref() on the return
+ * value when no longer needed.
+ * Since: 3.14
+ */
GFile *
gtk_source_file_get_location (GtkSourceFile *file)
{
@@ -274,6 +290,13 @@ gtk_source_file_get_location (GtkSourceFile *file)
return g_object_ref (file->priv->location);
}
+/**
+ * gtk_source_file_get_buffer:
+ * @file: a #GtkSourceFile.
+ *
+ * Returns: (transfer none): the buffer.
+ * Since: 3.14
+ */
GtkSourceBuffer *
gtk_source_file_get_buffer (GtkSourceFile *file)
{
@@ -282,6 +305,13 @@ gtk_source_file_get_buffer (GtkSourceFile *file)
return file->priv->buffer;
}
+/**
+ * gtk_source_file_get_encoding:
+ * @file: a #GtkSourceFile.
+ *
+ * Returns: the encoding.
+ * Since: 3.14
+ */
const GtkSourceEncoding *
gtk_source_file_get_encoding (GtkSourceFile *file)
{
@@ -290,6 +320,16 @@ gtk_source_file_get_encoding (GtkSourceFile *file)
return file->priv->encoding;
}
+/**
+ * gtk_source_file_set_encoding:
+ * @file: a #GtkSourceFile.
+ * @encoding: the new encoding.
+ *
+ * Changes the encoding used for file loading and saving. Note that the
+ * #GtkSourceBuffer has always a UTF-8 encoding.
+ *
+ * Since: 3.14
+ */
void
gtk_source_file_set_encoding (GtkSourceFile *file,
const GtkSourceEncoding *encoding)
@@ -303,6 +343,13 @@ gtk_source_file_set_encoding (GtkSourceFile *file,
}
}
+/**
+ * gtk_source_file_get_newline_type:
+ * @file: a #GtkSourceFile.
+ *
+ * Returns: the newline type.
+ * Since: 3.14
+ */
GtkSourceNewlineType
gtk_source_file_get_newline_type (GtkSourceFile *file)
{
@@ -311,9 +358,19 @@ gtk_source_file_get_newline_type (GtkSourceFile *file)
return file->priv->newline_type;
}
+/**
+ * gtk_source_file_set_newline_type:
+ * @file: a #GtkSourceFile.
+ * @newline_type: the new newline type.
+ *
+ * Changes the newline type used for the file loading and saving. It doesn't
+ * change the newline type of the #GtkSourceBuffer.
+ *
+ * Since: 3.14
+ */
void
-gtk_source_file_set_newline_type (GtkSourceFile *file,
- GtkSourceNewlineType newline_type)
+gtk_source_file_set_newline_type (GtkSourceFile *file,
+ GtkSourceNewlineType newline_type)
{
g_return_if_fail (GTK_SOURCE_IS_FILE (file));
@@ -324,6 +381,13 @@ gtk_source_file_set_newline_type (GtkSourceFile *file,
}
}
+/**
+ * gtk_source_file_get_compression_type:
+ * @file: a #GtkSourceFile.
+ *
+ * Returns: the compression type.
+ * Since: 3.14
+ */
GtkSourceCompressionType
gtk_source_file_get_compression_type (GtkSourceFile *file)
{
@@ -332,6 +396,16 @@ gtk_source_file_get_compression_type (GtkSourceFile *file)
return file->priv->compression_type;
}
+/**
+ * gtk_source_file_set_compression_type:
+ * @file: a #GtkSourceFile.
+ * @compression_type: the new compression type.
+ *
+ * Changes the compression type used for the file loading and saving. It doesn't
+ * affect the #GtkSourceBuffer.
+ *
+ * Since: 3.14
+ */
void
gtk_source_file_set_compression_type (GtkSourceFile *file,
GtkSourceCompressionType compression_type)
@@ -345,6 +419,13 @@ gtk_source_file_set_compression_type (GtkSourceFile *file,
}
}
+/**
+ * gtk_source_file_get_ensure_trailing_newline:
+ * @file: a #GtkSourceFile.
+ *
+ * Returns: whether the file should end with a trailing newline.
+ * Since: 3.14
+ */
gboolean
gtk_source_file_get_ensure_trailing_newline (GtkSourceFile *file)
{
@@ -353,6 +434,25 @@ gtk_source_file_get_ensure_trailing_newline (GtkSourceFile *file)
return file->priv->ensure_trailing_newline;
}
+/**
+ * gtk_source_file_set_ensure_trailing_newline:
+ * @file: a #GtkSourceFile.
+ * @ensure_trailing_newline: whether the file should end with a trailing
+ * newline.
+ *
+ * If a #GtkTextBuffer contains a trailing newline, there will be one more
+ * visible line in a #GtkTextView. This is generally not what the user expects.
+ *
+ * When @ensure_trailing_newline is %TRUE, the trailing newline (if present) is
+ * removed when the file is loaded into the #GtkTextBuffer. When the buffer is
+ * saved into the file, a trailing newline is always added.
+ *
+ * On the other hand, when @ensure_trailing_newline is %FALSE, the file's
+ * contents is not modified when loaded into the buffer, and the buffer's
+ * contents is not modified when saved into the file.
+ *
+ * Since: 3.14
+ */
void
gtk_source_file_set_ensure_trailing_newline (GtkSourceFile *file,
gboolean ensure_trailing_newline)
@@ -368,6 +468,19 @@ gtk_source_file_set_ensure_trailing_newline (GtkSourceFile *file,
}
}
+/**
+ * gtk_source_file_set_mount_operation_factory:
+ * @file: a #GtkSourceFile.
+ * @callback: a #GtkSourceMountOperationFactory to call when a #GMountOperation
+ * is needed.
+ * @user_data: the data to pass to the @callback function.
+ *
+ * Sets a #GtkSourceMountOperationFactory function that will be called when a
+ * #GMountOperation must be created. This is useful for creating a
+ * #GtkMountOperation with the parent #GtkWindow.
+ *
+ * Since: 3.14
+ */
void
gtk_source_file_set_mount_operation_factory (GtkSourceFile *file,
GtkSourceMountOperationFactory callback,
@@ -390,19 +503,6 @@ _gtk_source_file_create_mount_operation (GtkSourceFile *file)
}
/* FIXME add load flags parameter for future expension? */
-gboolean
-gtk_source_file_load (GtkSourceFile *file,
- GCancellable *cancellable,
- GFileProgressCallback progress_callback,
- gpointer progress_callback_data,
- GError **error)
-{
- g_return_val_if_fail (GTK_SOURCE_IS_FILE (file), FALSE);
- g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
-
- return TRUE;
-}
-
void
gtk_source_file_load_async (GtkSourceFile *file,
gint io_priority,
@@ -426,20 +526,26 @@ gtk_source_file_load_finish (GtkSourceFile *file,
return TRUE;
}
-gboolean
-gtk_source_file_save (GtkSourceFile *file,
- GtkSourceFileSaveFlags flags,
- GCancellable *cancellable,
- GFileProgressCallback progress_callback,
- gpointer progress_callback_data,
- GError **error)
-{
- g_return_val_if_fail (GTK_SOURCE_IS_FILE (file), FALSE);
- g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
-
- return TRUE;
-}
-
+/**
+ * gtk_source_file_save_async:
+ * @file: a #GtkSourceFile.
+ * @flags: a set of #GtkSourceFileSaveFlags.
+ * @io_priority: the I/O priority of the request. E.g. %G_PRIORITY_LOW,
+ * %G_PRIORITY_DEFAULT or %G_PRIORITY_HIGH.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @progress_callback: (allow-none): function to call back with progress
+ * information, or %NULL if progress information is not needed.
+ * @progress_callback_data: user data to pass to @progress_callback.
+ * @callback: (scope async): a #GAsyncReadyCallback to call when the request is
+ * satisfied.
+ * @user_data: user data to pass to @callback.
+ *
+ * Saves asynchronously the #GtkSourceFile:buffer into the
+ * #GtkSourceFile:location. See the #GAsyncResult documentation to know how to
+ * use this function.
+ *
+ * Since: 3.14
+ */
void
gtk_source_file_save_async (GtkSourceFile *file,
GtkSourceFileSaveFlags flags,
@@ -495,6 +601,17 @@ gtk_source_file_save_async (GtkSourceFile *file,
user_data);
}
+/**
+ * gtk_source_file_save_finish:
+ * @file: a #GtkSourceFile.
+ * @result: a #GAsyncResult.
+ * @error: a #GError, or %NULL.
+ *
+ * Finishes a file saving started with gtk_source_file_save_async().
+ *
+ * Returns: whether the file was saved successfully.
+ * Since: 3.14
+ */
gboolean
gtk_source_file_save_finish (GtkSourceFile *file,
GAsyncResult *result,
diff --git a/gtksourceview/gtksourcefile.h b/gtksourceview/gtksourcefile.h
index 2545bcb..7ebddd0 100644
--- a/gtksourceview/gtksourcefile.h
+++ b/gtksourceview/gtksourcefile.h
@@ -37,6 +37,15 @@ G_BEGIN_DECLS
typedef struct _GtkSourceFileClass GtkSourceFileClass;
typedef struct _GtkSourceFilePrivate GtkSourceFilePrivate;
+/**
+ * GtkSourceNewlineType:
+ * @GTK_SOURCE_NEWLINE_TYPE_LF: line feed, used on UNIX.
+ * @GTK_SOURCE_NEWLINE_TYPE_CR: carriage return, used on Mac.
+ * @GTK_SOURCE_NEWLINE_TYPE_CR_LF: carriage return followed by a line feed, used
+ * on Windows.
+ *
+ * Since: 3.14
+ */
typedef enum
{
GTK_SOURCE_NEWLINE_TYPE_LF,
@@ -55,7 +64,7 @@ typedef enum
* @GTK_SOURCE_COMPRESSION_TYPE_NONE: save file in plain text.
* @GTK_SOURCE_COMPRESSION_TYPE_GZIP: save file using gzip compression.
*
- * Since: 3.12
+ * Since: 3.14
*/
typedef enum
{
@@ -71,7 +80,7 @@ typedef enum
*
* FIXME ignore invalid chars is not yet used in gsv
*
- * Since: 3.12
+ * Since: 3.14
*/
typedef enum
{
@@ -93,8 +102,13 @@ enum
};
/**
- * GtkSourceMountOperationFactory: (skip)
- * @userdata:
+ * GtkSourceMountOperationFactory:
+ * @userdata: user data
+ *
+ * Type definition for a function that will be called to create a
+ * #GMountOperation. This is useful for creating a #GtkMountOperation.
+ *
+ * Since: 3.14
*/
typedef GMountOperation *(*GtkSourceMountOperationFactory)(gpointer userdata);
@@ -148,12 +162,6 @@ void gtk_source_file_set_mount_operation_factory
GtkSourceMountOperationFactory callback,
gpointer user_data);
-gboolean gtk_source_file_load (GtkSourceFile *file,
- GCancellable *cancellable,
- GFileProgressCallback progress_callback,
- gpointer
progress_callback_data,
- GError **error);
-
void gtk_source_file_load_async (GtkSourceFile *file,
gint io_priority,
GCancellable *cancellable,
@@ -166,13 +174,6 @@ gboolean gtk_source_file_load_finish (GtkSourceFile
*file,
GAsyncResult *result,
GError **error);
-gboolean gtk_source_file_save (GtkSourceFile *file,
- GtkSourceFileSaveFlags flags,
- GCancellable *cancellable,
- GFileProgressCallback progress_callback,
- gpointer
progress_callback_data,
- GError **error);
-
void gtk_source_file_save_async (GtkSourceFile *file,
GtkSourceFileSaveFlags flags,
gint io_priority,
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
