More wiki changes

Daniel_Carrera · January 15, 2010, 10:09pm

Hi Robin,

Thanks for your reply. It was very informative.

Ok, so we definitely want to remove SetSizerAndFit since that will not always do the right thing. I noticed that someone reverted the change where I put SetSizerAndFit in the examples. Was that you? What would you recommend we teach to new users?

I just did a search for SetSizer and I found two blocks:

# Block 1
self.SetSizer(self.sizer)
self.SetAutoLayout(1)
self.sizer.Fit(self)

···

------

# Block 2
mainSizer.Add(hSizer, 0, wx.ALL, 5)
mainSizer.Add(self.button, 0, wx.CENTER)
self.SetSizerAndFit(mainSizer)

These have to be made consistent. How about:

# Block 1
self.SetSizer(self.sizer)
self.sizer.Fit(self)

# Block 2
mainSizer.Add(hSizer, 0, wx.ALL, 5)
mainSizer.Add(self.button, 0, wx.CENTER)
self.SetSizer(mainSizer)
mainSizer.Fit(self)

In the first block I removed SetAutoLayout(1) and in the other I replaced SetSizerAndFit(mainSizer). Now the two blocks are consistent. Is this what you would recommend we teach new users?

Daniel.

Robin Dunn wrote:

On 1/14/10 10:10 PM, Daniel Carrera wrote:

Could you make a decision about this comment:

Getting Started - wxPyWiki

The SetAutoLayout is redundant, as it is set to True when SetSizer is called and I've never seen anybody use code that actually turns it off. So I always tell people to not bother with SetAutoLayout. If you want to remove all occurrences of it in the wiki pages you are working on then it would probably be a good thing.

SetSizerAndFit is a different can of worms that boils down to the fact that it is not the same thing as:

    window.SetSizer(sizer)
    sizer.Fit(window)

In actuality it is essentially the same as:

    window.SetSizer(sizer)
    sizer.SetSizeHints(window)

which means that not only will window be resized to fit the size needed by the sizer, but the window's minsize will also be set to that size, and that is often *not* what is wanted. For example if the content of the widgets in the sizer could ever change in a way that the sizer's best size will be smaller than what it is at the beginning, then you'll want to allow it to become smaller. So it is not often that I use SetSizerAndFit, and it is usually the first thing I change when dealing with layout problems in other people's code. IMO 99% of the time it is better to just use SetSizer everywhere and then only for the top-level window use window.Fit if you want it to start out being exactly the right size for the content.

Robin · January 15, 2010, 10:53pm

Hi Robin,

Thanks for your reply. It was very informative.

Ok, so we definitely want to remove SetSizerAndFit since that will not
always do the right thing. I noticed that someone reverted the change
where I put SetSizerAndFit in the examples. Was that you?

No. Look at the page info to see the change log.

What would you
recommend we teach to new users?

I just did a search for SetSizer and I found two blocks:

# Block 1
self.SetSizer(self.sizer)
self.SetAutoLayout(1)
self.sizer.Fit(self)
------

# Block 2
mainSizer.Add(hSizer, 0, wx.ALL, 5)
mainSizer.Add(self.button, 0, wx.CENTER)
self.SetSizerAndFit(mainSizer)

These have to be made consistent. How about:

# Block 1
self.SetSizer(self.sizer)
self.sizer.Fit(self)

# Block 2
mainSizer.Add(hSizer, 0, wx.ALL, 5)
mainSizer.Add(self.button, 0, wx.CENTER)
self.SetSizer(mainSizer)
mainSizer.Fit(self)

In the first block I removed SetAutoLayout(1) and in the other I
replaced SetSizerAndFit(mainSizer). Now the two blocks are consistent.
Is this what you would recommend we teach new users?

That's probably fine, if the Fit is actually needed. It really depends on the content of the window managed by the sizer and what the desired intent of the layout is. If there is something that is set to expand so the window is filled then the Fit may not be needed because it will look good at any size. If, OTOH, the content is a fixed size then the Fit will probably be wanted.

