## gimppalette

gimppalette — Functions operating on a single palette.

## Synopsis

    gchar*              gimp_palette_new                    (const gchar *name);
    gchar*              gimp_palette_duplicate              (const gchar *name);
    gchar*              gimp_palette_rename                 (const gchar *name,
                                                             const gchar *new_name);
    gboolean            gimp_palette_delete                 (const gchar *name);
    gboolean            gimp_palette_get_info               (const gchar *name,
                                                             gint *num_colors);
    GimpRGB*            gimp_palette_get_colors             (const gchar *name,
                                                             gint *num_colors);
    gint                gimp_palette_get_columns            (const gchar *name);
    gboolean            gimp_palette_set_columns            (const gchar *name,
                                                             gint columns);
    gboolean            gimp_palette_add_entry              (const gchar *name,
                                                             const gchar *entry_name,
                                                             const GimpRGB *color,
                                                             gint *entry_num);
    gboolean            gimp_palette_delete_entry           (const gchar *name,
                                                             gint entry_num);
    gboolean            gimp_palette_entry_get_color        (const gchar *name,
                                                             gint entry_num,
                                                             GimpRGB *color);
    gboolean            gimp_palette_entry_set_color        (const gchar *name,
                                                             gint entry_num,
                                                             const GimpRGB *color);
    gboolean            gimp_palette_entry_get_name         (const gchar *name,
                                                             gint entry_num,
                                                             gchar **entry_name);
    gboolean            gimp_palette_entry_set_name         (const gchar *name,
                                                             gint entry_num,
                                                             const gchar *entry_name);
    gboolean            gimp_palette_get_foreground         (GimpRGB *foreground);
    gboolean            gimp_palette_get_background         (GimpRGB *background);
    gboolean            gimp_palette_set_foreground         (const GimpRGB *foreground);
    gboolean            gimp_palette_set_background         (const GimpRGB *background);
    gboolean            gimp_palette_set_default_colors     (void);
    gboolean            gimp_palette_swap_colors            (void);
    gboolean            gimp_palette_is_editable            (const gchar *name);

## Description

Functions operating on a single palette.

## Details

### gimp_palette_new ()

    gchar*              gimp_palette_new                    (const gchar *name);

Creates a new palette

This procedure creates a new, uninitialized palette

`name` : | The requested name of the new palette.
Returns : | The actual new palette name.

Since GIMP 2.2

### gimp_palette_duplicate ()

    gchar*              gimp_palette_duplicate              (const gchar *name);

Duplicates a palette

This procedure creates an identical palette by a different name

`name` : | The palette name.
Returns : | The name of the palette's copy.

Since GIMP 2.2

### gimp_palette_rename ()

    gchar*              gimp_palette_rename                 (const gchar *name,
                                                             const gchar *new_name);

Rename a palette

This procedure renames a palette

`name` : | The palette name.
`new_name` : | The new name of the palette.
Returns : | The actual new name of the palette.

Since GIMP 2.2

### gimp_palette_delete ()

    gboolean            gimp_palette_delete                 (const gchar *name);

Deletes a palette

This procedure deletes a palette

`name` : | The palette name.
Returns : | TRUE on success.

Since GIMP 2.2

### gimp_palette_get_info ()

    gboolean            gimp_palette_get_info               (const gchar *name,
                                                             gint *num_colors);

Retrieve information about the specified palette.

This procedure retrieves information about the specified palette. This includes the name, and the number of colors.

`name` : | The palette name.
`num_colors` : | The number of colors in the palette.
Returns : | TRUE on success.

Since GIMP 2.2

### gimp_palette_get_colors ()

    GimpRGB*            gimp_palette_get_colors             (const gchar *name,
                                                             gint *num_colors);

Gets all colors from the specified palette.

This procedure retrieves all color entries of the specified palette.

`name` : | The palette name.
`num_colors` : | Length of the colors array.
Returns : | The colors in the palette.

Since GIMP 2.6

### gimp_palette_get_columns ()

    gint                gimp_palette_get_columns            (const gchar *name);

Retrieves the number of columns to use to display this palette

This procedures retrieves the prefered number of columns to use when the palette is being displayed.

`name` : | The palette name.
Returns : | The number of columns used to display this palette.

Since GIMP 2.4

### gimp_palette_set_columns ()

    gboolean            gimp_palette_set_columns            (const gchar *name,
                                                             gint columns);

Sets the number of columns to use when displaying the palette

This procedures allows to control how many colors are shown per row when the palette is being displayed. This value can only be changed if the palette is writable. The maximum allowed value is 64.

`name` : | The palette name.
`columns` : | The new number of columns.
Returns : | TRUE on success.

Since GIMP 2.4

### gimp_palette_add_entry ()

    gboolean            gimp_palette_add_entry              (const gchar *name,
                                                             const gchar *entry_name,
                                                             const GimpRGB *color,
                                                             gint *entry_num);

Adds a palette entry to the specified palette.

This procedure adds an entry to the specifed palette. It returns an error if the entry palette does not exist.

`name` : | The palette name.
`entry_name` : | The name of the entry.
`color` : | The new entry's color color.
`entry_num` : | The index of the added entry.
Returns : | TRUE on success.

