/**
 * 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_Unknown.idl"
#include "Bonobo_Property.idl"

module Bonobo {

interface ControlFrame : Bonobo::Unknown {

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

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

	/** 
	 * queueResize:
	 *
	 * Tell the container that the Control would like to be
	 * resized.  The container should follow-up by calling
	 * Control::setSize ()
	 *
	 */
	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
	 */
	void activateURI (in string uri, in boolean relative);

	/**
	 * getUIHandler:
	 *
	 * Returns: The interface to be used for menu/toolbar item merging.
	 */
	Bonobo::Unknown getUIHandler ();

	void unused ();
};

interface Control : Bonobo::Unknown {
	/*
	 * This is a ':' delimited string
	 *   under X11 the first entry ( before a ':' ) contains
	 *  window ID as an integer. Other fields are reserved for
	 *  future use.
	 * See also bonobo-control.c (window_id_demangle)
	 */
	typedef string windowId;

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

	/**
	 * setFrame:
	 * @frame: A Bonobo_ControlFrame.
	 *
	 * Gives the Control a handle to its ControlFrame.
	 */
	void setFrame (in ControlFrame frame);

	/**
	 * setWindowId:
	 * @id: An X Window ID.
	 *
	 *   Sets the window ID that should be used for the plug
	 * of this window, the id encoding is as described above.
	 */
	void setWindowId (in windowId id);

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

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

	/**
	 * getDesiredSize:
	 * @desired_width: In this value you should return the desired width you want.
	 * @desired_height: In this value you should return the desired height you want.
	 */
	void getDesiredSize (out short desired_width, out short desired_height);

	enum State {
		StateNormal,
		StateActive,
		StatePrelight,
		StateSelected,
		StateInsensitive
	};

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

	/**
	 *   These methods are used to synchronize the Async X event
	 * queue with the synchronous CORBA connection. Effectively
	 * the 'X sync' extension in Bonobo.
	 */
	void realize   ();
	void unrealize ();

	/* GTK+ focus direction equivalents */
	enum FocusDirection {
		TAB_FORWARD,
		TAB_BACKWARD,
		UP,
		DOWN,
		LEFT,
		RIGHT
	};

	/* Control proxy for GtkContainer::focus() */
	boolean focusChild (in FocusDirection direction);
};

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);

};

};

#endif