Add apidox for kwineffects group, showing the necessary steps for
adding a new effect. svn path=/trunk/KDE/kdebase/workspace/; revision=767202
This commit is contained in:
Rivo Laks
parent
f30cbc2e18
commit
5b38737dee
1 changed files with 99 additions and 10 deletions
|
|
@ -38,22 +38,12 @@ along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|||
|
||||
#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 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
|
||||
*
|
||||
|
|
|
|||
Loading…
Reference in a new issue