Re: [Tk] Docummentation for Events

Dnia Tue, 24 Jan 2006 11:25:08 +0100, Donal K. Fellows skrobie:
> 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. :-)

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.

> > 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. ;-)

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"
.