PIKApp/pdb/groups/plug_in.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 plug_ins_query {
    $blurb = 'Queries the plug-in database for its contents.';
    $help  = 'This procedure queries the contents of the plug-in database.';

    &andy_pdb_misc('1998');

    $lib_private = 1;

    @inargs = (
	{ name  => 'search_string', type => 'string', no_validate => 1,
	  desc  => 'If not an empty string then use this as a search pattern' }
    );

    @outargs = (
	{ name => 'procedures', type => 'strv',
	  desc => 'The plug-in procedure name' },
	{ name => 'accelerators', type => 'strv',
	  desc => 'String representing keyboard accelerator (could be empty
		   string)', },
	{ name => 'locations', type => 'strv',
	  desc => 'Location of the plug-in program' },
	{ name => 'install_times', type => 'int32array',
	  desc => 'Time that the plug-in was installed',
	  array => { name => 'num_install_times',
		     desc => 'The number of matching procedures' } }
    );

    %invoke = (
	code => <<'CODE'
{
  num_install_times = pika_plug_in_manager_query (pika->plug_in_manager,
                                                  search_string,
                                                  &procedures,
                                                  &accelerators,
                                                  &locations,
                                                  &install_times);
}
CODE
    );
}

sub plug_in_help_register {
    $blurb = "Register a help path for a plug-in.";

    $help = <<HELP;

This procedure registers user documentation for the calling plug-in
with the PIKA help system. The domain_uri parameter points to the root
directory where the plug-in help is installed. For each supported
language there should be a file called 'pika-help.xml' that maps the
help IDs to the actual help files.
HELP

    &mitch_pdb_misc('2000');

    $lib_private = 1;

    @inargs = (
	{ name => 'domain_name', type => 'string',
	  desc => "The XML namespace of the plug-in's help pages" },
	{ name => 'domain_file', type => 'file',
	  desc => "The root URI of the plug-in's help pages" }
    );

    %invoke = (
        code => <<'CODE'
{
  PikaPlugIn *plug_in = pika->plug_in_manager->current_plug_in;

  if (plug_in && plug_in->call_mode == PIKA_PLUG_IN_CALL_QUERY)
    {
      gchar *domain_uri = domain_file ? g_file_get_uri (domain_file) : NULL;

      pika_plug_in_def_set_help_domain (plug_in->plug_in_def,
                                        domain_name, domain_uri);

      g_free (domain_uri);
    }
  else
    success = FALSE;
}
CODE
    );
}

sub plug_in_menu_branch_register {
    $blurb = "Register a sub-menu.";

    $help = <<HELP;
This procedure installs a sub-menu which does not belong to any procedure.
The menu-name should be the untranslated menu label. PIKA will look up the
translation in the textdomain registered for the plug-in.
HELP

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

    $lib_private = 1;

    @inargs = (
	{ name => 'menu_path', type => 'string',
	  desc => "The sub-menu's menu path" },
	{ name => 'menu_name', type => 'string',
	  desc => 'The name of the sub-menu' }
    );

    %invoke = (
        code => <<'CODE'
{
  PikaPlugIn *plug_in = pika->plug_in_manager->current_plug_in;

  if (plug_in)
    {
      pika_plug_in_manager_add_menu_branch (pika->plug_in_manager,
                                            plug_in->file, menu_path, menu_name);
    }
  else
    success = FALSE;
}
CODE
    );
}

sub plug_in_set_pdb_error_handler {
    $blurb = "Sets an error handler for procedure calls.";

    $help = <<HELP;
This procedure changes the way that errors in procedure calls are
handled. By default PIKA will raise an error dialog if a procedure
call made by a plug-in fails. Using this procedure the plug-in can
change this behavior. If the error handler is set to
%PIKA_PDB_ERROR_HANDLER_PLUGIN, then the plug-in is responsible for
calling pika_get_pdb_error() and handling the error whenever one if
its procedure calls fails. It can do this by displaying the error
message or by forwarding it in its own return values.
HELP

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

    $lib_private = 1;

    @inargs = (
	{ name => 'handler', type => 'enum PikaPDBErrorHandler',
	  desc => "Who is responsible for handling procedure call errors" }
    );

    %invoke = (
        code => <<'CODE'
{
  PikaPlugIn *plug_in = pika->plug_in_manager->current_plug_in;

  if (plug_in)
    {
      pika_plug_in_set_error_handler (plug_in, handler);
    }
  else
    success = FALSE;
}
CODE
    );
}

sub plug_in_get_pdb_error_handler {
    $blurb = "Retrieves the active error handler for procedure calls.";

    $help = <<HELP;
This procedure retrieves the currently active error handler for
procedure calls made by the calling plug-in. See
pika_plugin_set_pdb_error_handler() for details.
HELP

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

    $lib_private = 1;

    @outargs = (
	{ name => 'handler', type => 'enum PikaPDBErrorHandler',
	  desc => "Who is responsible for handling procedure call errors" }
    );

    %invoke = (
        code => <<'CODE'
{
  PikaPlugIn *plug_in = pika->plug_in_manager->current_plug_in;

  if (plug_in)
    {
      handler = pika_plug_in_get_error_handler (plug_in);
    }
  else
    success = FALSE;
}
CODE
    );
}

@headers = qw(<string.h>
              <stdlib.h>
              "libpikabase/pikabase.h"
              "core/pika.h"
              "plug-in/pikaplugin.h"
              "plug-in/pikaplugindef.h"
              "plug-in/pikapluginmanager.h"
              "plug-in/pikapluginmanager-menu-branch.h"
              "plug-in/pikapluginmanager-query.h"
              "plug-in/pikapluginprocedure.h"
              "pikapdb-utils.h");

@procs = qw(plug_ins_query
            plug_in_help_register
            plug_in_menu_branch_register
            plug_in_set_pdb_error_handler
            plug_in_get_pdb_error_handler);

%exports = (app => [@procs], lib => [@procs[1,2,3,4]]);

$desc = 'Plug-in';

$lib_private = 1;

1;