kwin/clients/PORTING
Luboš Luňák f52b8e48cd branches/work/kwin_composite becomes new trunk kwin.
svn path=/trunk/KDE/kdebase/workspace/; revision=659202
2007-04-29 17:35:43 +00:00

159 lines
7.8 KiB
Text

It's suggested you check sources of some KDE CVS decoration if in doubts or in need of an example.
Also, the API is documented in the .h header files.
Makefile.am:
- Change kwin_ to kwin3_ (in LDFLAGS, LIBADD, kde_module_LTLIBRARIES, SOURCES).
- Make sure LDFLAGS contains $(KDE_PLUGIN) and -module .
- Add -lkdecorations to LIBADD.
- Do NOT rename the directory where the .desktop file is installed ( $(kde_datadir)/kwin/ ).
.desktop file:
- Change kwin_ to kwin3_ in X-KDE-Library.
Sources:
- There are no kwin/something.h includes, and don't use the KWinInternal namespace.
- Use QToolTip instead of KWinToolTip.
- Use QButton instead of KWinButton, QToolButton instead of KWinToolButton and QWidget
instead of KWinWidgetButton.
- For tooltips, use simply QToolTip::add().
- Change Client* to MyClient* (or whatever is your main client class) in your MyButton.
- Pass parent->widget() to QButton constructor in your MyButton constructor.
- Make your MyClient class inherit from KDecoration instead of Client.
- Make MyClient constructor take KDecorationBridge* and KDecorationFactory* as arguments,
and pass these arguments to KDecoration constructor.
- Except for data members initialization, make the constructor empty, move everything
to void MyClient::init().
- As the first thing in init(), call createMainWidget(); if your client class took some
flags such as WResizeNoErase, pass them to this function.
- Then, do 'widget()->installEventFilter( this );'.
- Implement MyClient::eventFilter() - as MyClient is now no longer QWidget, you need the event
filter to call all the functions that used to be called directly. Usually, it's something
like:
=====
bool MyClient::eventFilter( QObject* o, QEvent* e )
{
if ( o != widget() )
return false;
switch ( e->type() )
{
case QEvent::Resize:
resizeEvent( static_cast< QResizeEvent* >( e ) );
return true;
case QEvent::Paint:
paintEvent( static_cast< QPaintEvent* >( e ) );
return true;
case QEvent::MouseButtonDblClick:
mouseDoubleClickEvent( static_cast< QMouseEvent* >( e ) );
return true;
case QEvent::Wheel:
wheelEvent( static_cast< QWheelEvent* >( e ));
return true;
case QEvent::MouseButtonPress:
processMousePressEvent( static_cast< QMouseEvent* >( e ) );
return true;
case QEvent::Show:
showEvent( static_cast< QShowEvent* >( e ) );
return true;
default:
return false;
}
}
=====
- In MyClient, 'this' will have to be often replaced with 'widget()', pay special attention
to cases where this won't cause compile error (e.g. in connect() calls, which take QObject* ).
- Also, many calls may need 'widget()->' prepended.
- Layout is created in init(), so call createLayout() directly there (if it's implemented).
- Remove calls to Client methods (Client::resizeEvent() and so on).
- Replace Options:: with KDecorationOptions:: .
- Replace 'options' with 'options()' in MyClient (which is KDecoration::options()), if often used
outside of MyClient, you may want to create (this assumes your code is in its namespace):
=====
inline const KDecorationOptions* options() { return KDecoration::options(); }
=====
- Options for colors need 'Color' prepended (e.g. 'ColorButtonBg').
- Replace miniIcon() with getting the right pixmap from icon() (usually
'icon().pixmap( QIcon::Small, QIcon::Normal )' ).
- Replace stickyChange() with desktopChange(), and test isOnAllDesktops().
- Replace Sticky with OnAllDestops.
- Replace iconify with minimize.
- Change activeChange(bool) to activeChange(), and use isActive() to check the state.
Similar for desktopChange, captionChange(), iconChange(), maximizeChange().
- Replace 'contextHelp()' with 'showContextHelp()'.
- WindowWrapperShowEvent() is gone, simply use showEvent() filtered by the event filter if needed.
- Change 'animateIconifyOrDeiconify()' to 'animateMinize()', if it's empty, simply remove it.
Make sure it doesn't reenter the event loop (no kapp->processEvents()).
- Buttons should use explicit setCursor() if they don't want cursor set by mousePosition().
I.e. usually call setCursor( ArrowCursor ) in your MyButton.
- In the part where you insert windowWrapper() into the layout, i.e. something like
=====
layout->addWidget( windowWrapper());
=====
replace it with something like
=====
if( isPreview())
layout->addWidget( new QLabel( i18n( "<center><b>MyDecoration</b></center>" ), widget()));
else
layout->addItem( new QSpacerItem( 0, 0 ));
=====
- Implement MyClient::minimumSize().
- Handling maximization - to change vertical or horizontal maximalization, use e.g.
'maximize( maximizeMode() ^ MaximizeVertical', to change normal maximalization, i.e. after
left-clicking on the button, use
'maximize( maximizeMode() == MaximizeFull ? MaximizeRestore : MaximizeFull );' (which also
means that there's also no maximize() slot).
Also, if your decoration button has only two visual states representing the maximalization state,
it's recommended that it shows the maximized state only for MaximizeFull state.
- Make sure the decoration matches the window state after init() is finished, that is, that
the buttons represent correctly the maximalization, on-all-desktops etc. states. As the
simplest solution, you can call maximizeChange(), desktopChange(), etc. at the end
of init().
- Use 'titlebarDblClickOperation()' for performing the application after doubleclicking
the titlebar.
- Implement borders() returning the width of the top,left,right and bottom border. You may
check values like 'maximizeMode() == MaximizeFull && !options()->moveResizeMaximizedWindows()'
to check whether you can disable some borders completely.
Note that your painting code must of course match these sizes.
- If your code uses XGrabServer() or XUnGrabServer(), replace them with (un)grabXServer().
- In cases where you call some function from the KDecoration API that can possibly destroy
the decoration (e.g. showWindowMenu() or closeWindow()), make sure to use exists() if some more
code will follow this call. Refer to showWindowMenu() documentation for an example.
- Create class MyFactory inheriting from KDecorationFactory, and move the code that was
in 'extern "C"' to it: From init() to constructor, from deinit() to destructor, from allocate()
or create() to createDecoration(). Pass the KDecorationBridge* argument and 'this' to created
MyClient objects. If createDecoration() needs to know the window type (e.g. it used the tool
argument), use windowType() similarly like in KDecoration, and pass it the KDecorationBridge*
argument.
- Add something like this:
=====
extern "C"
{
KDecorationFactory *create_factory()
{
return new MyNamespace::MyFactory();
}
}
=====
- The reset handling has changed: There's no signal resetClients(), and no
slotResetAllClientsDelayed(). If your MyClient has some slotReset(), make it
reset( unsigned long ), where the argument is mask of things that have changed ( SettingXYZ ).
If you have some global function that handles resetting, make it
MyFactory::reset( unsigned long ). Try to minimize the effects of the changed things,
e.g. if only the color setting has changed, doing a repaint is often enough, and there's no need
to recreate the decorations. If you need to recreate the decorations, return true
from MyFactory::reset(), otherwise, you may call resetDecorations() to call reset() in all
MyClient instances.
- Implement resize() to resize the decoration to the given size
(usually 'widget()->resize( s );' is enough).
- Review mousePosition() if it's implemented. Position constants need 'Position' prepended,
e.g. Top -> PositionTop.
- Note that you cannot use "appdata" with KStandardDirs, as the decoration will be used
also in other applications than kwin.
- Implement all missing pure virtual functions. For mousePosition(), you may call
KDecoration::mousePosition() if it's sufficient.