After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 661857 - New tutorial for gtkmm - keyboard events
New tutorial for gtkmm - keyboard events
Status: RESOLVED FIXED
Product: gtkmm
Classification: Bindings
Component: documentation
unspecified
Other All
: Normal enhancement
: ---
Assigned To: gtkmm-forge
Depends on:
Blocks:
 
 
Reported: 2011-10-15 17:16 UTC by Pedro Ferreira
Modified: 2012-01-30 17:55 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
Contains the examples and description (5.97 KB, application/zip)
2011-10-15 17:16 UTC, Pedro Ferreira
  Details
Incomplete patch: New chapter of the gtkmm tutorial (5.54 KB, patch)
2011-10-19 07:56 UTC, Kjell Ahlstedt
none Details | Review
examples v2 (3.71 KB, application/x-compressed-tar)
2011-10-20 01:59 UTC, Pedro Ferreira
  Details
v3 (5.40 KB, application/octet-stream)
2011-10-21 01:56 UTC, Pedro Ferreira
  Details
Html files with the new chapter (8.58 KB, application/x-compressed-tar)
2011-10-21 14:18 UTC, Kjell Ahlstedt
  Details
Incomplete patch: New chapter of the gtkmm tutorial, v2 (7.40 KB, patch)
2011-10-25 09:05 UTC, Kjell Ahlstedt
none Details | Review
code examples v4 + chapter (5.68 KB, application/x-compressed-tar)
2011-10-29 18:51 UTC, Pedro Ferreira
  Details
Patch: New chapter: Keyboard Events (gtkmm-documentation) (39.35 KB, patch)
2011-11-01 15:20 UTC, Kjell Ahlstedt
none Details | Review
Complete the event propagation explanation (2.94 KB, application/x-compressed-tar)
2012-01-18 03:21 UTC, Pedro Ferreira
  Details
patch: Keyboard Events chapter: Clarify keyboard event propagation. (10.80 KB, patch)
2012-01-22 19:05 UTC, Kjell Ahlstedt
none Details | Review

Description Pedro Ferreira 2011-10-15 17:16:31 UTC
Created attachment 199071 [details]
Contains the examples and description

Currently in the gtkmm documentation, there's no mention of how to deal with keyboard events, so I've written a couple of examples and some introduction to explain this.

I think this would fit in a new chapter in the gtkmm book, since there isn't a related chapter where this could be added.

The introduction isn't well written and structured, so if someone with better writing skills could re-write it, I would be ok with that.
Comment 1 Kjell Ahlstedt 2011-10-19 07:56:26 UTC
Created attachment 199402 [details] [review]
Incomplete patch: New chapter of the gtkmm tutorial

Here's a patch with the new chapter "X Event Signals". It's a draft, it needs
modification. The patch contains only modifications of gtkmm-tutorial-in.xml.

This contribution to the gtkmm tutorial started on the gtkmm-list:
https://mail.gnome.org/archives/gtkmm-list/2011-September/msg00087.html
https://mail.gnome.org/archives/gtkmm-list/2011-October/msg00080.html

Pedro, have you installed the development system for gtkmm? I.e., can you use
the patch to easily modify a copy of gtkmm-tutorial-in.xml and make html files
from it?

Comments on the new chapter and the example programs:

The explanation of event propagation in the pygtk FAQ
http://faq.pygtk.org/index.py?file=faq03.011.htp&req=show
is quite good. Shall we copy part of it to the "X Event signals" section in
the "Signals" appendix?

Shall the new chapter be called "X Event Signals" or "Keyboard Events" or what?

The keyboardEvents program did not work quite as expected. I had to make two
modifications to it:

1. Call hide() instead of on_hide() to close the program. on_hide() hides the
window, but the program does not end.

2. The condition in the test
  if ( (event->keyval == GDK_KEY_1) && (event->state == GDK_MOD1_MASK) )
is never true if NumLock is active. It counts as a modification key, and then
event->state is not == GDK_MOD1_MASK. I changed to
  if ( (event->keyval == GDK_KEY_1) && (event->state & GDK_MOD1_MASK) )
