nautilus/libnautilus/nautilus-view-component.idl

/* -*- Mode: IDL; tab-width: 8; indent-tabs-mode: 8; c-basic-offset: 8 -*- */

/*
 *  libnautilus: A library for nautilus view implementations.
 *
 *  Copyright (C) 1999, 2000 Red Hat, Inc.
 *  Copyright (C) 2000, 2001 Eazel, Inc.
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Library General Public
 *  License as published by the Free Software Foundation; either
 *  version 2 of the License, or (at your option) any later version.
 *
 *  This library 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
 *  Library General Public License for more details.
 *
 *  You should have received a copy of the GNU Library General Public
 *  License along with this library; if not, write to the Free
 *  Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 *
 *  Authors: Elliot Lee <sopwith@redhat.com>
 *           Darin Adler <darin@bentspoon.com>
 *           Maciej Stachowiak <mjs@eazel.com>
 *
 */


#ifndef NAUTILUS_VIEW_COMPONENT_IDL
#define NAUTILUS_VIEW_COMPONENT_IDL

#if !defined(__nautilus_view_component_COMPILATION) && defined(__ORBIT_IDL__)
%{
#pragma include_defs libnautilus/nautilus-view-component.h
%}
#pragma inhibit push
#endif

#include <Bonobo.idl>

module Nautilus {

	/* URIs are just plain strings, but we use a typedef to make
	 * the interface definitions clearer.
	 */
	typedef string URI;
	typedef sequence<URI> URIList;

	struct HistoryItem {
		string title;
		URI location;
	};
	typedef sequence<HistoryItem> History;

	/* The View interface is used by the Nautilus shell to control
	 * the view. A view that is a Bonobo::Control can choose to
	 * implement the View interface for additional finer control
	 * by Nautilus.
	 */
	interface View : ::Bonobo::Unknown {
		/* Called to tell the view about location changes.
		 * Called again with the same location again to request a
		 * reload.
		 */
		oneway void load_location (in URI location);
		oneway void stop_loading ();
	};
	
	/* The ViewFrame interface is used by the view to communicate
	 * with the Nautilus shell. It's implemented as an interface
	 * on the Bonobo::ControlFrame for the view.
	 *
	 * The Ambient properties on the ControlFrame are:
	 *      'title'     - ro - string            - the title
	 *      'history'   - ro - Nautilus::History - the history list
	 *      'selection' - ro - URIList           - the selection
	 */
	interface ViewFrame : ::Bonobo::Unknown {
		/* Called by the view component to change the location
		 * shown in the window, or to open a window. The
		 * "prefer existing window" variant will use an
		 * existing window if one exists for that location and
		 * will otherwise open a new window (with no
		 * selection). In the case where you force a new
		 * window, you can specify the initial selection.
		 */
		oneway void open_location_in_this_window (in URI location);
		oneway void open_location_prefer_existing_window (in URI location);
		oneway void open_location_force_new_window (in URI location,
							    in URIList selection);

		/* Called by a view component when the location
		 * changes, but the view component is handling it
		 * directly. This differs from
		 * "open_location_in_this_window" in that it
		 * understands that the same component is reused, and
		 * also it treats the load as "already underway" and
		 * does not send a "load_location",
		 * "selection_changed", or "title_changed" to the view
		 * that initiates this. The redirect version should be
		 * used when the location change does not deserve its
		 * own element in history.
		 */
		oneway void report_location_change (in URI location,
						    in URIList selection,
						    in string title);
		oneway void report_redirect (in URI from_location,
					     in URI to_location,
					     in URIList selection,
					     in string title);

		/* Called by a view component to announce a change in the
		 * selection. This selection change will be reported back
		 * to the original view along with the others.
		 */
		oneway void report_selection_change (in URIList selection);

		/* Called by a view component to change the contents
		 * of the status bar.
		 */
		oneway void report_status (in string status);

		/* Called by a view component to give an update about
		 * progress loading the view for the current
		 * location. Calling underway repeatedly tells the
		 * shell that the view is making progress. For views
		 * that know how far along they are, calling
		 * report_load_progress (instead of
		 * report_load_underway) with a number from 0.0 to 1.0
		 * expresses how much of the total is done. When the
		 * load is complete or has failed, either
		 * report_load_failed or report_load_complete
		 * indicates that.
		 */
		oneway void report_load_underway ();
		oneway void report_load_progress (in float fraction_done);
		oneway void report_load_complete ();
		oneway void report_load_failed ();

		/* Called by a view component to change the title. */
		oneway void set_title (in string new_title);

		/* Called when a view component wants to make the
		 * window it's in "go back". At some point we may add a more
		 * complete set of operations. This one is very useful for
		 * components that do something and then return.
		 * If there's nowhere to go back to, it goes home, which
		 * is not quite the same as the "back" button in the UI,
		 * which does nothing if there's nowhere to go.
		 */
		oneway void go_back ();
		oneway void close_window ();
	};

};

#if !defined(__nautilus_view_component_COMPILATION) && defined(__ORBIT_IDL__)
#pragma inhibit pop
#endif

#endif /* NAUTILUS_VIEW_COMPONENT_IDL */