From 5b38737dee4d4160fae38c6b50c3c328bcdd437e Mon Sep 17 00:00:00 2001 From: Rivo Laks Date: Sun, 27 Jan 2008 14:43:05 +0000 Subject: [PATCH] Add apidox for kwineffects group, showing the necessary steps for adding a new effect. svn path=/trunk/KDE/kdebase/workspace/; revision=767202 --- lib/kwineffects.h | 109 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 99 insertions(+), 10 deletions(-) diff --git a/lib/kwineffects.h b/lib/kwineffects.h index 5706b155d1..3871591666 100644 --- a/lib/kwineffects.h +++ b/lib/kwineffects.h @@ -38,22 +38,12 @@ along with this program. If not, see . #include -/** @addtogroup kwineffects */ -/** @{ */ - -#define KWIN_EFFECT_API_MAKE_VERSION( major, minor ) (( major ) << 8 | ( minor )) -#define KWIN_EFFECT_API_VERSION_MAJOR 0 -#define KWIN_EFFECT_API_VERSION_MINOR 6 -#define KWIN_EFFECT_API_VERSION KWIN_EFFECT_API_MAKE_VERSION( \ - KWIN_EFFECT_API_VERSION_MAJOR, KWIN_EFFECT_API_VERSION_MINOR ) class KLibrary; class KConfigGroup; class KActionCollection; class QKeyEvent; -/** @defgroup kwineffects KWin effects library */ - namespace KWin { @@ -75,6 +65,105 @@ typedef QPair< Effect*, Window > InputWindowPair; typedef QList< EffectWindow* > EffectWindowList; +/** @defgroup kwineffects KWin effects library + * KWin effects library contains necessary classes for creating new KWin + * compositing effects. + * + * @section creating Creating new effects + * This example will demonstrate the basics of creating an effect. We'll use + * CoolEffect as the class name, cooleffect as internal name and + * "Cool Effect" as user-visible name of the effect. + * + * This example doesn't demonstrate how to write the effect's code. For that, + * see the documentation of the Effect class. + * + * @subsection creating-class CoolEffect class + * First you need to create CoolEffect class which has to be a subclass of + * @ref KWin::Effect. In that class you can reimplement various virtual + * methods to control how and where the windows are drawn. + * + * @subsection creating-macro KWIN_EFFECT macro + * To make KWin aware of your new effect, you first need to use the + * @ref KWIN_EFFECT macro to connect your effect's class to it's internal + * name. The internal name is used by KWin to identify your effect. It can be + * freely chosen (although it must be a single word), must be unique and won't + * be shown to the user. For our example, you would use the macro like this: + * @code + * KWIN_EFFECT(cooleffect, CoolEffect) + * @endcode + * + * @subsection creating-buildsystem Buildsystem + * To build the effect, you can use the KWIN_ADD_EFFECT() cmake macro which + * can be found in effects/CMakeLists.txt file in KWin's source. First + * argument of the macro is the name of the library that will contain + * your effect. Although not strictly required, it is usually a good idea to + * use the same name as your effect's internal name there. Following arguments + * to the macro are the files containing your effect's source. If our effect's + * source is in cooleffect.cpp, we'd use following: + * @code + * KWIN_ADD_EFFECT(cooleffect cooleffect.cpp) + * @endcode + * + * This macro takes care of compiling your effect. You'll also need to install + * your effect's .desktop file, so the example CMakeLists.txt file would be + * as follows: + * @code + * KWIN_ADD_EFFECT(cooleffect cooleffect.cpp) + * install( FILES cooleffect.desktop DESTINATION ${SERVICES_INSTALL_DIR}/kwin ) + * @endcode + * + * @subsection creating-desktop Effect's .desktop file + * You will also need to create .desktop file to set name, description, icon + * and other properties of your effect. Important fields of the .desktop file + * are: + * @li Name User-visible name of your effect + * @li Icon Name of the icon of the effect + * @li Comment Short description of the effect + * @li Type must be "Service" + * @li X-KDE-ServiceTypes must be "KWin/Effect" + * @li X-KDE-PluginInfo-Name effect's internal name as passed to the KWIN_EFFECT macro plus "kwin4_effect_" prefix + * @li X-KDE-PluginInfo-Category effect's category. Should be one of Appearance, Accessibility, Window Management, Demos, Tests, Misc + * @li X-KDE-PluginInfo-EnabledByDefault whether the effect should be enabled by default (use sparingly). Default is false + * @li X-KDE-Library name of the library containing the effect. This is the first argument passed to the KWIN_ADD_EFFECT macro in cmake file plus "kwin4_effect_" prefix. + * + * Example cooleffect.desktop file follows: + * @code +[Desktop Entry] +Name=Cool Effect +Comment=The coolest effect you've ever seen +Icon=preferences-system-windows-effect-cooleffect + +Type=Service +X-KDE-ServiceTypes=KWin/Effect +X-KDE-PluginInfo-Author=My Name +X-KDE-PluginInfo-Email=my@email.here +X-KDE-PluginInfo-Name=kwin4_effect_cooleffect +X-KDE-PluginInfo-Category=Misc +X-KDE-Library=kwin4_effect_cooleffect + * @endcode + * + * + * @section accessing Accessing windows and workspace + * Effects can gain access to the properties of windows and workspace via + * EffectWindow and EffectsHandler classes. + * + * There is one global EffectsHandler object which you can access using the + * @ref effects pointer. + * For each window, there is an EffectWindow object which can be used to read + * window properties such as position and also to change them. + * + * For more information about this, see the documentation of the corresponding + * classes. + * + * @{ + **/ + +#define KWIN_EFFECT_API_MAKE_VERSION( major, minor ) (( major ) << 8 | ( minor )) +#define KWIN_EFFECT_API_VERSION_MAJOR 0 +#define KWIN_EFFECT_API_VERSION_MINOR 6 +#define KWIN_EFFECT_API_VERSION KWIN_EFFECT_API_MAKE_VERSION( \ + KWIN_EFFECT_API_VERSION_MAJOR, KWIN_EFFECT_API_VERSION_MINOR ) + /** * @short Base class for all KWin effects *