GtkImageToolSelector

GtkImageToolSelector — Image tool for selecting rectangular regions

Screenshot showing a GtkImageToolSelector with an active selection on a GtkImageView

Functions

Properties

GtkImageView * view Write / Construct Only

Signals

void selection-changed Run Last

Types and Values

Object Hierarchy

    GEnum
    ╰── HotspotType
    GObject
    ╰── GtkImageToolSelector

Description

GtkImageToolSelector is a tool for selecting areas of an image. It is useful for cropping an image, for example. The tool is an implementor of the GtkIImageTool inteface which means that it can be plugged into a GtkImageView by using the gtk_image_view_set_tool() method.

GtkImageToolSelector changes the default display of the GtkImageView. It darkens down the unselected region of the image which provides a nice effect and makes it clearer what part of the image that is currently selected. Unfortunately, this effect is somewhat incompatible with how GtkImageNav behaves because that widget will show the image without darkening it.

The tool also changes the default behaviour of the mouse. When a GtkImageToolSelector is set on a GtkImageView, mouse presses do not "grab" the image and you cannot scroll by dragging. Instead mouse presses and dragging is used to resize and move the selection rectangle. When the mouse drags the selection rectangle to the border of the widget, the view autoscrolls which is a convenient way for a user to position the selection.

Please note that GtkImageToolSelector draws the image in two layers. One darkened and the selection rectangle in normal luminosity. Because it uses two draw operations instead one one like GtkImageToolDragger does, it is significantly slower than that tool. Therefore, it makes sense for a user of this library to set the interpolation to GDK_INTERP_NEAREST when using this tool to ensure that performance is acceptable to the users of the program.

Zoom bug

There is a small bug in GtkImageToolSelector that becomes apparent when the zoom factor is greater than about 30. The edge of the selection rectangle may in that case intersect a pixel:

The selection rectangle intersects the border pixel

The bug is caused by bug 389832 in gdk-pixbuf. There is no way to solve this bug on GtkImageView's level (but if someone knows how, I'd really like to know).

Functions

gtk_image_tool_selector_new ()

GtkIImageTool *
gtk_image_tool_selector_new (GtkImageView *view);

Creates a new selector tool for the specified view with default values. The default values are:

  • selection : (0, 0) - [0, 0]

Parameters

view

a GtkImageView

 

returns

a new GtkImageToolSelector

 

gtk_image_tool_selector_get_selection ()

void
gtk_image_tool_selector_get_selection (GtkImageToolSelector *selector,
                                       GdkRectangle *rect);

Fills in rect with the current selection rectangle. If either the width or the height of rect is zero, then nothing is selected and the selection should be considered inactive. See “selection-changed” for an example.

Parameters

selector

a GtkImageToolSelector

 

rect

a GdkRectangle to fill in with the current selection rectangle.

 

gtk_image_tool_selector_set_selection ()

void
gtk_image_tool_selector_set_selection (GtkImageToolSelector *selector,
                                       GdkRectangle *rect);

Sets the selection rectangle for the tool. Setting this attribute will cause the widget to immediately repaint itself if its view is realized.

This method does nothing under the following circumstances:

  • If the views pixbuf is NULL.
  • If rect is wider or taller than the size of the pixbuf
  • If rect equals the current selection rectangle.

If the selection falls outside the pixbufs area, its position is moved so that it is within the pixbuf.

Calling this method causes the ::selection-changed signal to be emitted.

The default selection is (0,0) - [0,0].

Parameters

selector

a GtkImageToolSelector

 

rect

Selection rectangle in image space coordinates.

 

Types and Values

enum HotspotType

Members

HOTSPOT_INSIDE

   

HOTSPOT_RESIZE_NORTH_WEST

   

HOTSPOT_RESIZE_NORTH_EAST

   

HOTSPOT_RESIZE_SOUTH_WEST

   

HOTSPOT_RESIZE_SOUTH_EAST

   

HOTSPOT_RESIZE_NORTH

   

HOTSPOT_RESIZE_EAST

   

HOTSPOT_RESIZE_SOUTH

   

HOTSPOT_RESIZE_WEST

   

HOTSPOT_OUTSIDE

   

HOTSPOT_LAST

   

Property Details

The “view” property

  “view”                     GtkImageView *

Image View to navigate.

Flags: Write / Construct Only

Signal Details

The “selection-changed” signal

void
user_function (GtkImageToolSelector *selector,
               gpointer              user_data)

The ::selection-changed signal is emitted when the selection rectangle on the selector is moved or resized. It is inteded to be used by applications that wants to print status information. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
static void
sel_changed_cb (GtkImageToolSelector *selector)
{
    GdkRectangle sel;
    gtk_image_tool_selector_get_selection (selector, &sel);
    if (!sel.width || !sel.height)
        printf ("No selection\n");
    else
        printf ("The selection is %d, %d - %d, %d\n",
                sel.x, sel.y, sel.width, sel.height);
}
...
// selector is an already initialized GtkImageToolSelector
// object.
g_signal_connect (G_OBJECT(selector), "selection_changed",
                  G_CALLBACK (sel_changed_cb), NULL);

Parameters

selector

the selector that emitted the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

See Also

GtkIImageTool, GtkImageToolDragger, gtk_image_view_set_tool()