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

Improve docs for creating KWin effects

Browse source 
- use kcoreaddons_add_plugin CMake macro, the other one is KWin internal
- reference embedded json metadata in section about macros
- Provide codesnippet to json metadata
- Do not explicitly define plugin id in metadata, instead we can derive it from the library name
This commit is contained in:
Alexander Lohnau 2022-07-08 18:34:03 +02:00
parent b97d12efc0
commit e96b9ba499
1 changed files with 24 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

69
src/libkwineffects/kwineffects.h
View file

@ -110,59 +110,38 @@ typedef QList<KWin::EffectWindow *> EffectWindowList;
* This library provides a specialized KPluginFactory subclass and macros to
* create a sub class. This subclass of KPluginFactory has to be used, otherwise
* KWin won't load the plugin. Use the @ref KWIN_EFFECT_FACTORY macro to create the
* plugin factory.
* plugin factory. This macro will take the embedded json metadata filename as the second argument.
*
* @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:
* To build the effect, you can use the kcoreaddons_add_plugin cmake macro which
* takes care of creating the library and installing it.
* The first parameter is the name of the library, this is the same as the id of the plugin.
* If our effect's source is in cooleffect.cpp, we'd use following:
* @code
* KWIN_ADD_EFFECT(cooleffect cooleffect.cpp)
* kcoreaddons_add_plugin(cooleffect SOURCES cooleffect.cpp INSTALL_NAMESPACE "kwin/effects/plugins")
* @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:
* @subsection creating-json-metadata Effect's .json file for embedded metadata
* The format follows the one of the @see KPluginMetaData class.
*
* Example cooleffect.json file:
* @code
* KWIN_ADD_EFFECT(cooleffect cooleffect.cpp)
* install( FILES cooleffect.desktop DESTINATION ${SERVICES_INSTALL_DIR}/kwin )
{
"KPlugin": {
"Authors": [
{
"Email": "my@email.here",
"Name": "My Name"
}
],
"Category": "Misc",
"Description": "The coolest effect you've ever seen",
"Icon": "preferences-system-windows-effect-cooleffect",
"Name": "Cool Effect"
}
}
* @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" for scripted effects
* @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.