POLL: wx.DC methods

[Robin]

Hi all,

Ever since I made the changes to the wx.DC methods I've gone back and forth on whether I like it or not. The general consensus on wxPython-dev was that it was a good idea, but since it still hasn't sunk in for me I thought I would try to get opinions from a wider audience.

Please (re)read this section of the MigrationGuide and then vote for one of the following:

http://wxpython.org/MigrationGuide.html#new-wx-dc-methods

A) It's fine as-is, please leave it alone for future versions

B) It stinks, consistency isn't that important. Revert it.

C) Allow both TypeA and TypeB methods to use the same "normal" name.[1]

[1] This is possible using SWIG 1.3's method overloading abilities, but we will lose the use of keyword args for those methods. IOW, both of these will be possible:

  dc.DrawBitmap(bmp, x, y)
  dc.DrawBitmap(bmp, point)

but because of what SWIG has to do to make overloading work you would only be able to use positional args, so this would not be allowed:

  dc.Blit(dest, size, otherDC, src, useMask=True)

If I do (C) then I'll leave the 'XY' versions in place for a few releases as aliases.

···

--
Robin Dunn
Software Craftsman
http://wxPython.org Java give you jitters? Relax with wxPython!

[Jean_Brouwers]

My vote is for A). Or C) iff TypeB is deprecated.

/Jean Brouwers
  ProphICy Semiconductor, Inc.

Robin Dunn wrote:

···

Hi all,

Ever since I made the changes to the wx.DC methods I've gone back and forth on whether I like it or not. The general consensus on wxPython-dev was that it was a good idea, but since it still hasn't sunk in for me I thought I would try to get opinions from a wider audience.

Please (re)read this section of the MigrationGuide and then vote for one of the following:

http://wxpython.org/MigrationGuide.html#new-wx-dc-methods

A) It's fine as-is, please leave it alone for future versions

B) It stinks, consistency isn't that important. Revert it.

C) Allow both TypeA and TypeB methods to use the same "normal" name.[1]

[1] This is possible using SWIG 1.3's method overloading abilities, but we will lose the use of keyword args for those methods. IOW, both of these will be possible:

    dc.DrawBitmap(bmp, x, y)
    dc.DrawBitmap(bmp, point)

but because of what SWIG has to do to make overloading work you would only be able to use positional args, so this would not be allowed:

    dc.Blit(dest, size, otherDC, src, useMask=True)

If I do (C) then I'll leave the 'XY' versions in place for a few releases as aliases.

[Kevin_Altis]

I've been making a stink about this offlist, so I guess I should explain that at least for me this issue is bigger than the DC methods. The fundamental problem is that wxWidgets and wxPython are not consistent about the usage of tuples versus separate x, y or width, height args. This is less of a problem in wxWidgets because C++ supports overloading.

Since wxPython 2.5.x is our opportunity to get the wxPython API "fixed" for the next stable release this is the time to decide whether it is worth the pain of updating all the methods to consistently use tuples or separate args. Tuples (wxPoint, wxSize) are far more common as far as I can tell and is generally what you find for class initialization, some of the wxPython-specific classes are the exception.

For those that have already upgraded to use the new wxDC method calling conventions, you know that changing your old code can be a pain, but even with the pain I'm leaning toward picking tuples and using that everywhere for consistency. Even if wxPython doesn't go this route, PythonCard will almost certainly pick tuples because consistency is more important in the long run and I have a hard time justifying changing all the class inits to use separate x, y and width, height args for position (stupidly abbreviated as pos) and size.

Losing the keyword calling convention doesn't seem acceptable to me. If all of wxPython isn't going to be consistent, then choice B might be better since it means less pain when moving from 2.4.x to 2.5.x/2.6.x but I would prefer wxPython to pick one style and use it everywhere. <puts on flame retardant clothing>

ka

···

On Apr 21, 2004, at 12:31 PM, Robin Dunn wrote:

Hi all,

Ever since I made the changes to the wx.DC methods I've gone back and forth on whether I like it or not. The general consensus on wxPython-dev was that it was a good idea, but since it still hasn't sunk in for me I thought I would try to get opinions from a wider audience.

Please (re)read this section of the MigrationGuide and then vote for one of the following:

