← Back to branch summary

~ubuntu-branches/ubuntu/utopic/kde-workspace/utopic-proposed

« back to all changes in this revision

Viewing changes to plasma/design/containmentactions

  • Committer: Bazaar Package Importer
  • Author(s): Michał Zając
  • Date: 2011-07-09 08:31:15 UTC
  • Revision ID: james.westby@ubuntu.com-20110709083115-ohyxn6z93mily9fc
Tags: upstream-4.6.90
Import upstream version 4.6.90

Show diffs side-by-side

added added

removed removed

Lines of Context:
plasma/design/containmentactions
 
1
ContainmentActions
 
2
==========
 
3
 
 
4
Overview
 
5
--------
 
6
"ContainmentActions" are components that respond to mouse events, usually by either performing an
 
7
action or showing a menu with multiple actions.
 
8
 
 
9
Timeline
 
10
--------
 
11
Introduced in: libplasma x.x (KDE 4.4.0)
 
12
 
 
13
Component Type
 
14
--------------
 
15
ContainmentActions are plugins of ServiceType Plasma/ContainmentActions.
 
16
 
 
17
Component Description
 
18
---------------------
 
19
ContainmentAction plugins are registered using .desktop files. These files should be
 
20
named using the following naming scheme:
 
21
 
 
22
    plasma-containmentactions-<pluginname>.desktop
 
23
 
 
24
If a containmentactions plugin provides a configuration UI,
 
25
it should include the line X-Plasma-HasConfigurationInterface=true.
 
26
 
 
27
All other entries should follow the standard .desktop specification,
 
28
supplemented by the standard KPluginInfo keys.
 
29
 
 
30
Component API
 
31
-------------
 
32
Subclasses: QObject
 
33
 
 
34
*** Key Methods ***
 
35
 
 
36
        void contextEvent(QEvent *event);
 
37
Implement this method to get events. you'll probably want to check the event type and send different
 
38
events to your own methods; see the plugins in workspace for examples.
 
39
Currently you can expect to get mouse press, release, and wheel events.
 
40
If you're showing a menu you should use MousePress and ignore MouseRelease.
 
41
If you're performing an immediate action you should ignore MousePress and use MouseRelease.
 
42
 
 
43
The incoming event will always have the buttons and modifiers that the user configured as the trigger, so
 
44
there's no sense in checking those values.
 
45
 
 
46
        void init(const KConfigGroup &config);
 
47
Do whatever initialization is needed here (not in the constructor).
 
48
 
 
49
A configuration UI can optionally be provided by overloading the configuration methods:
 
50
        QWidget* createConfigurationInterface(QWidget* parent);
 
51
        void configurationAccepted();
 
52
        void save(KConfigGroup &config);
 
53
 
 
54
when configurationAccepted is called, you should read from your config UI and extract all your data
 
55
from it; the UI may be deleted after the function returns.
 
56
when save is called, save that data to the provided config group.
 
57
 
 
58
if your plugin needs to be configured before it is useful, call setConfigurationRequired() from
 
59
init().
 
60
 
 
61
Containment Interface
 
62
---------------------
 
63
The Containment class supports loading and using containmentactions plugins.
 
64
Subclasses need do nothing to get this support. If a subclass has extra actions it wants in the
 
65
contextmenu, it can provide them in contextualActions() the same as before - but there's no longer
 
66
any need to return standard actions like "add widgets" and "run command".
 
67
 
 
68
ContextActions plugins to use are set using the setContainmentActions(const QString &trigger, const QString &pluginName)
 
69
method. an empty string removes any plugin set for the given trigger.
 
70
Trigg format is determined by the static function ContextActions::eventToString().
 
71
 
 
72
User Configuration
 
73
------------------
 
74
It is up to the host application to provide a configuration interface, such
 
75
as a dialog, to the user.
 
76
 
 
77
*** Plasma Desktop Implementation ***
 
78
 
 
79
A settings dialog is provided for the DesktopView (a second page in the same dialog as the wallpaper)
 
80
 
 
81
This dialog allows selecting one trigger for each installed plugin.
 
82
 
 
83
Future Work
 
84
-----------
 
85
* Current UI in shells/desktop/ needs work.
 
86