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

#include <Bonobo.idl>

module GNOME {
module Evolution {
	interface Shell;

	/* URI schemas, e.g. mailto:.  */
	typedef string URISchema;
	typedef sequence<URISchema> URISchemaList;

	/* A type of item that the component can create when asked by the user,
	   e.g. a mail message or an appointment.  */
	struct UserCreatableItemType {
		string id;
		string description;
		string menuDescription;
		string tooltip;
		char menuShortcut;
		Icon icon;

		// This specifies the folder type for which this user creatable
		// type is a default type.
		string folderType;
	};
	typedef sequence<UserCreatableItemType> UserCreatableItemTypeList;

	/* Definition for a folder type.  */
	struct FolderType {
		string name;
		string iconName;

		string displayName;
		string description;

		boolean userCreatable;

		sequence<string> acceptedDndTypes;
		sequence<string> exportedDndTypes;

		UserCreatableItemTypeList userCreatableItemTypes;
	};
	typedef sequence<FolderType> FolderTypeList;

	interface ShellComponentListener;

	interface ShellComponent : Bonobo::Unknown {
		exception AlreadyOwned {};
		exception Busy {};
		exception InternalError {};
		exception NotFound {};
		exception NotOwned {};
		exception OldOwnerHasDied {};
		exception UnsupportedSchema {};
		exception UnsupportedType {};
		exception AlreadyPopulated {};
		exception NotPopulated {};

		/* List of folders that the component supports.  */
		readonly attribute FolderTypeList supportedTypes;

		/* Custom URI schemas that the component supports.
		   (e.g. mailto, see ::handleExternalURI).  */
		readonly attribute URISchemaList externalUriSchemas ;

		/* List of the item that the user can create (see
		   ::userCreateNewItem).  */
		readonly attribute UserCreatableItemTypeList userCreatableItemTypes;

		/* This method is invoked after the components is activated by
		   the shell to notify the component that the shell is
		   alive.  */
		void setOwner (in Shell shell, in string evolution_homedir)
			raises (AlreadyOwned, OldOwnerHasDied);

		/* This is invoked when the shell releases the component.  */
		void unsetOwner ()
			raises (NotOwned);

		/* Notify the component of whether the shell is currently
		 * running in interactive mode or not.  (I.e. basically,
		 * whether there are any Evolution windows on the screen.)
		 * @new_view_xid is an X Window ID ("None" if
		 * @now_interactive is FALSE) */
		void interactive (in boolean now_interactive,
				  in unsigned long new_view_xid);

		/* Send debugging output to the file specified.  */
		void debug (in string log_path);

		/* Create a view for the specified @physical URI.  */
		Bonobo::Control createView (in string physical_uri,
					    in string type,
					    in string view_info)
			raises (NotFound, UnsupportedType, InternalError);

		/* Handle a registered external URI scheme (eg. mailto:).  */
		void handleExternalURI (in string external_uri)
			raises (NotFound, UnsupportedSchema, InternalError);

		/* Folder operations:  */

		/* 1. Create a folder.  */
		void createFolderAsync (in ShellComponentListener listener,
					in string physical_uri,
					in string type)
			raises (Busy);

		/* 2. Remove a folder.  */
		void removeFolderAsync (in ShellComponentListener listener,
					in string physical_uri,
					in string type)
			raises (Busy);

		/* 3. Copy/move a folder.  */
		void xferFolderAsync (in ShellComponentListener listener,
				      in string source_physical_uri,
				      in string destination_physical_uri,
				      in string type,
				      in boolean remove_source)
			raises (Busy);

		/* Ask the component to populate the UIC with the
		   folder-specific menu items of the folder at the specified
		   @physical_uri.  */
		void populateFolderContextMenu (in Bonobo::UIContainer uih,
						in string physical_uri,
						in string type)
			raises (AlreadyPopulated);

		/* After you are done, you have to remove the items.  This is
		   because of BonoboUI sucking and not allowing the shell to
		   remove the items itself.  */
		void unpopulateFolderContextMenu (in Bonobo::UIContainer uih,
						  in string physical_uri,
						  in string type)
			raises (NotPopulated);

		/* Make the component create a new item of the specify @id in
		   the folder specified by @parent_folder_physical_uri.  This
		   is supposed to pop up a dialog (say, the Addressbook
		   editor) when necessary.  */
		void userCreateNewItem (in string id,
					in string parent_folder_physical_uri,
					in string parent_folder_type)
			raises (UnsupportedType);

		/* Make the component start a Send/Receive operation.  If
		   @show_dialog is true, display a progress dialog for the
		   operation as well.  */
		void sendReceive (in boolean show_dialog);

		/* Request the component to quit.  The component should report
		   through the listener (through OK or CANCEL) whether the
		   shell can quit safely.  (This is meant to be used for
		   confirmations before quitting.)  */
		oneway void requestQuit (in ShellComponentListener listener);
	};

	interface ShellComponentListener {
		enum Result {
			OK,
			CANCEL,
			UNSUPPORTED_OPERATION,
			UNSUPPORTED_TYPE,
			EXISTS,
			INVALID_URI,
			PERMISSION_DENIED,
			HAS_SUBFOLDERS,
			NO_SPACE
		};

		void notifyResult (in Result result);
	};
};
};