GtkToolPalette: GTK+ 2 Reference Manual

## GtkToolPalette GtkToolPalette — A tool palette with categories |

## Functions

GtkWidget * | gtk_tool_palette_new ()
gboolean | gtk_tool_palette_get_exclusive ()
void | gtk_tool_palette_set_exclusive ()
gboolean | gtk_tool_palette_get_expand ()
void | gtk_tool_palette_set_expand ()
gint | gtk_tool_palette_get_group_position ()
void | gtk_tool_palette_set_group_position ()
GtkIconSize | gtk_tool_palette_get_icon_size ()
void | gtk_tool_palette_set_icon_size ()
void | gtk_tool_palette_unset_icon_size ()
GtkToolbarStyle | gtk_tool_palette_get_style ()
void | gtk_tool_palette_set_style ()
void | gtk_tool_palette_unset_style ()
void | gtk_tool_palette_add_drag_dest ()
GtkWidget * | gtk_tool_palette_get_drag_item ()
const GtkTargetEntry * | gtk_tool_palette_get_drag_target_group ()
const GtkTargetEntry * | gtk_tool_palette_get_drag_target_item ()
GtkToolItemGroup * | gtk_tool_palette_get_drop_group ()
GtkToolItem * | gtk_tool_palette_get_drop_item ()
void | gtk_tool_palette_set_drag_source ()
GtkAdjustment * | gtk_tool_palette_get_hadjustment ()
GtkAdjustment * | gtk_tool_palette_get_vadjustment ()

## Properties

GtkIconSize | icon-size | Read / Write
gboolean | icon-size-set | Read / Write
GtkToolbarStyle | toolbar-style | Read / Write

## Child Properties

gboolean | exclusive | Read / Write
gboolean | expand | Read / Write

## Signals

void | set-scroll-adjustments | Action

## Types and Values

struct | GtkToolPalette
enum | GtkToolPaletteDragTargets

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkObject
                ╰── GtkWidget
                    ╰── GtkContainer
                        ╰── GtkToolPalette

## Implemented Interfaces

GtkToolPalette implements AtkImplementorIface, GtkBuildable and GtkOrientable.

## Includes

    #include <gtk/gtk.h>

## Description

A GtkToolPalette allows you to add GtkToolItems to a palette-like container with different categories and drag and drop support.

A GtkToolPalette is created with a call to `gtk_tool_palette_new()`.

GtkToolItems cannot be added directly to a GtkToolPalette - instead they are added to a GtkToolItemGroup which can than be added to a GtkToolPalette. To add a GtkToolItemGroup to a GtkToolPalette, use `gtk_container_add()`.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    GtkWidget *palette, *group;
    GtkToolItem *item;

    palette = gtk_tool_palette_new ();
    group = gtk_tool_item_group_new (_("Test Category"));
    gtk_container_add (GTK_CONTAINER (palette), group);

    item = gtk_tool_button_new_from_stock (GTK_STOCK_OK);
    gtk_tool_item_group_insert (GTK_TOOL_ITEM_GROUP (group), item, -1);

The easiest way to use drag and drop with GtkToolPalette is to call `gtk_tool_palette_add_drag_dest()` with the desired drag source `palette` and the desired drag target `widget` . Then `gtk_tool_palette_get_drag_item()` can be used to get the dragged item in the “drag-data-received” signal handler of the drag target.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    static void
    passive_canvas_drag_data_received (GtkWidget        *widget,
                                       GdkDragContext   *context,
                                       gint              x,
                                       gint              y,
                                       GtkSelectionData *selection,
                                       guint             info,
                                       guint             time,
                                       gpointer          data)
    {
      GtkWidget *palette;
      GtkWidget *item;

      /<!-- -->* Get the dragged item *<!-- -->/
      palette = gtk_widget_get_ancestor (gtk_drag_get_source_widget (context),
                                         GTK_TYPE_TOOL_PALETTE);
      if (palette != NULL)
        item = gtk_tool_palette_get_drag_item (GTK_TOOL_PALETTE (palette),
                                               selection);

      /<!-- -->* Do something with item *<!-- -->/
    }

    GtkWidget *target, palette;

    palette = gtk_tool_palette_new ();
    target = gtk_drawing_area_new ();

    g_signal_connect (G_OBJECT (target), "drag-data-received",
                      G_CALLBACK (passive_canvas_drag_data_received), NULL);
    gtk_tool_palette_add_drag_dest (GTK_TOOL_PALETTE (palette), target,
                                    GTK_DEST_DEFAULT_ALL,
                                    GTK_TOOL_PALETTE_DRAG_ITEMS,
                                    GDK_ACTION_COPY);

