gimpselection

## gimpselection gimpselection — Functions for manipulating selections. |

## Synopsis

    gboolean            gimp_selection_bounds               (gint32 image_ID,
                                                             gboolean *non_empty,
                                                             gint *x1,
                                                             gint *y1,
                                                             gint *x2,
                                                             gint *y2);
    gboolean            gimp_selection_all                  (gint32 image_ID);
    gboolean            gimp_selection_none                 (gint32 image_ID);
    gboolean            gimp_selection_clear                (gint32 image_ID);
    gboolean            gimp_selection_is_empty             (gint32 image_ID);
    gint32              gimp_selection_float                (gint32 image_ID,
                                                             gint32 drawable_ID,
                                                             gint offx,
                                                             gint offy);
    gboolean            gimp_selection_load                 (gint32 channel_ID);
    gint32              gimp_selection_save                 (gint32 image_ID);
    gint                gimp_selection_value                (gint32 image_ID,
                                                             gint x,
                                                             gint y);
    gboolean            gimp_selection_grow                 (gint32 image_ID,
                                                             gint steps);
    gboolean            gimp_selection_shrink               (gint32 image_ID,
                                                             gint steps);
    gboolean            gimp_selection_invert               (gint32 image_ID);
    gboolean            gimp_selection_feather              (gint32 image_ID,
                                                             gdouble radius);
    gboolean            gimp_selection_sharpen              (gint32 image_ID);
    gboolean            gimp_selection_border               (gint32 image_ID,
                                                             gint radius);
    gboolean            gimp_selection_translate            (gint32 image_ID,
                                                             gint offx,
                                                             gint offy);
    gboolean            gimp_selection_layer_alpha          (gint32 layer_ID);
    gboolean            gimp_selection_combine              (gint32 channel_ID,
                                                             GimpChannelOps operation);

## Description

Functions for manipulating selections.

## Details

### gimp_selection_bounds ()

    gboolean            gimp_selection_bounds               (gint32 image_ID,
                                                             gboolean *non_empty,
                                                             gint *x1,
                                                             gint *y1,
                                                             gint *x2,
                                                             gint *y2);

Find the bounding box of the current selection.

This procedure returns whether there is a selection for the specified image. If there is one, the upper left and lower right corners of the bounding box are returned. These coordinates are relative to the image. Please note that the pixel specified by the lower righthand coordinate of the bounding box is not part of the selection. The selection ends at the upper left corner of this pixel. This means the width of the selection can be calculated as (x2 - x1), its height as (y2 - y1).

`image_ID` : | The image.
`non_empty` : | TRUE if there is a selection.
`x1` : | x coordinate of upper left corner of selection bounds.
`y1` : | y coordinate of upper left corner of selection bounds.
`x2` : | x coordinate of lower right corner of selection bounds.
`y2` : | y coordinate of lower right corner of selection bounds.
Returns : | TRUE on success.

### gimp_selection_all ()

    gboolean            gimp_selection_all                  (gint32 image_ID);

Select all of the image.

This procedure sets the selection mask to completely encompass the image. Every pixel in the selection channel is set to 255.

`image_ID` : | The image.
Returns : | TRUE on success.

### gimp_selection_none ()

    gboolean            gimp_selection_none                 (gint32 image_ID);

Deselect the entire image.

This procedure deselects the entire image. Every pixel in the selection channel is set to 0.

`image_ID` : | The image.
Returns : | TRUE on success.

### gimp_selection_clear ()

    gboolean            gimp_selection_clear                (gint32 image_ID);

### Warning

`gimp_selection_clear` is deprecated and should not be used in newly-written code.

This procedure is deprecated! Use `gimp_selection_none()` instead.

`image_ID` : | The image.
Returns : | TRUE on success.

### gimp_selection_is_empty ()

    gboolean            gimp_selection_is_empty             (gint32 image_ID);

Determine whether the selection is empty.

This procedure returns TRUE if the selection for the specified image is empty.

`image_ID` : | The image.
Returns : | Is the selection empty?

### gimp_selection_float ()

    gint32              gimp_selection_float                (gint32 image_ID,
                                                             gint32 drawable_ID,
                                                             gint offx,
                                                             gint offy);

Float the selection from the specified drawable with initial offsets as specified.

This procedure determines the region of the specified drawable that lies beneath the current selection. The region is then cut from the drawable and the resulting data is made into a new layer which is instantiated as a floating selection. The offsets allow initial positioning of the new floating selection.

`image_ID` : | ignored
`drawable_ID` : | The drawable from which to float selection.
`offx` : | x offset for translation.
`offy` : | y offset for translation.
Returns : | The floated layer.