http://wxpython.org/MigrationGuide.html#new-wx-dc-methods

A) It's fine as-is, please leave it alone for future versions

B) It stinks, consistency isn't that important. Revert it.

C) Allow both TypeA and TypeB methods to use the same "normal" name.[1]

[1] This is possible using SWIG 1.3's method overloading abilities, but we will lose the use of keyword args for those methods. IOW, both of these will be possible:

  dc.DrawBitmap(bmp, x, y)
  dc.DrawBitmap(bmp, point)

but because of what SWIG has to do to make overloading work you would only be able to use positional args, so this would not be allowed:

  dc.Blit(dest, size, otherDC, src, useMask=True)

If I do (C) then I'll leave the 'XY' versions in place for a few releases as aliases.

--
Robin Dunn
Software Craftsman
http://wxPython.org Java give you jitters? Relax with wxPython!

---------------------------------------------------------------------
To unsubscribe, e-mail: wxPython-users-unsubscribe@lists.wxwidgets.org
For additional commands, e-mail: wxPython-users-help@lists.wxwidgets.org

[Roger_Binns]

Robin Dunn wrote:

Ever since I made the changes to the wx.DC methods I've gone back and
forth on whether I like it or not. The general consensus on
wxPython-dev was that it was a good idea, but since it still hasn't sunk
in for me I thought I would try to get opinions from a wider audience.

I would prefer that wxPython sticks as closely to the documented C++
API as possible. For example, the wx 2.5 C++ doc for DrawBitmap and
DrawArc says:

void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y, bool transparent)
void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, wxCoord xc, wxCoord yc)

There are no *documented* variants taking points/sizes/rects. I assume
from the migration guide that they exist and are in common usage in C++,
but the doc makes no mention of them.

For some there is doc on alternative forms:

void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height)
void DrawEllipse(const wxPoint& pt, const wxSize& size)
void DrawEllipse(const wxRect& rect)

I would expect the first variant to be the most common/useful/normal
and that ties in with the functions that don't document alternatives.

So my vote is that wxPython does whatever variant is documented alone or
first for each method. That may mean fixing wxPython or fixing the
doc - it doesn't matter which to me.

The documentation does appear to be thoroughly consistent for all examples
I looked at (including wx.Window.SetSize) in that the variant taking
individual parts (x, y, width, height etc) come first. Others such as
wx.Window.SetSizeHints only had that variant documented.

Roger

[Roger_Binns]

(I posted my message and opinion before seeing this one)

Kevin Altis wrote:

Tuples (wxPoint, wxSize) are far more common as far as I can tell

How did you come to that conclusion?

and is generally what you find for class initialization,

That is certainly one place where point/size is consistently
documented (as the only way).

In DC, and many other places it is documented the other way round.
I have found a few exceptions, such as

bool wxListCtrl::SetItemPosition(long item, const wxPoint& pos)

Mouse events have both forms, but the method names are different
at the C++ level so that doesn't matter.

Picking another random recent class, HtmlCell is nicely consistent.
The Draw methods take x,y. There is a SetPos that takes x,y.
OnMouseClick takes x,y. There is no GetPos method, but instead
GetPosX, GetPosY, GetWidth, GetHeight, GetDescent.

So I would say that with the exception of constructors, the
documentation exclusively mentions the long (x,y,w,h) form
or mentions it first. I haven't really been able to find a
counter example.

Roger

[Chris_Barker1]

Kevin Altis wrote:

Since wxPython 2.5.x is our opportunity to get the wxPython API "fixed"

What he said!

except a note:

For those that have already upgraded to use the new wxDC method calling conventions, you know that changing your old code can be a pain,

actually, a very small pain, really, thanks to the niftyness of Python:

dc.Acall(x, y, w, h) --> dc.Acall( (x,y), (w,h) )

is very easy.

using that everywhere for consistency.

Either way, consistency is key.

FWIW, I'm going to make FloatCanvas take all (x,y) tuples as well.

Losing the keyword calling convention doesn't seem acceptable to me.

I agree keywords are fabulous!

Roger Binns wrote:

I would prefer that wxPython sticks as closely to the documented C++
API as possible.

I agree, but this is more an issue with the docs. They need to be correct, and they need to have wxPython notes everywhere they are called for. Or we need the wxPython-specific docs...how is that coming?

