GTK+ 3 Reference Manual: GtkToolPalette

## GtkToolPalette GtkToolPalette — A tool palette with categories |

## Synopsis

    #include <gtk/gtk.h>

    struct              GtkToolPalette;
    GtkWidget *         gtk_tool_palette_new                (void);
    gboolean            gtk_tool_palette_get_exclusive      (GtkToolPalette *palette,
                                                             GtkToolItemGroup *group);
    void                gtk_tool_palette_set_exclusive      (GtkToolPalette *palette,
                                                             GtkToolItemGroup *group,
                                                             gboolean exclusive);
    gboolean            gtk_tool_palette_get_expand         (GtkToolPalette *palette,
                                                             GtkToolItemGroup *group);
    void                gtk_tool_palette_set_expand         (GtkToolPalette *palette,
                                                             GtkToolItemGroup *group,
                                                             gboolean expand);
    gint                gtk_tool_palette_get_group_position (GtkToolPalette *palette,
                                                             GtkToolItemGroup *group);
    void                gtk_tool_palette_set_group_position (GtkToolPalette *palette,
                                                             GtkToolItemGroup *group,
                                                             gint position);
    GtkIconSize         gtk_tool_palette_get_icon_size      (GtkToolPalette *palette);
    void                gtk_tool_palette_set_icon_size      (GtkToolPalette *palette,
                                                             GtkIconSize icon_size);
    void                gtk_tool_palette_unset_icon_size    (GtkToolPalette *palette);
    GtkToolbarStyle     gtk_tool_palette_get_style          (GtkToolPalette *palette);
    void                gtk_tool_palette_set_style          (GtkToolPalette *palette,
                                                             GtkToolbarStyle style);
    void                gtk_tool_palette_unset_style        (GtkToolPalette *palette);
    void                gtk_tool_palette_add_drag_dest      (GtkToolPalette *palette,
                                                             GtkWidget *widget,
                                                             GtkDestDefaults flags,
                                                             GtkToolPaletteDragTargets targets,
                                                             GdkDragAction actions);
    GtkWidget *         gtk_tool_palette_get_drag_item      (GtkToolPalette *palette,
                                                             const GtkSelectionData *selection);
    const GtkTargetEntry * gtk_tool_palette_get_drag_target_group
                                                            (void);
    const GtkTargetEntry * gtk_tool_palette_get_drag_target_item
                                                            (void);
    GtkToolItemGroup *  gtk_tool_palette_get_drop_group     (GtkToolPalette *palette,
                                                             gint x,
                                                             gint y);
    GtkToolItem *       gtk_tool_palette_get_drop_item      (GtkToolPalette *palette,
                                                             gint x,
                                                             gint y);
    enum                GtkToolPaletteDragTargets;
    void                gtk_tool_palette_set_drag_source    (GtkToolPalette *palette,
                                                             GtkToolPaletteDragTargets targets);
    GtkAdjustment *     gtk_tool_palette_get_hadjustment    (GtkToolPalette *palette);
    GtkAdjustment *     gtk_tool_palette_get_vadjustment    (GtkToolPalette *palette);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkWidget
                   +----GtkContainer
                         +----GtkToolPalette

## Implemented Interfaces

GtkToolPalette implements AtkImplementorIface, GtkBuildable, GtkOrientable and GtkScrollable.

## Properties

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

## Child Properties

      "exclusive"                gboolean              : Read / Write
      "expand"                   gboolean              : Read / Write

## 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
    10
    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_new (NULL, _("_Open"));
    gtk_tool_button_set_icon_name (GTK_TOOL_BUTTON (item), "document-open");
    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);

## Details

### struct GtkToolPalette

    struct GtkToolPalette;

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

### 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()`.

`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.

`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()`.

`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.

`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()`.

`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.

`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()`.

`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.

`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.

`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.

`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.

`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.

`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()`.

`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.

`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).

`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()`.

`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

### enum GtkToolPaletteDragTargets

    typedef enum {
      GTK_TOOL_PALETTE_DRAG_ITEMS = (1 << 0),
      GTK_TOOL_PALETTE_DRAG_GROUPS = (1 << 1)
    } GtkToolPaletteDragTargets;

Flags used to specify the supported drag targets.

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

### 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()`.

`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);

### Warning

`gtk_tool_palette_get_hadjustment` has been deprecated since version 3.0 and should not be used in newly-written code. Use `gtk_scrollable_get_hadjustment()`

Gets the horizontal adjustment of the tool palette.

`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);

### Warning

`gtk_tool_palette_get_vadjustment` has been deprecated since version 3.0 and should not be used in newly-written code. Use `gtk_scrollable_get_vadjustment()`

Gets the vertical adjustment of the tool palette.

`palette` : | a GtkToolPalette
Returns : | the vertical adjustment of `palette`. [transfer none]

Since 2.20

## Property Details

### The `"icon-size"` property

      "icon-size"                GtkIconSize           : Read / Write

The size of the icons in a tool palette. When this property is set, it overrides the default 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.

Default value: GTK_ICON_SIZE_SMALL_TOOLBAR

Since 2.20

### The `"icon-size-set"` property

      "icon-size-set"            gboolean              : Read / Write

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

Default value: FALSE

Since 2.20

### The `"toolbar-style"` property

      "toolbar-style"            GtkToolbarStyle       : Read / Write

The style of items in the tool palette.

Default value: GTK_TOOLBAR_ICONS

Since 2.20

## Child Property Details

### The `"exclusive"` child property

      "exclusive"                gboolean              : Read / Write

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

Default value: FALSE

Since 2.20

### The `"expand"` child property

      "expand"                   gboolean              : Read / Write

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

Default value: FALSE

Since 2.20