No current support for custom auto-complete

[john01dav]

I'm currently trying to use this crate in a project that needs heavy-duty source code editing. Part of that is a basic auto-complete implementation. It needs to be a bit more context-sensitive than the current words-based implementation, but not by much. I've decided what algorithms I want to use to do the actual completion, but getting the library to call my code to do the completion and present it to the user seems to currently be impossible. As such, this is a feature request to add the necessary API hooks to make that happen.

While only adding the necessary traits as described in the linked issue is one way of adding this support, ideally, a subclass or interface implementation would not be needed to use these features, as those techniques are cumbersome with GObject in general, but, it would seem, especially so in Rust since one must not only deal with GObject (which is as cumbersome as any C API), but must also deal with the intricacies of the binding at the same time.

As such, I propose a different interface where there is a simple trait that the user can implement, and then pass a dyn object to the Rust bindings to act in a similar way as the GObject interface, but where it is significantly easier to use because Rust has built-in support for implementing traits. This could be implemented via adding those traits, then creating a Rust implementation that has a Box<dyn TheTraitThatIJustMentioned> as a member.

While I am willing to attempt this addition myself and PR it, I don't think that I'm the best person to do that. I'm currently new to Rust, GTK/GObject, and these bindings (I've never even used Rust's FFI support), so if I were to do it it would likely have many errors, if I could get it working at all. I do have significant experience with other tools though, such as C without GObject, C++, and some minimal assembly (I once had to write some assembly to call C functions and be called as a C function, without the aid of a compiler, so I am familiar with how FFI probably works despite the fact that I haven't looked into it.).

[john01dav]

@GuillaumeGomez Since you won't be doing this, can I get your opinion on what I said about using a Rust trait instead of normal interface implementations before I attempt to PR this? Also, would such a PR be welcome?

[GuillaumeGomez]

If the API is easy to use in the end for the users, then I'm fine with it. We currently generate most of the API with gir, which allows us to have a low maintenance. With all this in mind, this library doesn't change much (even less since the version 4 has been released) so I guess it's ok to have more manual code.

So if you have the motivation to do it, then please do so. It's very welcome.

[john01dav]

I'm going to attempt it.... I'm not sure how well it will turn out, but I'm attempting it.

Also let me know if you want to work on adding the subclassing pieces for this specific interface to the sourceview bindings. Then I can give you links to good code examples for what has to be done there in this case.

@sdroege Could I get these links? The most basic example that is currently here would be best, so that I just see what's important.

[sdroege]

So, CompletionProvider fortunately exists already for the "consume" side of the bindings, and I hope it's complete enough: https://github.com/gtk-rs/sourceview/blob/master/src/auto/completion_provider.rs

Now this is an interface. So you would have to add something like https://github.com/gtk-rs/gio/blob/master/src/subclass/seekable.rs . Instead of the virtual methods of Seekable, you would add the ones from CompletionProvider there with the correct behaviour/semantics. https://developer.gnome.org/gtksourceview/stable/GtkSourceCompletionProvider.html#GtkSourceCompletionProviderIface gives a list of all of them. That fortunately doesn't look like it's a special or complicated case. So this comes in 4 parts: 1) an Impl trait with the virtual methods, 2) an IsImplementable impl, 3) the C/Rust FFI translation functions

At that point you would then have enough bindings to actually implement some glib::Object subclass that implements this interface. An example would here be the ReadInputStream in gio, which implements the Seekable interface: https://github.com/gtk-rs/gio/blob/master/src/read_input_stream.rs. The important parts here are the two top impl blocks and the SeekableImpl block.

[sdroege]

The important parts here are the two top impl blocks and the SeekableImpl block.

Below that with glib_wrapper! and all that is not absolutely required and only exists to provide nice high-level Rust bindings for the new subclass. Only the part inside the imp module there is required. Without all that other stuff you would also just create an instance via glib::Object::new() like is done there.

[john01dav]

