[gtksourceview/gtksourcecompletion] Updated documentation
- From: Jesse van den Kieboom <jessevdk src gnome org>
- To: svn-commits-list gnome org
- Subject: [gtksourceview/gtksourcecompletion] Updated documentation
- Date: Fri, 24 Apr 2009 16:42:46 -0400 (EDT)
commit babeb3bde74a68274493e8d2b049ee0009d2112c
Author: Jesse van den Kieboom <jesse icecrew nl>
Date: Fri Apr 24 22:42:34 2009 +0200
Updated documentation
---
gtksourceview/gtksourcecompletion.c | 102 ++++++++------
gtksourceview/gtksourcecompletioninfo.c | 204 ++++++++++++++-------------
gtksourceview/gtksourcecompletionitem.c | 25 ++--
gtksourceview/gtksourcecompletionproposal.c | 28 +++--
gtksourceview/gtksourcecompletionprovider.c | 49 +++++--
5 files changed, 231 insertions(+), 177 deletions(-)
diff --git a/gtksourceview/gtksourcecompletion.c b/gtksourceview/gtksourcecompletion.c
index daa6b24..3ba4038 100644
--- a/gtksourceview/gtksourcecompletion.c
+++ b/gtksourceview/gtksourcecompletion.c
@@ -1410,10 +1410,10 @@ gtk_source_completion_class_init (GtkSourceCompletionClass *klass)
klass->hide = gtk_source_completion_hide_default;
/**
- * GtkSourceCompletion:manage-completion-keys:
+ * GtkSourceCompletion:view:
+ *
+ * The #GtkSourceView bound to the completion object.
*
- * %TRUE if this object must control the completion keys pressed into the
- * #GtkTextView associated (up next proposal, down previous proposal etc.)
*/
g_object_class_install_property (object_class,
PROP_VIEW,
@@ -1426,8 +1426,9 @@ gtk_source_completion_class_init (GtkSourceCompletionClass *klass)
/**
* GtkSourceCompletion:manage-completion-keys:
*
- * %TRUE if this object must control the completion keys pressed into the
- * #GtkTextView associated (up next proposal, down previous proposal etc.)
+ * Determines whether the completion object should manage key presses
+ * for navigating and activating proposals.
+ *
*/
g_object_class_install_property (object_class,
PROP_MANAGE_KEYS,
@@ -1439,8 +1440,10 @@ gtk_source_completion_class_init (GtkSourceCompletionClass *klass)
/**
* GtkSourceCompletion:remember-info-visibility:
*
- * %TRUE if the completion must remember the last info state
- * (visible or hidden)
+ * Determines whether the visibility of the info window should be
+ * saved when the completion is hidden, and restored when the completion
+ * is shown again.
+ *
*/
g_object_class_install_property (object_class,
PROP_REMEMBER_INFO_VISIBILITY,
@@ -1452,8 +1455,9 @@ gtk_source_completion_class_init (GtkSourceCompletionClass *klass)
/**
* GtkSourceCompletion:select-on-show:
*
- * %TRUE if the completion must to mark as selected the first proposal
- * on show (and when the filter is updated)
+ * Determines whether the first proposal should be selected when the
+ * completion is first shown.
+ *
*/
g_object_class_install_property (object_class,
PROP_SELECT_ON_SHOW,
@@ -1466,8 +1470,9 @@ gtk_source_completion_class_init (GtkSourceCompletionClass *klass)
/**
* GtkSourceCompletion:show-headers:
*
- * %TRUE if providers should be shown as separator headers in the
- * popup when there are proposals from multiple providers
+ * Determines whether provider headers should be shown in the proposal
+ * list if there is more than one provider with proposals.
+ *
*/
g_object_class_install_property (object_class,
PROP_SHOW_HEADERS,
@@ -1480,13 +1485,15 @@ gtk_source_completion_class_init (GtkSourceCompletionClass *klass)
/**
* GtkSourceCompletion:auto-complete-delay:
*
- * The auto completion delay (in milliseconds)
+ * Determines the popup delay (in milliseconds) at which the completion
+ * will be shown for interactive completion.
+ *
*/
g_object_class_install_property (object_class,
PROP_AUTO_COMPLETE_DELAY,
g_param_spec_uint ("auto-complete-delay",
_("Auto Complete Delay"),
- _("Auto completion delay when typing"),
+ _("Completion popup delay for interactive completion"),
0,
G_MAXUINT,
250,
@@ -1494,7 +1501,8 @@ gtk_source_completion_class_init (GtkSourceCompletionClass *klass)
/**
* GtkSourceCompletion:min-len:
*
- * The minimum word length to initiate auto completion
+ * The minimum word length to initiate interactive completion.
+ *
*/
g_object_class_install_property (object_class,
PROP_MINIMUM_AUTO_COMPLETE_LENGTH,
@@ -1510,9 +1518,10 @@ gtk_source_completion_class_init (GtkSourceCompletionClass *klass)
* GtkSourceCompletion::show:
* @completion: The #GtkSourceCompletion who emits the signal
*
- * Emitted when the completion window is popped up. The default handler
+ * Emitted when the completion window is shown. The default handler
* will actually show the window.
- **/
+ *
+ */
signals[SHOW] =
g_signal_new ("show",
G_TYPE_FROM_CLASS (klass),
@@ -1529,9 +1538,10 @@ gtk_source_completion_class_init (GtkSourceCompletionClass *klass)
* GtkSourceCompletion::hide:
* @completion: The #GtkSourceCompletion who emits the signal
*
- * Emitted when the completion window is popped up. The default handler
+ * Emitted when the completion window is hidden. The default handler
* will actually hide the window.
- **/
+ *
+ */
signals[HIDE] =
g_signal_new ("hide",
G_TYPE_FROM_CLASS (klass),
@@ -1989,15 +1999,15 @@ add_proposals (GtkSourceCompletion *completion,
/**
* gtk_source_completion_show:
- * @completion: the #GtkSourceCompletion
- * @providers: the list of #GtkSourceCompletionProvider
- * @criteria: the filter criteria
- * @place: the place where you want to situate the popup window, or %NULL
+ * @completion: A #GtkSourceCompletion
+ * @providers: A list of #GtkSourceCompletionProvider
+ * @criteria: The filter criteria
+ * @place: The place where you want to position the popup window, or %NULL
*
* Shows the show completion window. If @place if %NULL the popup window will
* be placed on the cursor position.
*
- * Returns: %TRUE if it was possible show the show completion window.
+ * Returns: %TRUE if it was possible to the show completion window.
*/
gboolean
gtk_source_completion_show (GtkSourceCompletion *completion,
@@ -2074,11 +2084,11 @@ gtk_source_completion_error_quark (void)
/**
* gtk_source_completion_new:
- * @view: the #GtkSourceView to create the completion for
+ * @view: A #GtkSourceView
*
- * Create a new #GtkSourceCompletion associated with @view
+ * Create a new #GtkSourceCompletion associated with @view.
*
- * Returns: The new #GtkSourceCompletion
+ * Returns: The new #GtkSourceCompletion.
*/
GtkSourceCompletion *
gtk_source_completion_new (GtkSourceView *view)
@@ -2086,21 +2096,22 @@ gtk_source_completion_new (GtkSourceView *view)
g_return_val_if_fail (GTK_IS_SOURCE_VIEW (view), NULL);
return g_object_new (GTK_TYPE_SOURCE_COMPLETION,
- "view", view,
- NULL);
+ "view", view,
+ NULL);
}
/**
* gtk_source_completion_add_provider:
- * @completion: the #GtkSourceCompletion
- * @provider: The #GtkSourceCompletionProvider.
+ * @completion: A #GtkSourceCompletion
+ * @provider: A #GtkSourceCompletionProvider
+ * @error: A #GError
*
* Add a new #GtkSourceCompletionProvider to the completion object. This will
* add a reference @provider, so make sure to unref your own copy when you
* no longer need it.
*
- * Returns: %TRUE if @provider was successfully added to @completion, or %FALSE
- * if @provider was already added to @completion before
+ * Returns: %TRUE if @provider was successfully added, otherwise if @error
+ * is provided, it will be set with the error and %FALSE is returned.
**/
gboolean
gtk_source_completion_add_provider (GtkSourceCompletion *completion,
@@ -2150,12 +2161,14 @@ gtk_source_completion_add_provider (GtkSourceCompletion *completion,
/**
* gtk_source_completion_remove_provider:
- * @completion: the #GtkSourceCompletion
- * @provider: The #GtkSourceCompletionProvider.
+ * @completion: A #GtkSourceCompletion
+ * @provider: A #GtkSourceCompletionProvider
+ * @error: A #GError
*
* Remove @provider from the completion.
*
- * Returns: %TRUE if @provider was successfully removed
+ * Returns: %TRUE if @provider was successfully removed, otherwise if @error
+ * is provided, it will be set with the error and %FALSE is returned.
**/
gboolean
gtk_source_completion_remove_provider (GtkSourceCompletion *completion,
@@ -2211,7 +2224,7 @@ gtk_source_completion_remove_provider (GtkSourceCompletion *completion,
/**
* gtk_source_completion_hide:
- * @completion: a #GtkSourceCompletion
+ * @completion: A #GtkSourceCompletion
*
* Hides the completion if it is active (visible).
*/
@@ -2229,13 +2242,12 @@ gtk_source_completion_hide (GtkSourceCompletion *completion)
/**
* gtk_source_completion_get_info_window:
- * @completion: The #GtkSourceCompletion
+ * @completion: A #GtkSourceCompletion
*
- * The info widget is the window where the completion shows the
- * proposal info or help. DO NOT USE IT (only to connect to some signal
- * or set the content in a custom widget).
+ * The info widget is the window where the completion displays optional extra
+ * information of the proposal.
*
- * Returns: The internal #GtkSourceCompletionInfo widget.
+ * Returns: The #GtkSourceCompletionInfo window.
*/
GtkSourceCompletionInfo *
gtk_source_completion_get_info_window (GtkSourceCompletion *completion)
@@ -2243,6 +2255,14 @@ gtk_source_completion_get_info_window (GtkSourceCompletion *completion)
return GTK_SOURCE_COMPLETION_INFO (completion->priv->info_window);
}
+/**
+ * gtk_source_completion_get_view:
+ * @completion: A #GtkSourceCompletion
+ *
+ * The #GtkSourceView associated with @completion.
+ *
+ * Returns: The #GtkSourceView associated with @completion.
+ */
GtkSourceView *
gtk_source_completion_get_view (GtkSourceCompletion *completion)
{
diff --git a/gtksourceview/gtksourcecompletioninfo.c b/gtksourceview/gtksourcecompletioninfo.c
index c2d8e9b..13ba17a 100644
--- a/gtksourceview/gtksourcecompletioninfo.c
+++ b/gtksourceview/gtksourcecompletioninfo.c
@@ -79,7 +79,7 @@ G_DEFINE_TYPE(GtkSourceCompletionInfo, gtk_source_completion_info, GTK_TYPE_WIND
#define GTK_SOURCE_COMPLETION_INFO_GET_PRIVATE(object)(G_TYPE_INSTANCE_GET_PRIVATE ((object), GTK_TYPE_SOURCE_COMPLETION_INFO, GtkSourceCompletionInfoPrivate))
static void
-get_scrolled_window_sizing (GtkSourceCompletionInfo *self,
+get_scrolled_window_sizing (GtkSourceCompletionInfo *info,
gint *border,
gint *hscroll,
gint *vscroll)
@@ -90,18 +90,18 @@ get_scrolled_window_sizing (GtkSourceCompletionInfo *self,
*hscroll = 0;
*vscroll = 0;
- if (self->priv->scroll != NULL)
+ if (info->priv->scroll != NULL)
{
- *border = gtk_container_get_border_width (GTK_CONTAINER (self));
+ *border = gtk_container_get_border_width (GTK_CONTAINER (info));
- scrollbar = gtk_scrolled_window_get_hscrollbar (GTK_SCROLLED_WINDOW (self->priv->scroll));
+ scrollbar = gtk_scrolled_window_get_hscrollbar (GTK_SCROLLED_WINDOW (info->priv->scroll));
if (GTK_WIDGET_VISIBLE (scrollbar))
{
*hscroll = scrollbar->allocation.height;
}
- scrollbar = gtk_scrolled_window_get_vscrollbar (GTK_SCROLLED_WINDOW (self->priv->scroll));
+ scrollbar = gtk_scrolled_window_get_vscrollbar (GTK_SCROLLED_WINDOW (info->priv->scroll));
if (GTK_WIDGET_VISIBLE (scrollbar))
{
@@ -111,7 +111,7 @@ get_scrolled_window_sizing (GtkSourceCompletionInfo *self,
}
static void
-window_resize (GtkSourceCompletionInfo *self)
+window_resize (GtkSourceCompletionInfo *info)
{
GtkRequisition req;
gint width;
@@ -120,82 +120,82 @@ window_resize (GtkSourceCompletionInfo *self)
gint border;
gint hscroll;
gint vscroll;
- GtkStyle *style = GTK_WIDGET (self)->style;
+ GtkStyle *style = GTK_WIDGET (info)->style;
- gtk_window_get_default_size (GTK_WINDOW (self), &width, &height);
+ gtk_window_get_default_size (GTK_WINDOW (info), &width, &height);
- if (self->priv->widget != NULL)
+ if (info->priv->widget != NULL)
{
/* Try to resize to fit widget, if necessary */
- gtk_widget_size_request (self->priv->widget, &req);
+ gtk_widget_size_request (info->priv->widget, &req);
- get_scrolled_window_sizing (self, &border, &hscroll, &vscroll);
- off = (gtk_container_get_border_width (GTK_CONTAINER (self)) + border) * 2;
+ get_scrolled_window_sizing (info, &border, &hscroll, &vscroll);
+ off = (gtk_container_get_border_width (GTK_CONTAINER (info)) + border) * 2;
- if (self->priv->shrink_height)
+ if (info->priv->shrink_height)
{
- if (self->priv->max_height == -1)
+ if (info->priv->max_height == -1)
{
height = req.height + style->ythickness * 2;
}
else
{
- height = MIN (req.height + style->ythickness * 2, self->priv->max_height);
+ height = MIN (req.height + style->ythickness * 2, info->priv->max_height);
}
height += off + hscroll;
}
- if (self->priv->shrink_width)
+ if (info->priv->shrink_width)
{
- if (self->priv->max_width == -1)
+ if (info->priv->max_width == -1)
{
width = req.width + style->xthickness * 2;
}
else
{
- width = MIN (req.width + style->xthickness * 2, self->priv->max_width);
+ width = MIN (req.width + style->xthickness * 2, info->priv->max_width);
}
width += off + vscroll;
}
}
- gtk_window_resize (GTK_WINDOW (self), width, height);
+ gtk_window_resize (GTK_WINDOW (info), width, height);
}
static void
-gtk_source_completion_info_init (GtkSourceCompletionInfo *self)
+gtk_source_completion_info_init (GtkSourceCompletionInfo *info)
{
- self->priv = GTK_SOURCE_COMPLETION_INFO_GET_PRIVATE (self);
+ info->priv = GTK_SOURCE_COMPLETION_INFO_GET_PRIVATE (info);
/* Tooltip style */
- gtk_window_set_title (GTK_WINDOW (self), _("Completion Info"));
- gtk_widget_set_name (GTK_WIDGET (self), "gtk-tooltip");
- gtk_widget_ensure_style (GTK_WIDGET (self));
+ gtk_window_set_title (GTK_WINDOW (info), _("Completion Info"));
+ gtk_widget_set_name (GTK_WIDGET (info), "gtk-tooltip");
+ gtk_widget_ensure_style (GTK_WIDGET (info));
- gtk_window_set_type_hint (GTK_WINDOW (self),
+ gtk_window_set_type_hint (GTK_WINDOW (info),
GDK_WINDOW_TYPE_HINT_NORMAL);
- gtk_window_set_default_size (GTK_WINDOW (self), 300, 200);
- gtk_container_set_border_width (GTK_CONTAINER (self), 1);
+ gtk_window_set_default_size (GTK_WINDOW (info), 300, 200);
+ gtk_container_set_border_width (GTK_CONTAINER (info), 1);
}
static gboolean
-idle_resize (GtkSourceCompletionInfo *self)
+idle_resize (GtkSourceCompletionInfo *info)
{
- self->priv->idle_resize = 0;
+ info->priv->idle_resize = 0;
- window_resize (self);
+ window_resize (info);
return FALSE;
}
static void
-queue_resize (GtkSourceCompletionInfo *self)
+queue_resize (GtkSourceCompletionInfo *info)
{
- if (self->priv->idle_resize == 0)
+ if (info->priv->idle_resize == 0)
{
- self->priv->idle_resize = g_idle_add ((GSourceFunc)idle_resize, self);
+ info->priv->idle_resize = g_idle_add ((GSourceFunc)idle_resize, info);
}
}
@@ -205,21 +205,21 @@ gtk_source_completion_info_get_property (GObject *object,
GValue *value,
GParamSpec *pspec)
{
- GtkSourceCompletionInfo *self = GTK_SOURCE_COMPLETION_INFO (object);
+ GtkSourceCompletionInfo *info = GTK_SOURCE_COMPLETION_INFO (object);
switch (prop_id)
{
case PROP_MAX_WIDTH:
- g_value_set_int (value, self->priv->max_width);
+ g_value_set_int (value, info->priv->max_width);
break;
case PROP_MAX_HEIGHT:
- g_value_set_int (value, self->priv->max_height);
+ g_value_set_int (value, info->priv->max_height);
break;
case PROP_SHRINK_WIDTH:
- g_value_set_boolean (value, self->priv->shrink_width);
+ g_value_set_boolean (value, info->priv->shrink_width);
break;
case PROP_SHRINK_HEIGHT:
- g_value_set_boolean (value, self->priv->shrink_height);
+ g_value_set_boolean (value, info->priv->shrink_height);
break;
default:
G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
@@ -233,25 +233,25 @@ gtk_source_completion_info_set_property (GObject *object,
const GValue *value,
GParamSpec *pspec)
{
- GtkSourceCompletionInfo *self = GTK_SOURCE_COMPLETION_INFO (object);
+ GtkSourceCompletionInfo *info = GTK_SOURCE_COMPLETION_INFO (object);
switch (prop_id)
{
case PROP_MAX_WIDTH:
- self->priv->max_width = g_value_get_int (value);
- queue_resize (self);
+ info->priv->max_width = g_value_get_int (value);
+ queue_resize (info);
break;
case PROP_MAX_HEIGHT:
- self->priv->max_height = g_value_get_int (value);
- queue_resize (self);
+ info->priv->max_height = g_value_get_int (value);
+ queue_resize (info);
break;
case PROP_SHRINK_WIDTH:
- self->priv->shrink_width = g_value_get_boolean (value);
- queue_resize (self);
+ info->priv->shrink_width = g_value_get_boolean (value);
+ queue_resize (info);
break;
case PROP_SHRINK_HEIGHT:
- self->priv->shrink_height = g_value_get_boolean (value);
- queue_resize (self);
+ info->priv->shrink_height = g_value_get_boolean (value);
+ queue_resize (info);
break;
default:
G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
@@ -262,11 +262,11 @@ gtk_source_completion_info_set_property (GObject *object,
static void
gtk_source_completion_info_finalize (GObject *object)
{
- GtkSourceCompletionInfo *self = GTK_SOURCE_COMPLETION_INFO (object);
+ GtkSourceCompletionInfo *info = GTK_SOURCE_COMPLETION_INFO (object);
- if (self->priv->idle_resize != 0)
+ if (info->priv->idle_resize != 0)
{
- g_source_remove (self->priv->idle_resize);
+ g_source_remove (info->priv->idle_resize);
}
G_OBJECT_CLASS (gtk_source_completion_info_parent_class)->finalize (object);
@@ -391,16 +391,18 @@ gtk_source_completion_info_new (void)
/**
* gtk_source_completion_info_move_to_iter:
- * @self: The #GtkSourceCompletionInfo
- * @view: The current GtkTextView where we want to show the info
- * @iter: a #GtkTextIter
+ * @info: A #GtkSourceCompletionInfo
+ * @view: A #GtkTextView on which the info window should be positioned
+ * @iter: A #GtkTextIter
*
- * Moves the #GtkSourceCompletionInfo to under the @iter. If it cannot be shown down,
- * it will be shown up. If @iter is %NULL @self is moved to the cursor position.
+ * Moves the #GtkSourceCompletionInfo to @iter. If @iter is %NULL @info is
+ * moved to the cursor position. Moving will respect the #GdkGravity setting
+ * of the info window and will ensure the line at @iter is not occluded by
+ * the window.
*
*/
void
-gtk_source_completion_info_move_to_iter (GtkSourceCompletionInfo *self,
+gtk_source_completion_info_move_to_iter (GtkSourceCompletionInfo *info,
GtkTextView *view,
GtkTextIter *iter)
{
@@ -408,7 +410,7 @@ gtk_source_completion_info_move_to_iter (GtkSourceCompletionInfo *self,
GtkTextMark *insert_mark;
GtkTextIter start;
- g_return_if_fail (GTK_IS_SOURCE_COMPLETION_INFO (self));
+ g_return_if_fail (GTK_IS_SOURCE_COMPLETION_INFO (info));
g_return_if_fail (GTK_IS_SOURCE_VIEW (view));
if (iter == NULL)
@@ -422,18 +424,18 @@ gtk_source_completion_info_move_to_iter (GtkSourceCompletionInfo *self,
start = *iter;
}
- gtk_source_completion_utils_move_to_iter (GTK_WINDOW (self),
+ gtk_source_completion_utils_move_to_iter (GTK_WINDOW (info),
GTK_SOURCE_VIEW (view),
&start);
}
/**
* gtk_source_completion_info_set_sizing:
- * @self: The #GtkSourceCompletionInfo
- * @width: the maximum/requested width of the window (-1 to default)
- * @height: the maximum/requested height of the window (-1 to default)
- * @shrink_width: whether to shrink the width of the window to fit its contents
- * @shrink_height: whether to shrink the height of the window to fit its
+ * @info: A #GtkSourceCompletionInfo
+ * @width: The maximum/requested width of the window (-1 to default)
+ * @height: The maximum/requested height of the window (-1 to default)
+ * @shrink_width: Whether to shrink the width of the window to fit its contents
+ * @shrink_height: Whether to shrink the height of the window to fit its
* contents
*
* Set sizing information for the info window. If @shrink_width or
@@ -444,28 +446,28 @@ gtk_source_completion_info_move_to_iter (GtkSourceCompletionInfo *self,
*
*/
void
-gtk_source_completion_info_set_sizing (GtkSourceCompletionInfo *self,
+gtk_source_completion_info_set_sizing (GtkSourceCompletionInfo *info,
gint width,
gint height,
gboolean shrink_width,
gboolean shrink_height)
{
- g_return_if_fail (GTK_IS_SOURCE_COMPLETION_INFO (self));
+ g_return_if_fail (GTK_IS_SOURCE_COMPLETION_INFO (info));
- if (self->priv->max_width == width &&
- self->priv->max_height == height &&
- self->priv->shrink_width == shrink_width &&
- self->priv->shrink_height == shrink_height)
+ if (info->priv->max_width == width &&
+ info->priv->max_height == height &&
+ info->priv->shrink_width == shrink_width &&
+ info->priv->shrink_height == shrink_height)
{
return;
}
- self->priv->max_width = width;
- self->priv->max_height = height;
- self->priv->shrink_width = shrink_width;
- self->priv->shrink_height = shrink_height;
+ info->priv->max_width = width;
+ info->priv->max_height = height;
+ info->priv->shrink_width = shrink_width;
+ info->priv->shrink_height = shrink_height;
- queue_resize (self);
+ queue_resize (info);
}
static gboolean
@@ -526,41 +528,43 @@ create_scrolled_window (GtkSourceCompletionInfo *info)
/**
* gtk_source_completion_info_set_widget:
- * @self: The #GtkSourceCompletionInfo
+ * @info: A #GtkSourceCompletionInfo
* @widget: A #GtkWidget
*
- * Sets the contents widget of the info window.
+ * Sets the content widget of the info window. If @widget does not fit within
+ * the size requirements of the window, a #GtkScrolledWindow will automatically
+ * be created and added to the window.
*
*/
void
-gtk_source_completion_info_set_widget (GtkSourceCompletionInfo *self,
+gtk_source_completion_info_set_widget (GtkSourceCompletionInfo *info,
GtkWidget *widget)
{
GtkWidget *child;
- g_return_if_fail (GTK_IS_SOURCE_COMPLETION_INFO (self));
+ g_return_if_fail (GTK_IS_SOURCE_COMPLETION_INFO (info));
g_return_if_fail (widget == NULL || GTK_IS_WIDGET (widget));
- if (self->priv->widget == widget)
+ if (info->priv->widget == widget)
{
return;
}
- if (self->priv->widget != NULL)
+ if (info->priv->widget != NULL)
{
- g_signal_handler_disconnect (self->priv->widget, self->priv->request_id);
+ g_signal_handler_disconnect (info->priv->widget, info->priv->request_id);
- gtk_container_remove (GTK_CONTAINER (gtk_widget_get_parent (self->priv->widget)),
- self->priv->widget);
+ gtk_container_remove (GTK_CONTAINER (gtk_widget_get_parent (info->priv->widget)),
+ info->priv->widget);
- if (self->priv->scroll != NULL)
+ if (info->priv->scroll != NULL)
{
- gtk_widget_destroy (self->priv->scroll);
- self->priv->scroll = NULL;
+ gtk_widget_destroy (info->priv->scroll);
+ info->priv->scroll = NULL;
}
}
- self->priv->widget = widget;
+ info->priv->widget = widget;
if (widget != NULL)
{
@@ -570,15 +574,15 @@ gtk_source_completion_info_set_widget (GtkSourceCompletionInfo *self,
g_object_ref (widget);
}
- self->priv->request_id = g_signal_connect_after (widget,
+ info->priv->request_id = g_signal_connect_after (widget,
"size-request",
G_CALLBACK (widget_size_request_cb),
- self);
+ info);
/* See if it needs a viewport */
- if (use_scrolled_window (self, widget))
+ if (use_scrolled_window (info, widget))
{
- create_scrolled_window (self);
+ create_scrolled_window (info);
child = widget;
if (needs_viewport (widget))
@@ -590,34 +594,34 @@ gtk_source_completion_info_set_widget (GtkSourceCompletionInfo *self,
gtk_container_add (GTK_CONTAINER (child), widget);
}
- gtk_container_add (GTK_CONTAINER (self->priv->scroll), child);
+ gtk_container_add (GTK_CONTAINER (info->priv->scroll), child);
}
else
{
- gtk_container_add (GTK_CONTAINER (self), widget);
+ gtk_container_add (GTK_CONTAINER (info), widget);
}
gtk_widget_show (widget);
}
- window_resize (self);
+ window_resize (info);
}
/**
* gtk_source_completion_info_get_widget:
- * @self: The #GtkSourceCompletionInfo
+ * @info: A #GtkSourceCompletionInfo
*
- * Get the current contents widget
+ * Get the current content widget.
*
- * Returns: The current contents widget
+ * Returns: The current content widget.
*
*/
GtkWidget *
-gtk_source_completion_info_get_widget (GtkSourceCompletionInfo* self)
+gtk_source_completion_info_get_widget (GtkSourceCompletionInfo* info)
{
- g_return_val_if_fail (GTK_IS_SOURCE_COMPLETION_INFO (self), NULL);
+ g_return_val_if_fail (GTK_IS_SOURCE_COMPLETION_INFO (info), NULL);
- return self->priv->widget;
+ return info->priv->widget;
}
diff --git a/gtksourceview/gtksourcecompletionitem.c b/gtksourceview/gtksourcecompletionitem.c
index 06f8b99..a8b5dc7 100644
--- a/gtksourceview/gtksourcecompletionitem.c
+++ b/gtksourceview/gtksourcecompletionitem.c
@@ -163,7 +163,7 @@ gtk_source_completion_item_class_init (GtkSourceCompletionItemClass *klass)
/**
* GtkSourceCompletionItem:label:
*
- * Label to be shown for this item
+ * Label to be shown for this proposal.
*/
g_object_class_install_property (object_class,
PROP_LABEL,
@@ -176,7 +176,7 @@ gtk_source_completion_item_class_init (GtkSourceCompletionItemClass *klass)
/**
* GtkSourceCompletionItem:icon:
*
- * Icon to be shown for this item
+ * Icon to be shown for this proposal.
*/
g_object_class_install_property (object_class,
PROP_ICON,
@@ -189,7 +189,7 @@ gtk_source_completion_item_class_init (GtkSourceCompletionItemClass *klass)
/**
* GtkSourceCompletionItem:info:
*
- * Optional extra information to be shown for this item
+ * Optional extra information to be shown for this proposal.
*/
g_object_class_install_property (object_class,
PROP_INFO,
@@ -210,14 +210,15 @@ gtk_source_completion_item_init (GtkSourceCompletionItem *self)
/**
* gtk_source_completion_item_new:
- * @label: the item label
- * @icon: the item icon
- * @info: the item extra information
+ * @label: The item label
+ * @icon: The item icon
+ * @info: The item extra information
*
* Create a new #GtkSourceCompletionItem with label @label, icon @icon and
- * extra information @info
+ * extra information @info. Both @icon and @info can be %NULL in which case
+ * there will be no icon shown and no extra information available.
*
- * Return value: the newly constructed #GtkSourceCompletionItem
+ * Returns: The new #GtkSourceCompletionItem.
*
*/
GtkSourceCompletionItem *
@@ -234,14 +235,14 @@ gtk_source_completion_item_new (const gchar *label,
/**
* gtk_source_completion_item_new_from_stock:
- * @label: the item label
- * @stock: the stock icon
- * @info: the item extra information
+ * @label: The item label
+ * @stock: The stock icon
+ * @info: The item extra information
*
* Creates a new #GtkSourceCompletionItem from a stock item. If @label is %NULL,
* the stock label will be used.
*
- * Returns: the newly constructed #GtkSourceCompletionItem
+ * Returns: the newly constructed #GtkSourceCompletionItem.
*
*/
GtkSourceCompletionItem *
diff --git a/gtksourceview/gtksourcecompletionproposal.c b/gtksourceview/gtksourcecompletionproposal.c
index 2e54e9a..32a007c 100644
--- a/gtksourceview/gtksourcecompletionproposal.c
+++ b/gtksourceview/gtksourcecompletionproposal.c
@@ -73,6 +73,14 @@ gtk_source_completion_proposal_init (GtkSourceCompletionProposalIface *iface)
if (!initialized)
{
+ /**
+ * GtkSourceCompletionProposal::changed:
+ * @proposal: The #GtkSourceCompletionProposal
+ *
+ * Emitted when the proposal has changed. The completion popup
+ * will react to this by updating the shown information.
+ *
+ */
signals[CHANGED] =
g_signal_new ("changed",
G_TYPE_FROM_INTERFACE (iface),
@@ -120,11 +128,13 @@ gtk_source_completion_proposal_get_type ()
/**
* gtk_source_completion_proposal_get_label:
- * @proposal: The #GtkSourceCompletionProposal
+ * @proposal: A #GtkSourceCompletionProposal
*
- * Gets the label of @proposal
+ * Gets the label of @proposal. The label is shown in the list of proposals and
+ * may contain markup. It should be a valid UTF-8 string ready for display to
+ * the user.
*
- * Returns: The label of @proposal
+ * Returns: The label of @proposal.
*/
const gchar *
gtk_source_completion_proposal_get_label (GtkSourceCompletionProposal *proposal)
@@ -135,11 +145,11 @@ gtk_source_completion_proposal_get_label (GtkSourceCompletionProposal *proposal)
/**
* gtk_source_completion_proposal_get_icon:
- * @proposal: The #GtkSourceCompletionProposal
+ * @proposal: A #GtkSourceCompletionProposal
*
- * Gets the icon of @proposal
+ * Gets the icon of @proposal.
*
- * Returns: The icon of @proposal
+ * Returns: The icon of @proposal.
*/
GdkPixbuf *
gtk_source_completion_proposal_get_icon (GtkSourceCompletionProposal *proposal)
@@ -150,14 +160,14 @@ gtk_source_completion_proposal_get_icon (GtkSourceCompletionProposal *proposal)
/**
* gtk_source_completion_proposal_get_info:
- * @proposal: The #GtkSourceCompletionProposal
+ * @proposal: A #GtkSourceCompletionProposal
*
* Gets extra information associated to the proposal. This information will be
* used to present the user with extra, detailed information about the
* selected proposal.
*
* Returns: The extra information of @proposal or %NULL if no extra information
- * is associated to @proposal
+ * is associated to @proposal.
*/
const gchar *
gtk_source_completion_proposal_get_info (GtkSourceCompletionProposal *proposal)
@@ -168,7 +178,7 @@ gtk_source_completion_proposal_get_info (GtkSourceCompletionProposal *proposal)
/**
* gtk_source_completion_proposal_changed:
- * @proposal: The #GtkSourceCompletionProposal
+ * @proposal: A #GtkSourceCompletionProposal
*
* Emits the "changed" signal on @proposal. This should be called by
* implementations whenever the name, icon or info of the proposal has
diff --git a/gtksourceview/gtksourcecompletionprovider.c b/gtksourceview/gtksourcecompletionprovider.c
index f160f27..697ee1d 100644
--- a/gtksourceview/gtksourcecompletionprovider.c
+++ b/gtksourceview/gtksourcecompletionprovider.c
@@ -161,9 +161,9 @@ gtk_source_completion_provider_get_type ()
* @provider: The #GtkSourceCompletionProvider
*
* Get the name of the provider. This should be a translatable name for
- * display to the user. For example: _("Document word completion provider")
+ * display to the user. For example: _("Document word completion provider").
*
- * Returns: The name of the provider
+ * Returns: The name of the provider.
*/
const gchar *
gtk_source_completion_provider_get_name (GtkSourceCompletionProvider *provider)
@@ -178,7 +178,8 @@ gtk_source_completion_provider_get_name (GtkSourceCompletionProvider *provider)
*
* Get the icon of the provider.
*
- * Returns: The icon to be used for the provider, or %NULL
+ * Returns: The icon to be used for the provider, or %NULL if the provider does
+ * not have a special icon.
*/
GdkPixbuf *
gtk_source_completion_provider_get_icon (GtkSourceCompletionProvider *provider)
@@ -192,7 +193,7 @@ gtk_source_completion_provider_get_icon (GtkSourceCompletionProvider *provider)
* @provider: The #GtkSourceCompletionProvider
* @iter: A #GtkTextIter
*
- * Get proposals from the provider for completion
+ * Get proposals from the provider for completion.
*
* Returns: a list of #GtkSourceViewProposal or NULL if there are no proposals.
* The returned list and the contained #GtkSourceViewProposal are
@@ -214,10 +215,12 @@ gtk_source_completion_provider_get_proposals (GtkSourceCompletionProvider *provi
* @criteria: A string representing the filter criteria
*
* Determines whether to filter @proposal based on @criteria. It is guaranteed
- * that @criteria is always a valid UTF-8 string (and never %NULL)
+ * that @criteria is always a valid UTF-8 string (and never %NULL).
+ * Implementations are not restricted to using @criteria as a filter criteria.
+ * They may also use @iter to do their own matching.
*
- * Returns: %TRUE if @proposal conforms to @criteria and should be available,
- * or %FALSE if @proposal should be hidden
+ * Returns: %TRUE if @proposal conforms to @criteria and should be show,
+ * or %FALSE if @proposal should be hidden.
*/
gboolean
gtk_source_completion_provider_filter_proposal (GtkSourceCompletionProvider *provider,
@@ -240,9 +243,9 @@ gtk_source_completion_provider_filter_proposal (GtkSourceCompletionProvider *pro
* @provider: The #GtkSourceCompletionProvider
*
* Get whether @provider responds to interactive completion (e.g. completion
- * when typing)
+ * when typing).
*
- * Returns: %TRUE if @provider can be used interactively, or %FALSE otherwise
+ * Returns: %TRUE if @provider can be used interactively, or %FALSE otherwise.
*/
gboolean
gtk_source_completion_provider_get_interactive (GtkSourceCompletionProvider *provider)
@@ -255,9 +258,12 @@ gtk_source_completion_provider_get_interactive (GtkSourceCompletionProvider *pro
* gtk_source_completion_provider_get_automatic:
* @provider: The #GtkSourceCompletionProvider
*
- * Get whether @provider is automatically included in the list of completions
+ * Get whether @provider is automatically included in the list of completions.
+ * This means that it will be shown in the default list of completions as
+ * activated by the "show-completion" keybinding (<Ctrl>space by default) on
+ * the #GtkSourceView.
*
- * Returns: %TRUE if @provider is automatically included, or %FALSE otherwise
+ * Returns: %TRUE if @provider is automatically included, or %FALSE otherwise.
*/
gboolean
gtk_source_completion_provider_get_automatic (GtkSourceCompletionProvider *provider)
@@ -271,16 +277,16 @@ gtk_source_completion_provider_get_automatic (GtkSourceCompletionProvider *provi
* @provider: The #GtkSourceCompletionProvider
* @proposal: The currently selected #GtkSourceCompletionProposal
*
- * Get a customized info widget to show extra information of a proposal with.
+ * Get a customized info widget to show extra information of a proposal.
* This allows for customized widgets on a proposal basis, although in general
* providers will have the same custom widget for all their proposals and
- * @proposal can be ignored. The implementation of this function is optional,
- * if implemented, #gtk_source_completion_provider_update_info MUST also be
+ * @proposal can be ignored. The implementation of this function is optional.
+ * If implemented, #gtk_source_completion_provider_update_info MUST also be
* implemented. If not implemented, the default
* #gtk_source_completion_proposal_get_info will be used to display extra
* information about a #GtkSourceCompletionProposal.
*
- * Returns: a custom #GtkWidget to show extra information about @proposal
+ * Returns: a custom #GtkWidget to show extra information about @proposal.
*/
GtkWidget *
gtk_source_completion_provider_get_info_widget (GtkSourceCompletionProvider *provider,
@@ -315,6 +321,19 @@ gtk_source_completion_provider_update_info (GtkSourceCompletionProvider *provide
GTK_SOURCE_COMPLETION_PROVIDER_GET_INTERFACE (provider)->update_info (provider, proposal, info);
}
+/**
+ * gtk_source_completion_provider_activate_proposal:
+ * @provider: A #GtkSourceCompletionProvider
+ * @proposal: A #GtkSourceCompletionProposal
+ * @iter: A #GtkTextIter
+ *
+ * Activate @proposal at @iter. When this functions returns %FALSE, the default
+ * activation of @proposal will take place which replaces the word at @iter
+ * with the label of @proposal.
+ *
+ * Returns: %TRUE to indicate that the proposal activation has been handled,
+ * %FALSE otherwise.
+ */
gboolean
gtk_source_completion_provider_activate_proposal (GtkSourceCompletionProvider *provider,
GtkSourceCompletionProposal *proposal,
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
