Am Montag, 11. Dezember 2006 15:30, schrieb Andreas Hartmetz:
> The list of methods is quite long. It's harder than necessary to find
> what you are looking for and that makes the API harder to use. About
> the 5% that need non-default parameters: it's basically
> act.setDefaultShortcut() vs. act.setShortcut(DefaultShortcut).
> ATM there are 4 convenience methods for every type of shortcut a
> KAction can have (local and global), 8 total. To illustrate, here is
> what they do for local shortcuts:
> activeShortcut() -> shortcut()
> setActiveShortcut() -> setShortcut(ActiveShortcut)
> defaultShortcut() -> shortcut(DefaultShortcut)
> setDefaultShortcut() -> setShortcut(DefaultShortcut)
> In the out-of-date API docs on the web, "active" is still called "custom".
> You can trust me or grep some KDE source tree yourself to see that
> everything except setShortcut() is rarely used.

Instead of grepping locally one can also use http://lxr.kde.org, e.g.
http://lxr.kde.org/ident?i=setActiveShortcut

> For every new kind of trigger we'd need another 4 convenience methods
> to maintain consistency. There will be at least mouse gestures and
> maybe more new triggers...
> Better ordering and grouping of related functions in the docs could
> help, too, if the convenience methods should stay.

That might be a very good idea. Besides the alphabetic listing of methods 
there should be also grouped lists, based on properties or aspects, perhaps 
similar to what the Trolls do.

> Cheers,
> Andreas
>
> 2006/12/11, Matt Rogers <mattr@kde.org>:
> > The purpose of convenience methods is to make it easier on the user to
> > use a piece of API. How does removing these convenience methods affect
> > the ease of use of the API?  What about the other 5% of the use cases
> > that aren't well served by the normal version of the calls with default
> > parameters? What are they supposed to do?

What are the overall costs of convenience methods? Does it help if they are 
only inline functions?

Friedrich