-Chris

···

--
Christopher Barker, Ph.D.
Oceanographer
                                         
NOAA/OR&R/HAZMAT (206) 526-6959 voice
7600 Sand Point Way NE (206) 526-6329 fax
Seattle, WA 98115 (206) 526-6317 main reception

Chris.Barker@noaa.gov

[Roger_Binns]

Chris Barker wrote:

> I would prefer that wxPython sticks as closely to the documented C++
> API as possible.

I agree, but this is more an issue with the docs. They need to be
correct,

That however contradicts your earlier bit. I think I conclusively
showed that (with the exception of constructors) long forms
(x,y,width,height) as opposed to the short forms (point/rect/tuple)
are the only thing that is documented, or the first thing
documented.

Personally I think "fixing" wxPython to reflect the docs will
be considerably easier and more sensible than changing all the
docs to reflect wxPython. Arguably wxPython 2.4 is already
that way.

And don't forget that the docs are used by C++ programmers and
Perl programmers and any other language they have bindings for.
There is no value in being different than everyone else unless
very necessary.

and they need to have wxPython notes everywhere they are called
for. Or we need the wxPython-specific docs...how is that coming?

My preference would be for wxPython to differ as little as possible
from the standard (ie C++) docs. Obviously some wxPython notes
will be needed, but I don't see the value in being gratuitiously
different even if it is slightly more "Pythonic".

I would much rather participate in a larger wxWidgets community
than a smaller one that is different and language specific.

Roger

[Jean_Brouwers]

Great! Fix the API first and now, since this is *the* chance.

Consistency with wxPython must be the first priority, next
priority is Python affinity and then consistency with the
underlying C/C++ wxWidgets.

The documentation has been incomplete -a work in progress- for
quite while and should be fixed next. But after the API is
done.

/Jean Brouwers
  ProphICy Semiconductor, Inc.

PS) If any class does have methods like GetPosX, GetWidth, etc.
but not GetPos or GetSize, the latter should be added. The
existing ones can stay for a while, obviously.

Chris Barker wrote:

···

Kevin Altis wrote:

Since wxPython 2.5.x is our opportunity to get the wxPython API "fixed"

What he said!

except a note:

For those that have already upgraded to use the new wxDC method calling conventions, you know that changing your old code can be a pain,

actually, a very small pain, really, thanks to the niftyness of Python:

dc.Acall(x, y, w, h) --> dc.Acall( (x,y), (w,h) )

is very easy.

using that everywhere for consistency.

Either way, consistency is key.

FWIW, I'm going to make FloatCanvas take all (x,y) tuples as well.

Losing the keyword calling convention doesn't seem acceptable to me.

I agree keywords are fabulous!

Roger Binns wrote:

I would prefer that wxPython sticks as closely to the documented C++
API as possible.

I agree, but this is more an issue with the docs. They need to be correct, and they need to have wxPython notes everywhere they are called for. Or we need the wxPython-specific docs...how is that coming?

-Chris

[Jean_Brouwers]

Roger,

Your point is well taken, but the issue lies with the
wxWidget documentation.

If you check the include/wx/dc.h source file, nearly
every wx.DC method is available in both versions, with
individual x, y, w, h, etc. arguments and with point,
size, some with rect arguments.

But the current documentation shows one the first form.
That is clearly an issue and has been one for quite a
while, it seems. The documentation should be fixed,
not for wxPython, but for all wxWidget bindings, in
particular the native C++ one.

/Jean Brouwers
  ProphICy Semiconductor, Inc.

Roger Binns wrote:

···

Chris Barker wrote:

I would prefer that wxPython sticks as closely to the documented C++
API as possible.

I agree, but this is more an issue with the docs. They need to be
correct,

That however contradicts your earlier bit. I think I conclusively
showed that (with the exception of constructors) long forms
(x,y,width,height) as opposed to the short forms (point/rect/tuple)
are the only thing that is documented, or the first thing
documented.

Personally I think "fixing" wxPython to reflect the docs will
be considerably easier and more sensible than changing all the
docs to reflect wxPython. Arguably wxPython 2.4 is already
that way.

