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

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 /*< flags >*/
{
  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 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.

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