/***************************************************************************
                          KApplication.h  -  description
                             -------------------
    begin                : Tue Mar 14 2000
    copyright            : (C) 2000 by Richard Dale
    email                : Richard_Dale@tipitina.demon.co.uk
 ***************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/

#ifndef KAPPLICATION_H
#define KAPPLICATION_H

#include <X11/Xlib.h>
#include <X11/Xatom.h>

#include <Foundation/NSObject.h>
#include <Foundation/NSString.h>
#include <Foundation/NSArray.h>

#include <qtobjc/QObject.h>
#include <qtobjc/QApplication.h>
#include <qtobjc/QEvent.h>
#include <qtobjc/QPixmap.h>
#include <qtobjc/QWidget.h>
#include <qtobjc/QColor.h>
#include <qtobjc/QFont.h>
#include <qtobjc/QPopupMenu.h>

#include <kdeobjc/KIconLoader.h>
#include <kdeobjc/KLocale.h>
#include <kdeobjc/KCharsets.h>
#include <kdeobjc/Drag.h>
#include <kdeobjc/KConfig.h>


/**
  *@author Richard Dale
  */

@class KApplication;
@class KIconLoader;
@class KCharsets;

/**
* A base class for all KDE applications.
*
* KApplication provides the application with KDE defaults such as
* accelerators, common menu entries, a KConfig object
* etc. KApplication installs a signal handler for the SIGCHLD signal
* in order to avoid zombie children. If you want to catch this signal
* yourself or don't want it to be caught at all, you have set a new
* signal handler (or SIG_IGN) after KApplication has been initialized.
*
* @short A base class for all KDE applications.
* Header derived from the C++ header 'kapp.h'
* by Matthias Kalle Dalheimer <kalle@kde.org>
*/
@interface KApplication : QApplication

  /**
	* Initializer. Pass command-line arguments.
	*
	* A KConfig object is
	* created that contains an application-specific config file whose
	* name is "~/." + argv[0] + "rc". This initializer should be considered
	* obsolete. The state of the application-specific config file may be
	* queried afterwards with - getConfigState.
	*/
- initFromArgc: (int) argc argv: (char **) argv;
  /**
	* Initializer. Pass command-line arguments.
	*
	* A KConfig object is
	* created that contains an application-specific config file whose
	* name is "~/." + rAppName + "rc". The state of the application-specific
	* config file may be queried afterwards with - getConfigState.
	*/
- initFromArgc: (int) argc argv: (char **) argv appName: (NSString *) appName;

/**
  * Called at app termination time
  */
- (void) dealloc;

  /** A global event filter for KApplication.
	* Filters out Ctrl-Alt-F12 for KDebug.
	*/
- (BOOL) eventFilter: (QObject *) filter event: (QEvent *) event;

  /**
	* Return the current application object.
	*
	* This is similar to +[QApplication qApp]. It allows access
	* to the single global KApplication object, since more than one cannot be
	* created in the same application. It saves the trouble of having to pass
	* the reference to it explicitly to every function that may require it.
	*/
+ (KApplication *) getKApplication;

  /**
	* Return the logical application name as set in the initializer.
	*/
+ (NSString *) appName;

  /**
	* Retrieve the application config object.
	*
	* @return a reference to the application's global KConfig object.
	* @see KConfig
	*/
- (KConfig *) getConfig;

  /**
	* Retrieve the application session config object.
	*
	* @return a reference to the application's instance specific KConfig object.
	* @see KConfig
	*/
- (KConfig *) getSessionConfig;

  /**
	* Is the application restored from the session manager?
	*
	* @return If true, this application was restored by the session manager.
	*	Note that this may mean the config object returned by
	*	- getSessionConfig contains data saved by a session closedown.
	* @see #-getSessionConfig
	*/
- (BOOL) isRestored;

  /**
	* Enable session management
	*
	* If userdefined = True then the WmCommand can be defined with setWmCommand.
	* Note that you do not get an instance specific config object with
	* @ref #getSessionConfig in this case!
	*
	* Session management will apply to the top widget.
	*/
- enableSessionManagement: (BOOL) userdefined;

  /**
	* Set the WmCommand for the session manager.
	*
	* This has an effect if either session management is disabled (then it
	* is used for pseudo session management) or if session management is
	* enabled with userdefined: YES.
	* @see #enableSessionManagement
	*/
- setWmCommand: (NSString *) wmCommand;

  /**
	* Return a standard help menu
	* @param appAboutText a little text about the application
	* @return a standard help menu
	*/
- (QPopupMenu *) getHelpMenu: (NSString *) appAboutText;

  /**
    * Get an iconloader for the application. If it does not yet exist,
    * create one.
    * @return a reference to the Iconloader of the application
    * @see KIconLoader
    */
- (KIconLoader *) getIconLoader;

  /**
    * Get a KLocale object for the application. If it does not yet exist,
    * create one.
    * @return a reference to the KLocale object of the application
    * @see KLocale
    */
