PIKApp/pdb/groups/text_layer.pdb

# PIKA - Photo and Image Kooker Application
# Copyright (C) 1995 Spencer Kimball and Peter Mattis

# New Text PDB API
# Copyright (C) 2008 Marcus Heese <heese@cip.ifi.lmu.de>

# 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/>.


sub text_layer_new {
    $blurb = 'Creates a new text layer.';

    $help = <<'HELP';
This procedure creates a new text layer. The arguments are kept as
simple as necessary for the normal case. All text attributes, however,
can be modified with the appropriate pika_text_layer_set_*()
procedures. The new layer still needs to be added to the image, as
this is not automatic. Add the new layer using pika_image_insert_layer().
HELP

    &marcus_pdb_misc('2008', '2.6');

    $lib_private = 1;

    @inargs = (
        { name => 'image', type => 'image',
          desc => 'The image' },
        { name => 'text', type => 'string',
          desc => 'The text to generate (in UTF-8 encoding)' },
        { name => 'font', type => 'font',
          desc => 'The font to write the text with' },
        { name => 'size', type => '0.0 <= float <= 8192.0',
          desc => 'The size of text in either pixels or points' },
        { name => 'unit', type => 'unit',
          desc => 'The units of specified size' }
    );

    @outargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The new text layer.' }
    );

    %invoke = (
        code => <<'CODE'
{
  PikaText *pika_text;
  PikaRGB   color;

  pika_context_get_foreground (context, &color);
  
  pika_text = g_object_new (PIKA_TYPE_TEXT,
                            "text",           text,
                            "font",           font,
                            "font-size",      size,
                            "font-size-unit", unit,
                            "color",          &color,
                            NULL);
  
  layer = PIKA_TEXT_LAYER (pika_text_layer_new (image, pika_text));
  g_object_unref (pika_text);

  if (! layer)
    {
      g_set_error (error, PIKA_PDB_ERROR, PIKA_PDB_ERROR_INVALID_ARGUMENT,
                   _("Failed to create text layer"));

      success = FALSE;
    }
}
CODE
    );
}

sub text_layer_get_text {
    $blurb = 'Get the text from a text layer as string.';

    $help = <<'HELP';
This procedure returns the text from a text layer as a string.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' }
    );

    @outargs = (
        { name => 'text', type => 'string',
          desc => 'The text from the specified text layer.' }
    );
    
    %invoke = (
        code => <<'CODE'
{
  g_object_get (pika_text_layer_get_text (layer),
                "text", &text,
                NULL);
}
CODE
    );
}

sub text_layer_set_text {
    $blurb = 'Set the text of a text layer.';

    $help = <<'HELP';
This procedure changes the text of a text layer.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' },
        { name => 'text', type => 'string',
          desc => 'The new text to set' }
    );

    %invoke = (
        code => <<'CODE'
{
  pika_text_layer_set (layer,
                       _("Set text layer attribute"),
                       "text", text,
                       NULL);
}
CODE
    );
}

sub text_layer_get_markup {
    $blurb = 'Get the markup from a text layer as string.';

    $help = <<'HELP';
This procedure returns the markup of the styles from a text layer.
The markup will be in the form of Pango's markup - See
https://www.pango.org/ for more information about Pango and its markup.
HELP

    barak_pdb_misc('2010', '2.8');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' }
    );

    @outargs = (
        { name => 'markup', type => 'string',
          desc => 'The markup which represents the style of the specified text layer.' }
    );
    
    %invoke = (
        code => <<'CODE'
{
  g_object_get (pika_text_layer_get_text (layer),
                "markup", &markup,
                NULL);
}
CODE
    );
}

