* tp_account_channel_request_new() would benefit from an example; and the @user_action_time should give hints for what value to get from GTK+, or what value to use otherwise. * An explanation of how {create,ensure}_and_handle work could be useful for some people. * ::re-handled should be better explained, also potentially with an example.
Empathy defines these constants: #define EMPATHY_DISPATCHER_NON_USER_ACTION (G_GINT64_CONSTANT (0)) #define EMPATHY_DISPATCHER_CURRENT_TIME G_MAXINT64 cf http://telepathy.freedesktop.org/spec/generic-types.html#User_Action_Timestamp What about introducing those in tp-glib so we can refer them directly in the doc?
That makes sense to me!
For the user action time constants, how's this? tp_channel_dispatch_operation_handle_with_time_async() does document how to get a user action time from Gdk; we should put this in one place (perhaps move it to ACR) and have everywhere else reference it. Similarly, #TpHandleChannelsContext:user-action-time does (mostly) document what handlers should do with the UAT when they get it. We should put this in one place (or leaving it where it is might be appropriate), mention gtk_window_present_with_time(), and have everywhere else reference it. In principle we ought to have a telepathy-gdk with this stuff in, but that's rather annoying, particularly with the Gtk2/Gtk3 switch, Clutter, and other GUI uncertainties...
looks good to me.
I've updated the branch with more docs and more user action time stuff. It turns out that CurrentTime = 0 is part of the X11 protocol, and there are matching constants in both Gdk and Clutter, so I think tp_user_action_time_from_x11() is useful. (In reply to comment #0) > * tp_account_channel_request_new() would benefit from an example Not done here; I think the best example would probably be to add higher-level API (I'm not quite sure what shape that should be yet), include "this is equivalent to tp_account_channel_request_new() with this @request" in its docs, and add those to tp_account_channel_request_new() as a "see also". > * An explanation of how {create,ensure}_and_handle work could be useful for > some people. I've added brief explanations of how they work behind the scenes. > * ::re-handled should be better explained, also potentially with an example. I explained why it's like it is, but didn't add an example. Example handlers would be a great place to show off g-i, actually - we can add pygtk examples without actually having to (build-)depend on Gtk :-)
If someone want to add a proper example of TpAccountChannelRequest I started writing one (for testing purpose): http://git.collabora.co.uk/?p=user/cassidy/telepathy-glib;a=shortlog;h=refs/heads/request-example (Note all the code needed just to get accounts and connection ready if you are wondering why I'd like to have bug #29529 ;) )
++
Fixed in git for 0.11.13
The documentation doesn't currently discuss the purpose of @context. i.e. if you pass a pointer to store the context in, are you then responsible for calling accept/fail/delay? (It seems you are not, which makes me wonder the purpose of providing the context). Similarly in the re-handled signal.
(In reply to comment #9) > The documentation doesn't currently discuss the purpose of @context. i.e. if > you pass a pointer to store the context in, are you then responsible for > calling accept/fail/delay? (It seems you are not, which makes me wonder the > purpose of providing the context). The purpose is so you can call methods on @context to retrieve information from Handler_Info, but it's impossible to give a concrete example because we don't define any keys yet. For instance, if we were to define a Handler_Info key "approver" that's the unique name of the process that called HandleWith(), I'd add: const gchar *tp_handle_channels_context_get_approver (TpHCC *); and that'd be the first example of a use for @context.
Then we should add this, because at the moment you might naïvely believe that you need to use it if you want to delay or fail the handler.
Like I said, I can't give a concrete example of a key in Handler_Info because we don't have any yet, but I've added an accessor for Handler_Info itself and some more explanation in the docs: http://git.collabora.co.uk/?p=user/smcv/telepathy-glib-smcv.git;a=shortlog;h=refs/heads/trivia What do you think? Also, closing Bug #25073 would make this less hypothetical by defining the first key in Handler_Info.
Looks good :)
Fixed (again) in git for 0.11.14
Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.