I've been trying to make heads or tails out of GObject enough to be able to write something like this, and I'm not getting anywhere. Is there some documentation that exists that will clearly spell out how this is supposed to work? Even if it doesn't have the complete story, I know nothing right now aside from how to use the existing bindings. I'm seeing a jumble of macros, traits, structs, etc. when I look at the existing source, with no clear pattern to them. When I think that I've figured something out, I invariably find something else a few hours later that contradicts it. I don't think that I can do this without at least some documentation — I have literally no idea how GObject works, yet I'm trying to implement bindings in another language! It's mildly absurd, and I'll need some help if it is going to happen.

[sdroege]

Maybe https://developer.gnome.org/gobject/2.62/pt02.html can help? That's the C part of the whole story.

From looking at the pieces of the gio::Seekable interface bindings, which parts are causing you trouble? Do my explanations in gtk-rs/examples#279 help you in any way?

I agree that we need to put something into a more complete documentation here to explain how all the pieces fit together but I don't really have the time to do that right now, it's going to be a day or two of work. So feel free to ask questions for now.

[john01dav]

So feel free to ask questions for now. ... which parts are causing you trouble?

I think that probably the best way to help clarify this is if I put some questions here as I come across them — that should allow me to get an authoritative answer in a reasonable amount of time (as opposed to hours of digging through source to infer something that's probably wrong, which is what I've been doing).

The first issue that I'm having relates to "an Impl trait with the virtual methods." I created a trait that looks like this:

use glib::subclass::prelude::*;

pub trait CompletionImpl: ObjectImpl + Send + 'static {
    //...
}

and, I presume, that the methods from here should be mirrored into this trait, but it's not clear what the signatures should be. For example, take the C method get_name. The following all seem like valid Rust equivalents to me (among others):

fn get_name(&self) -> glib::char::Char; //Why would this type exist if it isn't used at the low level like this? The same pointer stuff below applies here to create 2 additional possibilities.
fn get_name(&self) -> char; //The seekable example seems to use native Rust types/
fn get_name(&self) -> *char; //Maybe Rust's unsafe pointers should be used?
fn get_name(&self) -> *mut char; //The pointer is mutable in C, maybe it is here too?

Of course, only one of them is likely correct, but I have no basis from which to make that determination (for this function, or for others). What are the rules for rewriting these signatures?

I know that it seems like I haven't gotten very far — that's because what I've done so far as mostly consisted of reading things and trying to make heads or tails out of what's going on. My learning style usually requires me to first use some well-written documentation to get a good conceptual foundation, and only then go on to writing code (or doing whatever it is that I'm trying to learn). For obvious reasons though, that didn't work very well in this case, so I'm now trying something different.

[sdroege]

Of course, only one of them is likely correct, but I have no basis from which to make that determination (for this function, or for others). What are the rules for rewriting these signatures?

You would use the corresponding proper Rust types. So for example get_name() in C takes the instance as argument and returns a string (i.e. gchar *). In Rust that would be function taking &self as your guesses did, and you would return a String or Option<String> depending whether the C function is allowed to return NULL (that would be in the docs somewhere, or in the worst case you would have to read the code. My understanding is that it must not be NULL but various other functions there are allowed to return NULL). That would already be almost correct (and in fact would work). However we have a custom string type in the glib crate that uses the GLib allocator to prevent some more copies (glib::GString). You could use String but glib::String would be a bit more efficient here.

Now the function doesn't return a const gchar* but non-const one. That hints at us that the ownership of the string is returned to the caller. Similarly the documentation of the actual function confirms that (the part about g_free()). So for conversion from a Rust glib::GString (or String) to a gchar * you would use glib::translate::ToGlibPtr::to_glib_full() (i.e. your_string.to_glib_full() after the trait is in scope).

I know that it seems like I haven't gotten very far

No worries about that :) This is not exactly easy stuff. Personally I would tackle this by reading other code in the bindings that does similar things and try to understand that, probably having problems understanding how things fit together and then ask based on the existing code. But let's just go through it one by one here if you prefer that.

[sdroege]

I forgot to actually write the whole signature in the end, sorry. That would be fn get_name(&self, obj: &CompletionProvider) -> glib::GString. In addition to &self we also always provide the GObject to the functions as second parameter. The first is your implementation of it (think: private state, the collection of private member variables if this was C++ or Java), the second is the public part.