And don't forget that the docs are used by C++ programmers and Perl programmers and any other language they have bindings for.
There is no value in being different than everyone else unless
very necessary.

and they need to have wxPython notes everywhere they are called
for. Or we need the wxPython-specific docs...how is that coming?

My preference would be for wxPython to differ as little as possible
from the standard (ie C++) docs. Obviously some wxPython notes
will be needed, but I don't see the value in being gratuitiously
different even if it is slightly more "Pythonic".

I would much rather participate in a larger wxWidgets community
than a smaller one that is different and language specific.

Roger

---------------------------------------------------------------------
To unsubscribe, e-mail: wxPython-users-unsubscribe@lists.wxwidgets.org
For additional commands, e-mail: wxPython-users-help@lists.wxwidgets.org

[Robin]

Roger Binns wrote:

Robin Dunn wrote:

Ever since I made the changes to the wx.DC methods I've gone back and
forth on whether I like it or not. The general consensus on
wxPython-dev was that it was a good idea, but since it still hasn't sunk
in for me I thought I would try to get opinions from a wider audience.

I would prefer that wxPython sticks as closely to the documented C++
API as possible.

Would your preference change if there was full Python specific reference docs available within a few months?

···

--
Robin Dunn
Software Craftsman
http://wxPython.org Java give you jitters? Relax with wxPython!

[Robin]

Chris Barker wrote:

I agree, but this is more an issue with the docs. They need to be correct, and they need to have wxPython notes everywhere they are called for. Or we need the wxPython-specific docs...how is that coming?

Quite well actually.

I made a mental shift this week that is making it seem much more possible to reach the very bright light at the end of the tunnel than before. I decided that instead of using the metadata produced by SWIG to generate something that epydoc can grok, that I would take epydoc out behind the woodshed teach it a few new tricks so it can grok the raw .py modules produced by SWIG with my docstring patches. So far, I've given epy the ability to dynamically skip garbage in the module that shouldn't be documented, and to always try getting the function signature from the docstring first and then use introspection it there isn't one in the docstring. This lets it document the real args instead of the very unhelpful "(*args, **kwargs)" that is in the python wrapper method.

There are still a few more things that need done, but to help satisfy your curiousity (or to just make you slobber uncontrollably) I've put a couple sample files here:

http://alldunn.com/wxPython/apitest/

Don't worry about content yet, just the structure and the metadata. Once that is all figured out then the content will come over time in several iterations.

···

--
Robin Dunn
Software Craftsman
http://wxPython.org Java give you jitters? Relax with wxPython!

[Roger_Binns]

Robin Dunn wrote:

Roger Binns wrote:
> I would prefer that wxPython sticks as closely to the documented C++
> API as possible.

Would your preference change if there was full Python specific reference
docs available within a few months?

Nope. You seem to be implying that wxPython must be different for
some unstated reason. What is actually broken with the documented
C++ api? And if it is broken, will it be fixed or will wxPython
have different documentation and be "fixed"?

Even though I have been doing wxPython for almost 2 years, I still have
documentation open all the time, and use it regularly. A frequently
stated compliant is that the documentation isn't that good. (I don't
agree but that is just my opinion).

I don't see the benefit of wxPython doing its own thing. A wiki for
all wxWidgets programmers is better than a seperate one for each language.
For example look at section 3 of
http://wiki.wxpython.org/index.cgi/Frequently_20Asked_20Questions

Note how few of the questions are actually Python specific. Obviously
there are some Python specific things. I consider myself a wxWidgets
programmer first, and wxPython second.

Roger

[Roger_Binns]

http://alldunn.com/wxPython/apitest/

It is looking nice.

Have you considered HTMLizing the demo code? I think it
would be great if each class had a URL pointing to some
demo code so you could see how it is all used, or you
could include it inline in the doc for the class. Bonus points
for pointers attached to methods showing how to use them

The biggest problem with the epydoc style documentation
is that it is terse UNIX man page style, sort of like a
language dictionary. Often people want an idea of context
(eg following the analogy, how to use a word in a sentence
rather than just the literal definition).

I think the demo provides that, and although not all the
demo code is the best example, it is certainly complete
and a lot better than nothing.

Roger

[Grimmtooth]

Kevin Altis wrote:

