Re: Code completion proposal for GtkSourceView

[Emmanuele Bassi <ebassi gmail com>]

* Paolo Maggi <paolo maggi polito it>:

> I have read your specification but I'm unable to comment on it since I
> have not understood how your GtkSourceCompletionEngine is going to
> interact with GtkSourceBuffer. Could you please try to be more clear
> about this really important aspect?

Right now, and as a first implementation of my specs, I was planning
little or no interaction; basically, the GtkSourceCompletionEngine class
will hold a reference to the GtkSourceBuffer.

> Why complete takes two GtkTextIter as parameters and can_complete does
> not?

The ::complete vfunc is were the magic happens, i.e.:
	
	GtkSourceBuffer *sb;
	GtkSourceCompletionEngine *sce;
	GSList *alternatives;
	
	sce = my_code_completion_engine ();
	
	gtk_source_completion_engine_set_buffer (sce, GTK_TEXT_BUFFER (sb));
	alternatives = gtk_source_completion_engine (sce);
	...

A basic form of code completion feature should be implemented like this.

The ::can_complete method is a flag setter like GtkSourceUndoManager::can_undo.
Imagine a completion engine implemented upon CTags: if ctags has not
been found on the system, code completion will be disabled at runtime; the
code above would become:

	GtkSourceBuffer *sb;
	GtkSourceCompletionEngine *sce;
	GSList *alternatives;

	sce = my_code_completion_engine ();

+	if (! gtk_source_completion_engine_can_complete (sce))
+	{
+		error_message_dialog ("No code completion available");
+		return;
+	}
+
	gtk_source_completion_engine_set_buffer (sce, GTK_TEXT_BUFFER (sb));
	alternatives = gtk_source_completion_engine (sce);
	...

> I'm not sure that complete should return a list of strings. I think you
> should return some more complex object. For example, you would have to
> show the user the visibility (public/private/protected) of the function
> you are going to complete and eventually some form of documentation.

This would mean creating a CompletionMeta object, which could contain
some user stuff.  Something along these lines:

/* visibility flags */
typedef enum {
	GTK_SOURCE_META_PUBLIC = 1<<0,
	GTK_SOURCE_META_PRIVATE = 1<<1,
	GTK_SOURCE_META_PROTECTED = 1<<2,
	...
} GtkSourceMetaVisibility;

/* function */
struct _GtkSourceFunctionMeta
{
	gint visibility : 1;
	
	gchar *name;
	
	gint args_num;
	gchar **args_types;

	gchar *return_type;
};

/* variable */
struct _GtkSourceVariableMeta
{
	gint visibility : 1;

	gchar *name;
	gchar *type;
};

/* symbolic stuff (label, macro, etc.) */
struct _GtkSourceSymbolicMeta
{
	gchar *name;
}

/* opaque container types */
typedef enum {
	GTK_SOURCE_META_FUNCTION = 0,
	GTK_SOURCE_META_VARIABLE,
	GTK_SOURCE_META_SYMBOL,
	...
} GtkSourceMetaType;

/* the opaque container for metadata */
struct _GtkSourceCompletionMeta
{
	GtkSourceMetaType type;

	union {
		GtkSourceFunctionMeta *function;
		GtkSourceVariableMeta *variable;
		GtkSourceSymbolicMeta *symbol;
		...
	} d;
};

> I gave the problem of displaying an autocompletion list some thought
> last year and I should have a prototype on one of my PC... I will send
> you it if I will be able to find it.

That would be most useful.

Regards,
 Emmanuele.

-- 
Emmanuele Bassi (Zefram)                 [ http://www.emmanuelebassi.net ]
GnuPG Key fingerprint = 4DD0 C90D 4070 F071 5738  08BD 8ECC DB8F A432 0FF4