[john01dav]

Okay... what you've said has been very helpful. Thank you :) I think that I have a correct Impl trait. Is there any way to have the compiler check it? I'd rather have that happen at each step, to avoid the situation where there's some issue somewhere, and things mysteriously don't work (This usually happens when I work with C APIs, after implementing a big chunk of stuff without the ability to test each step. OpenGl has been the worst offender.).

Here's what I have:

use crate::CompletionActivation;
use crate::CompletionContext;
use crate::CompletionInfo;
use crate::CompletionProposal;
use crate::CompletionProvider;
use glib::subclass::prelude::*;

pub trait CompletionImpl: ObjectImpl + Send + 'static {
    fn get_name(&self, obj: &CompletionProvider) -> glib::GString;
    fn get_icon(&self, obj: &CompletionProvider) -> Option<gdk_pixbuf::Pixbuf>;
    fn get_icon_name(&self, obj: &CompletionProvider) -> Option<glib::GString>;
    fn get_gicon(&self, obg: &CompletionProvider) -> Option<gio_sys::GIcon>;
    fn populate(&self, obg: &CompletionProvider, context: &CompletionContext);
    fn get_activation(&self, obg: &CompletionProvider) -> CompletionActivation;
    fn provider_match(&self, obg: &CompletionProvider, context: &CompletionContext) -> bool;
    fn get_info_widget(
        &self,
        obg: &CompletionProvider,
        proposal: &CompletionProposal,
    ) -> Option<gtk::Widget>;
    fn update_info(
        &self,
        obg: &CompletionProvider,
        proposal: &CompletionProposal,
        info: &CompletionInfo,
    );
    fn get_start_iter(
        &self,
        obg: &CompletionProvider,
        context: &CompletionContext,
        proposal: &CompletionProposal,
        iter: &gtk::TextIter,
    ) -> bool;
    fn activate_proposal(
        &self,
        obg: &CompletionProvider,
        proposal: &CompletionProposal,
        iter: &gtk::TextIter,
    ) -> bool;
    fn get_interactive_delay(&self, obj: &CompletionProvider) -> i32;
    fn get_priority(&self, obg: &CompletionProvider) -> i32;
}

[sdroege]

I think that I have a correct Impl trait. Is there any way to have the compiler check it

Not really. If it compiles then there's no mistake the compiler could catch. The trait looks generally good to me, not obvious problems.

When implementing the other pieces you might notice that things don't fit together in a way the compiler likes it (or the implementation doesn't make sense). But that would be exactly the next step. You'd add one by one the unsafe extern "C" functions for each of them. After each one you can check if it compiles. And in the very end you can add the IsImplementable trait implementation to put it all together.

[john01dav]

When moving on to implementing the glue functions (the functions that the C code can call, which then delegate to the Rust implementation, such as this one — I'm not sure what the standard name is for these, so I must clearly define the terms that I'm using.), once again, I'm having trouble with determining the method signature. Specifically, I am working on the get_name() function, and its return type in C is gchar. I expected there to be a similar type in glib_sys, since that's where the seeker example that you linked gets its primitive types from (an example with gboolean). I was then expecting to have a pointer to the type, making the return type *glib_sys::gchar (or something similar) and the method signature in its entirety being

unsafe fn get_name_glue<T: ObjectSubclass + CompletionImpl>(completion_provider: *mut gtk_source_sys::GtkSourceCompletionProvider) -> *glib_sys::gchar;

, but, it would appear that no such type exists in glib_sys, even under other names.

[sdroege]

It's std::os::raw::c_char / libc::c_char. The correct signature would be

unsafe fn get_name_glue<T: ObjectSubclass>(completion_provider: *mut gtk_source_sys::GtkSourceCompletionProvider) -> *mut c_char;

Also for consistency your trait should be called CompletionProviderImpl.

[sdroege]

https://gitlab.freedesktop.org/gstreamer/gstreamer-rs/-/blob/master/gstreamer/src/subclass/uri_handler.rs#L75 would be an example of an interface that has functions returning strings.