Merge pull request #465 from Cogitri/virtual-methods-example

examples: add virtual_methods

Author: sdroege

examples/Cargo.toml

@@ -104,4 +104,7 @@ path = "text_viewer/main.rs"
 name = "video_player"
 path = "video_player/main.rs"
 
+[[bin]]
+name = "virtual_methods"
+path = "virtual_methods/main.rs"
 

examples/virtual_methods/README.md

@@ -0,0 +1,12 @@
+# Virtual methods
+
+Example for how to create a base widget which exposes virtual methods that other widgets can override.
+In this case, a `BaseButton` class is defined which is a gtk::Button with two additional methods:
+
+* sync_method`: Synchronous method that updates the button label to `BaseButton sync`, or `BaseButton sync {extra_text}`. This showcases how arguments
+   can be passed to virtual methods. The `Option<String>` has to be boxed to be FFI-safe.
+* `async_method`: Asynchronous method that updates the button label to `BaseButton async`
+
+`DerivedButton` overrides the two methods. During construction `sync_method` is called in
+`BaseButton` which will set the label to `BaseButton sync` for `BaseButton` and to
+`DerivedButton sync` for `DerivedButton`.

examples/virtual_methods/base_button/imp.rs

@@ -0,0 +1,94 @@
+use super::BaseButtonExt;
+use gtk::{
+    gio,
+    glib::{self, Error},
+    prelude::*,
+    subclass::prelude::*,
+};
+use std::{future::Future, pin::Pin};
+
+pub type BaseButtonInstance = super::BaseButton;
+pub type PinnedFuture = Pin<Box<dyn Future<Output = Result<(), Error>> + 'static>>;
+
+/// GObject glue code for our BaseButtonClass which holds the function pointers to our virtual functions.
+#[repr(C)]
+pub struct BaseButtonClass {
+    pub parent_class: gtk::ffi::GtkButtonClass,
+    // If these functions are meant to be called from C, you need to make these functions
+    // `extern "C"` & use FFI-safe types (usually raw pointers).
+    pub sync_method: Option<unsafe fn(&BaseButtonInstance, extra_text: Option<String>)>,
+    pub async_method: Option<unsafe fn(&BaseButtonInstance) -> PinnedFuture>,
+}
+
+unsafe impl ClassStruct for BaseButtonClass {
+    type Type = BaseButton;
+}
+
+#[derive(Debug, Default)]
+pub struct BaseButton;
+
+// Virtual method default implementation trampolines
+fn sync_method_default_trampoline(this: &BaseButtonInstance, extra_text: Option<String>) {
+    BaseButton::from_instance(this).sync_method(this, extra_text)
+}
+
+fn async_method_default_trampoline(this: &BaseButtonInstance) -> PinnedFuture {
+    BaseButton::from_instance(this).async_method(this)
+}
+
+pub(super) unsafe fn base_button_sync_method(
+    this: &BaseButtonInstance,
+    extra_text: Option<String>,
+) {
+    let klass = &*(this.class() as *const _ as *const BaseButtonClass);
+    (klass.sync_method.unwrap())(this, extra_text)
+}
+
+pub(super) unsafe fn base_button_async_method(this: &BaseButtonInstance) -> PinnedFuture {
+    let klass = &*(this.class() as *const _ as *const BaseButtonClass);
+    klass.async_method.unwrap()(this)
+}
+
+/// Default implementations of our sync_method and async_method.
+impl BaseButton {
+    fn sync_method(&self, obj: &super::BaseButton, extra_text: Option<String>) {
+        if let Some(text) = extra_text {
+            obj.set_label(&format!("BaseButton sync: {}", text));
+        } else {
+            obj.set_label("BaseButton sync");
+        }
+    }
+
+    fn async_method(&self, obj: &super::BaseButton) -> PinnedFuture {
+        Box::pin(gio::GioFuture::new(
+            obj,
+            glib::clone!(@weak obj => move |_, _, send| {
+                obj.set_label("BaseButton async");
+                send.resolve(Ok(()));
+            }),
+        ))
+    }
+}
+
+#[glib::object_subclass]
+impl ObjectSubclass for BaseButton {
+    const NAME: &'static str = "ExampleBaseButton";
+    type ParentType = gtk::Button;
+    type Type = super::BaseButton;
+    type Class = BaseButtonClass;
+
+    fn class_init(klass: &mut Self::Class) {
+        klass.sync_method = Some(sync_method_default_trampoline);
+        klass.async_method = Some(async_method_default_trampoline);
+    }
+}
+
+impl ObjectImpl for BaseButton {
+    fn constructed(&self, obj: &Self::Type) {
+        // For demo purposes, call the sync_method during construction to set the button label
+        obj.sync_method(Some(String::from("Sync extra text")));
+    }
+}
+
+impl WidgetImpl for BaseButton {}
+impl ButtonImpl for BaseButton {}

examples/virtual_methods/base_button/mod.rs

@@ -0,0 +1,122 @@
+/// Public part of the BaseButton
+mod imp;
+
+pub use self::imp::PinnedFuture;
+use gtk::{
+    glib::{self, subclass::prelude::*},
+    prelude::*,
+    subclass::prelude::*,
+};
+
+glib::wrapper! {
+    pub struct BaseButton(ObjectSubclass<imp::BaseButton>)
+        @extends gtk::Widget, gtk::Button;
+}
+
+impl BaseButton {
+    pub fn new() -> Self {
+        glib::Object::new(&[]).expect("Failed to create BaseButton")
+    }
+}
+
+impl Default for BaseButton {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Public trait that implements our functions for everything that derives from BaseButton
+pub trait BaseButtonExt {
+    fn sync_method(&self, extra_text: Option<String>);
+    fn async_method(&self) -> PinnedFuture;
+}
+
+/// We call into imp::BaseButton_$method_name for each function. These will retrieve the
+/// correct class (the base class for the BaseButton or the derived class for DerivedButton)
+/// and call the correct implementation of the function.
+impl<O: IsA<BaseButton>> BaseButtonExt for O {
+    fn sync_method(&self, extra_text: Option<String>) {
+        unsafe { imp::base_button_sync_method(self.upcast_ref::<BaseButton>(), extra_text) }
+    }
+
+    fn async_method(&self) -> PinnedFuture {
+        unsafe { imp::base_button_async_method(self.upcast_ref::<BaseButton>()) }
+    }
+}
+
+/// The BaseButtonImpl that each derived private struct has to implement. See derived_button/imp.rs for how
+/// to override functions.
+pub trait BaseButtonImpl: ButtonImpl + ObjectImpl + 'static {
+    fn sync_method(&self, obj: &BaseButton, extra_text: Option<String>) {
+        self.parent_sync_method(obj, extra_text)
+    }
+
+    fn async_method(&self, obj: &BaseButton) -> PinnedFuture {
+        self.parent_async_method(obj)
+    }
+}
+
+pub trait BaseButtonImplExt: ObjectSubclass {
+    fn parent_sync_method(&self, obj: &BaseButton, extra_text: Option<String>);
+    fn parent_async_method(&self, obj: &BaseButton) -> PinnedFuture;
+}
+
+impl<T: BaseButtonImpl> BaseButtonImplExt for T {
+    fn parent_sync_method(&self, obj: &BaseButton, extra_text: Option<String>) {
+        unsafe {
+            let data = Self::type_data();
+            let parent_class = data.as_ref().parent_class() as *mut imp::BaseButtonClass;
+            if let Some(ref f) = (*parent_class).sync_method {
+                f(obj, extra_text)
+            } else {
+                unimplemented!()
+            }
+        }
+    }
+
+    fn parent_async_method(&self, obj: &BaseButton) -> PinnedFuture {
+        unsafe {
+            let data = Self::type_data();
+            let parent_class = data.as_ref().parent_class() as *mut imp::BaseButtonClass;
+            if let Some(ref f) = (*parent_class).async_method {
+                f(obj)
+            } else {
+                unimplemented!()
+            }
+        }
+    }
+}
+
+/// Make the BaseButton subclassable
+unsafe impl<T: BaseButtonImpl> IsSubclassable<T> for BaseButton {
+    fn class_init(class: &mut glib::Class<Self>) {
+        <gtk::Button as IsSubclassable<T>>::class_init(class.upcast_ref_mut());
+
+        let klass = class.as_mut();
+        klass.sync_method = Some(sync_method_trampoline::<T>);
+        klass.async_method = Some(async_method_trampoline::<T>);
+    }
+
+    fn instance_init(instance: &mut glib::subclass::InitializingObject<T>) {
+        <gtk::Button as IsSubclassable<T>>::instance_init(instance);
+    }
+}
+
+// Virtual method implementation trampolines
+unsafe fn sync_method_trampoline<T>(this: &BaseButton, extra_text: Option<String>)
+where
+    T: ObjectSubclass + BaseButtonImpl,
+{
+    let instance = &*(this as *const _ as *const T::Instance);
+    let imp = instance.impl_();
+    imp.sync_method(this, extra_text)
+}
+
+unsafe fn async_method_trampoline<T>(this: &BaseButton) -> PinnedFuture
+where
+    T: ObjectSubclass + BaseButtonImpl,
+{
+    let instance = &*(this as *const _ as *const T::Instance);
+    let imp = instance.impl_();
+    imp.async_method(this)
+}

examples/virtual_methods/derived_button/imp.rs

@@ -0,0 +1,35 @@
+use crate::base_button::*;
+use gtk::{gio, glib, prelude::*, subclass::prelude::*};
+
+#[derive(Debug, Default)]
+pub struct DerivedButton {}
+
+#[glib::object_subclass]
+impl ObjectSubclass for DerivedButton {
+    const NAME: &'static str = "ExampleDerivedButton";
+    type ParentType = BaseButton;
+    type Type = super::DerivedButton;
+}
+
+impl ObjectImpl for DerivedButton {}
+impl WidgetImpl for DerivedButton {}
+impl ButtonImpl for DerivedButton {}
+
+/// Implement the base trait and override the functions
+impl BaseButtonImpl for DerivedButton {
+    fn sync_method(&self, obj: &BaseButton, extra_text: Option<String>) {
+        if let Some(text) = extra_text {
+            obj.set_label(&format!("DerivedButton sync {}", text));
+        } else {
+            obj.set_label("DerivedButton sync");
+        }
+    }
+
+    fn async_method(&self, obj: &BaseButton) -> PinnedFuture {
+        let obj_cloned = obj.clone();
+        Box::pin(gio::GioFuture::new(obj, move |_, _, send| {
+            obj_cloned.set_label("DerivedButton async");
+            send.resolve(Ok(()));
+        }))
+    }
+}

examples/virtual_methods/derived_button/mod.rs

@@ -0,0 +1,20 @@
+mod imp;
+
+use gtk::glib;
+
+glib::wrapper! {
+    pub struct DerivedButton(ObjectSubclass<imp::DerivedButton>)
+        @extends gtk::Widget, gtk::Button, crate::base_button::BaseButton;
+}
+
+impl DerivedButton {
+    pub fn new() -> Self {
+        glib::Object::new(&[]).expect("Failed to create DerivedButton")
+    }
+}
+
+impl Default for DerivedButton {
+    fn default() -> Self {
+        Self::new()
+    }
+}

examples/virtual_methods/main.rs

@@ -0,0 +1,42 @@
+mod base_button;
+mod derived_button;
+
+use crate::base_button::BaseButtonExt;
+use gtk::{
+    glib::{self, clone},
+    prelude::*,
+};
+
+fn main() {
+    let application = gtk::Application::new(
+        Some("com.github.gtk-rs.examples.virtual_methods"),
+        Default::default(),
+    );
+
+    application.connect_activate(|app| {
+        let win = gtk::ApplicationWindow::new(app);
+        let boxed = gtk::Box::new(gtk::Orientation::Horizontal, 6);
+        let base_button = base_button::BaseButton::new();
+        let derived_button = derived_button::DerivedButton::new();
+
+        base_button.connect_clicked(|b| {
+            let ctx = glib::MainContext::default();
+            ctx.spawn_local(clone!(@weak b => async move {
+                b.async_method().await.unwrap();
+            }));
+        });
+        derived_button.connect_clicked(|b| {
+            let ctx = glib::MainContext::default();
+            ctx.spawn_local(clone!(@weak b => async move {
+                b.async_method().await.unwrap();
+            }));
+        });
+
+        boxed.append(&base_button);
+        boxed.append(&derived_button);
+        win.set_child(Some(&boxed));
+        win.show();
+    });
+
+    application.run();
+}