## Functions

### gtk_tool_palette_new ()

    GtkWidget *
    gtk_tool_palette_new (void);

Creates a new tool palette.

#### Returns

a new GtkToolPalette

Since: 2.20

### gtk_tool_palette_get_exclusive ()

    gboolean
    gtk_tool_palette_get_exclusive (GtkToolPalette *palette,
                                    GtkToolItemGroup *group);

Gets whether `group` is exclusive or not. See `gtk_tool_palette_set_exclusive()`.

#### Parameters

palette | a GtkToolPalette |
group | a GtkToolItemGroup which is a child of palette |

#### Returns

`TRUE` if `group` is exclusive

Since: 2.20

### gtk_tool_palette_set_exclusive ()

    void
    gtk_tool_palette_set_exclusive (GtkToolPalette *palette,
                                    GtkToolItemGroup *group,
                                    gboolean exclusive);

Sets whether the group should be exclusive or not. If an exclusive group is expanded all other groups are collapsed.

#### Parameters

palette | a GtkToolPalette |
group | a GtkToolItemGroup which is a child of palette |
exclusive | whether the group should be exclusive or not |

Since: 2.20

### gtk_tool_palette_get_expand ()

    gboolean
    gtk_tool_palette_get_expand (GtkToolPalette *palette,
                                 GtkToolItemGroup *group);

Gets whether group should be given extra space. See `gtk_tool_palette_set_expand()`.

#### Parameters

palette | a GtkToolPalette |
group | a GtkToolItemGroup which is a child of palette |

#### Returns

`TRUE` if group should be given extra space, `FALSE` otherwise

Since: 2.20

### gtk_tool_palette_set_expand ()

    void
    gtk_tool_palette_set_expand (GtkToolPalette *palette,
                                 GtkToolItemGroup *group,
                                 gboolean expand);

Sets whether the group should be given extra space.

#### Parameters

palette | a GtkToolPalette |
group | a GtkToolItemGroup which is a child of palette |
expand | whether the group should be given extra space |

Since: 2.20

### gtk_tool_palette_get_group_position ()

    gint
    gtk_tool_palette_get_group_position (GtkToolPalette *palette,
                                         GtkToolItemGroup *group);

Gets the position of `group` in `palette` as index. See `gtk_tool_palette_set_group_position()`.

#### Parameters

palette | a GtkToolPalette |
group | a GtkToolItemGroup |

#### Returns

the index of group or -1 if `group` is not a child of `palette`

Since: 2.20

### gtk_tool_palette_set_group_position ()

    void
    gtk_tool_palette_set_group_position (GtkToolPalette *palette,
                                         GtkToolItemGroup *group,
                                         gint position);

Sets the position of the group as an index of the tool palette. If position is 0 the group will become the first child, if position is -1 it will become the last child.

#### Parameters

palette | a GtkToolPalette |
group | a GtkToolItemGroup which is a child of palette |
position | a new index for group |

Since: 2.20

### gtk_tool_palette_get_icon_size ()

    GtkIconSize
    gtk_tool_palette_get_icon_size (GtkToolPalette *palette);

Gets the size of icons in the tool palette. See `gtk_tool_palette_set_icon_size()`.

#### Parameters

palette | a GtkToolPalette |

#### Returns

the GtkIconSize of icons in the tool palette.

[type int]

Since: 2.20

### gtk_tool_palette_set_icon_size ()

    void
    gtk_tool_palette_set_icon_size (GtkToolPalette *palette,
                                    GtkIconSize icon_size);

