Re: [api-dev] Re: [allfeatures] changed/CWS fwk95 : Extended UNO AWT menu API
Stephan Bergmann wrote: On 01/27/09 09:13, Mathias Bauer wrote: BTW: a keyword unpublished would come in handy here as it could become the hyperlink itself! It seems we did it the wrong way. Not only because of this but also because (as usual!) not the standard way of doing things (the published API) should be marked by a special attribute, but the one off the road (the unpublished API). The rationale for having a published keyword instead of an unpublished one was that actually publishing an API is a deliberate activity. Also, this way the publishing concept could be added backwards-compatibly into UNO rather late in the game. And its safer this way, in that the default (no extra keyword given) case lets you easily fix your mistake and move to the non-default (published keyword added) case, while that is not true the other way around. Granted, all this might be more relevant from the perspective of the API producer than from the perspective of the API consumer. API consumers indeed need to be trained now to look for explicitly published API and ignore implicitly unpublished one. As we are talking about the HTML version of the API we could perhaps use a commentary addition unpublished with the link I mentioned. No need to change the original IDL files. Regards, Mathias -- Mathias Bauer (mba) - Project Lead OpenOffice.org Writer OpenOffice.org Engineering at Sun: http://blogs.sun.com/GullFOSS Please don't reply to nospamfor...@gmx.de. I use it for the OOo lists and only rarely read other mails sent to it. - To unsubscribe, e-mail: dev-unsubscr...@api.openoffice.org For additional commands, e-mail: dev-h...@api.openoffice.org
Re: [api-dev] Re: [allfeatures] changed/CWS fwk95 : Extended UNO AWT menu API
Hi Ariel, Means: If existing API is unpublished, then IMO we should extend it incompatibly, if it becomes a little better / less ugly thereby I've found no way to change its ugliness without breaking API design rules. Don't know what you have in mind. Yes, doing it completely right is impossible without breaking rules. I just suggest to make use of the fact that XMenuExtended is not yet published, and merge everything from XMenuExtended2 into XMenuExtended. This would get us rid of at least one 2 interface. If one really has a lot of time, I would take this opportunity to rename XMenuExtended to XExtendedMenu (or XMenu2 :), since this still sounds like a strange name to me. Of course, if I were left at my own will, I would add every method to XMenu (common to PopupMenu and MenuBar) and XPopupMenu. And it *can* even be discussed if css.awt.MenuBar and css.awt.PopupMenu are *really* published: Technically, they are, and I am not sure making exceptions here is good. I'd prefer this problem being solved in general. And the problem here, as in many other places, is that an old-style service, which effectively describes an *implementation* (rather than an abstract contract), must be able to be adjusted to properly describe the evolving implementation. Ciao Frank -- - Frank Schönheit, Software Engineer frank.schoenh...@sun.com - - Sun Microsystems http://www.sun.com/staroffice - - OpenOffice.org Base http://dba.openoffice.org - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - To unsubscribe, e-mail: dev-unsubscr...@api.openoffice.org For additional commands, e-mail: dev-h...@api.openoffice.org
Re: [api-dev] Re: [allfeatures] changed/CWS fwk95 : Extended UNO AWT menu API
Ariel Constenla-Haile wrote: Hello Juergen, On Sunday 18 January 2009 09:50, Juergen Schmidt wrote: I know my design is awful and looks complicated, but that's the best I could imagine in the current OOo API design/situation; vid. http://wiki.services.openoffice.org/wiki/User:Arielch/Menu_API_Enhancemen t#New_Menu_API_.28and_its_design_problems.29 Today [in d...@openoffice.org] Jürgen suggested an incompatible change and redesign of the toolkit or a complete new one. First and foremost should we make use of the UNO ease of use features, means multiple inheritance, service constructor etc. to make it more comfortable and easier to use. well, this have to be seen in the correct context. If we really think about a replacement of VCL and if we want a clear separation between UI and core via an abstract layer than i would suggest that we start with a incompatible redesign or a new UNO toolkit. And of course we should then allow incompatible changes over years to allow fixing design errors. The awt module is just a reflection of the global situation in OOo API, or how do we interpret things like css.ucb.XSimpleFIleAccess/2/3 ... n? When will it stop? when they reach XSimpleFileAccess30? Of course css.ucb.SimpleFIleAccess/XSimpleFileAccess cannot be changed because they are published, the same goes for css.awt.X/PopupMenu and css.awt.X/MenuBar, so IMHO the published/unpublished concept should be redesign. or it should be used more accurately. An interface that is intended for public use and not published after 4 years is questionable. this is not the underlying problem. Of course it may be confusing for an API client why some API is unplushed after a long time. But once I asked a developer, he answered that leaving a service unpublished was the only way to add functionality as the implementation evolved (instead of declaring this new functionality to be Optional, or design an XSomthing2/3/4...n) i think there is no 100% solution. Sometimes it might be better to let an API as it is even it is not 100% perfect. But changing it would bring only a minimal advantage but a lot of work in many areas. From my point of view API design is a main part of a new feature implementation and we should spent more time on it. We should take it more serious ... An implementation can be changed easier later. OOo API describes an abstract specification, but on the other hand it's not that abstract in the sense that there are different vendor's implementations; in this sense OOo API describes concrete impls. inside OOo project only, so it has to evolve as OOo evolves. Besides evolving, some stablished things may/should be redisign to take advantage of service constructors and multiple inheritance. sure and some of these changes would be possible compatible. Ok compatible in the sense of no necessary changes in client code because a createInstance would still work. With things like XDocument Document.create() to create a new doc. and get access to *all* its functinality XDocument Document.create(URL aURL) to load an existing one form its URL etc. etc. OOo will win more enthusiastic developers. sure i 100% agree and Andreas Schluens has already started to change the document services etc. But all this is a lot of work and often the developers has other priorities. We know the advantages very well at least some of us but we have to find a common agreement. And that is not only an agreement of developers that develop for OO.org but also the ones they work with OO.org or simply use the API. If nobody has problems to adapt the own code from time to time, lets say with a new major version, we can of course start to think about redesigning a lot of API's. The last time i asked how people think about it was at OOCon in Barcelona and the answer was that people (mainly API users) like the compatibility statement and our commitment to compatible API's. But over the time we see more and more disadvantages and we recognize that it becomes impossible to provide good, complete and easy to use API's ... We need a clear and well communicated concept how can handle incompatible API changes and when we want allow them. That includes well documented migration steps, examples etc. Juergen Regards - To unsubscribe, e-mail: dev-unsubscr...@api.openoffice.org For additional commands, e-mail: dev-h...@api.openoffice.org
Re: [api-dev] Re: [allfeatures] changed/CWS fwk95 : Extended UNO AWT menu API
Hi Ariel, first: no offense intended with my mail. I perfectly understand the difficulties of extending an existing ... suboptimal API ... There is one problem with your solution, I don't want that we change an interface (XMenuExtended) incompatible which has been available since four years. Although it's not published yet changing it would be a bad signal for developers who already use the interface. Therefore, from my point of view, the only solution would be to add a new interface providing access to images. uhm - in my opinion, this makes the published concept absurd. If we say a published interfaces cannot be changed, but unpublished ones can, but then don't dare to do the latter ... then just let's say Never change an interface. That's far easier. And no, this is no serious suggestion. I suppose my attitude towards API changes is well known, so I won't start this from the ground here. That's the long-promised responsibility of Jürgen :) In this particular case, one has to ask which problems existing users of this interface would have, if we would add a new base interface, and some new methods. For Basic users, it doesn't matter. For Java clients, it's about re-compilation, at most. For Java implementors (highly unlikely), its about adding new methods to their implementation. For C++, the situation is the same as for Java. So, considering this, I think the expected grief for developers using this interface is nearly 0. (And while we are at it ... is it just me as non-native English speaker who thinks that XFooExtended sounds like ... well, non-native English speakers creating API names? XExtendedFoo, or XFooExtension, or XFoo2, or ... but XFooExtended?) yes, there is the (deprecated) XExtendedToolkit. I just followed the XMenuExtended naming scheme, as it wouldn't make any sense to name XExtendedMenu2 with a XMenuExtended, so I also named XPopupMenuExtended, XMenuBarExtended. Well understood. This doesn't make it sound better :) The awt module is just a reflection of the global situation in OOo API, or how do we interpret things like css.ucb.XSimpleFIleAccess/2/3 ... n? When will it stop? when they reach XSimpleFileAccess30? Well, above, you cited Carsten who argued for making the API uglier (yes!) for the sake of (questionable, in this case at least) API stability. Here, you complain (rightfully) about ugly APIs. You know, the APIs you just created (no offense intended) will be next year's example for ugly APIs :) Means: If existing API is unpublished, then IMO we should extend it incompatibly, if it becomes a little better / less ugly thereby Of course css.ucb.SimpleFIleAccess/XSimpleFileAccess cannot be changed because they are published, the same goes for css.awt.X/PopupMenu and css.awt.X/MenuBar, so IMHO the published/unpublished concept should be redesign. No, you won't get me in joining this discussion here. But you're absolutely right :) Ciao Frank -- - Frank Schönheit, Software Engineer frank.schoenh...@sun.com - - Sun Microsystems http://www.sun.com/staroffice - - OpenOffice.org Base http://dba.openoffice.org - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - To unsubscribe, e-mail: dev-unsubscr...@api.openoffice.org For additional commands, e-mail: dev-h...@api.openoffice.org
Re: [api-dev] Re: [allfeatures] changed/CWS fwk95 : Extended UNO AWT menu API
Hello Frank, On Sunday 18 January 2009 17:08, Frank Schönheit - Sun Microsystems Germany wrote: Hi Ariel, first: no offense intended with my mail. I perfectly understand the difficulties of extending an existing ... suboptimal API ... There is one problem with your solution, I don't want that we change an interface (XMenuExtended) incompatible which has been available since four years. Although it's not published yet changing it would be a bad signal for developers who already use the interface. Therefore, from my point of view, the only solution would be to add a new interface providing access to images. uhm - in my opinion, this makes the published concept absurd. If we say a published interfaces cannot be changed, but unpublished ones can, but then don't dare to do the latter ... then just let's say Never change an interface. That's far easier. And no, this is no serious suggestion. I suppose my attitude towards API changes is well known, so I won't start this from the ground here. That's the long-promised responsibility of Jürgen :) In this particular case, one has to ask which problems existing users of this interface would have, if we would add a new base interface, and some new methods. For Basic users, it doesn't matter. For Java clients, it's about re-compilation, at most. For Java implementors (highly unlikely), its about adding new methods to their implementation. For C++, the situation is the same as for Java. So, considering this, I think the expected grief for developers using this interface is nearly 0. (And while we are at it ... is it just me as non-native English speaker who thinks that XFooExtended sounds like ... well, non-native English speakers creating API names? XExtendedFoo, or XFooExtension, or XFoo2, or ... but XFooExtended?) yes, there is the (deprecated) XExtendedToolkit. I just followed the XMenuExtended naming scheme, as it wouldn't make any sense to name XExtendedMenu2 with a XMenuExtended, so I also named XPopupMenuExtended, XMenuBarExtended. Well understood. This doesn't make it sound better :) The awt module is just a reflection of the global situation in OOo API, or how do we interpret things like css.ucb.XSimpleFIleAccess/2/3 ... n? When will it stop? when they reach XSimpleFileAccess30? Well, above, you cited Carsten who argued for making the API uglier (yes!) for the sake of (questionable, in this case at least) API stability. Here, you complain (rightfully) about ugly APIs. You know, the APIs you just created (no offense intended) will be next year's example for ugly APIs :) haha! I don't feel offended at all, because I was the first to tell myself how ugly it is (back in September 2008 http://wiki.services.openoffice.org/wiki/User:Arielch/Menu_API_Enhancement#New_Menu_API_.28and_its_design_problems.29) Means: If existing API is unpublished, then IMO we should extend it incompatibly, if it becomes a little better / less ugly thereby I've found no way to change its ugliness without breaking API design rules. Don't know what you have in mind. Besides, even if methods were added to the only unpublished interface, XMenuExtended, there will be methods that can not be added here becasue they are PopupMenu specifics (not common to PopupMenu and MenuBar); this means that a XPopupMenuExtended is still needed. Of course, if I were left at my own will, I would add every method to XMenu (common to PopupMenu and MenuBar) and XPopupMenu. And it *can* even be discussed if css.awt.MenuBar and css.awt.PopupMenu are *really* published: do not forget they were added after I open issues http://api.openoffice.org/issues/show_bug.cgi?id=82512 http://api.openoffice.org/issues/show_bug.cgi?id=82514 I doubt to name they published (the time I submited that issues, the only place in OOo source code that used the service name was in the form image control's context menu, even the SDK gui examples use/d the stardiv impl. name). Regards -- Ariel Constenla-Haile La Plata, Argentina Aus der Kriegsschule des Lebens - Was mich nicht umbringt, macht mich härter. Nietzsche Götzendämmerung, Sprüche und Pfeile, 8. - To unsubscribe, e-mail: dev-unsubscr...@api.openoffice.org For additional commands, e-mail: dev-h...@api.openoffice.org
Re: [api-dev] Re: [allfeatures] changed/CWS fwk95 : Extended UNO AWT menu API
And it *can* even be discussed if css.awt.MenuBar and css.awt.PopupMenu are *really* published: do not forget they were added after I open issues http://api.openoffice.org/issues/show_bug.cgi?id=82512 http://api.openoffice.org/issues/show_bug.cgi?id=82514 my mistake when copypaste: i82514 is unrelated (nevertheless it did good, becasue I had forgotten about it) Regards -- Ariel Constenla-Haile La Plata, Argentina Aus der Kriegsschule des Lebens - Was mich nicht umbringt, macht mich härter. Nietzsche Götzendämmerung, Sprüche und Pfeile, 8. - To unsubscribe, e-mail: dev-unsubscr...@api.openoffice.org For additional commands, e-mail: dev-h...@api.openoffice.org
Re: [api-dev] Re: [allfeatures] changed/CWS fwk95 : Extended UNO AWT menu API
Hello Frank,
On Saturday 17 January 2009 19:08, Frank Schönheit - Sun Microsystems Germany
wrote:
Hi Carsten,
With the following we work have been enhanced this API, by extending
it with new interfaces.
+com.sun.star.awt.XMenuExtended2
interface XMenuExtended2
{
interface com::sun::star::awt::XMenuExtended;
interface com::sun::star::awt::XMenu;
...
Given that XMenuExtended is not published, I suggest putting the
extensions made to it via XMenuExtended2 directly into
XMenuExtended. This would noticably reduce the API complexity IMO.
I first proposed that, but Carsten answered (I quote a private mail assuming
his kind permission):
There is one problem with your
solution, I don't want that we change an interface (XMenuExtended)
incompatible which has been available since four years. Although it's
not published yet changing it would be a bad signal for developers who
already use the interface. Therefore, from my point of view, the only
solution would be to add a new interface providing access to images.
(And while we are at it ... is it just me as non-native English speaker
who thinks that XFooExtended sounds like ... well, non-native English
speakers creating API names? XExtendedFoo, or XFooExtension, or XFoo2,
or ... but XFooExtended?)
yes, there is the (deprecated) XExtendedToolkit. I just followed the
XMenuExtended naming scheme, as it wouldn't make any sense to name
XExtendedMenu2 with a XMenuExtended, so I also named XPopupMenuExtended,
XMenuBarExtended.
I know my design is awful and looks complicated, but that's the best I could
imagine in the current OOo API design/situation; vid.
http://wiki.services.openoffice.org/wiki/User:Arielch/Menu_API_Enhancement#New_Menu_API_.28and_its_design_problems.29
Today [in d...@openoffice.org] Jürgen suggested an incompatible change and
redesign of the toolkit or a complete new one. First and foremost should we
make use of the UNO ease of use features, means multiple inheritance,
service constructor etc. to make it more comfortable and easier to use.
The awt module is just a reflection of the global situation in OOo API, or how
do we interpret things like css.ucb.XSimpleFIleAccess/2/3 ... n? When will it
stop? when they reach XSimpleFileAccess30?
Of course css.ucb.SimpleFIleAccess/XSimpleFileAccess cannot be changed because
they are published, the same goes for css.awt.X/PopupMenu and
css.awt.X/MenuBar, so IMHO the published/unpublished concept should be
redesign.
Others FOSS projects are not affraid of incompatible changes, as FOSS is life
and movement not something mummified.
Regards
--
Ariel Constenla-Haile
La Plata, Argentina
Aus der Kriegsschule des Lebens
- Was mich nicht umbringt,
macht mich härter.
Nietzsche Götzendämmerung, Sprüche und Pfeile, 8.
-
To unsubscribe, e-mail: dev-unsubscr...@api.openoffice.org
For additional commands, e-mail: dev-h...@api.openoffice.org
