/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*- */
/*
 * 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, see <http://www.gnu.org/licenses/>.
 */

#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);
}