Tcl - [Tk] Docummentation for Events

Author

[Tk] Docummentation for Events

Sektor van Skijlen

2006-01-23, 7:05 pm

I tried and found nothing.

No, I don't mean the basic documentation about Tk events. It is available in
the documentation, wiki etc. However, when I want to get the information what
some % flag in the event binding means, I receive, for example:

%s
The state field from the event. For ButtonPress, ButtonRelease, Enter,
KeyPress, KeyRelease, Leave, and Motion events, a decimal string is
substituted. For Visibility, one of the strings VisibilityUnobscured,
VisibilityPartiallyObscured, and VisibilityFullyObscured is substituted.

Good, and similarly at 'event' command description, there is:

-state state
State specifies the state field for the event. For KeyPress, KeyRelease,
ButtonPress, ButtonRelease, Enter, Leave, and Motion events it must be an
integer value. For Visibility events it must be one of VisibilityUnobscured,
VisibilityPartiallyObscured, or VisibilityFullyObscured. This option overrides
any modifiers such as Meta or Control specified in the base event. Corresponds
to the %s substitution for binding scripts.

Still good, that it looks consistent, but WHAT does this flag mean for a
particular event?

Basing on the explanation above, I guess it is the value of an event modifier
(Control, Shift, Meta etc.).

The situation is similar with other flags.

I need such a description, which shall say, for example:

Event: MouseWheel
Tags:
- %D - value of wheel delta

Event: ButtonPress
Tags:
- %b - number of button that was pressed
- %s - the modifier key state
- %X - root-window relative x position of the mouse cursor
- %Y - root-window relative Y position of the mouse cursor

Describing what "could" mean particular %-tags is definitely NOT ENOUGH,
especially because the exact meaning can vary between events. This
description, of course, need not contain the description of flags that are
valid for all events, like event type. ;)

Does anybody know if anywhere on the net is it able to find the description of
Tk events in THIS style?

--
// _ ___ Michal "Sektor" Malecki <sektor(whirl)kis.p.lodz.pl>
\\ L_ |/ `| /^\ ,() <ethourhs(O)wp.pl>
// \_ |\ \/ \_/ /\ C++ bez cholesterolu: http://www.intercon.pl/~sektor/cbx
"I am allergic to Java because programming in Java reminds me casting spells"

Donal K. Fellows

2006-01-24, 7:57 am

Sektor van Skijlen wrote:
> I tried and found nothing.
>
> No, I don't mean the basic documentation about Tk events. It is available in
> the documentation, wiki etc. However, when I want to get the information what
> some % flag in the event binding means, I receive, for example:
[...]
> I need such a description, which shall say, for example:
>
> Event: MouseWheel
> Tags:
> - %D - value of wheel delta

Which version of the documentation are we talking here? Tk 8.5 is better
documented here than 8.4 (and before) was, and it is all online at
http://www.tcl.tk/man/ so you don't even need to install 8.5 to take
advantage of it. :-)

However, the meaning of some of the substitutions is a bit wooly. If you
want to know what the meaning of NotifyNonlinearVirtual is, I suggest
you google it. :-)

> Event: ButtonPress
> Tags:
> - %b - number of button that was pressed
> - %s - the modifier key state
> - %X - root-window relative x position of the mouse cursor
> - %Y - root-window relative Y position of the mouse cursor

Ah, the documentation "indexes things the other way round". Luckily, you
can search in a webpage easily enough. ;-)

Donal.

Sektor van Skijlen

2006-01-24, 7:05 pm

Dnia Tue, 24 Jan 2006 11:25:08 +0100, Donal K. Fellows skrobie:
> Sektor van Skijlen wrote:
> [...]
[color=darkred]
> Which version of the documentation are we talking here? Tk 8.5 is better
> documented here than 8.4 (and before) was, and it is all online at
> http://www.tcl.tk/man/ so you don't even need to install 8.5 to take
> advantage of it. :-)

Yes, it looks much better since it describes particular events in more
details. But it still lacks of description of particular arguments that are
passed thru %tags and may be bound to the handler.

Believe me, saying that:

%x, %y
The x and y fields from the event. For ButtonPress, ButtonRelease, Motion,
KeyPress, KeyRelease, and MouseWheel events, %x and %y indicate the position
of the mouse pointer relative to the receiving window. For Enter and Leave
events, the position where the mouse pointer crossed the window, relative to
the receiving window. For Configure and Create requests, the x and y
coordinates of the window relative to its parent window.

is spreading a lot of various information, from which the user must extract
the things they are interrested with. It is that, say.. hmm... %x means thing A
in context M, thing B in context N and thing C in context T.

And next say that context M is an event I am interrested with. But, of course,
it does not mention about the data it provides; I must go to the description
of flags, extract the context M from this description...

When a developer wants to set a handler for some event, they are interrested
with the name of event and the list of data this event can pass to the
handler. Please pay attention that the explanation of particular tags per
event is much shorter than the "global explanation" of each tag. Some events
have also same signatures, so they can be described tags in common.

When a developer wants to GENERATE the event, he needs such a description
moreover. They need to be told what options they have to use to conform to the
global signature and therefore to any potential handler for this event.

Does anyone else need the description? If not, what is the reason of indexing
things this way?

> However, the meaning of some of the substitutions is a bit wooly. If you
> want to know what the meaning of NotifyNonlinearVirtual is, I suggest
> you google it. :-)

Ok; say, saying that NotifyNonlinearVirtual is passed in %d by e.g. Enter
event is ENOUGH.

But it's better that it be described near the description of the Enter event,
not just under the %d.

[color=darkred]
> Ah, the documentation "indexes things the other way round". Luckily, you
> can search in a webpage easily enough. ;-)

Where? I wouldn't ask if I knew.

--
// _ ___ Michal "Sektor" Malecki <sektor(whirl)kis.p.lodz.pl>
\\ L_ |/ `| /^\ ,() <ethourhs(O)wp.pl>
// \_ |\ \/ \_/ /\ C++ bez cholesterolu: http://www.intercon.pl/~sektor/cbx
"I am allergic to Java because programming in Java reminds me casting spells"