but that's perhaps not perfect.

In the eventPropagation program, wouldn't it be nice to handle key press events
in the Gtk::Grid instead of in the Gtk::Window? It will show that events can
be propagated to a widget without an X window.

Change
  bool EventPropagation::onKeyPress( GdkEventKey *event )
  bool EventPropagation::entryKeyPress( GdkEventKey *event )
to
  bool EventPropagation::onKeyPress( GdkEventKey* /* event */ )
  bool EventPropagation::entryKeyPress( GdkEventKey* /* event */ )
or
  bool EventPropagation::onKeyPress( GdkEventKey* )
  bool EventPropagation::entryKeyPress( GdkEventKey* )

Some compilers will complain that 'event' is not used.
Comment 2 Pedro Ferreira 2011-10-20 01:57:42 UTC
(In reply to comment #1)
> Created an attachment (id=199402) [details] [review]
> Incomplete patch: New chapter of the gtkmm tutorial
> 
> Here's a patch with the new chapter "X Event Signals". It's a draft, it needs
> modification. The patch contains only modifications of gtkmm-tutorial-in.xml.
> 
> This contribution to the gtkmm tutorial started on the gtkmm-list:
> https://mail.gnome.org/archives/gtkmm-list/2011-September/msg00087.html
> https://mail.gnome.org/archives/gtkmm-list/2011-October/msg00080.html
> 
> Pedro, have you installed the development system for gtkmm? I.e., can you use
> the patch to easily modify a copy of gtkmm-tutorial-in.xml and make html files
> from it?
> 

Yes, I can apply the patch with git, but don't know how to make html files from it. I can open the gtkmm-tutorial-in.xml file and see the changes.

> Comments on the new chapter and the example programs:
> 
> The explanation of event propagation in the pygtk FAQ
> http://faq.pygtk.org/index.py?file=faq03.011.htp&req=show
> is quite good. Shall we copy part of it to the "X Event signals" section in
> the "Signals" appendix?
> 

I think we could re-use from the python faq. I'm just not sure about the last part there, that says that keyboard events are first sent to the toplevel window. 

In my example (the one with cout), the Window isn't called first. We have first the entry. 
That text was last modified on 2002, so maybe thats how it was done back then, I guess.

> Shall the new chapter be called "X Event Signals" or "Keyboard Events" or what?
> 
I think keyboard events is more obvious.

> The keyboardEvents program did not work quite as expected. I had to make two
> modifications to it:
> 
> 1. Call hide() instead of on_hide() to close the program. on_hide() hides the
> window, but the program does not end.
> 
> 2. The condition in the test
>   if ( (event->keyval == GDK_KEY_1) && (event->state == GDK_MOD1_MASK) )
> is never true if NumLock is active. It counts as a modification key, and then
> event->state is not == GDK_MOD1_MASK. I changed to
>   if ( (event->keyval == GDK_KEY_1) && (event->state & GDK_MOD1_MASK) )
> but that's perhaps not perfect.
> 

Ok, fixed.

> In the eventPropagation program, wouldn't it be nice to handle key press events
> in the Gtk::Grid instead of in the Gtk::Window? It will show that events can
> be propagated to a widget without an X window.
> 

See the last version, I have all three receiving the event, and printing to the terminal. It shows the propagation.

> Change
>   bool EventPropagation::onKeyPress( GdkEventKey *event )
>   bool EventPropagation::entryKeyPress( GdkEventKey *event )
> to
>   bool EventPropagation::onKeyPress( GdkEventKey* /* event */ )
>   bool EventPropagation::entryKeyPress( GdkEventKey* /* event */ )
> or
>   bool EventPropagation::onKeyPress( GdkEventKey* )
>   bool EventPropagation::entryKeyPress( GdkEventKey* )
> 
> Some compilers will complain that 'event' is not used.

That probably will add confusion to the people reading the code... unless we add some comment explaining it.
Comment 3 Pedro Ferreira 2011-10-20 01:59:23 UTC
Created attachment 199495 [details]
examples v2
Comment 4 Kjell Ahlstedt 2011-10-20 14:45:44 UTC
(In reply to comment #2)
> Yes, I can apply the patch with git, but don't know how to make html files
> from it. I can open the gtkmm-tutorial-in.xml file and see the changes.

If you have got a git clone of gtkmm-documentation (fetched with jhbuild?),
you should be able to build it.
  ./autogen.sh --prefix=/where/you/want/to/install # done once
  make  # every time you want to remake
  make install # not necessary

'make' stores html files in gtkmm-documentation/docs/tutorial/html/.
'make install' copies them to $prefix/share/doc/gtkmm-3.0/tutorial/html/.

> I think we could re-use from the python faq. I'm just not sure about the last
> part there, that says that keyboard events are first sent to the toplevel
> window.

I think the last paragraph says that keyboard shortcuts defined for menu items
are handled by gtk+ before any of your event handlers are called. (In the gtk+
and gtkmm docs they are called accelerators, but I suspect it's the same
thing.)

This point would need further investigation. We can just skip that last
paragraph, if we're not certain that it still holds, or what it means. The
gtkmm tutorial can't contain the whole truth, although of course it shall
contain only truths.

> I think keyboard events is more obvious.

Ok, I'll change the title. Anything else you think I shall change?

> See the last version, I have all three receiving the event, and printing to
> the terminal. It shows the propagation.

That's better.

> That probably will add confusion to the people reading the code... unless we
> add some comment explaining it.

No, it won't add confusion to readers who know C++ well enough. It's normal
C++ practice. See e.g. Bjarne Stroustrup's "The C++ Programming Lnaguage",
section 7.1.1 "Function Definitions". This technique is used in other example
programs in the gtkmm tutorial. Search for '*)' and you will find some of them.

This change is not optional. If the program is compiled with gcc with arguments
-pedantic -Wall -Werror (--enable-warnings=fatal in autogen.sh or configure)
it's considered an error to name an unused argument in a function definition.
But it can, and ought to, be named in the function declaration.


Do you plan to change your example programs more? They still don't comply with
gtkmm's design rules. Look at some of the other example programs.
Comment 5 Pedro Ferreira 2011-10-21 01:56:49 UTC
Created attachment 199603 [details]
v3
Comment 6 Pedro Ferreira 2011-10-21 01:59:02 UTC
(In reply to comment #4)
> (In reply to comment #2)
> > Yes, I can apply the patch with git, but don't know how to make html files
> > from it. I can open the gtkmm-tutorial-in.xml file and see the changes.
> 
> If you have got a git clone of gtkmm-documentation (fetched with jhbuild?),
> you should be able to build it.
>   ./autogen.sh --prefix=/where/you/want/to/install # done once
>   make  # every time you want to remake
>   make install # not necessary
> 

I just used git, no jhbuild.

I get: 
    ./autogen.sh: line 5: mm-common-prepare: command not found


> 'make' stores html files in gtkmm-documentation/docs/tutorial/html/.
> 'make install' copies them to $prefix/share/doc/gtkmm-3.0/tutorial/html/.
> 
> > I think we could re-use from the python faq. I'm just not sure about the last
> > part there, that says that keyboard events are first sent to the toplevel
> > window.
> 
> I think the last paragraph says that keyboard shortcuts defined for menu items
> are handled by gtk+ before any of your event handlers are called. (In the gtk+
> and gtkmm docs they are called accelerators, but I suspect it's the same
> thing.)
> 
> This point would need further investigation. We can just skip that last
> paragraph, if we're not certain that it still holds, or what it means. The
> gtkmm tutorial can't contain the whole truth, although of course it shall
> contain only truths.
> 

hmm, unless someone comes and explains it, I think its better to leave it out.


> > I think keyboard events is more obvious.
> 
> Ok, I'll change the title. Anything else you think I shall change?
> 
> > See the last version, I have all three receiving the event, and printing to
> > the terminal. It shows the propagation.
> 
> That's better.
> 
> > That probably will add confusion to the people reading the code... unless we
> > add some comment explaining it.
> 
> No, it won't add confusion to readers who know C++ well enough. It's normal
> C++ practice. See e.g. Bjarne Stroustrup's "The C++ Programming Lnaguage",
> section 7.1.1 "Function Definitions". This technique is used in other example
> programs in the gtkmm tutorial. Search for '*)' and you will find some of them.
> 
> This change is not optional. If the program is compiled with gcc with arguments
> -pedantic -Wall -Werror (--enable-warnings=fatal in autogen.sh or configure)
> it's considered an error to name an unused argument in a function definition.
> But it can, and ought to, be named in the function declaration.
> 
> 
> Do you plan to change your example programs more? They still don't comply with
> gtkmm's design rules. Look at some of the other example programs.

Ok, its changed now.
Comment 7 Kjell Ahlstedt 2011-10-21 14:18:00 UTC
Created attachment 199645 [details]
Html files with the new chapter

(In reply to comment #6)
> I just used git, no jhbuild.
> I get: 
>    ./autogen.sh: line 5: mm-common-prepare: command not found

This is what you can expect, when you clone a module from the git repository.
The cloned module depends on modules that you have not installed. In this case
mm-common. You could have guessed, if you had read the comment in autogen.sh.
Less obvious is that gnome-doc-prepare on line 9 is part of the gnome-doc-utils
module. You also need the autotools (autoreconf, autoconf, automake).


I've attached the new html files. Then you can study the new chapter in a more
readable form than gtkmm-tutorial-in.xml before you manage to build the html
files from the patched gtkmm-tutorial-in.xml.

I have not made any changes yet. The attached html files are built from my
patch in comment 1, but with v3 of your source code. I'll make changes when you
have had a chance to comment on the whole chapter.
Comment 8 Pedro Ferreira 2011-10-23 18:37:48 UTC
(In reply to comment #7)
> Created an attachment (id=199645) [details]
> Html files with the new chapter
> 
> (In reply to comment #6)
> > I just used git, no jhbuild.
> > I get: 
> >    ./autogen.sh: line 5: mm-common-prepare: command not found
> 
> This is what you can expect, when you clone a module from the git repository.
> The cloned module depends on modules that you have not installed. In this case
> mm-common. You could have guessed, if you had read the comment in autogen.sh.
> Less obvious is that gnome-doc-prepare on line 9 is part of the gnome-doc-utils
> module. You also need the autotools (autoreconf, autoconf, automake).
> 

I tried installing jhbuild but I'm getting an error.. I'll try it again later.

Either-way, why is this so overly complicated?

I mean, why not use simple html pages for the book, its easier to work with, to set it up, to edit... having to install so many stuff, then editing a big file.. what's the advantage of the current implementation?

> 
> I've attached the new html files. Then you can study the new chapter in a more
> readable form than gtkmm-tutorial-in.xml before you manage to build the html
> files from the patched gtkmm-tutorial-in.xml.
> 
> I have not made any changes yet. The attached html files are built from my
> patch in comment 1, but with v3 of your source code. I'll make changes when you
> have had a chance to comment on the whole chapter.

Ok, some stuff seems to be missing, for example the links to the gtk documentation ( http://developer.gnome.org/gdk3/stable/gdk3-Events.html#GdkEventMask for the add_events(), for example).
We should point out where the full list of options are.

The example you written, I'm not understanding what its doing, you seem to be looking for shift + 1, but that results in another key (the ! key).

Also, the code where you setup the key release/press, could have a comment saying that it should be in a constructor/init function.


What about that part explaining the bitwise operations?

I know, I know, any competent c++ programmer knows about that, but I think we should consider that there may be novice programmers (like me.. :p) reading the documentation.



I've been thinking about the numlock changing the modifier... how would one define a condition to test for a very specific keyboard shortcut (alt + 1 in the example), without having to check if numlock (and the other locks?..) are set?

As we have now, pressing ctrl + alt + 1 works too.

It seems to me that having numlock in the modifier doesn't make much sense. Ok, they're both modifiers keys, but numlock clearly isn't in the same category as the Alt key for example, those things should be separated.
Comment 9 Kjell Ahlstedt 2011-10-25 09:05:24 UTC
Created attachment 199907 [details] [review]
Incomplete patch: New chapter of the gtkmm tutorial, v2

(In reply to comment #8)
> Either-way, why is this so overly complicated?
> I mean, why not use simple html pages for the book, its easier to work with,
> to set it up, to edit... having to install so many stuff, then editing a big
> file.. what's the advantage of the current implementation?

This is a DocBook file (http://en.wikipedia.org/wiki/DocBook,
http://www.docbook.org/). It can be used for creating files in different
formats (html, pdf and others). I don't know very much about the advantages of
DocBook. If you really want to know why it was selected for the gtkmm tutorial,
send your question to the gtkmm-list, and hope for a reply.

It takes some time to get used to jhbuild. Most people who make changes to
the gtkmm tutorial also make changes to the gtkmm source code. Jhbuild is great
for that job. Once you've installed everything you need for modifying the gtkmm
source code, the extra job for installing the gtkmm-documentation module is
insignificant.

> Ok, some stuff seems to be missing, for example the links to the gtk
> documentation

Yes, I deliberately left that out. There are no links to gtk+ docs in the gtkmm
tutorial. I don't know if there is a good reason for that.
It would be better to link to Gdk::EventMask. Unfortunately enums are poorly
documented in gtkmm (bug 544694), and the URL of Gdk::EventMask is
http://developer.gnome.org/gtkmm/unstable/group__gdkmmEnums.html#ga0288c23e93ded8c0326235f1f1120c61
Obviously not suitable for a link from outside
developer.gnome.org/gtkmm/unstable/. I think the terrible last part of the URL
is automatically generated by Doxygen.

See also the last part of this comment.

> The example you written, I'm not understanding what its doing, you seem to be
> looking for shift + 1, but that results in another key (the ! key).
> Also, the code where you setup the key release/press, could have a comment
> saying that it should be in a constructor/init function.

I've changed it.

> What about that part explaining the bitwise operations?

The very first section of the gtkmm tutorial says "This book assumes a good
understanding of C++, and how to create C++ programs."

Once again, see also the last part of this comment.

> I've been thinking about the numlock changing the modifier... how would one
> define a condition to test for a very specific keyboard shortcut (alt + 1 in
> the example), without having to check if numlock (and the other locks?..) are
> set?
> As we have now, pressing ctrl + alt + 1 works too.

It's not very good as it is. This is not perfect, but good enough here:
  if ((event->keyval == GDK_KEY_1) &&

    (event->state & (GDK_SHIFT_MASK | GDK_CONTROL_MASK | GDK_MOD1_MASK)) ==
    GDK_MOD1_MASK)

Other things to change in the example programs:
In EventPropagation there are functions called xxxKeyPress. They should be
called xxxKeyRelease, since they are connected to key release events.
File extension shall be .cc instead of .cpp.
File names shall not contain uppercase letters. (I think this is a requirement.
Probably it makes life somewhat easier on operating systems where file names
are case-insensitive (MS Windows).)

> It seems to me that having numlock in the modifier doesn't make much sense.
> Ok, they're both modifiers keys, but numlock clearly isn't in the same
> category as the Alt key for example, those things should be separated.

Ask the gtk+ developers. Here we just have to accept it the way it is.


I suggest that we proceed like this:
1. You get your development system up and running.
2. You continue the modification of gtkmm-tutorial-in.xml until you're
   satisfied with it. It shouldn't be overly difficult, even if you don't
   understand all the details of that file.
3. We need a complete patch with all modified and new files. I can help with
   that, if you want.
4. One of the gtkmm developers can look at the patch, and decide if it's good
   enough for inclusion in the gtkmm tutorial.
Comment 10 Pedro Ferreira 2011-10-29 18:51:23 UTC
Created attachment 200258 [details]
code examples v4 + chapter

[jhbuild]
I've tried to setup jhbuild, but failed... and ain't got more pacience for it, sorry. 
Can't I just send the xml file, and then when its done you can create a patch? Is that ok with you?

[links]
Its better some ugly links than none, so that you can find more information about this, in case you need it.

[explaining bitwise operations]
I disagree, but I'm not going to fight with you... :)


[key modifiers]
I tried to do something like:

int state = event->state;

    //clear the possible locks that may be set
//state &= ~GDK_LOCK_MASK; <-- thought it was this one
state &= ~GDK_MOD2_MASK;    //but this is the numlock key, on my pc at least

and then compare state == GDK_MOD1_MASK

and it works, but the documentation doesn't guarantee that MOD2 is always numlock, so... I guess we can go with your approach?


[the xml file]
I think its ok, I just have a doubt in the part where you say:

"Events differ in some ways from other signals."

but aren't signals and events the same thing? isn't it just a question of nomenclature?


I think we could ask for other developers opinion.
Comment 11 Kjell Ahlstedt 2011-10-30 18:46:24 UTC
(In reply to comment #10)
> Can't I just send the xml file, and then when its done you can create a
> patch? Is that ok with you?

Sure it's ok. I thought it would be easier for both of us, if you could check
your changes in a web browser, but you seem to have had much more trouble with
jhbuild than I have had.

> I think its ok, I just have a doubt in the part where you say:
> "Events differ in some ways from other signals."
> but aren't signals and events the same thing?

I'm not sure. Perhaps they are. I noticed the events we're interested in are
called "X events", not just "events" in the rest of the tutorial.
I've added an X.

> I think we could ask for other developers opinion.

Right now I have problems compiling programs after having upgraded to Ubuntu
11.10. When I've solved those problems, I'll create a complete patch and attach
it to this bug. I want to make sure everything is ok before I attach the patch.
Comment 12 Pedro Ferreira 2011-10-30 20:55:55 UTC
(In reply to comment #11)
> (In reply to comment #10)
> > Can't I just send the xml file, and then when its done you can create a
> > patch? Is that ok with you?
> 
> Sure it's ok. I thought it would be easier for both of us, if you could check
> your changes in a web browser, but you seem to have had much more trouble with
> jhbuild than I have had.
> 

Its just newbie problems.. :(

I still can open it in the browser, it just doesn't have any styling. 
When docbook generates the html, is it like in the website, all colourful?

Also, I thought about why docbook is used, and maybe its because there's a kindle ebook version, so docbook probably facilitates the difference in formats?

Still, there's probably a way to separate into several files, I'll ask in the mailing list about that.

> > I think its ok, I just have a doubt in the part where you say:
> > "Events differ in some ways from other signals."
> > but aren't signals and events the same thing?
> 
> I'm not sure. Perhaps they are. I noticed the events we're interested in are
> called "X events", not just "events" in the rest of the tutorial.
> I've added an X.
> 

Found this site -> http://zetcode.com/tutorials/pygtktutorial/signals/
(once again, pygtk for the rescue :p)

I guess we can call them X events, or just events, but probably just events is better, since gtkmm isn't just used in linux (the X is probably from the X-window).

> > I think we could ask for other developers opinion.
> 
> Right now I have problems compiling programs after having upgraded to Ubuntu
> 11.10. When I've solved those problems, I'll create a complete patch and attach
> it to this bug. I want to make sure everything is ok before I attach the patch.

Early updates are always like that :( that's why I only update much later.
Ok, thanks!
Comment 13 Kjell Ahlstedt 2011-11-01 15:16:53 UTC
(In reply to comment #12)
> I still can open it in the browser, it just doesn't have any styling. 
> When docbook generates the html, is it like in the website, all colourful?

If you have succeeded in generating the html files in gtkmm-documentation/docs/
tutorial/html/, and open index.html or any other file there, it won't look
good. The browser won't find the stylesheet, the screenshot images, or the
icons.

If you run 'make install' and open $prefix/share/doc/gtkmm-3.0/tutorial/html/
index.html, it looks much better, but it still doesn't look the same as
http://developer.gnome.org/gtkmm-tutorial/stable/.

> I guess we can call them X events, or just events, but probably just events
> is better, since gtkmm isn't just used in linux (the X is probably from the
> X-window).

Yes, the X comes from the X Window system. I've kept it, since it's used
elsewhere in the tutorial. I don't think it's important.
Comment 14 Kjell Ahlstedt 2011-11-01 15:20:44 UTC
Created attachment 200410 [details] [review]
Patch: New chapter: Keyboard Events (gtkmm-documentation)

This is a new chapter in the tutorial "Programming with gtkmm 3".
A few lines are also added to Appendix B "Signals", section "X Event signals".

Is it ok to add it to the tutorial? As is, or after modification?
Comment 15 Pedro Ferreira 2011-11-01 16:38:28 UTC
I think its ok as it is.
I just have doubts about the X events thing, since for example on windows, gtk doesn't use the x-window, but since that's how its done throughout the rest of the  book, I guess we can leave it like that.
Comment 16 Murray Cumming 2011-11-18 09:10:50 UTC
Thanks. I have pushed it to git master, and made some small code style changes:
http://git.gnome.org/browse/gtkmm-documentation/commit/?id=a7af3315d2e10b870624e955ada53c62e184e150

I also added Pedro to the list of authors:
http://git.gnome.org/browse/gtkmm-documentation/commit/?id=b5b9b4a5867a087a83dd912c0a44be618df3f215

Kjell, you might like to add yourself generally there too.
Comment 17 Pedro Ferreira 2011-11-18 20:49:33 UTC
nice! thanks
Comment 18 Kjell Ahlstedt 2011-11-20 16:11:45 UTC
(In reply to comment #16)
> Kjell, you might like to add yourself generally there too.

Done.
http://git.gnome.org/browse/gtkmm-documentation/commit/?id=bf55b1a8a2250f2832f4c502ce9f44b3a68d273b

Murray, if you prefer a different description of my contribution, feel free to
change it.
Comment 19 Pedro Ferreira 2012-01-18 03:21:00 UTC
Created attachment 205499 [details]
Complete the event propagation explanation

In the attachment there's a new version of the event propagation example (showing that the Gtk::Window's event handler is called first, before the actual propagation).

One thing I'm not sure, in the Gtk::Window's event function, it checks for the accelerator keys, mnemonics?.. anything else?


Also, in the simple example, we're overriding the on_key_press_event() function, we should rename that.
Comment 20 Kjell Ahlstedt 2012-01-18 12:57:38 UTC
Reopening this bug. (Status set to Unconfirmed, because I'm not allowed to set
it to Reopened.)

A discussion on the gtkmm-list, starting at
http://mail.gnome.org/archives/gtkmm-list/2012-January/msg00038.html,
made us aware that a possibly important piece of information is missing in the
Event Propagation section.

I can make a patch from the attachment in comment 19, but probably I will not
do it immediately.

> One thing I'm not sure, in the Gtk::Window's event function, it checks for
> the accelerator keys, mnemonics?.. anything else?

See functions gtk_window_key_press_event() and gtk_window_key_release_event()
in gtkwindow.c. http://git.gnome.org/browse/gtk+/tree/gtk/gtkwindow.c
Comment 21 Pedro Ferreira 2012-01-18 18:28:36 UTC
So, it checks for mnemonics and accelerators in the on_key_press_event(), but not on the on_key_release_event() (but to get the key release event, you probably get the key press first, so...).

After that it handles the events of the widget that is on focus, and then I'm not really sure (the chain up part), but I'm guessing is related to the propagation.

I could mention that the mnemonics/accelerators are dealt in the on_key_press_event().. what about the rest, is it ok?
Comment 22 Kjell Ahlstedt 2012-01-22 19:05:24 UTC
Created attachment 205827 [details] [review]
patch: Keyboard Events chapter: Clarify keyboard event propagation.

I think this will do for the tutorial. We can't describe every single detail
of the event handling. I have found no detailed documentation in gtk+.
Comment 23 Pedro Ferreira 2012-01-22 22:43:05 UTC
Ok, I think its good too.
Comment 24 Murray Cumming 2012-01-30 11:29:23 UTC
It looks good to me. Please push.