/***************************************************************************
                            KXMLGUIClient.java -  description
                             -------------------
    begin                : Fri Nov 15 11:45:52 2002
    copyright            : (C) 2000-2002 Lost Highway Ltd.
    email                : Richard_Dale@tipitina.demon.co.uk
    generated by         : duke@tipitina on Fri Nov 15 11:45:52 2002, using kalyptus 0.9.
 ***************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This program 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.                                   *
 *                                                                         *
***************************************************************************/

package org.kde.koala;

import org.kde.qt.*;
import java.util.*;
import java.lang.Error;

/**


 A KXMLGUIClient can be used with {@link KXMLGUIFactory} to create a
 GUI from actions and an XML document, and can be dynamically merged
 with other KXMLGUIClients.
 
 @short *

*/
public class  KXMLGUIClient implements QtSupport, KXMLGUIClientInterface {
	private long _qt;
	private boolean _allocatedInJavaWorld = true;

	protected KXMLGUIClient(Class dummy){}

	private native void newKXMLGUIClient();

/** 
 Constructs a KXMLGUIClient which can be used with a
 {@link KXMLGUIFactory} to create a GUI from actions and an XML document, and
 which can be dynamically merged with other KXMLGUIClients.
   
*/
	public KXMLGUIClient() {
		newKXMLGUIClient();
	}
	private native void newKXMLGUIClient( KXMLGUIClientInterface parent);

/** 
 Constructs a KXMLGUIClient which can be used with a {@link KXMLGUIFactory}
 to create a GUI from actions and an XML document,
 and which can be dynamically merged with other KXMLGUIClients.

 This constructor takes an additional <code>parent</code> argument, which makes
 the client a child client of the parent.

 Child clients are automatically added to the GUI if the parent is added.

   
*/
	public KXMLGUIClient( KXMLGUIClientInterface parent) {
		newKXMLGUIClient( parent);
	}

/** 
 Destructs the KXMLGUIClient.
   
*/
	protected native void finalize() throws InternalError;
	public native void dispose();
	public native boolean isDisposed();

/** 
 Retrieves an action of the client by name.  If not found, it looks in its child clients.
 This method is provided for convenience, as it uses {@link #actionCollection}
 to get the action object.
   
*/
	public native KAction action( String name);

/** 
 Retrieves an action for a given {@link QDomElement}. The default
 implementation uses the "name" attribute to query the action
 object via the other action() method.
   
*/
	public native KAction action( QDomElement element);

/** 
 Retrieves the entire action collection for the GUI client
   
*/
	public native KActionCollection actionCollection();

/** 

*/
	public native KInstanceInterface instance();

/** 

*/
	public native QDomDocument domDocument();

/** 
 This will return the name of the XML file as set by {@link #setXMLFile}.
 If {@link #setXML} is used directly, then this will return NULL.

 The filename that this returns is obvious for components as each
 component has exactly one XML file.  In non-components, however,
 there are usually two: the global file and the local file.  This
 function doesn't really care about that, though.  It will always
 return the last XML file set.  This, in almost all cases, will
 be the local XML file.

*/
	public native String xmlFile();
	public native String localXMLFile();

/** 

   
*/
	public native void setXMLGUIBuildDocument( QDomDocument doc);

/** 

   
*/
	public native QDomDocument xmlguiBuildDocument();

/** 
 This method is called by the {@link KXMLGUIFactory} as soon as the client
 is added to the KXMLGUIFactory's GUI.
   
*/
	public native void setFactory( KXMLGUIFactory factory);

/** 
 Retrieves a pointer to the {@link KXMLGUIFactory} this client is
 associated with (will return null if the client's GUI has not been built
 by a KXMLGUIFactory.
   
*/
	public native KXMLGUIFactory factory();

/** 
 KXMLGUIClients can form a simple child/parent object tree. This
 method returns a pointer to the parent client or null if it has no
 parent client assigned.
   
*/
	public native KXMLGUIClientInterface parentClient();

/** 
 Use this method to make a client a child client of another client.
 Usually you don't need to call this method, as it is called
 automatically when using the second constructor, which takes a
 arent argument.
   
*/
	public native void insertChildClient( KXMLGUIClientInterface child);

/** 
 Removes the given <code>child</code> from the client's children list.
   
*/
	public native void removeChildClient( KXMLGUIClientInterface child);

/** 
 Retrieves a list of all child clients.
   
*/
//	public native KXMLGUIClientPtrList childClients();

/** 
 A client can have an own {@link KXMLGUIBuilder}.
 Use this method to assign your builder instance to the client (so that the
 {@link KXMLGUIFactory} can use it when building the client's GUI)

 Client specific guibuilders are useful if you want to create
 custom container widgets for your GUI.
   
*/
	public native void setClientBuilder( KXMLGUIBuilderInterface builder);

/** 
 Retrieves the client's GUI builder or null if no client specific
 builder has been assigned via {@link #setClientBuilder}
   
*/
	public native KXMLGUIBuilderInterface clientBuilder();

/** 
 Forces this client to re-read its XML resource file.  This is
 intended to be used when you know that the resource file has
 changed and you will soon be rebuilding the GUI.  It has no
 useful effect with non-KParts GUIs, so don't bother using it
 unless your app is component based.
   
*/
	public native void reloadXML();

/** 
 ActionLists are a way for XMLGUI to support dynamic lists of
 actions.  E.g. if you are writing a file manager, and there is a
 menu file whose contents depend on the mimetype of the file that
 is selected, then you can achieve this using ActionLists. It
 works as follows:
 In your xxxui.rc file ( the one that you set in {@link #setXMLFile}
 ), you put an <ActionList name="xxx"> tag.  E.g.
 \verbatim
 <kpartgui name="xxx_part" version="1">
 <MenuBar>
   <Menu name="file">
     ...  <!-- some useful actions-.
     <ActionList name="xxx_file_actionlist" />
     ...  <!-- even more useful actions-.
   </Menu>
   ...
 </MenuBar>
 </kpartgui>
 \endverbatim

 This tag will get expanded to a list of actions.  In the example
 above ( a file manager with a dynamic file menu ), you would call
 \code
 QPtrList<KAction> file_actions;
 for( ... )
   if( ... )
     file_actions.append( cool_action );
 unplugActionList( "xxx_file_actionlist" );
 plugActionList( "xxx_file_actionlist", file_actions );
 \endcode
 every time a file is selected, unselected or ...

 \note You should not call createGUI() after calling this
       function.  In fact, that would remove the newly added
       actionlists again...
 \note Forgetting to call unplugActionList() before
       plugActionList() would leave the previous actions in the
       menu too..
   
*/
//	public native void plugActionList( String name, KActionPtrList actionList);

/** 
 The complement of \ref plugActionList() ...
   
*/
	public native void unplugActionList( String name);
	public native void addStateActionEnabled( String state, String action);
	public native void addStateActionDisabled( String state, String action);
//	public native StateChange getActionsToChangeForState( String state);
	public native void beginXMLPlug( QWidget arg1);
	public native void endXMLPlug();
	public native void prepareXMLUnplug( QWidget arg1);
	public static native String findMostRecentXMLFile( String[] files, String doc);

/** 
 Sets the instance ({@link KInstance}) for this part.

 Call this first in the inherited class constructor.
 (At least before {@link #setXMLFile}.)
   
*/
	public native void setInstance( KInstanceInterface instance);

/** 
 Sets the name of the rc file containing the XML for the part.

 Call this in the Part-inherited class constructor.

*/
	protected native void setXMLFile( String file, boolean merge, boolean setXMLDoc);
	protected native void setXMLFile( String file);
	protected native void setLocalXMLFile( String file);

/** 
 Sets the XML for the part.

 Call this in the Part-inherited class constructor if you
  don't call {@link #setXMLFile}.

*/
	protected native void setXML( String document, boolean merge);
	protected native void setXML( String document);

/** 
 Sets the Document for the part, describing the layout of the GUI.

 Call this in the Part-inherited class constructor if you don't call
 {@link setXMLFile} or {@link setXML} .
   
*/
	protected native void setDOMDocument( QDomDocument document, boolean merge);
	protected native void setDOMDocument( QDomDocument document);

/** 
 This function will attempt to give up some memory after the GUI
 is built.  It should never be used in apps where the GUI may be
 rebuilt at some later time (components, for instance).
   
*/
	protected native void conserveMemory();

/** 
 Actions can collectively be assigned a "State". To accomplish this
 the respective actions are tagged as <enable> or <disable> in
 a <State> </State> group of the XMLfile. During program execution the
 programmer can call stateChanged() to set actions to a defined state.

*/
	protected native void stateChanged( String newstate, int reverse);
	protected native void stateChanged( String newstate);
	protected native void virtual_hook( int identifier, int data);
	public static final int StateNoReverse = 0;
	public static final int StateReverse = 1;
}
