/***************************************************************************
                          KIconLoader.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 KICONLOADER_H
#define KICONLOADER_H

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

#include <qtobjc/QObject.h>
#include <qtobjc/QPixmap.h>
#include <kdeobjc/KConfig.h>

/**
  *@author Richard Dale
  */

/// Load icons from disk
/**
   KIconLoader is a derived class from QObject.
   It supports loading of icons from disk. It puts the icon and its name
   into a QList and if you call loadIcon() for a second time, the icon is taken
   out of the list and not reread from disk.
   So you can call loadIcon() as many times as you wish and you don't have
   to take care about multiple copies of the icon in memory.
*/
@interface KIconLoader : QObject
  /// Initializer
  /**
	 config is the reference to a KConfig object;
	 normally the global KConfig object.
	 group is the name of a group in a config file.
	 key is the name of an entry within this group.
	
	 Normaly group == "KDE Setup" and key == "IconPath"
	 Example for an entry in .kderc:
	 [KDE Setup]
	 IconPath=/usr/local/lib/kde/lib/pics:/usr/local/lib/kde/lib/pics/toolbar
	
	 This gives KIconLoader the path to search the icons in.
	
	 If you want to use another path in your application then write into
	 your .my_application_rc:
	 [MyApplication]
	 PixmapPath=/..../my_pixmap_path
	 and call KIconLoader( config, "MyApplication", "PixmapPath" ).
  */
- initFromConfig: (KConfig *) config appName: (NSString *) appName varName: (NSString *) varName;

  /**
	 There now exists a simple-to-use version of KIconLoader. If you
 	 create a KIconLoader without giving arguments, KIconLoader searches for
	 the path in [KDE Setup]:IconPath=... as a default.
  */
- init;
- (void) dealloc;

  /// Load an icon from disk
  /**
	 This function searches for the icon called name
	 and returns a QPixmap object
	 of this icon if it was found and 0 otherwise.
	 If name starts with "/..." loadIcon treats it as an absolut pathname.
	 -LoadIcon: creates a list of all loaded icons,
	 so calling -loadIcon: a second time
	 with the same name argument won't load the icon again, but gets it out of
	 its cache. By this you don't have to worry about multiple copies
	 of one and the same icon in memory, and you can call loadIcon()
	 as often as you like.

         If the icon is larger then the specified size, it is
         scaled down automatically. If the specified size is
         0, the icon is not scaled at all.

  */
- (QPixmap *) loadIcon: (NSString *) name width: (int) w height: (int) h;

  /// Load an icon from disk without cache
  /**
      Same like loadIcon, except that cached icons will be reloaded.
      This is useful if the icon has changed on the filesystem and you want to be
      sure that you get the new version, not the old one from the cache.
  */
- (QPixmap *) reloadIcon: (NSString *) name width: (int) w height: (int) h;

  /// Load an mini icon from disk
  /**
	 Same like loadIcon, but looks for "mini/name" first.
  */
- (QPixmap *) loadMiniIcon: (NSString *) name width: (int) w height: (int) h;

  /*
   * The loadApplication-Icon functions are similar to the
   * usual loadIcon functions except that they look in
   * kdedir()/share/icon first.
   *
   * These methods should be used if you are loading the
   * application icons. Normally KApplication does this for
   * you, but special programs like kpanel or kmenuedit
   * need to load the application icons of foreign applications.
   */
- (QPixmap *) loadApplicationIcon: (NSString *) name width: (int) w height: (int) h;
- (QPixmap *) loadApplicationMiniIcon: (NSString *) name width: (int) w height: (int) h;

  /// Insert directory into searchpath
  /**
         This functions inserts a new directory into the searchpath at
	 position index.
	 It returns YES if successful, or NO if index is out of range.
	 Note that the default searchpath looks like this:

	       1: $HOME/.kde/share/apps/<appName>/pics
	       2: $KDEDIR/share/apps/<appName>/pics
	       3: $HOME/.kde/share/apps/<appName>/toolbar
	       4: $KDEDIR/share/apps/<appName>/toolbar

	       5: $HOME/.kde/share/icons
	       6: $HOME/.kde/share/toolbar

	       7: $KDEDIR/share/icons
	       8: $KDEDIR/share/toolbar

	     9-x: list of directories in [KDE Setup]:IconPath=...

  */
- (BOOL) insertDirectory: (int) index name: (NSString *) dir_name;

  /// Get the complete path for an icon filename
  /**
      Set always_valid to YES if you want this method to return a valid
      pixmap is your wishes cannot be satisfied (Be aware, that if unknown.xpm
      is not found you will receive a null string)
  */
- (NSString *) getIconPath: (NSString *) name alwaysValid: (BOOL) always_valid;

  /// Flush cache
  /**
      Remove an icon from the cache given its name
  */
- flush: (NSString *) name;
@end

#endif

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