Sets the size of icons in the tool palette.

#### Parameters

palette | a GtkToolPalette |
icon_size | the GtkIconSize that icons in the tool palette shall have. | [type int]

Since: 2.20

### gtk_tool_palette_unset_icon_size ()

    void
    gtk_tool_palette_unset_icon_size (GtkToolPalette *palette);

Unsets the tool palette icon size set with `gtk_tool_palette_set_icon_size()`, so that user preferences will be used to determine the icon size.

#### Parameters

palette | a GtkToolPalette |

Since: 2.20

### gtk_tool_palette_get_style ()

    GtkToolbarStyle
    gtk_tool_palette_get_style (GtkToolPalette *palette);

Gets the style (icons, text or both) of items in the tool palette.

#### Parameters

palette | a GtkToolPalette |

#### Returns

the GtkToolbarStyle of items in the tool palette.

Since: 2.20

### gtk_tool_palette_set_style ()

    void
    gtk_tool_palette_set_style (GtkToolPalette *palette,
                                GtkToolbarStyle style);

Sets the style (text, icons or both) of items in the tool palette.

#### Parameters

palette | a GtkToolPalette |
style | the GtkToolbarStyle that items in the tool palette shall have |

Since: 2.20

### gtk_tool_palette_unset_style ()

    void
    gtk_tool_palette_unset_style (GtkToolPalette *palette);

Unsets a toolbar style set with `gtk_tool_palette_set_style()`, so that user preferences will be used to determine the toolbar style.

#### Parameters

palette | a GtkToolPalette |

Since: 2.20

### gtk_tool_palette_add_drag_dest ()

    void
    gtk_tool_palette_add_drag_dest (GtkToolPalette *palette,
                                    GtkWidget *widget,
                                    GtkDestDefaults flags,
                                    GtkToolPaletteDragTargets targets,
                                    GdkDragAction actions);

Sets `palette` as drag source (see `gtk_tool_palette_set_drag_source()`) and sets `widget` as a drag destination for drags from `palette` . See `gtk_drag_dest_set()`.

#### Parameters

palette | a GtkToolPalette |
widget | a GtkWidget which should be a drag destination for `palette` |
flags | the flags that specify what actions GTK+ should take for drops on that widget |
targets | the GtkToolPaletteDragTargets which the widget should support |
actions | the GdkDragActions which the widget should suppport |

Since: 2.20

### gtk_tool_palette_get_drag_item ()

    GtkWidget *
    gtk_tool_palette_get_drag_item (GtkToolPalette *palette,
                                    const GtkSelectionData *selection);

Get the dragged item from the selection. This could be a GtkToolItem or a GtkToolItemGroup.

#### Parameters

palette | a GtkToolPalette |
selection | a GtkSelectionData |

#### Returns

the dragged item in selection.

[transfer none]

Since: 2.20

### gtk_tool_palette_get_drag_target_group ()

    const GtkTargetEntry *
    gtk_tool_palette_get_drag_target_group
                                   (void);

Get the target entry for a dragged GtkToolItemGroup.

#### Returns

the GtkTargetEntry for a dragged group.

[transfer none]

Since: 2.20

### gtk_tool_palette_get_drag_target_item ()

    const GtkTargetEntry *
    gtk_tool_palette_get_drag_target_item (void);

Gets the target entry for a dragged GtkToolItem.

#### Returns

the GtkTargetEntry for a dragged item.

[transfer none]

Since: 2.20

### gtk_tool_palette_get_drop_group ()

    GtkToolItemGroup *
    gtk_tool_palette_get_drop_group (GtkToolPalette *palette,
                                     gint x,
                                     gint y);

Gets the group at position (x, y).

#### Parameters

palette | a GtkToolPalette |
x | the x position |
y | the y position |

#### Returns

the GtkToolItemGroup at position or `NULL` if there is no such group.

[transfer none]

Since: 2.20

### gtk_tool_palette_get_drop_item ()

    GtkToolItem *
    gtk_tool_palette_get_drop_item (GtkToolPalette *palette,
                                    gint x,
                                    gint y);