sub text_layer_set_markup {
    $blurb = 'Set the markup for a text layer from a string.';

    $help = <<'HELP';
This procedure sets the markup of the styles for a text layer.
The markup should be in the form of Pango's markup - See
https://docs.gtk.org/Pango/pango_markup.html for a reference.

Note that PIKA's text tool does not support all of Pango markup. Any unsupported
markup will still be applied to your text layer, yet would be dropped as soon as
you edit text with the tool.
HELP

    $author = 'Ian Munsie <darkstarsword@gmail.com>';
    $copyright = 'Ian Munsie';
    $date = '2014';
    $since = '3.0';

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' },
        { name => 'markup', type => 'string',
          desc => 'The new markup to set' }
    );

    %invoke = (
        code => <<'CODE'
{
  gchar *markup_cat = NULL;
  const gchar *markup_ptr = markup;

  if (strstr(markup, "<markup>") == NULL || strstr(markup, "</markup>") == NULL)
    {
      markup_cat = g_strconcat("<markup>", markup, "</markup>", NULL);
      markup_ptr = markup_cat;
    }

  if (pango_parse_markup (markup_ptr, -1, 0, NULL, NULL, NULL, error))
    {
      pika_text_layer_set (layer,
                           _("Set text layer markup"),
                           "markup", markup_ptr,
                           NULL);
    }
  else
    {
      success = FALSE;
    }

  g_free(markup_cat);
}
CODE
    );
}

sub text_layer_get_font {
    $blurb = 'Get the font from a text layer as string.';

    $help = <<'HELP';
This procedure returns the font from a text layer.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' }
    );

    @outargs = (
        { name => 'font', type => 'font',
          desc => 'The font which is used in the specified text layer.' }
    );
    
    %invoke = (
        code => <<'CODE'
{
  g_object_get (pika_text_layer_get_text (layer),
                "font", &font,
                NULL);
  /* The PikaText keeps a reference. Therefore unref before returning the
   * pointer so that we don't leak a reference.
   */
  g_object_unref (font);
}
CODE
    );
}

sub text_layer_set_font {
    $blurb = 'Set the font of a text layer.';

    $help = <<'HELP';
This procedure modifies the font used in the specified text layer.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' },
        { name => 'font', type => 'font',
          desc => 'The new font to use' }
    );

    %invoke = (
        code => <<'CODE'
{
  pika_text_layer_set (layer,
                       _("Set text layer attribute"),
                       "font", font,
                       NULL);
}
CODE
    );
}

sub text_layer_get_font_size {
    $blurb = 'Get the font size from a text layer.';

    $help = <<'HELP';
This procedure returns the size of the font which is used in a text
layer. You will receive the size as a float 'font-size' in 'unit'
units.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' }
    );

    @outargs = (
        { name => 'font_size', type => 'float',
          desc => 'The font size' },
        { name => 'unit', type => 'unit',
          desc => 'The unit used for the font size' }
    );
    
    %invoke = (
        code => <<'CODE'
{
   g_object_get (pika_text_layer_get_text (layer),
                 "font-size",      &font_size,
                 "font-size-unit", &unit,
                 NULL);
}
CODE
    );
}

sub text_layer_set_font_size {
    $blurb = 'Set the font size.';

    $help = <<'HELP';
This procedure changes the font size of a text layer. The size of your
font will be a double 'font-size' of 'unit' units.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' },
        { name => 'font_size', type => '0.0 <= float <= 8192.0',
          desc => 'The font size' },
        { name => 'unit', type => 'unit',
          desc => 'The unit to use for the font size' }
    );

    %invoke = (
        code => <<'CODE'
{
  pika_text_layer_set (layer,
                       _("Set text layer attribute"),
                       "font-size-unit", unit,
                       "font-size",      font_size,
                       NULL);
}
CODE
    );
}

sub text_layer_get_antialias {
    $blurb = 'Check if antialiasing is used in the text layer.';

    $help = <<'HELP';
This procedure checks if antialiasing is enabled in the specified text layer.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' }
    );

    @outargs = (
        { name => 'antialias', type => 'boolean',
          desc => 'A flag which is true if antialiasing is used for rendering the font in the text layer.' }
    );

    %invoke = (
        code => <<'CODE'
{
  g_object_get (pika_text_layer_get_text (layer),
                "antialias", &antialias,
                NULL);
}
CODE
    );
}

sub text_layer_set_antialias {
    $blurb = 'Enable/disable anti-aliasing in a text layer.';

    $help = <<'HELP';
This procedure enables or disables anti-aliasing of the text in a text layer.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' },
        { name => 'antialias', type => 'boolean',
          desc => 'Enable/disable antialiasing of the text' }
    );

    %invoke = (
        code => <<'CODE'
{
  pika_text_layer_set (layer,
                       _("Set text layer attribute"),
                       "antialias", antialias,
                       NULL);
}
CODE
    );
}

