Start of extender API draft

[Rob Scheepmaker]

On Monday 02 June 2008 19:08:31 Kevin Ottens wrote:
> Le Saturday 31 May 2008, Rob Scheepmaker a écrit :
> > On Friday 30 May 2008 18:38:30 Kevin Ottens wrote:
> >
> > Let's first consider the 2 points you make:
> > > 1) If the "detachable widgets" are a new class, I've this feeling that
> > > in the end they'll duplicate quite a lot of Applet features (need for
> > > layout management, config, formfactor, etc.).
> >
> > Ok, detachable widget will do some own config, but I think the
> > duplication will end there. You have to understand that detachable
> > widgets are never meant to exist 'stand alone'. They always are part of a
> > 'host applet'. So when you detach such a widget from an extender, a new
> > extender applet is created right where the widget is dropped, and the
> > detachable widget is added to it. When dropped on an existing applet, it
> > is just added to that applet. And in case the widget needs some applet
> > api (dataEngine for example), the public api of the host applet can be
> > accessed without any trouble. But in most cases dataEngine is the only
> > applet specific api function that needs to be accessed, so why not avoid
> > the overhead of using full applets for detachables?
>
> OK, from a user pov I somehow expected to have them exist standalone
> though.

But a user won't really notice the difference.

> > Let me explain why:
> > 1) We already have quite some nice qgw's in libplasma, and most likely,
> > that collection will become larger over time. Stuff like signalplotters,
> > icons, webcontent, meters, pushbuttons, labels. For a lot of detachables,
> > creating one of those widgets, or maybe a couple which are combined using
> > layouts, is all there is to it. A lot of applets already use these
> > widgets and migration to using extenders for these applets will be very
> > painless, as opposed to having to create a new applet just for using
> > detachables.
>
> Right.

This alone is, I think, reason enough to go the qgw way. My number 1 priority 
is making it as easy as possible for developers to use extenders in their 
applets. For a lot of applets it would complicate things if the developer 
would need to implement a sub applet instead of just being able to throw some 
of the standard plasma widgets through addDetachableWidget and be done with 
it. Implementation might be a little bit more difficult, but I don't think 
there would be a lot of duplication, and it eases the migration path. My goal 
is that a dev shouldn't have to add more then maybe 5-10 lines of code to 
extendify it's applet, because that's the way to achieve quick and massive 
adoption of the concept.

>
> > 2) Other applets which already display 'lists' of items, and which are
> > obvious candidates for extenderification, already use custom implemented
> > QGW's, look for example at the notify applet. Again, migration will be
> > easier here.
>
> I'm not sure which "notify" applet you're referring to. The only one I'm
> thinking of which has a list like that is the device notifier, and it'll be
> a pain to migrate whatever solution you choose. :-)

I mean the one in playground that dimsuz is working on (system notifications). 
The device notifier would indeed be a pain to extendify.

>
> > 3) Most detachables won't need the overhead of being full
> > applet and can use the hostApplet for certain applet api that they do
> > need.
>
> That's where I'm doubtful because of the reload needs.

Well, we always have a host applet that takes care of calling the factory 
provided by the source applet. This shouldn't be that difficult.

>
> > 5) Probably a moot point, but I'm philosophically against using applets
> > for thing that actually don't have any meaning on it's own, which would
> > be the case for quite some detachables. ;)
>
> Well, that's really a matter of personal perception, if that can be
> separated from its applet, be there even if the said applet is not around
> anymore, be moved... that looks a whole lot like an applet. :-)

Except that most detachables are things that you could never add through the 
'add widgets' dialog. Although you could probably hide them in the add widgets 
dialog through an option in the .desktop file. So yes, probably moot, it just 
feels a bit unnatural to me.

>
> > I hope this makes some design decisions clear. Again, please feel free to
> > convince me that I'm entirely wrong here, these kinds of discussion can
> > only benefit all.
>
> You're not entirely wrong if that helps, but just I'm wondering if you're
> going to reinvent quite a few applet facilities for the detachable widgets.

Well that's the main question. I personally think that duplication will be 
minimal, but I agree, I do have to be careful this doesn't get out of hand. 
But I will probably have the basics working soon enough, so I can then always 
reevaluate if there's indeed too much duplication.

>
> Well... if they'd be applet of their own... ;-)
> Otherwise yes, that'd mean a separate factory which would know which applet

(applet = widget)

> to reload. Probably something which could be kept private. Try to keep only
> the single factory method in the public API.

agreed.

> In such a case it could probably be made private. I'm missing the whole
> picture right now to be sure how, but that's a good indication of something
> which shouldn't be public.

Hmm, the detachable widgets should be able to do this move (for when 
detachables get dragged around), so in that case qgw should be friend of 
applet. And this function should at least be protected: applets should be able 
to add detachables of course.

>
> > You're of course free to use it in your applet as
> > well.
> >
> > > I also suspect it's to pass around
> > > widgets between extenders? If I'm right, then it probably makes sense
> > > to make it public.
> >
> > Yes, spot on. :)
>
> After thinking again about it, maybe not... I don't see a case where you
> want to programmatically pass these around. On user interaction that's
> different, but then it could probably be hidden.

Well, it might be useful to have a way to return a detached detachable to it's 
source applet (a 'return to source' button or something like that).

>
> > > >             void setAssociatedExtender(Extender *applet);
> > >
> > > I've no idea what this one is for... I have an extender, why would I
> > > want to associate it with another one?
> >
> > One very common usecase (as explained in the doxygen ;) ) of extenders
> > is: you have an applet. When on the desktop it shows a list of
> > detachables. When in the panel it doesn't have enough room for that and
> > it hides all its detachables in an other extender which appears when you
> > click the applet (of hover or whatever). With this method you can set
> > this extender so detachables move around automagically. Still people
> > should be able to disable this behavior: what if an applet uses multiple
> > extenders for example.
>
> I still don't get why a separate extender would be needed for that...

well the first 'extender' is actually the source applet itself. When on 
desktop it displays all detachables, when in the panel it displays just an 
icon or something like that. The second extender is being used when the source 
applet is in the panel. All detachables move to the second extender (the first 
one only displaying an icon). When the source applet is clicked it opens a top 
level view on that second extender to show its detachables. So that associated 
extender is normally not visible. It's just used as an applet to aim a top 
level view on. I hope I made this a little bit clearer now.
Any idea how I could make this more clear api wise?

>
> > > >             QString sourceAppletName();
> > > >             int sourceAppletId();
> > > >             ExtenderApplet *sourceApplet();
> > >
> > > I would only expect the sourceApplet() method here. All the other ones
> > > can be queried through the sourceApplet itself if I'm not mistaken.
> >
> > Problem here being that, as I explained earlier this mail we don't always
> > have an instance of the source applet since detachables should be able to
> > live on independently. Still we need to know what that applet was to be
> > able to recreate the detachables it spawned.
>
> Well, you also said they never live stand alone (which was your main
> argument to not make them Applets)... So, can they live standalone and
> indeed you don't have those information at hand (and then that means
> sourceApplet() could return 0... from an API stand-point I'd read that as a
> detachable with no source), or they can live standalone and you position
> against Applet might need to be reevaluated.

Detachables always have a host applet (from this pov they are never 
standalone), but that doesn't mean they always have a source applet. The 
source applet is the applet that created the detachable, so when you detach an 
item, and then remove the source applet, they still have a host applet but not 
a source applet. Sorry that I didn't make that more clear in my previous mail.

Again, thanks for this discussion. It really helps me set my mind straight. :)

Cheers,
Rob Scheepmaker