Wrong (?) usage of deprecated and usage of setActiveWindow vs. activateWindow (was: Re: kdelibs/kdecore)

[Lubos Lunak]

On Saturday 25 of October 2003 15:56, Ingo Klöcker wrote:
> On Thursday 23 October 2003 19:48, Luboš Luňák wrote:
> > --- kdelibs/kdecore/kwin.h  #1.81:1.82
> > @@ -101,8 +101,9 @@ public:
> >      static void setActiveWindow( WId win, long time );
> >      /**
> > -     * @overload
> > +     * @deprecated Consider using activateWindow(), use
> > setActiveWindow() +     * only if necessary.
> >       */
> >      // KDE4 merge with above with time = 0
> > -    static void setActiveWindow( WId win );
> > +    static void setActiveWindow( WId win ) KDE_DEPRECATED;
> >
> >      /**
>
> Why is setActiveWindow( WId win ) deprecated? Why do we have to call
> setActiveWindow( WId win, long time ) explicitely with time = 0? The
> comment "KDE4 merge with above with time = 0" suggests that you want to
> replace
>       static void setActiveWindow( WId win, long time );
> by
>       static void setActiveWindow( WId win, long time = 0 );
> in KDE 4. But this means that setActiveWindow( someWinId ) will again be
> okay in KDE 4 which isn't what "deprecated" means. AFAIK "deprecated"
> must only be used for function calls which will no longer work in a
> later release. But setActiveWindow( someWinId ) will still work AFAIU
> the comment about KDE 4.

 The point is that you usually don't have to call setActiveWindow() at all. 
That's why the comment next to @deprecated says what it says. The intention 
of marking the call as deprecated was that people will see the warning, will 
read the comment, and will update the app as necessary (I guess I'm naive). 
And the comment about the KDE4 merging should have ?? at the end.

 Using KDE_DEPRECATED that way probably is not exactly the way it's supposed 
to be, but I have no idea how to do it differently.

>
> Apart from that it's absolutely unclear to me whether I should use
> activateWindow or setActiveWindow in the following use cases in KMail:

 Hmm, is the description of KWin::activateWindow() not clear enough? Not that 
it really explains the matter in detail, because it can get a bit complicated 
and it wouldn't quite fit there - an attempt to explain that in detail is a 
section in kdebase/kwin/README.

> 1. The user clicks on KMail's system tray icon -> KMail's main window
> should be activated.

 Use KSystemTray.

> 2. The user wants to search for messages and presses 's'. In case the
> search window is already open it should be activated.

 "applications should use activateWindow()"

> 3. The user starts KMail a second time

 Hmm, the a bit complicated case. Use KUniqueApplication. If you insist on 
doing it yourself for some strange reason, consult 
KStartupInfo::setNewStartupId().

> or the dcop call openReader is
> used -> KMail's main window should be activated.

 Even more complicated, probably worth reading the relevant part of kwin's 
README. I don't know what openReader() is exactly supposed to be. You'll have 
to explain what it is, or you'll have to consult the README. Maybe both ... I 
invented this stuff few months back, and I'm still unsure about few details 
myself.

-- 
Lubos Lunak
KDE developer
---------------------------------------------------------------------
SuSE CR, s.r.o.  e-mail: l.lunak at suse.cz , l.lunak at kde.org
Drahobejlova 27  tel: +420 2 9654 2373
190 00 Praha 9   fax: +420 2 9654 2374
Czech Republic   http://www.suse.cz/