PIKApp/pdb/groups/display.pdb

# PIKA - Photo and Image Kooker Application
# 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>

sub display_id_is_valid {
    $blurb = 'Returns TRUE if the display ID is valid.';

    $help = <<'HELP';
This procedure checks if the given display ID is valid and refers to an
existing display.
HELP

    &neo_pdb_misc('2007', '3.0');

    @inargs = (
	{ name => 'display_id', type => 'int32',
	  desc => 'The display ID to check' }
    );

    @outargs = (
	{ name => 'valid', type => 'boolean',
	  desc => 'Whether the display ID is valid' }
    );

    %invoke = (
	code => <<'CODE'
{
  valid = (pika_display_get_by_id (pika, display_id) != NULL);
}
CODE
    );
}

sub display_new {
    $blurb = 'Create a new display for the specified image.';

    $help = <<'HELP';
Creates a new display for the specified image. If the image already has a
display, another is added. Multiple displays are handled transparently by
PIKA. The newly created display is returned and can be subsequently destroyed
with a call to pika_display_delete(). This procedure only makes sense for use
with the PIKA UI, and will result in an execution error if called when
PIKA has no UI.
HELP

    &std_pdb_misc;

    @inargs = (
	{ name => 'image', type => 'image',
	  desc => 'The image' }
    );

    @outargs = (
	{ name => 'display', type => 'display',
	  desc => 'The new display' }
    );

    %invoke = (
	code => <<'CODE'
{
  pika_image_flush (image);

  display = pika_create_display (pika, image, PIKA_UNIT_PIXEL, 1.0, NULL);

  if (display)
    {
      /* the first display takes ownership of the image */
      if (pika_image_get_display_count (image) == 1)
        g_object_unref (image);
    }
  else
    {
      success = FALSE;
    }
}
CODE
    );
}

sub display_delete {
    $blurb = 'Delete the specified display.';

    $help = <<'HELP';
This procedure removes the specified display. If this is the last remaining 
display for the underlying image, then the image is deleted also. Note that
the display is closed no matter if the image is dirty or not. Better save
the image before calling this procedure.
HELP

    &std_pdb_misc;

    @inargs = (
	{ name => 'display', type => 'display',
	  desc => 'The display to delete' }
    );

    %invoke = (
	code => <<'CODE'
{
  pika_delete_display (pika, display);
}
CODE
    );
}

sub display_present {
    $blurb = 'Present the specified display.';

    $help = <<'HELP';
This procedure presents the specified display at the top of the display stack.
HELP

    &jehan_pdb_misc('2021', '3.0');

    @inargs = (
	{ name => 'display', type => 'display',
	  desc => 'The display to present' }
    );

    %invoke = (
	code => <<'CODE'
{
  pika_display_present (display);
}
CODE
    );
}

sub display_get_window_handle {
    $blurb = 'Get a handle to the native window for an image display.';

    $help = <<'HELP';
This procedure returns a handle to the native window for a given image
display.

It can be different types of data depending on the platform you are running on.
For example in the X backend of GDK, a native window handle is an Xlib
XID whereas on Wayland, it is a string handle. A value of NULL is
returned for an invalid display or if this function is unimplemented for
the windowing system that is being used.
HELP

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

    @inargs = (
	{ name => 'display', type => 'display',
	  desc => 'The display to get the window handle from' }
    );

    @outargs = (
        { name => 'handle', type => 'bytes',
          desc => 'The native window handle or NULL' }
    );

    %invoke = (
	code => <<'CODE'
{
  handle = pika_get_display_window_id (pika, display);
}
CODE
    );
}

sub displays_flush {
    $blurb = 'Flush all internal changes to the user interface';

    $help = <<'HELP';
This procedure takes no arguments and returns nothing except a success status.
Its purpose is to flush all pending updates of image manipulations to the user
interface. It should be called whenever appropriate.
HELP

    &std_pdb_misc;

    %invoke = (
        headers => [ qw("core/pikacontainer.h") ],
        code    => <<'CODE'

{
  pika_container_foreach (pika->images, (GFunc) pika_image_flush, NULL);
}
CODE
    );
}

sub displays_reconnect {
    $blurb = 'Reconnect displays from one image to another image.';

    $help = <<'HELP';
This procedure connects all displays of the old_image to the
new_image.  If the old_image has no display or new_image already has a
display the reconnect is not performed and the procedure returns
without success.  You should rarely need to use this function.
HELP

    &std_pdb_misc;

    @inargs = ( 
	{ name => 'old_image', type => 'image',
	  desc => 'The old image (must have at least one display)' },
	{ name => 'new_image', type => 'image',
	  desc => 'The new image (must not have a display)' }
     );

    %invoke = (
	code => <<'CODE'
{
  success = (old_image != new_image    &&
             pika_image_get_display_count (old_image) > 0 &&
             pika_image_get_display_count (new_image) == 0);

  if (success)
    {
      pika_reconnect_displays (pika, old_image, new_image);

      /* take ownership of the image */
      if (pika_image_get_display_count (new_image) > 0)
        g_object_unref (new_image);
    }
}
CODE
    );
}


@headers = qw("core/pika.h"
              "core/pikadisplay.h");

@procs = qw(display_id_is_valid
            display_new
            display_delete
            display_get_window_handle
            display_present
            displays_flush
            displays_reconnect);

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

$desc = 'Display procedures';
$doc_title = 'pikadisplay';
$doc_short_desc = 'Functions to create, delete and flush displays (views) on an image.';
$doc_long_desc = 'Functions to create, delete and flush displays (views) on an image.';

1;