xdisp.c's struct it questions.

xdisp.c's struct it questions.

[Alan Mackenzie]

Hello, Emacs.

I'm trying to get some stuff in xdisp.c working.  It's hard.

I'm currently looking at routines like `move_it_to', which is described
as "Move IT forward until it satisfies one or more of the criteria in
TO_CHARPOS, TO_X, TO_Y, and TO_VPOS."

What I can't find anywhere is a description of what it means for a
"struct it" to _be_ somewhere.  There are around 100 fields in struct
it, and several of them record locations, coordinates, etc., in one way
and another.  Which of these fields are changed when move_it_to is
called?

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: xdisp.c's struct it questions.

[Andreas Schwab]

It is wrong to error out if select-safe-coding-system-function returns
nil.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: xdisp.c's struct it questions.

[Eli Zaretskii]

> Date: Sat, 3 Oct 2015 15:48:36 +0000
> From: Alan Mackenzie <acm@muc.de>
> 
> I'm trying to get some stuff in xdisp.c working.  It's hard.

My sympathies.  Please consider recording in the comments everything
you learn that isn't already there.  Let's take something positive and
useful from your ordeal ;-)

> I'm currently looking at routines like `move_it_to', which is described
> as "Move IT forward until it satisfies one or more of the criteria in
> TO_CHARPOS, TO_X, TO_Y, and TO_VPOS."
> 
> What I can't find anywhere is a description of what it means for a
> "struct it" to _be_ somewhere.  There are around 100 fields in struct
> it, and several of them record locations, coordinates, etc., in one way
> and another.  Which of these fields are changed when move_it_to is
> called?

It depends on the criteria.  For TO_CHARPOS, the goal value is in
it->pos.charpos; for TO_X, it's in it->current_x; for TO_Y, it's in
it->current_y; and for TO_VPOS, it's in it->vpos.

Also note that the criteria is actually tested to "reach or exceed"
the goal values, i.e. do not expect to always get an exact equality,
only "greater or equal".

Re: xdisp.c's struct it questions.

[Alan Mackenzie]

Hello, Eli,

Thanks for such a rapid and useful answer.

On Sat, Oct 03, 2015 at 07:09:09PM +0300, Eli Zaretskii wrote:
> > Date: Sat, 3 Oct 2015 15:48:36 +0000
> > From: Alan Mackenzie <acm@muc.de>

> > I'm trying to get some stuff in xdisp.c working.  It's hard.

> My sympathies.  Please consider recording in the comments everything
> you learn that isn't already there.  Let's take something positive and
> useful from your ordeal ;-)

I'll see what I can manage.

> > I'm currently looking at routines like `move_it_to', which is described
> > as "Move IT forward until it satisfies one or more of the criteria in
> > TO_CHARPOS, TO_X, TO_Y, and TO_VPOS."

> > What I can't find anywhere is a description of what it means for a
> > "struct it" to _be_ somewhere.  There are around 100 fields in struct
> > it, and several of them record locations, coordinates, etc., in one way
> > and another.  Which of these fields are changed when move_it_to is
> > called?

> It depends on the criteria.  For TO_CHARPOS, the goal value is in
> it->pos.charpos; for TO_X, it's in it->current_x; for TO_Y, it's in
> it->current_y; and for TO_VPOS, it's in it->vpos.

OK.

> Also note that the criteria is actually tested to "reach or exceed"
> the goal values, i.e. do not expect to always get an exact equality,
> only "greater or equal".

Ah.  Hmm.  OK.  That's rather important!  In fact, that's exactly what
seems to be happening to me.

So these routines are only for use in contexts where it only matters
that a particular range/position is _covered_, rather than reached
exactly.

Would `reseat' (or one of its variants) be the right function to put a
struct it _exactly_ at a particular position?

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: xdisp.c's struct it questions.

[Eli Zaretskii]

> Date: Sat, 3 Oct 2015 16:38:00 +0000
> Cc: emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > Also note that the criteria is actually tested to "reach or exceed"
> > the goal values, i.e. do not expect to always get an exact equality,
> > only "greater or equal".
> 
> Ah.  Hmm.  OK.  That's rather important!  In fact, that's exactly what
> seems to be happening to me.
> 
> So these routines are only for use in contexts where it only matters
> that a particular range/position is _covered_, rather than reached
> exactly.

Not sure I agree; perhaps I don't understand what you mean by
"covered".

If you give a goal value that _can_ be reached exactly, these
functions should do exactly that.  But a value might not be reachable
exactly.  A trivial example is a value of X that is in the middle of a
character (the value is in pixels).  A less trivial example is when
the goal is the character position in the middle of invisible text,
like text covered by 'invisible' text property or by a display string.

> Would `reseat' (or one of its variants) be the right function to put a
> struct it _exactly_ at a particular position?

If you change the value of it->pos by hand, you _must_ call 'reseat'
afterwards to synchronize all the other fields, so that you could
continue using the move_it_* functions.  But note that 'reseat' cannot
compute the screen coordinates (current_x, current_y, and vpos), which
is why most uses reseat the iterator to a beginning of a physical
line, where these coordinates can be set by you.

Re: xdisp.c's struct it questions.

[Alan Mackenzie]

Hello again, Eli.

On Sat, Oct 03, 2015 at 07:09:09PM +0300, Eli Zaretskii wrote:
> > Date: Sat, 3 Oct 2015 15:48:36 +0000
> > From: Alan Mackenzie <acm@muc.de>

> > I'm trying to get some stuff in xdisp.c working.  It's hard.

> My sympathies.  Please consider recording in the comments everything
> you learn that isn't already there.  Let's take something positive and
> useful from your ordeal ;-)

The biggest time sink for me at the moment is the vagueness in xdisp.c's
use of the word "line".  Sometimes it means a screen line, sometimes it
means a text line.

An example is `forward_to_next_line_start'.  It sounds like just what I
need, but is it?  If it were called `forward_to_next_screen_line_start',
or `forward_to_next_text_line_start', I could save myself an awful lot
of poring through source code.  Even the comments preceding these
routines tend to be vague about this.

A positive example is `move_it_in_display_line_to', which is explicit
about what sort of line it means.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: xdisp.c's struct it questions.

[Eli Zaretskii]

> Date: Sun, 4 Oct 2015 13:44:31 +0000
> Cc: emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> The biggest time sink for me at the moment is the vagueness in xdisp.c's
> use of the word "line".  Sometimes it means a screen line, sometimes it
> means a text line.

Yes, that's true.  The reason is the desire to keep identifier names
shorter, I guess.

> An example is `forward_to_next_line_start'.  It sounds like just what I
> need, but is it?  If it were called `forward_to_next_screen_line_start',
> or `forward_to_next_text_line_start', I could save myself an awful lot
> of poring through source code.

All the forward_to_*_line and back_to_*_line functions mean physical
lines.

If you need to move to the next screen line, you need to call
move_it_to instead.

> Even the comments preceding these routines tend to be vague about
> this.

The comments mention a newline, which is a clear sign they mean a
physical line.