Q on frame parameters *border-width

Q on frame parameters *border-width

[Drew Adams]

This is the total doc that I can find on these two frame parameters (from
the Elisp manual):

`border-width'
     The width in pixels of the window border.

`internal-border-width'
     The distance in pixels between text and border.

1. Wrt `border-width':

When I try this, I get an error, "Cannot change the border width of a
window":

 (modify-frame-parameters (selected-frame) '((border-width . 20)))

So, think I, perhaps you cannot change this parameter for an existing frame,
but perhaps you can set it for `default-frame-alist' and it will then affect
future frames. No such luck either.

Both the doc string and the error message speak of the "window" border, so I
guess this is a frame parameter that affects the border of each window in
the frame. Is that right? Just where is the window border? If not, if it is
about a frame border, then the doc string and error message should say
"frame", not "window".

What does this parameter do? Setting it doesn't seem to do anything, on
Windows XP at least (Emacs 20 or 22). Shouldn't the doc explain the
parameter a little more?


2. Wrt `internal-border-width':

The only difference in this parameter's name and that of the previous
parameter is "internal-". Does this mean that this too applies to Emacs
window borders (whatever they are) and not to frame borders?

Setting `internal-border-width' actually does change something, but it
appears to be the internal _frame_ border, not a border around each window.
If this parameter is about a frame border, but `border-width' is about
window borders, then shouldn't the parameter names indicate this difference?
And shouldn't the doc point out this difference?

The `internal-border-width' does not appear to be the distance between text
and border, if the border when fringe is present - in that case, it is the
distance between the fringe and the border.

Re: Q on frame parameters *border-width

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Fri, 20 Jan 2006 16:20:54 -0800
> 
> 1. Wrt `border-width':
> 
> When I try this, I get an error, "Cannot change the border width of a
> window":
> 
>  (modify-frame-parameters (selected-frame) '((border-width . 20)))
> 
> So, think I, perhaps you cannot change this parameter for an existing frame,
> but perhaps you can set it for `default-frame-alist' and it will then affect
> future frames. No such luck either.

In fact, you cannot change this for _any_ window.  At least on X, I
think this parameter is under control of the window manager.  But even
if I'm wrong, it looks like no one has written code to handle this, on
any windowing system.

> Both the doc string and the error message speak of the "window" border, so I
> guess this is a frame parameter that affects the border of each window in
> the frame. Is that right? Just where is the window border?

I don't know how to explain this better than the manual does.  Each
frame has a border--do you know what that border is?  If not, perhaps
your problem is not what border-width is, but what is the border.

With typical X window managers this border is clearly visible, because
it has a 3D appearance that makes it stand out.  On MS-Windows, this
is less visible, but you should still be able to see a narrow
2-pixel-wide strip between the outer edge of the Emacs frame and the
parts of the frame that Emacs displays: the fringe at the left side,
the title bar's background color on the top side, etc.

> If not, if it is about a frame border, then the doc string and error
> message should say "frame", not "window".

Maybe, I don't know.  The confusion between ``window'' and ``frame''
is not a simple one.  The parameter is for frames, not for windows.

> What does this parameter do? Setting it doesn't seem to do anything, on
> Windows XP at least (Emacs 20 or 22). Shouldn't the doc explain the
> parameter a little more?

I think this parameter exists so that one could compute the actual
size of the frame.

> 2. Wrt `internal-border-width':
> 
> The only difference in this parameter's name and that of the previous
> parameter is "internal-". Does this mean that this too applies to Emacs
> window borders (whatever they are) and not to frame borders?

No, the manual says it explicitly: this is the distance between the
border and the text area of the Emacs display.

> Setting `internal-border-width' actually does change something, but it
> appears to be the internal _frame_ border, not a border around each window.

It _is_ the frame border.