- (KLocale *) getLocale;

  /**
    * Get a KCharsets object for the application.
    * @return a reference to the KCharsets object of the application
    * @see KCharsets
    */
- (KCharsets *) getCharsets;

  /**
	* Get the icon for the application.
	* @return a QPixmap with the icon.
	* @see QPixmap
	*/
- (QPixmap *) getIcon;

  /**
	* Get the mini-icon for the application.
	* @return a QPixmap with the icon.
	* @see QPixmap
	*/
- (QPixmap *) getMiniIcon;

  /** Sets the top widget of the application . This widget will
    * be used for communication with the session manager.
    * You must not use this method if you are using
    * the KTopLevelWidget.
    */
- setTopWidget: (QWidget *) topWidget;
- (QWidget *) topWidget;

  /**
	* Possible return values for -getConfigState.
	*
	* @see #-getConfigState
	*/

#define ConfigState				int
#define APPCONFIG_NONE			0
#define APPCONFIG_READONLY		1
#define APPCONFIG_READWRITE		2

- (ConfigState) getConfigState;

  /**
	* Invoke the kdehelp HTML help viewer.
	*
	* @param aFilename	The filename that is to be loaded. Its location
	*			is computed automatically according to the KFSSTND.
	*			If aFilename is empty, the logical appname with .html
	*			appended to it is used.
	* @param aTopic		This allows context-sensitive help. Its value
	*			will be appended to the filename, prefixed with
	*			a "#" (hash) character.
	*/
- invokeHTMLHelp: (NSString *) aFilename topic: (NSString *) aTopic;

  /**
   * Returns the directory where KDE stores its HTML documentation
   *
   * The default for this directory is $KDEDIR/share/doc/HTML
   * @return the name of the directory
   */
+ (NSString *) kde_htmldir;

  /**
   * Returns the directory where KDE applications store their .kdelnk file
   *
   * The default for this directory is $KDEDIR/share/applnk
   * @return the name of the directory
   */
+ (NSString *) kde_appsdir;

  /**
   * Returns the directory where KDE icons are stored
   *
   * The default for this directory is $KDEDIR/share/icons
   * @return the name of the directory
   */
+ (NSString *) kde_icondir;

  /** 	
   * Returns the directory where KDE applications store their specific data
   *
   * The default for this directory is $KDEDIR/share/apps
   * @return the name of the directory
   */
+ (NSString *) kde_datadir;

  /**
   * Returns the directory where locale-specific information (like
   * translated on-screen messages are stored
   *
   * The default for this directory is $KDEDIR/share/locale
   * @return the name of the directory
   */
+ (NSString *) kde_localedir;

  /**
   * Returns the directory where cgi scripts are stored
   *
   * The default for this directory is $KDEDIR/cgi-bin
   * @return the name of the directory
   */
+ (NSString *) kde_cgidir;

  /**
   * Returns the directory where sound data are stored.
   * This directory is for KDE specific sounds. Sound data of
   * Applications should go into - kde_datadir
   *
   * The default for this directory is $KDEDIR/share/sounds
   *
   * @return the name of the directory
   */
+ (NSString *) kde_sounddir;

  /**
   * Returns the directory where toolbar icons are stored
   *
   * The default for this directory is $KDEDIR/share/toolbar
   * @return the name of the directory
   */
+ (NSString *) kde_toolbardir;

  /**
   * Returns the directory where wallpapers are stored
   *
   * The default for this directory is $KDEDIR/share/wallpapers
   * @return the name of the directory
   */
+ (NSString *) kde_wallpaperdir;

  /**
   * Returns the directory where executable programs are stored
   *
   * The default for this directory is $KDEDIR/bin
   * @return the name of the directory
   */
+ (NSString *) kde_bindir;

  /**
   * Returns the directory where KParts are stored
   *
   * The default for this directory is $KDEDIR/parts
   * @return the name of the directory
   */
+ (NSString *) kde_partsdir;

  /**
   * Returns the directory where config files are stored
   *
   * The default for this directory is $KDEDIR/share/config
   * @return the name of the directory
   */
+ (NSString *) kde_configdir;

 /**
  * Returns the directory where mimetypes are stored
  *
  * The default for this directory is $KDEDIR/share/mimelnk
  * @return the name of the directory
  */
+ (NSString *) kde_mimedir;

  /**
   * Get the local KDE base dir
   *
   * This is usually $HOME/.kde
   *
   * @return the name of the directory
   */
+ (NSString *) localkdedir;

  /**
	* Get the local KDE config dir
	*
	* This is usually $HOME/.kde/share/config
	*/
+ (NSString *) localconfigdir;

  /**
	* Find a file using standard KDE search paths.
	*
	* Possible search paths
	* include $KDEDIR, $KDEPATH, and "[KDE Setup]:Path=" entry in a config
	* file. If file is not found, - isEmpty will return True
	*/
