Proposed attention API

[shellreef at gmail.com]

n 8/13/07, Sean Egan <seanegan at gmail.com> wrote:
> do we need an "icon" parameter?
It is not used yet in msimprpl, but MySpaceIM has different icons for
each of the zaps.

Yahoo and MSN have icons as well, but they are only used in the button
for sending attention requests. Maybe Pidgin could have icons
representing buzz and nudge (or not).

I could imagine a poking finger icon to represent the "poke" attention
command in the hypothetical Facebook IM.

> serv_got_attention(PurpleConnection *gc, const char *who,
> PurpleAttentionType *attn, gboolean incoming)
>
> Will this ever be called if the attention *isn't* incoming?
I call it in msimprpl after the user sends an attention command and it
should be displayed in the conversation window as being sent. I was
thinking along the lines of how serv_got_im() has PURPLE_MESSAGE_RECV
and PURPLE_MESSAGE_SEND. Both events are displayed similarly (and in
some protocols, identically), so it makes sense to group them together
in the same function.

The outgoing attention command can't be displayed immediately when it
is sent, because like an outgoing instant message, it may fail for
some reason.


For comparison, before I added the incoming flag I was manually
writing "Sending zap to %s" to the conversation using serv_got_im()
after the user sent a zap (and this is what I still do if msimprpl is
compiled without the attention API). I think it is best if the client
handles displaying that an attention command was sent, rather than the
prpl.

> It seems like we shouldn't need an entire new object for this. Would
> it be enough to have:
>
> serv_got_attention(PurpleConnection *gc, const char *who, const char *text);
>
> It looks like that's the only place that object is even used.

Here's what I was thinking about how each of the fields in
PurpleAttentionType would be used:

http://msimprpl.darkthoughts.net/PurpleAttentionType-fields-20070813.png

(note that with a stable attention API, zapping will be accessible in
a more sensible place than the blist node menu - this is just a
proof-of-concept).



The problem with having a "const char *text" parameter is that the
attention text isn't really free-form, in any of the protocols. At
least in msimprpl, I'd have to search the list of attention commands
that are valid in MySpaceIM, and translate the text to a valid
protocol message. This isn't impossible, but it would be easier if an
integer code was passed, that I could use to index into into a list
with all the pertinent information on the attention command that is
needed.

Having an integer parameter instead of a text parameter also makes it
easy to send a generic attention command, if the protocol supports
only one: just send zero. Compare:

if (p->send_attention) p->send_attention(gc, username, 0);

vs

if (p->attention_types && p->send_attention)
{
    GList *types = p->attention_types(gc->account);
    p->send_attention(gc, username, (const char *)types->data);
}

and:

PurpleAttentionType *attn = g_list_nth_data(types, code);

vs

/* iterate over each of the attention commands - too long to write out
here :)  */

So basically, it would mean more coding to use a string instead.

We could pass NULL for the default attention command, but that
requires special-casing NULL, when an index of 0 wouldn't need to be
special-cased.



Also, it may be useful to have different tenses of the attention
command. In the screenshot above, I have:

1) description - an action that the user can perform, for GUI elements ("zap")
2) incoming_description - past tense ("You have been zapped")
3) outgoing_description - present tense ("Zapping msimprpl")

We could, of course, just have one term ("zap") and use it in all
instances ("You have received a zap", "You have sent a zap") but I
don't like that as much because it requires treating the action as a
inanimate noun when it really should be an active, living, verb that
actually does something. And it isn't trivial to conjugate verbs
programmatically ("You have been X'd", "X'ing msimprpl") so I don't
think we want to go there.

What is the real cost of adding a new data type? I think it is an
elegant solution, given the features that each of the protocols have
in common.

-Jeff


P.S.: Agreed about adding a new signal; it seems only logical.
Something like this:

	plugin_return = GPOINTER_TO_INT(
		purple_signal_emit_return_1(purple_conversations_get_handle(),
								  "receiving-im-attention", gc->account,
	&username, &attn, cnv, &flags));

where attn is a PurpleAttentionType *, allowing plugins access to all
of the fields described above. So they could process all attention
commands, handle certain ones differently (by inspecting the 'code'
field), or format the attention command for display to the user using
the textual fields.

And once the command is received:
purple_signal_emit(purple_conversations_get_handle(),
"received-im-attention", gc->account, name, attn)