sub text_layer_get_hint_style {
    $blurb = 'Get information about hinting in the specified text layer.';

    $help = <<'HELP';
This procedure provides information about the hinting that is being
used in a text layer. Hinting can be optimized for fidelity or contrast
or it can be turned entirely off.
HELP

    &marcus_pdb_misc('2008', '2.8');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' }
    );

    @outargs = (
        { name => 'style', type => 'enum PikaTextHintStyle',
          desc => 'The hint style used for font outlines' }
    );
    
    %invoke = (
        code => <<'CODE'
{
  g_object_get (pika_text_layer_get_text (layer),
                "hint-style", &style,
                NULL);
}
CODE
    );
}

sub text_layer_set_hint_style {
    $blurb = 'Control how font outlines are hinted in a text layer.';

    $help = <<'HELP';
This procedure sets the hint style for font outlines in a text
layer. This controls whether to fit font outlines to the pixel grid,
and if so, whether to optimize for fidelity or contrast.
HELP

    &neo_pdb_misc('2008', '2.8');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' },
        { name => 'style', type => 'enum PikaTextHintStyle',
          desc => 'The new hint style' }
    );

    %invoke = (
        code => <<'CODE'
{
  pika_text_layer_set (layer,
                       _("Set text layer attribute"),
                       "hint-style", style,
                       NULL);
}
CODE
    );
}

sub text_layer_get_kerning {
    $blurb = 'Check if kerning is used in the text layer.';

    $help = <<'HELP';
This procedure checks if kerning is enabled in the specified text layer.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' }
    );

    @outargs = (
        { name => 'kerning', type => 'boolean',
          desc => 'A flag which is true if kerning is used in the text layer.' }
    );

    %invoke = (
        code => <<'CODE'
{
  g_object_get (pika_text_layer_get_text (layer),
                "kerning", &kerning,
                NULL);
}
CODE
    );
}

sub text_layer_set_kerning {
    $blurb = 'Enable/disable kerning in a text layer.';

    $help = <<'HELP';
This procedure enables or disables kerning in a text layer.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' },
        { name => 'kerning', type => 'boolean',
          desc => 'Enable/disable kerning in the text' }
    );

    %invoke = (
        code => <<'CODE'
{
  pika_text_layer_set (layer,
                       _("Set text layer attribute"),
                       "kerning", kerning,
                       NULL);
}
CODE
    );
}

sub text_layer_get_language {
    $blurb = 'Get the language used in the text layer.';

    $help = <<'HELP';
This procedure returns the language string which is set for the text
in the text layer.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer.' }
    );

    @outargs = (
        { name => 'language', type => 'string',
          desc => 'The language used in the text layer.' }
    );

    %invoke = (
        code => <<'CODE'
{
  g_object_get (pika_text_layer_get_text (layer),
                "language", &language,
                NULL);
}
CODE
    );
}

sub text_layer_set_language {
    $blurb = 'Set the language of the text layer.';

    $help = <<'HELP';
This procedure sets the language of the text in text layer. For some
scripts the language has an influence of how the text is rendered.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' },
        { name => 'language', type => 'string',
          desc => 'The new language to use for the text layer' }
    );

    %invoke = (
        code => <<'CODE'
{
  pika_text_layer_set (layer,
                       _("Set text layer attribute"),
                       "language", language,
                       NULL);
}
CODE
    );
}

sub text_layer_get_base_direction {
    $blurb = 'Get the base direction used for rendering the text layer.';

    $help = <<'HELP';
This procedure returns the base direction used for rendering the text
in the text layer
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer.' }
    );

    @outargs = (
        { name => 'direction', type => 'enum PikaTextDirection',
          desc => 'The based direction used for the text layer.' }
    );

    %invoke = (
        code => <<'CODE'
{
  g_object_get (pika_text_layer_get_text (layer),
                "base-direction", &direction,
                NULL);
}
CODE
    );
}