> The `internal-border-width' does not appear to be the distance between text
> and border, if the border when fringe is present - in that case, it is the
> distance between the fringe and the border.

Yes.

RE: Q on frame parameters *border-width

[Drew Adams]

    > 1. Wrt `border-width':
    >
    > When I try this, I get an error, "Cannot change the border width of a
    > window":
    >
    >  (modify-frame-parameters (selected-frame) '((border-width . 20)))
    >
    > So, think I, perhaps you cannot change this parameter for an
    existing frame,
    > but perhaps you can set it for `default-frame-alist' and it
    will then affect
    > future frames. No such luck either.

    In fact, you cannot change this for _any_ window.  At least on X, I
    think this parameter is under control of the window manager.  But even
    if I'm wrong, it looks like no one has written code to handle this, on
    any windowing system.

Are you saying that X sets it, so you can at least read it (on X)? If so,
that should be documented: it is a read-only parameter that is set by (some?
all? only X?) window managers.

    > Both the doc string and the error message speak of the
    "window" border, so I
    > guess this is a frame parameter that affects the border of
    each window in
    > the frame. Is that right? Just where is the window border?

    I don't know how to explain this better than the manual does.  Each
    frame has a border--do you know what that border is?  If not, perhaps
    your problem is not what border-width is, but what is the border.

You are speaking of a frame border; the doc speaks of a window border.

    With typical X window managers this border is clearly visible, because
    it has a 3D appearance that makes it stand out.  On MS-Windows, this
    is less visible, but you should still be able to see a narrow
    2-pixel-wide strip between the outer edge of the Emacs frame and the
    parts of the frame that Emacs displays: the fringe at the left side,
    the title bar's background color on the top side, etc.

Again, you're speaking of the frame border. In that case, the doc shouldn't
mention "window" - or else it should say "window-manager window (frame)".

    > If not, if it is about a frame border, then the doc string and error
    > message should say "frame", not "window".

    Maybe, I don't know.  The confusion between ``window'' and ``frame''
    is not a simple one.  The parameter is for frames, not for windows.

If it is a frame parameter that is about a frame, not a window, border, then
why mention "window" at all? Why is this not simple?

    > What does this parameter do? Setting it doesn't seem to do
    anything, on
    > Windows XP at least (Emacs 20 or 22). Shouldn't the doc explain the
    > parameter a little more?

    I think this parameter exists so that one could compute the actual
    size of the frame.

OK. That's reasonable. It would be good to say that 1) the parameter is
read-only, 2) it is not (or might not be) set by window managers other than
X Window, and 3) it is useful for calculating the total frame size, in
pixels.

    > 2. Wrt `internal-border-width':
    >
    > The only difference in this parameter's name and that of the previous
    > parameter is "internal-". Does this mean that this too
    applies to Emacs
    > window borders (whatever they are) and not to frame borders?

    No, the manual says it explicitly: this is the distance between the
    border and the text area of the Emacs display.

Sure it does. My point here was about the _name_.

Anyway, the point is meaningless now, since you've confirmed that
`border-width' is also about the frame border, not an Emacs window border.

    > Setting `internal-border-width' actually does change something, but it
    > appears to be the internal _frame_ border, not a border
    around each window.

    It _is_ the frame border.

Yes, see above.

    > The `internal-border-width' does not appear to be the
    distance between text
    > and border, if the border when fringe is present - in that
    case, it is the
    > distance between the fringe and the border.

    Yes.

So, perhaps this could be stated explicitly in the doc.

Re: Q on frame parameters *border-width

[Richard M. Stallman]

    So, think I, perhaps you cannot change this parameter for an
    existing frame, but perhaps you can set it for
    `default-frame-alist' and it will then affect future frames. No
    such luck either.

It used to work, in the past, to set the border width for a new frame.
Perhaps it only works in a non-toolkit build.  Or perhaps modern window
managers don't allow the app to control this, while old ones did.

If someone could determine what the situation is, then we could
update the documentation to be clear about it.

    Both the doc string and the error message speak of the "window" border, so I
    guess this is a frame parameter that affects the border of each window in
    the frame.

They are mistaken.  The border belongs to the frame.

    Setting `internal-border-width' actually does change something, but it
    appears to be the internal _frame_ border, not a border around each window.

They are both for the frame.

Re: Q on frame parameters *border-width

[Eli Zaretskii]

> From: "Richard M. Stallman" <rms@gnu.org>
> Date: Sat, 21 Jan 2006 22:59:01 -0500
> Cc: emacs-devel@gnu.org
> 
>     Both the doc string and the error message speak of the "window" border, so I
>     guess this is a frame parameter that affects the border of each window in
>     the frame.
> 
> They are mistaken.  The border belongs to the frame.
> 
>     Setting `internal-border-width' actually does change something, but it
>     appears to be the internal _frame_ border, not a border around each window.
> 
> They are both for the frame.

I fixed the manual to say this explicitly.