yukijoou/kwin
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add apidox for kwineffects group, showing the necessary steps for

Browse source 
adding a new effect.

svn path=/trunk/KDE/kdebase/workspace/; revision=767202
This commit is contained in:
Rivo Laks 2008-01-27 14:43:05 +00:00
parent f30cbc2e18
commit 5b38737dee
1 changed files with 99 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

109
lib/kwineffects.h
View file

@ -38,22 +38,12 @@ along with this program. If not, see <http://www.gnu.org/licenses/>.
#include <assert.h> #include <assert.h>
/** @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 KLibrary;
class KConfigGroup; class KConfigGroup;
class KActionCollection; class KActionCollection;
class QKeyEvent; class QKeyEvent;
/** @defgroup kwineffects KWin effects library */
namespace KWin namespace KWin
{ {
@ -75,6 +65,105 @@ typedef QPair< Effect*, Window > InputWindowPair;
typedef QList< EffectWindow* > EffectWindowList; 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 * @short Base class for all KWin effects
* *