Losing the keyword calling convention doesn't seem acceptable to me. If all of wxPython isn't going to be consistent, then choice B might be better since it means less pain when moving from 2.4.x to 2.5.x/2.6.x but I would prefer wxPython to pick one style and use it everywhere. <puts on flame retardant clothing>

OK, I agree, for the most part, mostly since I'm a heartless prima donna that dings the coders in my department for inconsistent and non style guide compliant coding practices on a routine basis. But we all gotta have hobbies.

Seriously, though. I hate the whole tuples thing from a personal standpoint. I hate the 'proportion' keyward for sizers. I prefer 'pos' to 'position'. These have a common theme: more typing on my part.

But from a coding standpoint, the tuples and those keywords are superior because they convey more meaning during code review, or coming back to old code months later. And being a tin plated prima donna on these matters, I simply have to eat my own dog food here It's more typing, and sometimes trips up the creative flow a bit, but I think in the long run it will pay off.

Actually, I prefer wx.Point and wx.Size to tuples because they convey *more* meaning. But if I gather correctly, the new does not preclude using them. (Plus, wx.Point's internal math methods are pretty slick)

*However*

A very good point was raised somewhere about consistency with the formal docs for wxWidgets. I have a real problem going against the docs, though good release notes with thorough documentation of exceptions will do a lot to alleviate that. For me, keeping in tune with 'spec' (in this case, docs) is a very high priority (as is correcting errant docs to comply with actual code that is in place).

... Let not the sands of time get in your lunch.

[Paul_McNett]

Roger Binns writes:

> Would your preference change if there was full Python
> specific reference docs available within a few months?

Nope. You seem to be implying that wxPython must be
different for some unstated reason. What is actually broken
with the documented C++ api? And if it is broken, will it be
fixed or will wxPython have different documentation and be
"fixed"?

My opinion is perhaps worth little around gurus such as
yourselves, but I'd just like to chime in and say a couple
things anyway.

1) wxWidgets rocks, but the API really sucks and is inconsistent
in naming, argument position, what is implemented in various
widgets versus others, etc. The documentation is very good
actually.

2) Python rocks, and natively does a better job of handling all
kinds of things that wxWidgets has to implement to come even
close to being useful for C++ use. For instance, wx.Point is a
really important invention for C++ use but thanks to the
wxPython implementation I can just pass a tuple which is way
easier.

3) The API for wxPython seems to be getting more consistent and
to make more sense from a Python programmers point of view,
both very good things. Hearing that there is wxPython-specific
documentation in the works is icing on the cake.

I've used DC's very little so far, but in general I agree with
the changes being made of late to wxPython, and can't wait to
see more. While I can see your point of wanting the API to be
consistent with wxWidgets, I think it is more important for the
wxPython API to be more Pythonic than it is to maintain
consistency with wxWidgets, especially considering it is
impossible anyway.

Now, obviously there is a balance. It would be wrong to rename
or reorder things without good reason. But sending (x,y)
instead of x,y is just way more intuitive to this Python
hugger, so in that case it trumps the wx API IMO.

Anyway, I'll retreat humbly now.

···

--
Paul

[Grimmtooth]

Paul McNett wrote:

3) The API for wxPython seems to be getting more consistent and to make more sense from a Python programmers point of view, both very good things. Hearing that there is wxPython-specific documentation in the works is icing on the cake.

A nice point to offer to something Roger was talking about. While we are implementing a Python wrapper around wxWidgets, and thus in many ways want to be consistent with wxWidgets, a very good point can be made that we need to remember the PYTHON part of wxPython.

In other words, perhaps we shouldn't lose the Pythonic goodness for the sake of *external* consistency if the Pythonic idioms make more sense to a Python programmer. Let's not think so much about "how it looks to a wxWidgets programmer using Python" and more about "how it looks to a Python programmer implementing a GUI".

The big can of worms here is, of course, documentation. This puts demands on code documentation unlike anything that has been required before in wxPython. Rather than rely on the external documentation for everything, with a few tweaks here and there, strict attention has to be paid to what is and is not generally consistent, and clearly documented. If it can't be done well, it's not going to get us much beyond where we're at right now, in some cases (i.e. sometimes it's unclear if a class is implemented in wxPython or not, or we have wxPython classes and methods that are not documented in the main docs and which are not evident without source inspection).