sub text_layer_set_base_direction {
    $blurb = 'Set the base direction in the text layer.';

    $help = <<'HELP';
This procedure sets the base direction used in applying the Unicode
bidirectional algorithm when rendering the text.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' },
        { name => 'direction', type => 'enum PikaTextDirection',
          desc => 'The base direction of the text.' }
    );

    %invoke = (
        code => <<'CODE'
{
  pika_text_layer_set (layer,
                       _("Set text layer attribute"),
                       "base-direction", direction,
                       NULL);
}
CODE
    );
}

sub text_layer_get_justification {
    $blurb = 'Get the text justification information of the text layer.';

    $help = <<'HELP';
This procedure returns the alignment of the lines in the text layer
relative to each other.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer.' }
    );

    @outargs = (
        { name => 'justify', type => 'enum PikaTextJustification',
          desc => 'The justification used in the text layer.' }
    );

    %invoke = (
        code => <<'CODE'
{
  g_object_get (pika_text_layer_get_text (layer),
                "justify", &justify,
                NULL);
}
CODE
    );
}

sub text_layer_set_justification {
    $blurb = 'Set the justification of the text in a text layer.';

    $help = <<'HELP';
This procedure sets the alignment of the lines in the text layer
relative to each other.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' },
        { name => 'justify', type => 'enum PikaTextJustification',
          desc => 'The justification for your text.' }
    );

    %invoke = (
        code => <<'CODE'
{
  pika_text_layer_set (layer,
                       _("Set text layer attribute"),
                       "justify", justify,
                       NULL);
}
CODE
    );
}

sub text_layer_get_color {
    $blurb = 'Get the color of the text in a text layer.';

    $help = <<'HELP';
This procedure returns the color of the text in a text layer.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer.' }
    );

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

    %invoke = (
        code => <<'CODE'
{
  color = pika_text_layer_get_text (layer)->color;
}
CODE
    );
}

sub text_layer_set_color {
    $blurb = 'Set the color of the text in the text layer.';

    $help = <<'HELP';
This procedure sets the text color in the text layer 'layer'.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' },
        { name => 'color', type => 'color',
          desc => 'The color to use for the text' }
    );

    %invoke = (
        code => <<'CODE'
{
  pika_text_layer_set (layer,
                       _("Set text layer attribute"),
                       "color", &color,
                       NULL);
}
CODE
    );
}

sub text_layer_get_indent {
    $blurb = 'Get the line indentation of text layer.';

    $help = <<'HELP';
This procedure returns the indentation of the first line in a text layer.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer.' }
    );

    @outargs = (
        { name => 'indent', type => 'float',
          desc => 'The indentation value of the first line.' }
    );

    %invoke = (
        code => <<'CODE'
{
  g_object_get (pika_text_layer_get_text (layer),
                "indent", &indent,
                NULL);
}
CODE
    );
}

sub text_layer_set_indent {
    $blurb = 'Set the indentation of the first line in a text layer.';

    $help = <<'HELP';
This procedure sets the indentation of the first line in the text layer.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' },
        { name => 'indent', type => '-8192.0 <= float <= 8192.0',
          desc => 'The indentation for the first line.' }
     );

     %invoke = (
         code => <<'CODE'
{
  pika_text_layer_set (layer,
                       _("Set text layer attribute"),
                       "indent", indent,
                       NULL);
}
CODE
    );
}

sub text_layer_get_line_spacing {
    $blurb = 'Get the spacing between lines of text.';

    $help = <<'HELP';
This procedure returns the line-spacing between lines of text in a text layer.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer.' }
    );

    @outargs = (
        { name => 'line_spacing', type => 'float',
          desc => 'The line-spacing value.' }
    );

    %invoke = (
        code => <<'CODE'
{
  g_object_get (pika_text_layer_get_text (layer),
                "line-spacing", &line_spacing,
                NULL);
}
CODE
    );
}

sub text_layer_set_line_spacing {
    $blurb = 'Adjust the line spacing in a text layer.';

    $help = <<'HELP';
This procedure sets the additional spacing used between lines a text layer.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' },
        { name => 'line_spacing', type => '-8192.0 <= float <= 8192.0',
          desc => 'The additional line spacing to use.' }
    );

    %invoke = (
        code => <<'CODE'
{
  pika_text_layer_set (layer,
                       _("Set text layer attribute"),
                       "line-spacing", line_spacing,
                       NULL);
}
CODE
    );
}

