Merge branch 'bilelmoussaoui/examples' into 'master'

Add basic examples

See merge request !3

src/lib.rs

+///
+/// Retrieve a widget from a gtk::Builder
+///
+/// - Before:
+///
+///     Example:
+///
+///     ```no_run
+///     let builder = gtk::Builder::new_frm_resource("/org/gnome/App/ui/widget.ui");
+///     let widget: gtk::Label = builder.get_object("my_label").expect("Failed to find my_label object");
+///     widget.set_text("Hello world!");
+///     
+///     ```
+///
+/// - After:
+///
+///     Example 1:
+///     
+///     ```no_run
+///     let builder = gtk::Builder::new_from_resource("/org/gnome/App/ui/widget.ui");
+///     get_widget!(builder, gtk::Label, my_label);
+///     my_label.set_text("Hello world!");
+///     ```
+///     Example 2:
+///     
+///     ```no_run
+///     let builder = gtk::Builder::new_from_resource("/org/gnome/App/ui/widget.ui");
+///     get_widget!(builder, gtk::Label, @my_label).set_text("Hello world!");
+///     ```
 #[macro_export]
 macro_rules! get_widget {
     ($builder:expr, $wtype:ty, @$name:ident) => {{
@@ -9,6 +38,29 @@ macro_rules! get_widget {
     };
 }
 
+
+/// Spawn a future
+///
+/// - Before:
+///
+///     Example:
+///
+///     ```no_run
+///     let ctx = glib::MainContext::default();
+///     ctx.spawn_local(async {
+///         something.await;
+///     });
+///     ```
+///
+/// - After:
+///
+///     Example:
+///
+///     ```no_run
+///     spawn!(async {
+///         something.await;
+///     });
+///     ```
 #[macro_export]
 macro_rules! spawn {
     ($future:expr) => {
@@ -17,6 +69,23 @@ macro_rules! spawn {
     };
 }
 
+/// Send an event through a glib::Sender
+///
+/// - Before:
+///
+///     Example:
+///
+///     ```no_run
+///     sender.send(Action::DoThing).expect("Failed to send DoThing through the glib channel?");
+///     ```
+///
+/// - After:
+///
+///     Example:
+///
+///     ```no_run
+///     send!(self.sender, Action::DoThing);
+///     ```
 #[macro_export]
 macro_rules! send {
     ($sender:expr, $action:expr) => {
@@ -26,6 +95,40 @@ macro_rules! send {
     };
 }
 
+/// Create a new action
+///
+/// - Before:
+///
+///     Example:
+///
+///     ```no_run
+///     let widget = get_widget!(builder, gtk::Window, widget);
+///     let actions = gio::SimpleActionGroup::new();
+///     widget.insert_action_group("export", Some(&actions));
+///
+///     let action = gio::SimpleAction::new("do", None); 
+///     action.connect_activate(move |action, _| {
+///         // Do something
+///     });
+///     actions.add_action(&action);
+///     ```
+///
+/// - After:
+///
+///     Example:
+///
+///     ```no_run
+///     let widget = get_widget!(builder, gtk::Window, widget);
+///     let actions = gio::SimpleActionGroup::new();
+///     widget.insert_action_group("export", Some(&actions));
+///     action!(
+///         actions,
+///         "do",
+///         move |action, _| {
+///             // Do something
+///         },
+///     );
+///     ```
 #[macro_export]
 macro_rules! action {
     ($actions_group:expr, $name:expr, $callback:expr) => {
@@ -40,6 +143,41 @@ macro_rules! action {
     };
 }
 
+/// Create a new stateful action
+///
+/// - Before:
+///
+///     Example:
+///
+///     ```no_run
+///     let actions = gio::SimpleActionGroup::new();
+///     
+///     let is_dark_mode = false;
+///     let action = gio::SimpleAction::new_stateful("dark-mode", None, &is_dark_mode.to_variant()); 
+///     action.connect_activate(move |action, _| {
+///         let state = action.get_state().unwrap();
+///         let action_state: bool = state.get().unwrap();
+///         let is_dark_mode = !action_state;
+///         action.set_state(&is_dark_mode.to_variant());
+///     });
+///     actions.add_action(&action);
+///     ```
+///
+/// - After:
+///
+///     Example:
+///     ```no_run
+///     let actions = gio::SimpleActionGroup::new();
+///     let is_dark_mode = false;
+///     stateful_action!(actions, "dark-mode", is_dark_mode, move |action, _| {
+///         let state = action.get_state().unwrap();
+///         let action_state: bool = state.get().unwrap();
+///         let is_dark_mode = !action_state;
+///         action.set_state(&is_dark_mode.to_variant());
+///         
+///         // Store the state using gsettings for example
+///     });
+///     ```
 #[macro_export]
 macro_rules! stateful_action {
     ($actions_group:expr, $name:expr, $state:expr, $callback:expr) => {
@@ -54,7 +192,43 @@ macro_rules! stateful_action {
     };
 }
 
-
+/// Retrieve an action from a gio::ActionGroup
+///
+/// - Before:
+///
+///     Example:
+///
+///     ```no_run
+///     let actions = gio::SimpleActionGroup::new();
+///     action!(
+///         actions,
+///         "delete",
+///         move |action, _| {
+///             // Do something
+///         },
+///     );
+///     let action = actions.lookup_action("delete")
+///                     .unwrap()
+///                     .downcast::<gio::SimpleAction>()
+///                     .unwrap();
+///     action.set_enabled(false);
+///     ```
+///
+/// - After:
+///
+///     Example:  
+///
+///     ```no_run
+///     let actions = gio::SimpleActionGroup::new();
+///     action!(
+///         actions,
+///         "delete",
+///         move |action, _| {
+///             // Do something
+///         },
+///     );
+///     get_action!(actions, @delete).set_enabled(false);
+///     ```
 #[macro_export]
 macro_rules! get_action {
     ($actions:expr, @$name:ident) => {{