Anyway, I'll retreat humbly now.

Nope, stand up there and bask in the warm soapy flames

... Never drink coffee that's been anywhere near a fish.

[Roger_Binns]

Jeff Grimmett wrote:

A nice point to offer to something Roger was talking about. While we are
implementing a Python wrapper around wxWidgets, and thus in many ways
want to be consistent with wxWidgets, a very good point can be made that
we need to remember the PYTHON part of wxPython.

That is certainly the case, and I don't think anyone argues against
that. For example the choices parameter when constructing a ComboBox
is a Python list, but in C++ is a pointer and count. In Perl it would
be whatever Perl does.

The same goes for strings. They are the "native" representation in
each programming language.

In other words, perhaps we shouldn't lose the Pythonic goodness for the
sake of *external* consistency if the Pythonic idioms make more sense to
a Python programmer. Let's not think so much about "how it looks to a
wxWidgets programmer using Python" and more about "how it looks to a
Python programmer implementing a GUI".

The stuff that started all this are methods which could be called in
several ways:

1 DrawBitmap(bmp, x, y)
2 DrawBitmap(bmp, wx.Point(x,y))
3 DrawBitmap(bmp, (x,y)) # Python only

(1) is the only one that is exclusively documented, or documented first.
(2) is apparently available in C++ but not documented or documented second.
(3) is a Pythonic representation of (2) and not present in C++. (I'll
consider 2 and 3 the same thing from here on).

I certainly don't think that 1 or 2/3 is more Pythonic. In fact
I don't know any programming language where I would call one
of them way better suited to the language.

Given the preference in the documentation for the first form,
and the lack of any big "Pythonic" differences between the two
forms, I say pick the form in the documentation. Or change
the preferred form in the doc and then change wxPython to
match it.

Roger

[Chris_Barker1]

Robin Dunn wrote:

There are still a few more things that need done, but to help satisfy your curiousity (or to just make you slobber uncontrollably) I've put a couple sample files here:

http://alldunn.com/wxPython/apitest/

OK I'm slobbering...This is wonderful! I really like that the inherited methods are all listed.

And you've got FloatCanvas listed as a know subclass of wx.Panel, I can't help but be flattered by the recognition. Very nice work, Robin (and others that helped)

-Chris

···

--
Christopher Barker, Ph.D.
Oceanographer
                                         
NOAA/OR&R/HAZMAT (206) 526-6959 voice
7600 Sand Point Way NE (206) 526-6329 fax
Seattle, WA 98115 (206) 526-6317 main reception

Chris.Barker@noaa.gov

[Chris_Barker1]

Roger Binns wrote:

I think it
would be great if each class had a URL pointing to some
demo code so you could see how it is all used,

That would be very nice, but a bit tricky for very well used classes, like wx.Panel, as there are a million examples...

-Chris

···

--
Christopher Barker, Ph.D.
Oceanographer
                                         
NOAA/OR&R/HAZMAT (206) 526-6959 voice
7600 Sand Point Way NE (206) 526-6329 fax
Seattle, WA 98115 (206) 526-6317 main reception

Chris.Barker@noaa.gov

[Chris_Barker1]

Jeff Grimmett wrote:

A very good point was raised somewhere about consistency with the formal docs for wxWidgets. I have a real problem going against the docs,

I think we all agree with this, but poor docs shouldn't be considered a standard. The fact that the wxWidgets docs leave out standard methods should be corrected by putting them in the docs, not by making wxPython conform to what is essentially an arbitrary standard: what happens to be in the C++ docs.

How hard is it to add the discussed methods to the C++ docs? If that gets done, then we can all stop arguing about that, and focus on which of the overloaded C++ methods wxPython should support.

Personally, I like the "new" way, as I pass in (2,) sized Numeric arrays of integers, and passing in "Point[0], Point[1]", is much uglier than "Point".

-Chris

···

--
Christopher Barker, Ph.D.
Oceanographer
                                         
NOAA/OR&R/HAZMAT (206) 526-6959 voice
7600 Sand Point Way NE (206) 526-6329 fax
Seattle, WA 98115 (206) 526-6317 main reception

Chris.Barker@noaa.gov