/* -*- Mode: IDL; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
/*
 * Activity management for Evolution.
 *
 * Authors:
 *   Ettore Perazzoli <ettore@ximian.com>
 *
 * Copyright (C) 2000, 2001 Ximian, Inc.
 */

module GNOME {
module Evolution {

interface Activity : Bonobo::Unknown {
	typedef long ActivityId;

	enum DialogType {
		DIALOG_TYPE_NONE,
		DIALOG_TYPE_MESSAGE,
		DIALOG_TYPE_WARNING,
		DIALOG_TYPE_INPUT,
		DIALOG_TYPE_ERROR
	};

	enum DialogAction {
		DIALOG_ACTION_ERROR,
		DIALOG_ACTION_DISPLAY,
		DIALOG_ACTION_POSTPONE
	};

	exception InvalidIcon {};
	exception IdNotFound {};

	/* Events propagated through the listener:

	   - "ShowDetails": The user wants to know details about the
	     progressing operation.  The component should display additional
	     information about the operation in progress, or raise a pending
	     alert dialog.

	   - "Cancel": The user wants the operation to be cancelled.
	 */

	/**
	 * operationStarted:
	 * @component_id: Id of the component starting the operation.
	 * @information: Informative string about the operation being performed.
	 * @cancellable: Whether this operation should be cancellable by
	 * the user from the shell view.
	 * @event_listener: Listener which the events for the activity
	 * widget will be passed to.
	 * @activity_id: A unique Id for the activity, to be used to update the
	 * status of the operation.
	 * @suggest_display: Whether displaying the dialog might be a nice idea.
	 */
	void operationStarted (in string component_id,
			       in AnimatedIcon icon,
			       in string information,
			       in boolean cancellable,
			       in Bonobo::Listener event_listener,
			       out ActivityId activity_id,
			       out boolean suggest_display)
		raises (InvalidIcon);

	/**
	 * operationProgressing:
	 * @activity: The unique Id for the activity whose status we want to update.
	 * @information: New informative string.  If empty, the informative string
	 * isn't changed.
	 * @progress: A float from 0.0 to 1.0 indicating the status of completion.
	 *
	 * Update the status of the specified @activity.
	 */
	void operationProgressing (in ActivityId activity,
				   in string information,
				   in float progress)
		raises (IdNotFound);

	/**
	 * operationFinished:
	 * @activity: The unique Id for the activity that has been completed.
	 *
	 * Report that the specified @activity has been completed.  After this
	 * method is invoked, @activity is not considered to be a valid Id
	 * anymore.
	 */
	void operationFinished (in ActivityId activity);

	/**
	 * requestDialog:
	 *
	 * Inform the shell that the specified @activity requires user input
	 * from a dialog.  The returned value specifies whether the shell wants
	 * the dialog to be shown now (%DIALOG_ACTION_DISPLAY) or postponed
	 * (%DIALOG_ACTION_POSTPONE).  If the return value is
	 * %DIALOG_ACTION_POSTPONE, the component should wait for the
	 * "DisplayDialog" event before proceeding further.  In that case, the
	 * shell will flash the label related to this activity, and emit
	 * "DisplayDialog" through the event source when the user clicks on it.
	 */
	DialogAction requestDialog (in ActivityId activity,
				    in DialogType dialog_type);
};
		
};
};