Created attachment 249400 [details] [review]
improve GtkAction deprecation notices

First try at improving the deprecation notices for GtkAction. There is plenty to disagree over, so comments welcome.

I think we probably want to add a section to the migration guide about this, actually.

But sure, this looks like an improvement

Looks fine to me.

This is a big improvement. Thanks, David.

Can we add anything to GtkToggleAction to suggest how to achieve the same thing with GAction? It seems to involve GAction::state and the state-changed signal. It seems to need rather lengthy code for a simple boolean check item, such as:

GSimpleAction *action =
  g_simple_action_new_stateful("somename", G_VARIANT_TYPE_BOOLEAN, g_variant_new_boolean (TRUE));

and later:

g_action_change_state (action, g_variant_new_boolean (FALSE));

and

GVariant *state = g_action_get_state (action);
gboolean active = g_variant_get_boolean (state);
g_variant_unref (state);


It would be nice to have convenience API for that if none exists already.

It might also be nice to state, as I think is true, that the activate signal will be emitted whenever the state changes, so for a simple toggle menu item it would be enough to just handle the "activate" signal and ignore the "change-state" signal, assuming that you don't want to prevent toggling in some cases.

And I have no clue how to implement radio menu items. This suggests that it should be implemented by one action having n possible states:
https://wiki.gnome.org/HowDoI/GAction
But I don't see how to specify the human-readable text to be used for those states.

(In reply to comment #6)
> And I have no clue how to implement radio menu items. This suggests that it
> should be implemented by one action having n possible states:
> https://wiki.gnome.org/HowDoI/GAction
> But I don't see how to specify the human-readable text to be used for those
> states.

You use one action with multiple states, indeed. And you specify the human-readable text on the n menuitems, one for each state:

static GActionEntry win_entries[] = {
  { "justify", activate_radio, "s", "'left'", change_justify_state }
}

<menu>
  <section>
    <item>
      <attribute name='label'>Justify left</attribute>
      <attribute name='action'>win.justify</attribute>
      <attribute name='target'>left</attribute>
    </item>
    <item>
      <attribute name='label'>Justify right</attribute>
      <attribute name='action'>win.justify</attribute>
      <attribute name='target'>right</attribute>
    </item>
...

Thanks. Can I use anything other than a string for the target/state? For instance, it would be nice to use an enum value directly rather than creating a string representation of it just for this.

it is a serialized variant, the type of which is specified by the state-type property of the action.

Yes, thanks, but, the target in the GtkBuilder XML seems to only be able to represent a string. If we are meant to enter a GVariant serialization string there, we'll need more hints about what that might look like. 

By the way, the documentation uses the British/Canadian serialisation spelling of serialization.

(In reply to comment #10)
> Yes, thanks, but, the target in the GtkBuilder XML seems to only be able to
> represent a string.
> If we are meant to enter a GVariant serialization string
> there, we'll need more hints about what that might look like. 

OK, now I see that the format is quite simple, so a simple decimal number will be interpreted as that:
https://developer.gnome.org/glib/unstable/gvariant-text.html

This link is also useful:
https://developer.gnome.org/glib/unstable/gvariant-format-strings.html


I've also learned that radio items have a parameter and state that are equal "by convention", though I don't really know if that's a convention that the app must maintain, or one that glib or gtk+ will maintain for me.
https://wiki.gnome.org/HowDoI/GAction#Action_state_and_parameters


In general, this use of both the parameter and the state confuses the API for radio items, with the "target value" concept introducing yet a third thing:
- My GtkBuilder <menu> XML specifies a _target_ value that is the _parameter_ value that my callback will receive
- I g_action_activate() the action with the _parameter_ value (though maybe g_action_change_state() with the state would work too.)
- and I (think I) have to get the action's _state_ to discover which value is currently selected.


I know this isn't the best place to gripe about this, sorry, but I feel like I'm making progress at least.

Created attachment 250505 [details]
test_gmenu_radio_strings.c

This works.

Created attachment 250506 [details]
test_gmenu_radio_int32.c

This doesn't work.

If you want to use non-string target values you need to use the type= attribute with a GVariant type string, like so:


<attribute name='target' type='i'>100</attribute>


Admittedly, this is utterly undocumented.... anywhere, as far as I know.  We should really fix that.

(In reply to comment #4)
> It would be nice to have convenience API for that if none exists already.

I've filed that suggestion as bug #705655 .

GtkRecentAction also need improved deprecation documentation comments, though the main problem is that there is no replacement yet. I've filed that as bug #705656.

(In reply to comment #16)
> GtkRecentAction also need improved deprecation documentation comments, though
> the main problem is that there is no replacement yet. I've filed that as bug
> #705656.

Sorry, I mean bug #707422 .

We're moving to gitlab! As part of this move, we are moving bugs to NEEDINFO if they haven't seen activity in more than a year. If this issue is still important to you and still relevant with GTK+ 3.22 or master, please reopen it and we will migrate it to gitlab.

As announced a while ago, we are migrating to gitlab, and bugs that haven't seen activity in the last year or so will be not be migrated, but closed out in bugzilla.

If this bug is still relevant to you, you can open a new issue describing the symptoms and how to reproduce it with gtk 3.22.x or master in gitlab:

https://gitlab.gnome.org/GNOME/gtk/issues/new