Author:		Jan Nijtmans <[email protected]>
State:		Draft
Type:		Project
Vote:		Pending
Created:	2024-06-18
Tcl-Version:	9.1
Tk-Branch:	tip-698

Abstract

This TIP proposes to change the handling of negative screen distances. Currently, all Tk options specified with TK_OPTION_PIXELS or TK_CONFIG_PIXELS allow negative values as well as positive ones. But - in fact - almost none of those can actually handle negative values. Therefore Tk contains code which magically changes negative values to 0, without giving an error-message. Other kinds of invalid values throw an error, but negative values don't.

This TIP introduces a new flag TK_OPTION_NEG_OK. If this flag is used with TK_OPTION_PIXELS/TK_CONFIG_PIXELS, negative values will be kept as-is. Otherwise an error will be produced for negative values, the same as for other invalid input.

Rationale

Tk contains a lot of code like this (tkTextTag.c):

    if (tagPtr->borderWidth < 0) {
        tagPtr->borderWidth = 0;
    }

This protects the code from ever receiving negative values for -borderwidth (for example). There are only 5 options where negative values have an actual function, which is also documented and used in test-cases. Those are:

The -width, -height, -x, -y options from place
The -offset option for text tags.

Those options will get the new TK_OPTION_NEG_OK flag and therefore continue to accept negative values. All other options will start throwing an error when a negative value is input. Since this is now handled in generic code, the magic as in the example above can be removed everywhere.

Extensions can use the TK_OPTION_NEG_OK flags as well. It can only be used with TK_OPTION_PIXELS and TK_CONFIG_PIXELS, not with any of the other types.

Specification

All Tk options specified with TK_OPTION_PIXELS will, starting width Tk 9.0 return an error when a negative screen distance is supplied, in stead of magically changing the value to 0 or {}. If that is not desired, a new flag TK_OPTION_NEG_OK can be used (possibly in combination with the already existing TK_OPTION_NULL_OK).

The TK_OPTION_NEG_OK will be used by the -width, -height, '-x' and '-y' options from place, -dashoffset from canvas items, and the -offset option for text tags. No other PIXEL options currently can handle negative values. But if it turns out that negative values are useful for other options, the list might be extended to more options. This should be used with care.

The TK_OPTION_NEG_OK flag will be backported to 8.7 as well, but with a different implementation: No errors will be thrown for negative values, the flag only controls whether negative values will be kept or changed to 0 (or {}). No behavior is changing in 8.7, keeping maximum compatibility with 8.6.

The backport work to 8.7 is planned to be done after Tk 9.0 is finalized.

Compatibility

There's a possible incompatibility here. User code which sets a screen distance to a negative value will now return an error, in stead of the value magically changing to 0 (or {}). Code that depends on the current magic will break.

Extensions using TK_OPTION_PIXELS without the TK_OPTION_NEG_OK will notice the same behavioral change. Most likely, negative values where never intended to be used. If it was intended, the TK_OPTION_NEG_OK should be added to keep the original behavior with Tk 9.0.

Implementation

Implementation is in Tk branch "tip-698".

Copyright