sub text_layer_get_letter_spacing {
    $blurb = 'Get the letter spacing used in a text layer.';

    $help = <<'HELP';
This procedure returns the additional spacing between the single glyphs
in a text layer.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer.' }
    );

    @outargs = (
        { name => 'letter_spacing', type => 'float',
          desc => 'The letter-spacing value.' }
    );

    %invoke = (
        code => <<'CODE'
{
  g_object_get (pika_text_layer_get_text (layer),
                "letter-spacing", &letter_spacing,
                NULL);
}
CODE
    );
}

sub text_layer_set_letter_spacing {
    $blurb = 'Adjust the letter spacing in a text layer.';

    $help = <<'HELP';
This procedure sets the additional spacing between the single glyphs
in a text layer.
HELP

    &marcus_pdb_misc('2008', '2.6');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' },
        { name => 'letter_spacing', type => '-8192.0 <= float <= 8192.0',
          desc => 'The additional letter spacing to use.' }
    );
    
    %invoke = (    
        code => <<'CODE'
{
  pika_text_layer_set (layer,
                       _("Set text layer attribute"),
                       "letter-spacing", letter_spacing,
                       NULL);
}
CODE
    );
}

sub text_layer_resize {
    $blurb = 'Resize the box of a text layer.';

    $help = <<'HELP';
This procedure changes the width and height of a text layer while
keeping it as a text layer and not converting it to a bitmap like
pika_layer_resize() would do.
HELP

    barak_pdb_misc('2009', '2.8');

    @inargs = (
        { name => 'layer', type => 'text_layer',
          desc => 'The text layer' },
        { name => 'width', type => '0.0 <= float <= PIKA_MAX_IMAGE_SIZE',
          desc => 'The new box width in pixels' },
        { name => 'height', type => '0.0 <= float <= PIKA_MAX_IMAGE_SIZE',
          desc => 'The new box height in pixels' },
    );

    %invoke = (
        code => <<'CODE'
{
  PikaText *text = pika_text_layer_get_text (layer);
  gdouble   xres, yres;

  pika_image_get_resolution (pika_item_get_image (PIKA_ITEM (layer)),
                             &xres, &yres);

  pika_text_layer_set (layer,
                       _("Set text layer attribute"),
                       "box-mode",   PIKA_TEXT_BOX_FIXED,
                       "box-width",  pika_pixels_to_units (width,
                                                           text->box_unit,
                                                           xres),
                       "box-height", pika_pixels_to_units (height,
                                                           text->box_unit,
                                                           yres),
                       NULL);
}
CODE
    );
}


@headers = qw(<pango/pango.h>
              "libpikabase/pikabase.h"
              "core/pikacontext.h"
              "text/pikafont.h"
              "text/pikatext.h"
              "text/pikatextlayer.h"
              "pikapdb-utils.h"
              "pikapdberror.h"
              "pika-intl.h");

@procs = qw(text_layer_new
            text_layer_get_text
            text_layer_set_text
            text_layer_get_markup
            text_layer_set_markup
            text_layer_get_font
            text_layer_set_font
            text_layer_get_font_size
            text_layer_set_font_size
            text_layer_get_antialias
            text_layer_set_antialias
            text_layer_get_hint_style
            text_layer_set_hint_style
            text_layer_get_kerning
            text_layer_set_kerning
            text_layer_get_language
            text_layer_set_language
            text_layer_get_base_direction
            text_layer_set_base_direction
            text_layer_get_justification
            text_layer_set_justification
            text_layer_get_color
            text_layer_set_color
            text_layer_get_indent
            text_layer_set_indent
            text_layer_get_line_spacing
            text_layer_set_line_spacing
            text_layer_get_letter_spacing
            text_layer_set_letter_spacing
            text_layer_resize);

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

$desc = 'Text layer procedures';
$doc_title = 'pikatextlayer';
$doc_short_desc = 'Functions for querying and manipulating text layers.';
$doc_long_desc = 'Functions for querying and manipulating text layers.';

1;