Comments on display.texi

[storm@cua.dk (Kim F. Storm)]

Thanks for correcting my additions to display.texi.

You left some questions open in display.texi:


>   The way to display a bitmap in the left or right fringes for a given
> line in a window is by specifying the @code{display} property for one
> of the characters that appears in it.  Use a display specification of
> the form @code{(left-fringe @var{bitmap} [@var{face}])} or
> @code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display
> Property}).  Here, @var{bitmap} is an integer identifying the bitmap
> you want, and @var{face} (which is optional) is the name of the face
> whose colors should be used for displaying the bitmap.
> @c ??? Shouldn't the symbol name be used?

The code uses the integer value (the bitmap number), so I didn't see
any reason to use a symbol here.

It is the same for e.g. images -- you specify the image, not a symbol
identifying an image.

E.g. when you use (defimage my-image ...)  to define an image, what
really happens is that the image specified by ... is loaded and
saved in the variable my-image.


> @item Value indicating that no fringe bitmap is present:
> @code{no-fringe-bitmap}.
> @c ??? I don't understand what that means.
> @c ??? Where would you find that value?

In the car or cdr of the return value from fringe-bitmaps-at-pos if
there is no bitmap in left or right fringe.

> @item Value indicating a reference to an undefined bitmap:
> @code{undef-fringe-bitmap}.
> @c ??? I don't understand what that means.
> @c ??? Where would you find that value?

If you specify an undefined fringe bitmap in a display property,
e.g. using fringe bitmap number 100 and only 50 bitmaps are defined.
Then the fringe will contain the undef-fringe-bitmap (a question-mark).


> @defun fringe-bitmaps-at-pos &optional pos window
> This function returns the fringe bitmaps of the display line
> containing position @var{pos} in window @var{window}.  The return
> value has the form @code{(@var{left} . @var{right})}, where @var{left}
> is a list of fringe bitmap numbers for left fringe, and @var{right} is
> similar for the right fringe.  These bitmap numbers are usually values
> of symbols such as the ones listed above.
>  
> @c ??? Why not return a list of symbols that identify the bitmaps?
> @c ??? This is Lisp, not C.

Internally the bitmaps are represented and managed using integers
(indexes), so there are no internal symbols defining bitmaps --- just
like there are no internal symbols defining images.

For simplicity, I chose to expose those integers as "opaque fringe
bitmap numbers".  Using symbols would be a lot of extra work for no
added functionality!

> @defun define-fringe-bitmap bits &optional height width align bitmap
> This function defines a new fringe bitmap, or replaces an existing
> bitmap.
>
> @c ??? Why not pass a symbol as the first argument
> @c ??? and define that symbol.  It would be cleaner.

There is no symbol associated with a fringe bitmap, so why invent one.
This is similar to how images are handled.

There could be a `deffringe' macro similar to `defimage' which
binds the result of define-fringe-bitmap to a variable...

Or I could rename define-fringe-bitmap to make-fringe-bitmap if people
expect a function named `define-something' to have a symbol as first
arg.

> The argument @var{bits} specifies the image to use.  It should be
> either a string or a vector of integers, where each element (an
> integer) corresponds to one row of the bitmap.  Each bit of an integer
> corresponds to one pixel of the bitmap.
> @c ??? Is the low bit the leftmost or the rightmost bit?

rightmost

For example, if you define a bitmap as

[#B00001000
 #B00001100
 #B00001110
 #B11111111
 #B11111111
 #B00001110
 #B00001100
 #B00001000]

it defines an arrow pointing to the right.


> The return value on success is an integer identifying the new bitmap.
> You should save that integer in a variable so it can be used to select
> this bitmap.  The value can also be @code{nil} of there are no more
> free bitmap slots.
> @c ??? Why not signal an error?  That would be cleaner.

Ok, I will change that.


-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk