/**
 * bonobo-control.idl: Control interfaces
 *
 * Copyright (C) 1999, 2000  Helix Code, Inc.
 *
 * Authors:
 *   Nat Friedman <nat@nat.org>
 *   Miguel de Icaza <miguel@gnu.org>
 */

#ifndef BONOBO_CONTROL_IDL
#define BONOBO_CONTROL_IDL

#include "Bonobo_UI.idl"
#include "Bonobo_Gdk.idl"
#include "Bonobo_Property.idl"

module Bonobo {

interface ControlFrame : Bonobo::Unknown {

	/**
	 * getToplevelId
	 *
	 * Returns: the WindowId of the true toplevel of the
	 * application the control is embedded inside.
	 */
	Gdk::WindowId getToplevelId ();

	/**
	 * getAmbientProperties:
	 * 
	 * Returns: A PropertyBag containing the ambient properties
	 * for this container.
	 */
	PropertyBag getAmbientProperties ();

	/**
	 * getUIContainer:
	 *
	 * Returns: The interface to be used for menu/toolbar item merging.
	 */
	UIContainer getUIContainer ();

	/* --- Notifications --- */

	/**
	 * activated:
	 * @state: TRUE if the associated Control has been activated,
	 * FALSE if it just became inactive.
	 */
	oneway void notifyActivated (in boolean state);

	/** 
	 * queueResize:
	 *
	 * Tell the container that the Control would like to be
	 * resized.  The container should follow-up by calling
	 * Control::setSize ()
	 *
	 */
	oneway void queueResize ();

	/**
	 * activateURI:
	 * @uri: The uri we would like to get loaded.
	 * @relative: Whether the URI is relative to the current URI
	 *
	 * This is used by the containee when it needs
	 * to ask the container to perform some action
	 * with a given URI.
	 *
	 * The user has requested that the uri be loaded
	 */
	oneway void activateURI (in string uri, in boolean relative);

	/**
	 * getParentAccessible:
	 *
	 * Returns: A CORBA Accessibility reference, related to the
	 * parent of the container widget associated with this control
	 * frame.
	 */
	Unknown getParentAccessible ();

	/**
	 * unImplemented:
	 *
	 * placeholders for future expansion.
	 */
	void unImplemented ();
	void unImplemented2 ();
};

interface Control : Bonobo::Unknown {
	exception NoContents { };

	/**
	 * getProperties:
	 *
	 * Returns: A PropertyBag containing this Control's properties.
	 */
	PropertyBag getProperties ();

	/**
	 * getDesiredSize:
	 *
	 * Returns the requested size for the contained widget.
	 */
	Gtk::Requisition getDesiredSize ();

	/**
	 * getAccessible:
	 *
	 * Returns: accessibility related resources
	 */
	Bonobo::Unknown getAccessible ();

	/**
	 * getWindowId:
	 * @cookie: ',' delimited string, format:
	 *                'screen' = <int> [, [ <reserved for expansion> ] ]
	 *
	 * Returns: the windowId of the plug's window
	 */
	Gdk::WindowId getWindowId (in string cookie)
		raises (NoContents);

	/**
	 * getPopupContainer:
	 *
	 * Returns: A UIContainer for a parent to push popup items into
	 */
	UIContainer getPopupContainer ();

	/**
	 * setFrame:
	 * @frame: A Bonobo_ControlFrame.
	 *
	 * Gives the Control a handle to its ControlFrame.
	 *
	 * Returns: The windowId of the plug
	 */
	oneway void setFrame (in ControlFrame frame);

	/**
	 * setSize:
	 * @width: width given to the control
	 * @height: height given to the control
	 *
	 * Informs the Control of the size assigned by its container application
	 */
	oneway void setSize (in short width, in short height);

	/**
	 * setState:
	 * @state: The new state of the control.
	 *
	 * Set the control's activity state.
	 */
	oneway void setState (in Gtk::State state);

	/**
	 * activate:
	 *
	 * Activates or deactivates this Control.
	 */
	oneway void activate (in boolean activate);

	/**
	 * focus:
	 *
	 * a Control proxy for GtkContainer::focus()
	 *
	 * Returns: whether focus was transfered.
	 */
	boolean focus (in Gtk::Direction direction);

	/**
	 * unImplemented:
	 *
	 * placeholders for future expansion.
	 */
	void unImplemented  ();
	void unImplemented2 ();
	void unImplemented3 ();
};

interface PropertyControl : Bonobo::Unknown {

	readonly attribute long pageCount;

	enum Action {
		APPLY,
		HELP
	};

	/**
	 * NoPage: Raised when the page number specified 
	 * does not exist.
	 */
	exception NoPage {};
	
	/**
	 *   An interface for allowing a customization interface
	 * in addition / instead of a property bag; rather immature.
	 */

	/**
	 * getControl:
	 * @pagenumber: The number of the page to get.
	 *
	 * Gets the page number @pagenumber. Multiple pages can be used
	 * in a number of different ways. One way is for each page to be
	 * a new page in a GnomeDruid widget. Another way is for each page
	 * to be a page of a GtkNotebook in a GnomePropertyBox. The most
	 * common case, however, is for one single page.
	 *
	 * Returns: a Bonobo::Control for the page.
	 */
	Control getControl (in long pagenumber)
		raises (NoPage);
	/**
	 * notifyAction:
	 * @pagenumber: The page number that this action was performed on.
	 * @action: The action that should be performed on the settings.
	 *
	 * Tell the client what it should do with the settings in the
	 * PropertyControl.
	 */
	void notifyAction (in long pagenumber, in Action _action)
		raises (NoPage);

	void unImplemented  ();
	void unImplemented2 ();
};

};

#endif