/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*- */
/* gtksourcecompletionprovider.c
* This file is part of GtkSourceView
*
* Copyright (C) 2007 - 2009 Jesús Barbero Rodríguez <chuchiperriman@gmail.com>
* Copyright (C) 2009 - Jesse van den Kieboom <jessevdk@gnome.org>
*
* GtkSourceView is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* GtkSourceView is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
#include "gtksourcecompletionprovider.h"
#include "gtksourcecompletionproposal.h"
#include "gtksourcecompletioninfo.h"
/**
* SECTION:completionprovider
* @title: GtkSourceCompletionProvider
* @short_description: Completion provider interface
*
* You must implement this interface to provide proposals to #GtkSourceCompletion
*
* The provider may be displayed in the completion window as a header row, showing
* its name and optionally an icon.
* The icon may be specified as a #GdkPixbuf, as an icon name or as a #GIcon by
* implementing the corresponding get function. At most one of those get functions
* should return a value different from %NULL, if they all return %NULL no icon
* will be used.
*/
typedef GtkSourceCompletionProviderIface GtkSourceCompletionProviderInterface;
G_DEFINE_INTERFACE(GtkSourceCompletionProvider, gtk_source_completion_provider, G_TYPE_OBJECT)
/* Default implementations */
static gchar *
gtk_source_completion_provider_get_name_default (GtkSourceCompletionProvider *provider)
{
g_return_val_if_reached (NULL);
}
static GdkPixbuf *
gtk_source_completion_provider_get_icon_default (GtkSourceCompletionProvider *provider)
{
return NULL;
}
static const gchar *
gtk_source_completion_provider_get_icon_name_default (GtkSourceCompletionProvider *provider)
{
return NULL;
}
static GIcon *
gtk_source_completion_provider_get_gicon_default (GtkSourceCompletionProvider *provider)
{
return NULL;
}
static void
gtk_source_completion_provider_populate_default (GtkSourceCompletionProvider *provider,
GtkSourceCompletionContext *context)
{
gtk_source_completion_context_add_proposals (context, provider, NULL, TRUE);
}
static GtkSourceCompletionActivation
gtk_source_completion_provider_get_activation_default (GtkSourceCompletionProvider *provider)
{
return GTK_SOURCE_COMPLETION_ACTIVATION_INTERACTIVE |
GTK_SOURCE_COMPLETION_ACTIVATION_USER_REQUESTED;
}
static gboolean
gtk_source_completion_provider_match_default (GtkSourceCompletionProvider *provider,
GtkSourceCompletionContext *context)
{
return TRUE;
}
static GtkWidget *
gtk_source_completion_provider_get_info_widget_default (GtkSourceCompletionProvider *provider,
GtkSourceCompletionProposal *proposal)
{
return NULL;
}
static void
gtk_source_completion_provider_update_info_default (GtkSourceCompletionProvider *provider,
GtkSourceCompletionProposal *proposal,
GtkSourceCompletionInfo *info)
{
}
static gboolean
gtk_source_completion_provider_get_start_iter_default (GtkSourceCompletionProvider *provider,
GtkSourceCompletionContext *context,
GtkSourceCompletionProposal *proposal,
GtkTextIter *iter)
{
return FALSE;
}
static gboolean
gtk_source_completion_provider_activate_proposal_default (GtkSourceCompletionProvider *provider,
GtkSourceCompletionProposal *proposal,
GtkTextIter *iter)
{
return FALSE;
}
static gint
gtk_source_completion_provider_get_interactive_delay_default (GtkSourceCompletionProvider *provider)
{
/* -1 means the default value in the completion object */
return -1;
}
static gint
gtk_source_completion_provider_get_priority_default (GtkSourceCompletionProvider *provider)
{
return 0;
}
static void
gtk_source_completion_provider_default_init (GtkSourceCompletionProviderIface *iface)
{
iface->get_name = gtk_source_completion_provider_get_name_default;
iface->get_icon = gtk_source_completion_provider_get_icon_default;
iface->get_icon_name = gtk_source_completion_provider_get_icon_name_default;
iface->get_gicon = gtk_source_completion_provider_get_gicon_default;
iface->populate = gtk_source_completion_provider_populate_default;
iface->match = gtk_source_completion_provider_match_default;
iface->get_activation = gtk_source_completion_provider_get_activation_default;
iface->get_info_widget = gtk_source_completion_provider_get_info_widget_default;
iface->update_info = gtk_source_completion_provider_update_info_default;
iface->get_start_iter = gtk_source_completion_provider_get_start_iter_default;
iface->activate_proposal = gtk_source_completion_provider_activate_proposal_default;
iface->get_interactive_delay = gtk_source_completion_provider_get_interactive_delay_default;
iface->get_priority = gtk_source_completion_provider_get_priority_default;
}
/**
* gtk_source_completion_provider_get_name:
* @provider: a #GtkSourceCompletionProvider.
*
* Get the name of the provider. This should be a translatable name for
* display to the user. For example: _("Document word completion provider"). The
* returned string must be freed with g_free().
*
* Returns: a new string containing the name of the provider.
*/
gchar *
gtk_source_completion_provider_get_name (GtkSourceCompletionProvider *provider)
{
g_return_val_if_fail (GTK_SOURCE_IS_COMPLETION_PROVIDER (provider), NULL);
return GTK_SOURCE_COMPLETION_PROVIDER_GET_INTERFACE (provider)->get_name (provider);
}
/**
* gtk_source_completion_provider_get_icon:
* @provider: The #GtkSourceCompletionProvider
*
* Get the #GdkPixbuf for the icon of the @provider.
*
* Returns: (nullable) (transfer none): 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)
{
g_return_val_if_fail (GTK_SOURCE_IS_COMPLETION_PROVIDER (provider), NULL);
return GTK_SOURCE_COMPLETION_PROVIDER_GET_INTERFACE (provider)->get_icon (provider);
}
/**
* gtk_source_completion_provider_get_icon_name:
* @provider: The #GtkSourceCompletionProvider
*
* Gets the icon name of @provider.
*
* Returns: (nullable) (transfer none): The icon name to be used for the provider,
* or %NULL if the provider does not have a special icon.
*
* Since: 3.18
*/
const gchar *
gtk_source_completion_provider_get_icon_name (GtkSourceCompletionProvider *provider)
{
g_return_val_if_fail (GTK_SOURCE_IS_COMPLETION_PROVIDER (provider), NULL);
return GTK_SOURCE_COMPLETION_PROVIDER_GET_INTERFACE (provider)->get_icon_name (provider);
}
/**
* gtk_source_completion_provider_get_gicon:
* @provider: The #GtkSourceCompletionProvider
*
* Gets the #GIcon for the icon of @provider.
*
* Returns: (nullable) (transfer none): The icon to be used for the provider,
* or %NULL if the provider does not have a special icon.
*
* Since: 3.18
*/
GIcon *
gtk_source_completion_provider_get_gicon (GtkSourceCompletionProvider *provider)
{
g_return_val_if_fail (GTK_SOURCE_IS_COMPLETION_PROVIDER (provider), NULL);
return GTK_SOURCE_COMPLETION_PROVIDER_GET_INTERFACE (provider)->get_gicon (provider);
}
/**
* gtk_source_completion_provider_populate:
* @provider: a #GtkSourceCompletionProvider.
* @context: a #GtkSourceCompletionContext.
*
* Populate @context with proposals from @provider added with the
* gtk_source_completion_context_add_proposals() function.
*/
void
gtk_source_completion_provider_populate (GtkSourceCompletionProvider *provider,
GtkSourceCompletionContext *context)
{
g_return_if_fail (GTK_SOURCE_IS_COMPLETION_PROVIDER (provider));
GTK_SOURCE_COMPLETION_PROVIDER_GET_INTERFACE (provider)->populate (provider, context);
}
/**
* gtk_source_completion_provider_get_activation:
* @provider: a #GtkSourceCompletionProvider.
*
* Get with what kind of activation the provider should be activated.
*
* Returns: a combination of #GtkSourceCompletionActivation.
**/
GtkSourceCompletionActivation
gtk_source_completion_provider_get_activation (GtkSourceCompletionProvider *provider)
{
g_return_val_if_fail (GTK_SOURCE_IS_COMPLETION_PROVIDER (provider), GTK_SOURCE_COMPLETION_ACTIVATION_NONE);
return GTK_SOURCE_COMPLETION_PROVIDER_GET_INTERFACE (provider)->get_activation (provider);
}
/**
* gtk_source_completion_provider_match:
* @provider: a #GtkSourceCompletionProvider.
* @context: a #GtkSourceCompletionContext.
*
* Get whether the provider match the context of completion detailed in
* @context.
*
* Returns: %TRUE if @provider matches the completion context, %FALSE otherwise.
*/
gboolean
gtk_source_completion_provider_match (GtkSourceCompletionProvider *provider,
GtkSourceCompletionContext *context)
{
g_return_val_if_fail (GTK_SOURCE_IS_COMPLETION_PROVIDER (provider), TRUE);
return GTK_SOURCE_COMPLETION_PROVIDER_GET_INTERFACE (provider)->match (provider,
context);
}
/**
* gtk_source_completion_provider_get_info_widget:
* @provider: a #GtkSourceCompletionProvider.
* @proposal: a currently selected #GtkSourceCompletionProposal.
*
* 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 this function is not implemented, the default widget is a #GtkLabel. The
* return value of gtk_source_completion_proposal_get_info() is used as the
* content of the #GtkLabel.
*
* <note>
* <para>
* If implemented, gtk_source_completion_provider_update_info()
* <emphasis>must</emphasis> also be implemented.
* </para>
* </note>
*
* Returns: (nullable) (transfer none): a custom #GtkWidget to show extra
* information about @proposal, or %NULL if the provider does not have a special
* info widget.
*/
GtkWidget *
gtk_source_completion_provider_get_info_widget (GtkSourceCompletionProvider *provider,
GtkSourceCompletionProposal *proposal)
{
g_return_val_if_fail (GTK_SOURCE_IS_COMPLETION_PROVIDER (provider), NULL);
g_return_val_if_fail (GTK_SOURCE_IS_COMPLETION_PROPOSAL (proposal), NULL);
return GTK_SOURCE_COMPLETION_PROVIDER_GET_INTERFACE (provider)->get_info_widget (provider, proposal);
}
/**
* gtk_source_completion_provider_update_info:
* @provider: a #GtkSourceCompletionProvider.
* @proposal: a #GtkSourceCompletionProposal.
* @info: a #GtkSourceCompletionInfo.
*
* Update extra information shown in @info for @proposal.
*
* <note>
* <para>
* This function <emphasis>must</emphasis> be implemented when
* gtk_source_completion_provider_get_info_widget() is implemented.
* </para>
* </note>
*/
void
gtk_source_completion_provider_update_info (GtkSourceCompletionProvider *provider,
GtkSourceCompletionProposal *proposal,
GtkSourceCompletionInfo *info)
{
g_return_if_fail (GTK_SOURCE_IS_COMPLETION_PROVIDER (provider));
g_return_if_fail (GTK_SOURCE_IS_COMPLETION_PROPOSAL (proposal));
g_return_if_fail (GTK_SOURCE_IS_COMPLETION_INFO (info));
GTK_SOURCE_COMPLETION_PROVIDER_GET_INTERFACE (provider)->update_info (provider, proposal, info);
}
/**
* gtk_source_completion_provider_get_start_iter:
* @provider: a #GtkSourceCompletionProvider.
* @proposal: a #GtkSourceCompletionProposal.
* @context: a #GtkSourceCompletionContext.
* @iter: (out): a #GtkTextIter.
*
* Get the #GtkTextIter at which the completion for @proposal starts. When
* implemented, this information is used to position the completion window
* accordingly when a proposal is selected in the completion window. The
* @proposal text inside the completion window is aligned on @iter.
*
* If this function is not implemented, the word boundary is taken to position
* the completion window. See gtk_source_completion_provider_activate_proposal()
* for an explanation on the word boundaries.
*
* When the @proposal is activated, the default handler uses @iter as the start
* of the word to replace. See
* gtk_source_completion_provider_activate_proposal() for more information.
*
* Returns: %TRUE if @iter was set for @proposal, %FALSE otherwise.
*/
gboolean
gtk_source_completion_provider_get_start_iter (GtkSourceCompletionProvider *provider,
GtkSourceCompletionContext *context,
GtkSourceCompletionProposal *proposal,
GtkTextIter *iter)
{
g_return_val_if_fail (GTK_SOURCE_IS_COMPLETION_PROVIDER (provider), FALSE);
g_return_val_if_fail (GTK_SOURCE_IS_COMPLETION_CONTEXT (context), FALSE);
g_return_val_if_fail (GTK_SOURCE_IS_COMPLETION_PROPOSAL (proposal), FALSE);
g_return_val_if_fail (iter != NULL, FALSE);
return GTK_SOURCE_COMPLETION_PROVIDER_GET_INTERFACE (provider)->get_start_iter (provider,
context,
proposal,
iter);
}
/**
* 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 text of @proposal (see gtk_source_completion_proposal_get_text()).
*
* Here is how the default activation selects the boundaries of the word to
* replace. The end of the word is @iter. For the start of the word, it depends
* on whether a start iter is defined for @proposal (see
* gtk_source_completion_provider_get_start_iter()). If a start iter is defined,
* the start of the word is the start iter. Else, the word (as long as possible)
* will contain only alphanumerical and the "_" characters.
*
* Returns: %TRUE to indicate that the proposal activation has been handled,
* %FALSE otherwise.
*/
gboolean
gtk_source_completion_provider_activate_proposal (GtkSourceCompletionProvider *provider,
GtkSourceCompletionProposal *proposal,
GtkTextIter *iter)
{
g_return_val_if_fail (GTK_SOURCE_IS_COMPLETION_PROVIDER (provider), FALSE);
g_return_val_if_fail (GTK_SOURCE_IS_COMPLETION_PROPOSAL (proposal), FALSE);
return GTK_SOURCE_COMPLETION_PROVIDER_GET_INTERFACE (provider)->activate_proposal (provider,
proposal,
iter);
}
/**
* gtk_source_completion_provider_get_interactive_delay:
* @provider: a #GtkSourceCompletionProvider.
*
* Get the delay in milliseconds before starting interactive completion for
* this provider. A value of -1 indicates to use the default value as set
* by the #GtkSourceCompletion:auto-complete-delay property.
*
* Returns: the interactive delay in milliseconds.
**/
gint
gtk_source_completion_provider_get_interactive_delay (GtkSourceCompletionProvider *provider)
{
g_return_val_if_fail (GTK_SOURCE_IS_COMPLETION_PROVIDER (provider), -1);
return GTK_SOURCE_COMPLETION_PROVIDER_GET_INTERFACE (provider)->get_interactive_delay (provider);
}
/**
* gtk_source_completion_provider_get_priority:
* @provider: a #GtkSourceCompletionProvider.
*
* Get the provider priority. The priority determines the order in which
* proposals appear in the completion popup. Higher priorities are sorted
* before lower priorities. The default priority is 0.
*
* Returns: the provider priority.
**/
gint
gtk_source_completion_provider_get_priority (GtkSourceCompletionProvider *provider)
{
g_return_val_if_fail (GTK_SOURCE_IS_COMPLETION_PROVIDER (provider), 0);
return GTK_SOURCE_COMPLETION_PROVIDER_GET_INTERFACE (provider)->get_priority (provider);
}