···

On 1/15/10 2:09 PM, Daniel Carrera wrote:

--
Robin Dunn
Software Craftsman

Chris_Barker1 · January 16, 2010, 1:00am

Daniel,

Thanks for doing all this! It looks like things really will be easier for other new users.

I'm trying to move to the standard where ids are always either a standard one (e.g. wx.ID_ABOUT) or wx.ID_ANY.

good plan.

Did I understand you correctly that there are still some instances of "ID_ABOUT" without the "wx." in front?

I don't think so -- I was just answering quickly without looking carefully enough.

-> Does "New wxPyDocs" mean that the other ones are old and outdated?

well, no. They are "new" because they are the first result of a new system for generating docs -- unfortunately, that system never really got finished, so it's not entirely clear how they should be advertised.

-> What is the difference between "Online wxDocs" and other docs? Aren't the others online too?

The same docs are available for download as html or chm files, so this is the "online" version.

These things need to be integrated and explained better. After clicking around I can see that the latter two should probably be called "API Reference".

yes.

This is just a frame pointing to the wxWidgets docs!!!

well, yes, but they do have wxPython notes in them, so they are really the unified docs -- but yes, mostly C++ oriented. This is explained in the Wiki, but it would be nice to have it more clear on that main page.

-> Learn wxPython
-> wxPython API Reference
-> wxWidgets Documentation

That's good, but the "wxPython API Reference" (that is the "new docs, right") isn't really that good, so I'm not sure it should be highlighted.

C M wrote:

Really, I would prefer that there was only the wxPython API reference,
but the very best formatting of that. I think for at least beginner's
purposes, the wxWidgets API might be confusing, and if there is a
very good wxPython API reference it will be good enough to use just
that.

I think we all want that -- it would be really nice if the reference docs were auto-generated from source, but the problem is that wxPython is built on wxWidgets, so it's not just a python problem.

There has been a bunch of discussion on this list about, but no has yet found time to do it, or maybe the real problem is that is not yet a consensus about how.

Something Sphinx-based like matplotlib, scipy and numpy would be great. (Andrea did do a prototype of this) Scipy even has an online system for users to edit the docs, and then they go through an aproval process before the edits make it inot the official docs -- very nice for community written docs.

If anyone want to do some work on it, make sure to look for discussion in this list archive.

-Chris

···

