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
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkToolPalette

Implemented Interfaces

GtkToolPalette implements AtkImplementorIface, GtkBuildable and GtkOrientable.

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

Signals

  "set-scroll-adjustments"                         : Action

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

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

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

Signal Details

The "set-scroll-adjustments" signal

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

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.

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.

Since 2.20