### gimp_selection_load ()

    gboolean            gimp_selection_load                 (gint32 channel_ID);

Transfer the specified channel to the selection mask.

This procedure loads the specified channel into the selection mask.

`channel_ID` : | The channel.
Returns : | TRUE on success.

### gimp_selection_save ()

    gint32              gimp_selection_save                 (gint32 image_ID);

Copy the selection mask to a new channel.

This procedure copies the selection mask and stores the content in a new channel. The new channel is automatically inserted into the image's list of channels.

`image_ID` : | The image.
Returns : | The new channel.

### gimp_selection_value ()

    gint                gimp_selection_value                (gint32 image_ID,
                                                             gint x,
                                                             gint y);

Find the value of the selection at the specified coordinates.

This procedure returns the value of the selection at the specified coordinates. If the coordinates lie out of bounds, 0 is returned.

`image_ID` : | The image.
`x` : | x coordinate of value.
`y` : | y coordinate of value.
Returns : | Value of the selection.

### gimp_selection_grow ()

    gboolean            gimp_selection_grow                 (gint32 image_ID,
                                                             gint steps);

Grow the image's selection

This procedure grows the selection. Growing involves expanding the boundary in all directions by the specified pixel amount.

`image_ID` : | The image.
`steps` : | Steps of grow (in pixels).
Returns : | TRUE on success.

### gimp_selection_shrink ()

    gboolean            gimp_selection_shrink               (gint32 image_ID,
                                                             gint steps);

Shrink the image's selection

This procedure shrinks the selection. Shrinking invovles trimming the existing selection boundary on all sides by the specified number of pixels.

`image_ID` : | The image.
`steps` : | Steps of shrink (in pixels).
Returns : | TRUE on success.

### gimp_selection_invert ()

    gboolean            gimp_selection_invert               (gint32 image_ID);

Invert the selection mask.

This procedure inverts the selection mask. For every pixel in the selection channel, its new value is calculated as (255 - old-value).

`image_ID` : | The image.
Returns : | TRUE on success.

### gimp_selection_feather ()

    gboolean            gimp_selection_feather              (gint32 image_ID,
                                                             gdouble radius);

Feather the image's selection

This procedure feathers the selection. Feathering is implemented using a gaussian blur.

`image_ID` : | The image.
`radius` : | Radius of feather (in pixels).
Returns : | TRUE on success.

### gimp_selection_sharpen ()

    gboolean            gimp_selection_sharpen              (gint32 image_ID);

Sharpen the selection mask.

This procedure sharpens the selection mask. For every pixel in the selection channel, if the value is > 127, the new pixel is assigned a value of 255. This removes any \"anti-aliasing\" that might exist in the selection mask's boundary.

`image_ID` : | The image.
Returns : | TRUE on success.

### gimp_selection_border ()

    gboolean            gimp_selection_border               (gint32 image_ID,
                                                             gint radius);

Border the image's selection

This procedure borders the selection. Bordering creates a new selection which is defined along the boundary of the previous selection at every point within the specified radius.

`image_ID` : | The image.
`radius` : | Radius of border (in pixels).
Returns : | TRUE on success.

### gimp_selection_translate ()

    gboolean            gimp_selection_translate            (gint32 image_ID,
                                                             gint offx,
                                                             gint offy);

Translate the selection by the specified offsets.

This procedure actually translates the selection for the specified image by the specified offsets. Regions that are translated from beyond the bounds of the image are set to empty. Valid regions of the selection which are translated beyond the bounds of the image because of this call are lost.

`image_ID` : | The image.
`offx` : | x offset for translation.
`offy` : | y offset for translation.
Returns : | TRUE on success.

### gimp_selection_layer_alpha ()

    gboolean            gimp_selection_layer_alpha          (gint32 layer_ID);

Transfer the specified layer's alpha channel to the selection mask.

The alpha channel information is used to create a selection mask such that for any pixel in the image defined in the specified layer, that layer pixel's alpha value is transferred to the selection mask. If the layer is undefined at a particular image pixel, the associated selection mask value is set to 0. A layer without an alpha channel is considered opaque.

`layer_ID` : | Layer with alpha.
Returns : | TRUE on success.

### gimp_selection_combine ()

    gboolean            gimp_selection_combine              (gint32 channel_ID,
                                                             GimpChannelOps operation);

Combines the specified channel with the selection mask.

This procedure combines the specified channel into the selection mask.

`channel_ID` : | The channel.
`operation` : | The selection operation.
Returns : | TRUE on success.