--
Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R (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

Michael_H · January 16, 2010, 4:52am

Daniel,

Just wanted to say thanks for all your hard work on the wiki.

Thanks to everyone else who contributed to this effort as well, it
makes a big difference..

- michael

···

On Jan 15, 7:00 pm, Christopher Barker <Chris.Bar...@noaa.gov> wrote:

Daniel,

Thanks for doing all this! It looks like things really will be easier
for other new users.

> I'm trying to move to the standard where ids are always either a
> standard one (e.g. wx.ID_ABOUT) or wx.ID_ANY.

good plan.

> Did I understand you
> correctly that there are still some instances of "ID_ABOUT" without the
> "wx." in front?

I don't think so -- I was just answering quickly without looking
carefully enough.

> -> Does "New wxPyDocs" mean that the other ones are old and outdated?

well, no. They are "new" because they are the first result of a new
system for generating docs -- unfortunately, that system never really
got finished, so it's not entirely clear how they should be advertised.

> -> What is the difference between "Online wxDocs" and other docs? Aren't
> the others online too?

The same docs are available for download as html or chm files, so this
is the "online" version.

> These things need to be integrated and explained better. After clicking
> around I can see that the latter two should probably be called "API
> Reference".

yes.

> This is just a frame pointing to the wxWidgets docs!!!

well, yes, but they do have wxPython notes in them, so they are really
the unified docs -- but yes, mostly C++ oriented. This is explained in
the Wiki, but it would be nice to have it more clear on that main page.

> -> Learn wxPython
> -> wxPython API Reference
> -> wxWidgets Documentation

That's good, but the "wxPython API Reference" (that is the "new docs,
right") isn't really that good, so I'm not sure it should be highlighted.

C M wrote:
> Really, I would prefer that there was only the wxPython API reference,
> but the very best formatting of that. I think for at least beginner's
> purposes, the wxWidgets API might be confusing, and if there is a
> very good wxPython API reference it will be good enough to use just
> that.

I think we all want that -- it would be really nice if the reference
docs were auto-generated from source, but the problem is that wxPython
is built on wxWidgets, so it's not just a python problem.

There has been a bunch of discussion on this list about, but no has yet
found time to do it, or maybe the real problem is that is not yet a
consensus about how.

Something Sphinx-based like matplotlib, scipy and numpy would be great.
(Andrea did do a prototype of this) Scipy even has an online system for
users to edit the docs, and then they go through an aproval process
before the edits make it inot the official docs -- very nice for
community written docs.

If anyone want to do some work on it, make sure to look for discussion
in this list archive.

-Chris

--
Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R (206) 526-6959 voice
7600 Sand Point Way NE (206) 526-6329 fax
Seattle, WA 98115 (206) 526-6317 main reception

Chris.Bar...@noaa.gov

Daniel_Carrera · January 16, 2010, 5:51am

Hi Chris,

Thanks for doing all this! It looks like things really will be easier for other new users.

Thanks.

-> Learn wxPython
-> wxPython API Reference
-> wxWidgets Documentation

That's good, but the "wxPython API Reference" (that is the "new docs, right") isn't really that good, so I'm not sure it should be highlighted.

Thanks for the explanation. I've given a lot of thought to this and I've decided that it is not possible to explain the very important nuances you described in just 2-3 words. This is my suggestion:

REMOVE the last two links. Leave only "Learn wxPython". THEN, on the wiki page "Learn wxPython" we can link to the other two. WHY?

1) On the wiki we have the room to convey the right message about these links. I already updated the "Learn wxPython" page. PLEASE take a look to see what I mean.

http://wiki.wxpython.org/How%20to%20Learn%20wxPython

2) LOGICALLY, these links are part of "How to learn wxPython", right? Putting the links only on this page is actually a logical organization. And when the user arrives at the front page he'll be far more likely to click on the right link.

Daniel.

Daniel_Carrera · January 16, 2010, 5:51am

michael h wrote:

Daniel,

Just wanted to say thanks for all your hard work on the wiki.

Thanks to everyone else who contributed to this effort as well, it
makes a big difference..

Don_Dwiggins · January 18, 2010, 5:02pm

Robin Dunn wrote:

That's probably fine, if the Fit is actually needed. It really depends on the content of the window managed by the sizer and what the desired intent of the layout is. If there is something that is set to expand so the window is filled then the Fit may not be needed because it will look good at any size. If, OTOH, the content is a fixed size then the Fit will probably be wanted.

Sounds like this (and Robin's previous about the difference between SetSizer, then Fit vs SetSizerAndFit) belongs in a prominent place in the wiki. I remember thrashing quite a bit early on to get my windows to look and behave the way I wanted them to.

···

--
Don Dwiggins
Advanced Publishing Technology

Robin · January 19, 2010, 2:18am

Feel free to make a page discussing these issues (or just copy and paste my emails if you want) and link to it from other pages where it will help out.

···

On 1/18/10 9:02 AM, Don Dwiggins wrote:

Robin Dunn wrote:

That's probably fine, if the Fit is actually needed. It really depends
on the content of the window managed by the sizer and what the desired
intent of the layout is. If there is something that is set to expand
so the window is filled then the Fit may not be needed because it will
look good at any size. If, OTOH, the content is a fixed size then the
Fit will probably be wanted.

Sounds like this (and Robin's previous about the difference between
SetSizer, then Fit vs SetSizerAndFit) belongs in a prominent place in
the wiki.

--
Robin Dunn
Software Craftsman