PIKApp/pdb/groups/progress.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 progress_init {
    $blurb = 'Initializes the progress bar for the current plug-in.';

    $help = <<'HELP';
Initializes the progress bar for the current plug-in. It is only valid to call
this procedure from a plug-in.
HELP

    &std_pdb_misc;

    $lib_private = 1;

    @inargs = (
	{ name => 'message', type => 'string', null_ok => 1,
	  desc => 'Message to use in the progress dialog' },
	{ name => 'gdisplay', type => 'display', none_ok => 1,
	  desc => 'PikaDisplay to update progressbar in, or %NULL for a separate
		   window' }
    );

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

  if (plug_in && plug_in->open)
    {
      if (! pika->no_interface)
        pika_plug_in_progress_start (plug_in, message, gdisplay);
    }
  else
    success = FALSE;
}
CODE
    );
}

sub progress_update {
    $blurb = 'Updates the progress bar for the current plug-in.';

    $help = <<'HELP';
Updates the progress bar for the current plug-in. It is only valid to call this
procedure from a plug-in.
HELP

    &std_pdb_misc;

    $lib_private = 1;

    @inargs = (
	{ name => 'percentage', type => 'float',
	  desc => 'Percentage of progress completed which must
                   be between 0.0 and 1.0' }
    );

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

  if (plug_in && plug_in->open)
    {
      if (! pika->no_interface)
	pika_plug_in_progress_set_value (plug_in, percentage);
    }
  else
    success = FALSE;
}
CODE
    );
}

sub progress_pulse {
    $blurb = 'Pulses the progress bar for the current plug-in.';

    $help = <<'HELP';
Updates the progress bar for the current plug-in. It is only valid to
call this procedure from a plug-in. Use this function instead of
pika_progress_update() if you cannot tell how much progress has been
made. This usually causes the the progress bar to enter "activity
mode", where a block bounces back and forth.
HELP

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

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

  if (plug_in && plug_in->open)
    {
      if (! pika->no_interface)
        pika_plug_in_progress_pulse (plug_in);
    }
  else
    success = FALSE;
}
CODE
    );
}

sub progress_set_text {
    $blurb = 'Changes the text in the progress bar for the current plug-in.';

    $help = <<'HELP';
This function changes the text in the progress bar for the current
plug-in. Unlike pika_progress_init() it does not change the displayed
value.
HELP

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

    @inargs = (
	{ name => 'message', type => 'string', null_ok => 1,
	  desc => 'Message to use in the progress dialog' }
    );

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

  if (plug_in && plug_in->open)
    {
      if (! pika->no_interface)
        pika_plug_in_progress_set_text (plug_in, message);
    }
  else
    success = FALSE;
}
CODE
    );
}

sub progress_end {
    $blurb = 'Ends the progress bar for the current plug-in.';

    $help = <<'HELP';
Ends the progress display for the current plug-in. Most plug-ins don't need to call this, they just exit when the work is done. It is only valid to call this
procedure from a plug-in.
HELP

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

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

  if (plug_in && plug_in->open)
    {
      PikaPlugInProcFrame *proc_frame = pika_plug_in_get_proc_frame (plug_in);

      pika_plug_in_progress_end (plug_in, proc_frame);
    }
  else
    success = FALSE;
}
CODE
    );
}

sub progress_get_window_handle {
    $blurb = 'Returns the native handle of the toplevel window this plug-in\'s progress is displayed in.';

    $help = <<'HELP';
This function returns the native handle allowing to identify the toplevel window this plug-in's progress is displayed in.

This handle can be of various types (integer, string, etc.) depending on the platform you are running on which is why it
returns a GBytes. There are usually no reasons to call this directly.
HELP

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

    @outargs = (
	{ name => 'handle', type => 'bytes',
	  desc => 'The progress bar\'s toplevel window\'s handle' }
    );

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

  if (plug_in && plug_in->open)
    {
      if (! pika->no_interface)
        handle = pika_plug_in_progress_get_window_id (plug_in);
    }
  else
    success = FALSE;
}
CODE
    );
}

sub progress_install {
    $blurb = 'Installs a progress callback for the current plug-in.';

    $help = <<'HELP';
This function installs a temporary PDB procedure which will handle all
progress calls made by this plug-in and any procedure it calls. Calling
this function multiple times simply replaces the old progress callbacks.
HELP

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

    $lib_private = 1;

    @inargs = (
	{ name => 'progress_callback', type => 'string', non_empty => 1,
	  desc => 'The callback PDB proc to call' }
    );

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

  if (plug_in && plug_in->open)
    success = pika_plug_in_progress_install (plug_in, progress_callback);
  else
    success = FALSE;
}
CODE
    );
}

sub progress_uninstall {
    $blurb = 'Uninstalls the progress callback for the current plug-in.';

    $help = <<'HELP';
This function uninstalls any progress callback installed with
pika_progress_install() before.
HELP

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

    $lib_private = 1;

    @inargs = (
	{ name => 'progress_callback', type => 'string', non_empty => 1,
	  desc => 'The name of the callback registered for this progress' }
    );

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

  if (plug_in && plug_in->open)
    success = pika_plug_in_progress_uninstall (plug_in, progress_callback);
  else
    success = FALSE;
}
CODE
    );
}

sub progress_cancel {
    $blurb = 'Cancels a running progress.';

    $help = <<'HELP';
This function cancels the currently running progress.
HELP

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

    @inargs = (
	{ name => 'progress_callback', type => 'string', non_empty => 1,
	  desc => 'The name of the callback registered for this progress' }
    );

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

  if (plug_in && plug_in->open)
    success = pika_plug_in_progress_cancel (plug_in, progress_callback);
  else
    success = FALSE;
}
CODE
    );
}


@headers = qw("core/pika.h"
              "plug-in/pikaplugin.h"
              "plug-in/pikaplugin-progress.h"
              "plug-in/pikapluginmanager.h");

@procs = qw(progress_init
            progress_update
            progress_pulse
            progress_set_text
            progress_end
            progress_get_window_handle
            progress_install
            progress_uninstall
            progress_cancel);

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

$desc = 'Progress';
$doc_title = 'pikaprogress';
$doc_short_desc = "Functions for embedding the progress bar into a plug-in's GUI.";
$doc_long_desc = "Functions for embedding the progress bar into a plug-in's GUI.";

1;