+ (NSString *) findFile: (NSString *) file;

  /**
	* Get the KDE font list.
	*
	* This method allows you to get the KDE font
	* list which was composed by the user with kfontmanager. Usually you should
	* work only with those fonts in your kapplication.
	*
	*  @return YES on success.
	*/
- (BOOL) getKDEFonts: (NSArray *) fontlist;

  /**
	* Return a text for the window caption.
	*
	* This would be set either by
	* "-caption", otherwise it will be equivalent to the name of the
	* executable.
	*/
- (NSString *) getCaption;

  /** Get a file name in order to make a temporary copy of your
	* document.
	*
	* @param pFilename The full path to the current file of your
	* document.
	* @return A new filename for auto-saving. You have to release this
	* yourself, otherwise you have a memory leak!
	*/
- (NSString *) tempSaveName: (NSString *) pFilename;

  /** Check if there is an auto-save file for the document you want to
	* open.
	*
	* @param pFilename The full path to the document you want to open.
	* @param bRecover  This gets set to true if there was a recover
	* file.
	* @return The full path of the file to open. You must release this
	* string yourself, otherwise you have a memory leak.
	*/
- (NSString *) checkRecoverFile: (NSString *) pFilename recover: (BOOL *) bRecover;

  /**
	* Returns YES if the KLocale object for this application has already
	* been created
	*
	* @return whether the KLocale object has already been created
	*/
- (BOOL) localeConstructed;

  /**
	* An X11 atom used for IPC
	*/
- (Atom) getDndSelectionAtom;
  /**
	* An X11 atom used for IPC
	*/
- (Atom) getDndProtocolAtom;
  /**
	* An X11 atom used for IPC
	*/
- (Atom) getDndEnterProtocolAtom;
  /**
	* An X11 atom used for IPC
	*/
- (Atom) getDndLeaveProtocolAtom;
  /**
	* An X11 atom used for IPC
	*/
- (Atom) getDndRootProtocolAtom;

  /**
	* Get the X11 display
	*/
  Display *getDisplay;

  /**
	* Used by KDNDDropZone to register
	*/
- addDropZone: (KDNDDropZone *) _z;
  /**
	* Used by KDNDDropZone during shutdown
	*/
- removeDropZone: (KDNDDropZone *) _z;
  /**
	* Set the DropZone which receives root drop events.
	*/
- setRootDropZone: (KDNDDropZone *) _z;

- (KDNDDropZone *) lastEnteredDropZone;
- (KDNDDropZone *) rootDropZone;

- (BOOL) x11EventFilter: (XEvent *) event;

  /**
   * Get the KDE base dir.
   *
   * This is the value of the KDEDIR
   * environment variable if it is set in the process' environment,
   * the compile time default of, if this was not present, either,
   * /usr/local/kde.
   * @return the KDE base dir
   */
+ (NSString *) kdedir;

  /**
	* KApplication has changed its Palette due to a KDisplay request.
	*
	* Normally, widgets will update their palettes automatically, but you
	* should connect to this to program special behaviour.
	*/
- kdisplayPaletteChanged: sender;

  /**
	* KApplication has changed its GUI Style due to a KDisplay request.
	*
	* Normally, widgets will update their styles automatically (as they would
	* respond to an explicit -setGUIStyle: call), but you should connect to
	* this to program special behaviour.
	*/
- kdisplayStyleChanged: sender;

  /**
	* KApplication has changed its Font due to a KDisplay request.
	*
	* Normally widgets will update their fonts automatically, but you should
	* connect to this to monitor global font changes, especially if you are
	* using explicit fonts.
	*/
- kdisplayFontChanged: sender;

  /**
	* KApplication has changed either its GUI style, its font or its palette
	* due to a kdisplay request. Normally, widgets will update their styles
	* automatically, but you should connect to this to program special
	* behavior. */
- appearanceChanged: sender;

  /** Session management is about to close your application.
	*
	* Connect to this signal in order to save your data. Do NOT
	* manipulate the UI in that slot, it is blocked by kwm.
	*
	* Use the @ref -[KConfig getSessionConfig] object to store all
	* your instance specific datas.
	*
	* Do not do any closing at this point! The user may still
	* select "cancel" and then he wants to continue working with
	* your application. Cleanups could be done after - shutDown:
	* (see below)
	*
	* Note: You should not use this if you are using the KTopLevelWidget.
	*       Overload @ref -[KTopLevelWidget saveProperties] and
	*	@ref -[KTopLevelWidget readProperties] in that case.
	*	This allows you to simply handle applications with multiple
	* toplevel windows.  */
- saveYourself: sender;
  /** Your application is killed. Either by kwm's killwindow function,
	* xkill or (the usual case) by KDE's logout.
	*/
- shutDown: sender;

@end

#endif

Documentation generated by duke@tipitina on Sat May 6 11:42:52 EDT 2000