Gimp/pdb/groups/palette.pdb

# GIMP - The GNU Image Manipulation Program
# Copyright (C) 1995 Spencer Kimball and Peter Mattis

# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3 of the License, or
# (at your option) any later version.

# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.

# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.

# "Perlized" from C source by Manish Singh <yosh@gimp.org>

# The invoke code is compiled on the app side.
# The invoke code must assign to each result var


$palette_arg_spec = { name => 'palette', type => 'palette', non_empty => 1,
  desc => 'The palette' };

sub palette_new {
    $blurb = "Creates a new palette";
    $help = <<'HELP';
Creates a new palette.
The new palette has no color entries.
You must add color entries for a user to choose.
The actual name might be different than the requested name,
when the requested name is already in use.
HELP

    &mitch_pdb_misc('2004', '2.2');

    @inargs = (
      { name => 'name', type => 'string', non_empty => 1,
        desc => 'The requested name of the new palette' }
    );

    @outargs = (
    	${palette_arg_spec}
    );

    %invoke = (
        code => <<'CODE'
{
  palette = (GimpPalette*) gimp_data_factory_data_new (gimp->palette_factory,
                                                       context, name);
}
CODE
    );
}

sub palette_get_by_name {
    $blurb = "Returns the palette with the given name.";
    $help  = "Returns the palette with the given name.";

    &mitch_pdb_misc('2023', '3.0');

    @inargs = (
      { name => 'name', type => 'string', non_empty => 1,
        desc => 'The name of the palette' }
    );

    @outargs = (
      { name => 'palette', type => 'palette', non_empty => 1,
        desc => 'The palette' }
    );

    %invoke = (
        code => <<'CODE'
{
  palette = gimp_pdb_get_palette (gimp, name, GIMP_PDB_DATA_ACCESS_READ, error);

  if (! palette)
    success = FALSE;
}
CODE
    );
}

sub palette_is_editable {
    $blurb = "Whether the palette can be edited";
    $help  = "Returns TRUE if you have permission to change the palette";

    &bill_pdb_misc('2004', '2.4');

    @inargs = (
      ${palette_arg_spec}
    );

    @outargs = (
      { name => 'editable', type => 'boolean',
        desc => "TRUE if the palette can be edited" }
    );

    %invoke = (
        code => <<'CODE'
{
  editable = gimp_data_is_writable (GIMP_DATA (palette));
}
CODE
    );
}

sub palette_duplicate {
    $blurb = "Duplicates a palette";
    $help  = "Returns a copy having a different, unique ID.";

    &mitch_pdb_misc('2004', '2.2');

    @inargs = (
        ${palette_arg_spec}
    );

    @outargs = (
        { name => 'palette_copy',
          type => 'palette',
          desc => "A copy of the palette." }
    );

    %invoke = (
        code => <<'CODE'
{
  palette_copy = (GimpPalette *)
    gimp_data_factory_data_duplicate (gimp->palette_factory, GIMP_DATA (palette));
  /* Assert the copy has a unique name. */
  if (!palette_copy)
    success = FALSE;
}
CODE
    );
}

sub palette_rename {
    $blurb = "Rename a palette";
    $help = <<'HELP';
Renames a palette.  The name is the same as the ID.
When the proposed name is already used, GIMP generates a unique name,
which get_id() will return.

Returns a reference to a renamed palette, which you should assign
to the original var or a differently named var.
Any existing references will be invalid.
Resources in plugins are proxies holding an ID,
which can be invalid when the resource is renamed.
HELP

    &mitch_pdb_misc('2004', '2.2');

    @inargs = (
        ${palette_arg_spec},
        { name => 'new_name', type => 'string', non_empty => 1,
          desc => "The requested new name of the palette" }
    );

    @outargs = (
        { name => 'palette_renamed',
          type => 'palette',
          desc => "A reference to the renamed palette." }
        );

    %invoke = (
	code => <<'CODE'
{
  /* Rename the palette in app. */
  gimp_object_set_name (GIMP_OBJECT (palette), new_name);
  /* Assert GIMP might have set a name different from new_name. */

  /* Return a reference.
   * The wire protocol will create a new proxy on the plugin side.
   * We don't need an alias here, except to make clear
   * that we are returning the same real object as passed.
   */
   palette_renamed = palette;
}
CODE
    );
}