Gets the item at position (x, y). See `gtk_tool_palette_get_drop_group()`.

#### Parameters

palette | a GtkToolPalette |
x | the x position |
y | the y position |

#### Returns

the GtkToolItem at position or `NULL` if there is no such item.

[transfer none]

Since: 2.20

### gtk_tool_palette_set_drag_source ()

    void
    gtk_tool_palette_set_drag_source (GtkToolPalette *palette,
                                      GtkToolPaletteDragTargets targets);

Sets the tool palette as a drag source. Enables all groups and items in the tool palette as drag sources on button 1 and button 3 press with copy and move actions. See `gtk_drag_source_set()`.

#### Parameters

palette | a GtkToolPalette |
targets | the GtkToolPaletteDragTargets which the widget should support |

Since: 2.20

### gtk_tool_palette_get_hadjustment ()

    GtkAdjustment *
    gtk_tool_palette_get_hadjustment (GtkToolPalette *palette);

Gets the horizontal adjustment of the tool palette.

#### Parameters

palette | a GtkToolPalette |

#### Returns

the horizontal adjustment of `palette` .

[transfer none]

Since: 2.20

### gtk_tool_palette_get_vadjustment ()

    GtkAdjustment *
    gtk_tool_palette_get_vadjustment (GtkToolPalette *palette);

Gets the vertical adjustment of the tool palette.

#### Parameters

palette | a GtkToolPalette |

#### Returns

the vertical adjustment of `palette` .

[transfer none]

Since: 2.20

## Types and Values

### struct GtkToolPalette

    struct GtkToolPalette;

This should not be accessed directly. Use the accessor functions below.

### enum GtkToolPaletteDragTargets

Flags used to specify the supported drag targets.

#### Members

GTK_TOOL_PALETTE_DRAG_ITEMS | Support drag of items. |
GTK_TOOL_PALETTE_DRAG_GROUPS | Support drag of groups. |

## Property Details

### The `“icon-size”` property

      “icon-size”                GtkIconSize

The size of the icons in a tool palette is normally determined by the “toolbar-icon-size” setting. When this property is set, it overrides the setting.

This should only be used for special-purpose tool palettes, normal application tool palettes should respect the user preferences for the size of icons.

Owner: GtkToolPalette

Flags: Read / Write

Default value: GTK_ICON_SIZE_SMALL_TOOLBAR

Since: 2.20

### The `“icon-size-set”` property

      “icon-size-set”            gboolean

Is `TRUE` if the “icon-size” property has been set.

Owner: GtkToolPalette

Flags: Read / Write

Default value: FALSE

Since: 2.20

### The `“toolbar-style”` property

      “toolbar-style”            GtkToolbarStyle

The style of items in the tool palette.

Owner: GtkToolPalette

Flags: Read / Write

Default value: GTK_TOOLBAR_ICONS

Since: 2.20

## Child Property Details

### The `“exclusive”` child property

      “exclusive”                gboolean

Whether the item group should be the only one that is expanded at a given time.

Owner: GtkToolPalette

Flags: Read / Write

Default value: FALSE

Since: 2.20

### The `“expand”` child property

      “expand”                   gboolean

Whether the item group should receive extra space when the palette grows. at a given time.

Owner: GtkToolPalette

Flags: Read / Write

Default value: FALSE

Since: 2.20

## Signal Details

### The `“set-scroll-adjustments”` signal

    void
    user_function (GtkToolPalette *widget,
                   GtkAdjustment  *hadjustment,
                   GtkAdjustment  *vadjustment,
                   gpointer        user_data)

Set the scroll adjustments for the viewport. Usually scrolled containers like GtkScrolledWindow will emit this signal to connect two instances of GtkScrollbar to the scroll directions of the GtkToolpalette.

#### Parameters

widget | the GtkToolPalette that received the signal |
hadjustment | The horizontal adjustment |
vadjustment | The vertical adjustment |
user_data | user data set when the signal handler was connected. |

Flags: Action

Since: 2.20