Joe English

2006-01-24, 9:58 pm

Sektor van Skijlen wrote:
>Donal K. Fellows skrobie:
>
>Yes, it looks much better since it describes particular events in more
>details. But it still lacks of description of particular arguments that are
>passed thru %tags and may be bound to the handler.
>
>Believe me, saying that:
>
>%x, %y
>The x and y fields from the event. For ButtonPress, ButtonRelease, Motion,
>KeyPress, KeyRelease, and MouseWheel events, %x and %y indicate the position
>of the mouse pointer relative to the receiving window. For Enter and Leave
>events, the position where the mouse pointer crossed the window, relative to
>the receiving window. For Configure and Create requests, the x and y
>coordinates of the window relative to its parent window.
>
>is spreading a lot of various information, from which the user must extract
>the things they are interrested with. It is that, say.. hmm... %x means thing A
>in context M, thing B in context N and thing C in context T.

Agreed, the current organization of the manpage is suboptimal.
However, arranging things the other way around -- describing the
available substitutions under each event type, like you suggest --
only makes things worse.

(At least that's how it turned out when I tried reorganizing the
manpage. In the end, the end result ended up being a lot of
repeated duplicate information repeatedly repeated and duplicated,
over and over, repeatedly.)

A "Quick reference" section, listing just the event types
and the available substitutions for each event, would make a
useful annex.

--Joe English

Sektor van Skijlen

2006-01-25, 4:12 am

Dnia 25 Jan 2006 00:40:40 GMT, Joe English skrobie:
> Agreed, the current organization of the manpage is suboptimal.
> However, arranging things the other way around -- describing the
> available substitutions under each event type, like you suggest --
> only makes things worse.

> (At least that's how it turned out when I tried reorganizing the
> manpage. In the end, the end result ended up being a lot of
> repeated duplicate information repeatedly repeated and duplicated,
> over and over, repeatedly.)

Really?

Sorry, but I can't believe in this, moreover that I can see that some
descriptions are infinitely-recursive without ANY thorough explanation at all!

Not searching too far, an example of such infinitely-recursive description,
being a clear example of redirecting the problems to other people, is a %s
tag connected with [event -state] flag. Please read them both and it will be
enough for any comment.

If the description is organized in a reasonable way, there is no problem with
"repeating information". When you have a description of "one tag list per
event" (or per event group), the the list of available %tags can be completed
only of very short description, in most cases redirecting to events it is used
for. In most cases it can be even generated automatically, basing on
description of events.

If you see this problematic, I'll do it for you. And you will accept this or
rejected, as you wish. In the second case, this description will be at least
useful for me.

> A "Quick reference" section, listing just the event types
> and the available substitutions for each event, would make a
> useful annex.

Ok; I have prepared some description already. After a little rework I'll send
it here.

--
// _ ___ Michal "Sektor" Malecki <sektor(whirl)kis.p.lodz.pl>
\\ L_ |/ `| /^\ ,() <ethourhs(O)wp.pl>
// \_ |\ \/ \_/ /\ C++ bez cholesterolu: http://www.intercon.pl/~sektor/cbx
"I am allergic to Java because programming in Java reminds me casting spells"

Sponsored Links