sub palette_delete {
    $blurb = "Deletes a palette";
    $help = <<'HELP';
Deletes a palette.  Returns an error if the palette is not deletable.
Deletes the palette's data.  You should not use the palette afterwards.
HELP

    &mitch_pdb_misc('2004', '2.2');

    @inargs = (
      ${palette_arg_spec}
    );

    %invoke = (
	code => <<'CODE'
{
  if (palette && gimp_data_is_deletable (GIMP_DATA (palette)))
    success = gimp_data_factory_data_delete (gimp->palette_factory,
                                             GIMP_DATA (palette),
                                             TRUE, error);
  else
    success = FALSE;
}
CODE
    );
}

# When returns a single value, omit:  void_ret => 1,

sub palette_get_color_count {
    $blurb = 'Get the count of colors in the palette.';

    $help = 'Returns the number of colors in the palette.';

    &mitch_pdb_misc('2004', '2.2');

    @inargs = (
      ${palette_arg_spec}
    );
    @outargs = (
        { name => 'num_colors', type => 'int32',
          desc => 'The number of colors in the palette' }
    );

    %invoke = (
	code => <<'CODE'
{
  num_colors = gimp_palette_get_n_colors (palette);
}
CODE
    );
}

sub palette_get_colors {
    $blurb = 'Gets colors in the palette.';

    $help = "Returns an array of colors in the palette.";

    &neo_pdb_misc('2006', '2.6');

    @inargs = (
        ${palette_arg_spec}
    );

    @outargs = (
    	{ name => 'colors', type => 'colorarray',
        desc => 'The colors in the palette',
        array => { name => 'num_colors',
                   desc => 'Length of the colors array' } }
    );

    %invoke = (
	code => <<'CODE'
{
  GList *list = gimp_palette_get_colors (palette);
  gint   i;

  num_colors = gimp_palette_get_n_colors (palette);
  colors     = g_new (GimpRGB, num_colors);

  for (i = 0; i < num_colors; i++, list = g_list_next (list))
    {
      GimpPaletteEntry *entry = list->data;

      colors[i] = entry->color;
    }
}
CODE
    );
}

sub palette_get_columns {
    $blurb = "Gets the number of columns used to display the palette";
    $help = "Gets the preferred number of columns to display the palette.";

    &neo_pdb_misc('2005', '2.4');

    @inargs = (
        ${palette_arg_spec}
    );

    @outargs = (
        { name => 'num_columns', type => 'int32',
          desc => "The number of columns used to display this palette" }
    );

    %invoke = (
	code => <<'CODE'
{
  num_columns = gimp_palette_get_columns (palette);
}
CODE
    );
}

sub palette_set_columns {
    $blurb = "Sets the number of columns used to display the palette";
    $help = <<'HELP';
Set the number of colors shown per row when the palette is displayed.
Returns an error when the palette is not editable.
The maximum allowed value is 64.
HELP

    &neo_pdb_misc('2005', '2.4');

    @inargs = (
        ${palette_arg_spec},
        { name => 'columns', type => '0 <= int32 <= 64',
          desc => "The new number of columns" }
    );

    %invoke = (
	code => <<'CODE'
{
  if (gimp_data_is_writable (GIMP_DATA (palette)))
    gimp_palette_set_columns (palette, columns);
  else
    success = FALSE;
}
CODE
    );
}


# FIXME null_ok should allow None in Python for name, but fails.

sub palette_add_entry {
    $blurb = 'Appends an entry to the palette.';

    $help = <<'HELP';
Appends an entry to the palette.
Neither color nor name must be unique within the palette.
When name is the empty string, this sets the entry name to "Untitled".
Returns the index of the entry.
Returns an error when palette is not editable.
HELP

    &mitch_pdb_misc('2004', '2.2');

    @inargs = (
        ${palette_arg_spec},
        { name => 'entry_name', type => 'string', null_ok => 1,
          desc => 'A name for the entry' },
        { name => 'color', type => 'color',
          desc => 'The color for the added entry.' }
    );

    @outargs = (
        { name => 'entry_num', type => 'int32', void_ret => 1,
          desc => 'The index of the added entry' }
    );

    %invoke = (
	code => <<'CODE'
{
  /* Must check writeable here, because add_entry does not fail when not writeable. */
  if (gimp_data_is_writable (GIMP_DATA (palette)))
    {
      /* -1 for the index means append. */
      GimpPaletteEntry *entry = gimp_palette_add_entry (palette, -1, entry_name, &color);

      entry_num = gimp_palette_get_entry_position (palette, entry);
    }
  else
    {
      success = FALSE;
    }
}
CODE
    );
}