Since GIMP 2.2

### gimp_palette_delete_entry ()

    gboolean            gimp_palette_delete_entry           (const gchar *name,
                                                             gint entry_num);

Deletes a palette entry from the specified palette.

This procedure deletes an entry from the specifed palette. It returns an error if the entry palette does not exist.

`name` : | The palette name.
`entry_num` : | The index of the added entry.
Returns : | TRUE on success.

Since GIMP 2.2

### gimp_palette_entry_get_color ()

    gboolean            gimp_palette_entry_get_color        (const gchar *name,
                                                             gint entry_num,
                                                             GimpRGB *color);

Gets the specified palette entry from the specified palette.

This procedure retrieves the color of the zero-based entry specifed for the specified palette. It returns an error if the entry does not exist.

`name` : | The palette name.
`entry_num` : | The entry to retrieve.
`color` : | The color requested.
Returns : | TRUE on success.

Since GIMP 2.2

### gimp_palette_entry_set_color ()

    gboolean            gimp_palette_entry_set_color        (const gchar *name,
                                                             gint entry_num,
                                                             const GimpRGB *color);

Sets the specified palette entry in the specified palette.

This procedure sets the color of the zero-based entry specifed for the specified palette. It returns an error if the entry does not exist.

`name` : | The palette name.
`entry_num` : | The entry to retrieve.
`color` : | The new color.
Returns : | TRUE on success.

Since GIMP 2.2

### gimp_palette_entry_get_name ()

    gboolean            gimp_palette_entry_get_name         (const gchar *name,
                                                             gint entry_num,
                                                             gchar **entry_name);

Gets the specified palette entry from the specified palette.

This procedure retrieves the name of the zero-based entry specifed for the specified palette. It returns an error if the entry does not exist.

`name` : | The palette name.
`entry_num` : | The entry to retrieve.
`entry_name` : | The name requested.
Returns : | TRUE on success.

Since GIMP 2.2

### gimp_palette_entry_set_name ()

    gboolean            gimp_palette_entry_set_name         (const gchar *name,
                                                             gint entry_num,
                                                             const gchar *entry_name);

Sets the specified palette entry in the specified palette.

This procedure sets the name of the zero-based entry specifed for the specified palette. It returns an error if the entry does not exist.

`name` : | The palette name.
`entry_num` : | The entry to retrieve.
`entry_name` : | The new name.
Returns : | TRUE on success.

Since GIMP 2.2

### gimp_palette_get_foreground ()

    gboolean            gimp_palette_get_foreground         (GimpRGB *foreground);

### Warning

`gimp_palette_get_foreground` is deprecated and should not be used in newly-written code.

Get the current GIMP foreground color.

This procedure retrieves the current GIMP foreground color. The foreground color is used in a variety of tools such as paint tools, blending, and bucket fill.

`foreground` : | The foreground color.
Returns : | TRUE on success.

### gimp_palette_get_background ()

    gboolean            gimp_palette_get_background         (GimpRGB *background);

### Warning

`gimp_palette_get_background` is deprecated and should not be used in newly-written code.

Get the current GIMP background color.

This procedure retrieves the current GIMP background color. The background color is used in a variety of tools such as blending, erasing (with non-alpha images), and image filling.

`background` : | The background color.
Returns : | TRUE on success.

### gimp_palette_set_foreground ()

    gboolean            gimp_palette_set_foreground         (const GimpRGB *foreground);

### Warning

`gimp_palette_set_foreground` is deprecated and should not be used in newly-written code.

Set the current GIMP foreground color.

This procedure sets the current GIMP foreground color. After this is set, operations which use foreground such as paint tools, blending, and bucket fill will use the new value.

`foreground` : | The foreground color.
Returns : | TRUE on success.

### gimp_palette_set_background ()

    gboolean            gimp_palette_set_background         (const GimpRGB *background);

### Warning

`gimp_palette_set_background` is deprecated and should not be used in newly-written code.

Set the current GIMP background color.

This procedure sets the current GIMP background color. After this is set, operations which use background such as blending, filling images, clearing, and erasing (in non-alpha images) will use the new value.

`background` : | The background color.
Returns : | TRUE on success.

### gimp_palette_set_default_colors ()

    gboolean            gimp_palette_set_default_colors     (void);

### Warning

`gimp_palette_set_default_colors` is deprecated and should not be used in newly-written code.

Set the current GIMP foreground and background colors to black and white.

This procedure sets the current GIMP foreground and background colors to their initial default values, black and white.

Returns : | TRUE on success.

### gimp_palette_swap_colors ()

    gboolean            gimp_palette_swap_colors            (void);

### Warning

`gimp_palette_swap_colors` is deprecated and should not be used in newly-written code.

Swap the current GIMP foreground and background colors.

This procedure swaps the current GIMP foreground and background colors, so that the new foreground color becomes the old background color and vice versa.

Returns : | TRUE on success.

### gimp_palette_is_editable ()

    gboolean            gimp_palette_is_editable            (const gchar *name);

Tests if palette can be edited

Returns TRUE if you have permission to change the palette

`name` : | The palette name.
Returns : | TRUE if the palette can be edited.

Since GIMP 2.4