We are working toward cleaning up for a 2.4 release, and one of the
things that needs to be cleaned up is the new tools, including the
ones based on GimpRectangleTool, that is, the new rectangle select,
ellipse select, and crop tools.  In order to fix problems, we need bug
reports that describe them.  However, Sven feels that there is no
point in filing bug reports right now, because there is no
specification of how the tools are *supposed* to behave.  This
document is aimed at providing such a specification.  If a tool
doesn't work as described here in some way, or if you think that the
operations described here are not the way the tool *ought* to work,
then you should file a bug report.

(Of course, it is also possible that this document will not be
entirely perfect itself.  Suggestions for improvements or
clarifications, or questions, are welcome.)

I will focus here on the rectangle select tool.  Almost all of its
features also apply to the ellipse select and crop tools -- with a
couple of exceptions.

   The (New) Rectangle Select Tool

The Rectangle Select tool is used for making rectangular selections,
possibly feathered.  It is intended to be both simple to use and
powerful enough to allow fancy things when they are needed.

The basic operation is dragging out a selection, by clicking and
dragging.  This is done in the same way as with the old rect-select
tool.  Once you have dragged out a rectangle, the selection exists,
and you can switch to a different tool, or act on the selection in any
way you please.  An important different from the old tool is that the
rectangle you get is modifiable, as indicated by handles at the
corners.  You should be able to click on any corner or edge and drag
it -- the cursor should change to indicate when dragging is possible.
Clicking *inside* the rectangle, and then dragging, will move all of
the rectangle edges simultaneously without changing the shape.
Clicking *outside* the rectangle and dragging will start a new

The results are different if you click and release without dragging.  If 
there is an existing rectangle (with handles visible), then clicking 
without dragging converts it into a fixed, unmodifiable selection, with 
no handles.  (This is essentially useless, and only happens for
consistency.)  If there is no existing rectangle, and you click inside
an existing selection, then a new, modifiable rectangular selection is
created, whose bounds are just large enough to completely enclose the
previous selection.  If instead you click *outside* the existing
selection, then the selection is removed.

After you have pressed the mouse button, while you are holding it down
and dragging, the marching ants revert temporarily to follow the previous
selection.  This is useful if you are working in Add, Subtract, or
Intersect mode, but may be confusing in Replace mode.

The rectangle can also be modified using a set of controls located
inside the tool options.  (By default, these are hidden inside an
expander.)  You can use spinbuttons to enter values for the width,
height, aspect ratio, or coordinates of the corners.

  Modifier keys

As with other tools, the Rectangle Select tool can be switched between
Replace, Add, Subtract, and Intersect modes, either by using buttons
in the tool options, or by using the Shift and Control modifiers in
the standard combinations.  Modifier keys are only effective in
changing mode when pressed *before* the mouse click that starts a new
rectangle.  They can be released after the mouse click without
changing the mode of the operation.

Modifier keys change the click-and-drag behavior slightly.  When
modifiers are used to change the mode to something other than Replace,
then clicking always starts a new rectangle -- it never modifies the
existing rectangle.  Note that this applies only when the Mode is
changed using modifier keys, not when it is changed using the buttons
in the tool options.

When you modify an existing rectangle by dragging an edge or corner,
you don't need to press any modifier keys.  The operation performed for
a given rectangle (i.e., replace, add, subtract, or intersect) is
never changed simply by moving the edges of the rectangle.

  Keyboard Control

Only a few keys affect this tool.  The Esc key cancels the operation,
and causes the selection to revert to its state before the tool was
activated.  The Return key makes the selection unmodifiable, just like
clicking inside without moving.  The arrow keys move the rectangle
without changing its shape -- holding down Shift increases the
movement increment. 

  Tool Options

Mode:  as described above

Antialiasing: not available for this tool, shown for consistency

Feather edges: does not need describing here

Auto shrink selection: If this option is activated, then, after you
  drag out a rectangle and release the mouse button, the rectangle
  will automatically be shrunk as much as possible such that the
  border outside the rectangle is all the same color.  Checking this
  option makes available a "Sample merged" option that causes the tool
  to us the visible projection of the image rather than just the
  currently active layer.

Expand from center: If this option is activated, then the center of
  the rectangle is kept fixed when an edge or corner is dragged -- the
  opposite edge or corner is moved symmetrically.  Note that it is
  still possible to move the rectangle as a whole by clicking inside
  it and dragging.

Make square: If this option is activated, then the rectangle is
  constrained to be square -- moving an edge or corner causes
  corresponding movements in whatever other edges are appropriate.
  This has the same effect as setting the aspect ratio to 1.0 and
  checking the "Fixed Aspect Ratio" box, but is simpler to use.

Highlight: Darkly shade the region outside the current rectangle.

Guides: You have the option of showing various sorts of guidelines,
  either "no guides", "center lines", "rule of thirds", or "golden
  sections".  These may be useful when you intend to use the selection
  for copying and pasting.

  Center lines:  crosshairs intersecting at the center of the

  Rule of thirds: two horizontal and two vertical lines, dividing the
    rectangle into equal thirds.  These are helpful for placing image
    elements at the locations that some people think are aesthetically

  Golden sections: two horizontal and two vertical lines, dividing the
    rectangle into thirds such that the ratio of the inner to outer
    sectors equals the "golden ratio", approximately 1.6. These are
    helpful for placing image elements at the locations that some
    *other* people think are aesthetically best.

Rectangle Controls:  An expander containing a set of spinbuttons and
  checkboxes used for specifying the shape of the rectangle
  numerically.  There are checkboxes for "fixed width", "fixed
  height", and "fixed aspect".  If any of these are activated, then
  the number entered in the corresonding spinbutton will be used to
  set the relevant dimension of the rectangle, and will not be
  affected by any mouse actions.  It is possible for more than one to
  be activated.  If, for example, both "fixed width" and "fixed
  height" are active, then the shape of the rectangle will be fixed,
  and dragging any edge or corner will simply move the rectangle as a

  At the bottom of the Controls are a set of four spinsbuttons that
  can be used to change the coordinates of the rectangle corners.
  Changing any of these has the same effect as dragging one of the
  rectangle edges using the mouse, including the application of any
  constraints that are active.

______________ ______________ ______________ ______________
Sent via the CNPRC Email system at primate.ucdavis.edu

Gimp-developer mailing list

Reply via email to