sub palette_delete_entry {
    $blurb = 'Deletes an entry from the palette.';

    $help = <<'HELP';
Deletes an entry from the palette.
Returns an error if the index is out or range.
Returns an error if the palette is not editable.
HELP

    &mitch_pdb_misc('2004', '2.2');

    @inargs = (
        ${palette_arg_spec},
        { name => 'entry_num', type => 'int32',
          desc => 'The index of the entry to delete' }
    );

    %invoke = (
	code => <<'CODE'
{
  if (gimp_data_is_writable (GIMP_DATA (palette)))
    {
      GimpPaletteEntry *entry = gimp_palette_get_entry (palette, entry_num);

      if (entry)
        gimp_palette_delete_entry (palette, entry);
      else
        success = FALSE;
    }
  else
    success = FALSE;
}
CODE
    );
}

sub palette_entry_get_color {
    $blurb = 'Gets the color of an entry in the palette.';

    $help = <<'HELP';
Returns the color of the entry at the given zero-based index into the palette.
Returns an error when the index is out of range.
HELP

    &mitch_pdb_misc('2004', '2.2');

    @inargs = (
        ${palette_arg_spec},
        { name => 'entry_num', type => 'int32',
          desc => 'The index of the entry to get the color of.' }
    );

    @outargs = (
        { name => 'color', type => 'color', void_ret => 1,
          desc => 'The color at the index.' }
    );

    %invoke = (
	code => <<'CODE'
{
  GimpPaletteEntry *entry = gimp_palette_get_entry (palette, entry_num);

  if (entry)
    color = entry->color;
  else
    success = FALSE;
}
CODE
    );
}

sub palette_entry_set_color {
    $blurb = 'Sets the color of an entry in the palette.';

    $help = <<'HELP';
Sets the color of the entry at the zero-based index into the palette.
Returns an error when the index is out of range.
Returns an error when the palette is not editable.
HELP

    &mitch_pdb_misc('2004', '2.2');

    @inargs = (
        ${palette_arg_spec},
        { name => 'entry_num', type => 'int32',
          desc => 'The entry to get' },
        { name => 'color', type => 'color',
          desc => 'The new color' }
    );

    %invoke = (
	code => <<'CODE'
{
  if (gimp_data_is_writable (GIMP_DATA (palette)))
    success = gimp_palette_set_entry_color (palette, entry_num, &color);
  else
    success = FALSE;
}
CODE
    );
}

sub palette_entry_get_name {
    $blurb = 'Gets the name of an entry in the palette.';

    $help = <<'HELP';
Gets the name of the entry at the zero-based index into the palette.
Returns an error when the index is out of range.
HELP

    &mitch_pdb_misc('2004', '2.2');

    @inargs = (
        ${palette_arg_spec},
        { name => 'entry_num', type => 'int32',
          desc => 'The entry to get' }
    );

    @outargs = (
        { name => 'entry_name', type => 'string', void_ret => 1,
          desc => 'The name of the entry.' }
    );

    %invoke = (
	code => <<'CODE'
{
  GimpPaletteEntry *entry = gimp_palette_get_entry (palette, entry_num);

  if (entry)
    entry_name = g_strdup (entry->name);
  else
    success = FALSE;
}
CODE
    );
}

sub palette_entry_set_name {
    $blurb = 'Sets the name of an entry in the palette.';

    $help = <<'HELP';
Sets the name of the entry at the zero-based index into the palette.
Returns an error if the index is out or range.
Returns an error if the palette is not editable.
HELP

    &mitch_pdb_misc('2004', '2.2');

    @inargs = (
        ${palette_arg_spec},
        { name => 'entry_num', type => 'int32',
          desc => 'The entry to get' },
        { name => 'entry_name', type => 'string', null_ok => 1,
          desc => 'The new name' }
    );

    %invoke = (
	code => <<'CODE'
{
  if (gimp_data_is_writable (GIMP_DATA (palette)))
    success = gimp_palette_set_entry_name (palette, entry_num, entry_name);
  else
    success = FALSE;
}
CODE
    );
}


@headers = qw(<string.h>
              "core/gimp.h"
              "core/gimpcontext.h"
              "core/gimpdatafactory.h"
              "core/gimppalette.h"
              "gimppdb-utils.h");

@procs = qw(palette_new
            palette_get_by_name
            palette_duplicate
            palette_rename
            palette_delete
            palette_is_editable
            palette_get_color_count
            palette_get_colors
            palette_get_columns palette_set_columns
            palette_add_entry palette_delete_entry
            palette_entry_get_color palette_entry_set_color
            palette_entry_get_name palette_entry_set_name);

%exports = (app => [@procs], lib => [@procs]);

$desc = 'Palette';
$doc_title = 'gimppalette';
$doc_short_desc = 'Installable object, a small set of colors a user can choose from.';
$doc_long_desc = 'Installable object, a small set of colors a user can choose from.';

1;