wxWidgets needs your help to improve its documentation! Topic is solved

[tierra]

wxWidgets is in the middle of a process aimed to greatly improve its documentation by migrating from the existing LaTeX (parsed with TeX2RTF) docs to Doxygen (using a separate set of "interface" headers rather than the actual headers in wxWidgets).

Some wxWidgets developers have spent a number of months developing the automatic conversion script for this migration, and have reached the point where the scripts can no longer be helpful. The wxWidgets documentation is big and the new format for the documentation sources need to be reviewed by human eyes to fix the errors that the automatic conversion couldn't handle.

So, we need your help to complete this process in a reasonable amount of time. All the details can be found here:
http://www.wxwidgets.org/wiki/index.php ... ocs_review

If you are interested to help, you'll find all info on how to begin there, but if you have any doubts or questions, feel free to post them here.

This is a good opportunity to:
- Get involved and more familiar with wxWidgets
- Improve the parts of documentation you never liked
- Support wxWidgets in our goals of making it an even more competitive toolkit

Thanks!

P.S. Those interested in just watching the conversion in progress can find the daily Doxygen manual here:
http://wx.ibaku.net/manual/

[Auria]

I might have been interested in screenshots, but do requirements need to be so high? For instance, if I used OS X 10.4 and not 10.5? Most widgets look pretty much the same, I won't buy a new system just to take screenshots

[tierra]

I might have been interested in screenshots, but do requirements need to be so high? For instance, if I used OS X 10.4 and not 10.5? Most widgets look pretty much the same, I won't buy a new system just to take screenshots

I'm sure screenshots under 10.4 would be acceptable, as long as we know that the components haven't changed between the versions (most should be exactly the same really), but if we have two people with 10.5 to do the screenshots, that would be best.

[GeraldG]

I think it would be better to automate the screenshot creation.
For example a project with all controls, show them and make a bitmap from desktop dc like a screenshot program.

[Utensil]

Great news!

Some feeling after reading:

1) The new form of wxDoc seems using a smaller-sized font, I have to zoom in to read...

2) Why didn't the Classes by Category align in the table form as in the good old time? The end of the descriptions fluctuate like a saw...

I think it would be better to automate the screenshot creation.
For example a project with all controls, show them and make a bitmap from desktop dc like a screenshot program.

We can make use of the wxWidgets *official* samples e.g. samples/controls. To rewrite one with everything might be not that necessary and easy------Consider the extra customization of wxHtmlListBox or wxTreeCtrl...


I might have been interested in "Reviewing the Converted Interface Headers" part.

See http://wx.ibaku.net/manual/classwx_sock ... 845d4c8e67

The description of wxSocketBase::Close() is completely messed up by unrelavent contents. And wxSocketBase::Destroy(), too.
Are similar problems are we supposed to fix?

Regards,

Utensil

EDIT:

More feeling:

3) The member functions are listed in an orderless way...Neither placed the constructor/destructor/Create functions on the top, nor having function groups...

4) The overloaded functions are not organized together...This is really inconvinient...

[tierra]

1) The new form of wxDoc seems using a smaller-sized font, I have to zoom in to read...

We'll likely be working on various aesthetic issues like these last after we've finished with the content. I was planning on at least bumping up the size of the class member table fonts.

2) Why didn't the Classes by Category align in the table form as in the good old time? The end of the descriptions fluctuate like a saw...

Actually, the finished manual will line up in a table. We're in the process of removing this page, and replacing it with this one (which will have descriptions next to each class when we're done).

We can make use of the wxWidgets *official* samples e.g. samples/controls. To rewrite one with everything might be not that necessary and easy------Consider the extra customization of wxHtmlListBox or wxTreeCtrl...

This won't be possible actually for a few reasons. First, the samples shouldn't contain any code beyond the basics as well as the feature they illustrate usage of. Second, if we're writing this up, we don't want to duplicate the common "screenshot" functionality of it in every sample we want screenshots of. Third, we don't want to have to build and run each sample individually, per platform, just to regenerate all the screenshots. If we're writing up an automated tool, then it should be all automated.

See http://wx.ibaku.net/manual/classwx_sock ... 845d4c8e67

The description of wxSocketBase::Close() is completely messed up by unrelavent contents. And wxSocketBase::Destroy(), too.
Are similar problems are we supposed to fix?

If you read the wiki page linked to in my first post, you would have noticed that wxSocketBase is one of the classes that hasn't been reviewed and cleaned up. These are the issues we're asking for help with, in addition to all the other tasks outlined on the wiki page I linked.

[Utensil]

Aha! You are online

I've edited my post with a few more feelings. Sorry for the complaining...

This won't be possible actually for a few reasons.

What won't be possible? I said it wasn't necessary and easy to write an automatic thing...It seems that we're on the same side...

I have a new question: Should the pngs on different platforms, display the same content? Say, a button, should they have the same label? Or more complicated, a wxTreeCtrl, should they have abstract node names such as "root", "node1" etc. or concrete and casual names such as fruit names?

How do screenshot takers communicate with each other on that? I mean, this is the wxDoc, the screenshots in it should be kind of uniformed.

If you read the wiki page linked to in my first post, you would have noticed that wxSocketBase is one of the classes that hasn't been reviewed and cleaned up.

I did. I was only asking if it's the task and just showing an example of the undone work.

Regards,

Utensil

[frm]

Should the pngs on different platforms, display the same content? Say, a button, should they have the same label?

yes, this makes the docs more homogeneous.

Or more complicated, a wxTreeCtrl, should they have abstract node names such as "root", "node1" etc. or concrete and casual names such as fruit names?

I think that both will just do the job. Probably however naming the root item "root" and the nodes "node1", "node2" is better since the reader immediately "see" what does the "root" term means in that context...

How do screenshot takers communicate with each other on that?

the wiki page posted by Bryan is open for editing

If you can help on this revision process, then thanks a lot!

Bye,
Francesco

[tierra]

This won't be possible actually for a few reasons.

What won't be possible? I said it wasn't necessary and easy to write an automatic thing...It seems that we're on the same side...

Sorry if I wasn't clear. What I meant was that it wouldn't be possible to use the existing official samples for this. I didn't mean that it wouldn't be possible to write up a utility for automatically taking screenshots. I did in fact bring this up on the wx-dev mailing list as soon as I read GeraldG's post:
http://thread.gmane.org/gmane.comp.lib. ... evel/99116

I really like this idea, and just as you mentioned, we do want consistent screenshots between platforms (with say, the same fruits listed in wxTreeCtrl and various other controls). A utility for taking the screenshots would solve this easily, and would be beneficial for updating the screenshots in future versions of wxWidgets as well without needing to request help with screenshots again.

Though the question now is: who is willing to write this up?

I'd be happy to do it, but I don't have the time to right now. If we don't have anyone experienced enough to write this up, should we hold off on adding screenshots to the manual until someone can, or should we do this first batch by hand?

the wiki page posted by Bryan is open for editing

Francesco is referring to myself for those of you who don't know who Bryan is.

[Utensil]

The mission includes two parts:
1)Write a program to display all those controls in a uniformed face on all platforms.
2) Integrate the screenshot taking utility in it.

1) is the easier part.
2) could be the long-term plan, or as you’ve said, a low-priority job.

Maybe 1) can be done mostly within a week if I make use of my spare time. Teammates welcome!

Basic Strategies:

1)CodeBlocks wxWidgets Template-----Minimal
2)wxFormBuilder as part of the GUI Design
3) wxNotebook Page to group
4) wxFlexGridSizer to layout

Why them: CodeBlocks and wxFormBuilder are available on all platform and they are free. And they are really great…For the controls not supported by wxFormBuilder, we can write them by hand in the derived class.

Standards To Discuss: ( The classes supported by wxFormBuilder directly marked by * )

Code: Select all

1)Needs One Label //Just use the class name ?
wxButton *
wxCheckBox *
wxStaticText *
wxRadioButton *

wxControl //Isn't it pure abstract? I thought it was.

2)Needs A Label Group // Use the pattern like “choice1” “item1” “node1”?
wxChoice *
wxCheckListBox *
wxListBox *
wxRadioBox *
wxTreeCtrl *
wxComboBox *

3)Needs One Image // jpg? The official sign of wxWidgets?

wxBitmapButton *
wxBitmapToggleButton *
wxStaticBitmap *

3)Needs A Image List //…

wxBitmapComboBox

wxListCtrl  * //For such a complicated class, choose which format to display?
wxListView


4)Needs A GIF //…
wxAnimationCtrl

5)Needs A Range And A Current Value  //100 and 50 or 30?
wxGauge *
wxSlider *

6)Needs Nothing
wxColourPickerCtrl *
wxDirPickerCtrl *
wxFilePickerCtrl *
wxFontPickerCtrl * //It will show the default font

wxGenericDirCtrl *

7)Needs A Status
wxToggleButton * //Toggled Or Not?


8)Needs Text Or RichText
wxTextCtrl * // single-line or multi-line or (multi-line under single-line in the same png)?
wxRichTextCtrl * // How to keep it in a reasonable size? Put the sample contents written by the author Julian Smart in it?

9)Needs A Date----Some special day in wx history?
wxDatePickerCtrl *
wxCalendarCtrl *

10)Needs Nothing Too
wxScrollBar *
wxSpinButton *
wxSpinCtrl *

11)Needs HTML Styled Tags
wxHtmlListBox
wxSimpleHtmlListBox

12)Needs A URL // http://www.wxWidgets.org?
wxHyperlinkCtrl *

13)Needs A Customized Control To Popout  //Use the minimal class wxListViewComboPopup given in wxDoc?

wxComboCtrl

14)Needs A Derived Class //How to? A teammate is especially needed here
wxVListBox  //Variable, it has pure virtual functions
wxOwnerDrawnComboBox

15)Needs Something To Put In //Have no idea
wxCollapsiblePane
wxStaticBox

16)Needs Somebody To Tell Me What They Need…..// a bitmap, a date, a progress indicator, a label and a toggle??

wxDataViewCtrl
wxDataViewTreeCtrl

Anybody has any idea or suggestion about them?

One more question: I’m a little confused by who is who. tierra = Bryan? Francesco = who?

Regards,

Utensil

[tierra]

2) Integrate the screenshot taking utility in it.

Actually, this part will be easy. I can do this if the rest of the utility is written up by someone else.

Basic Stratege:

1)CodeBlocks wxWidgets Template-----Minimal
2)wxFormBuilder as part of the GUI Design
3) wxNotebook Page to group
4) wxFlexGridSizer to layout

Why them: CodeBlocks and wxFormBuilder is available on all platform and they are free. And they are really great…For the controls not supported by wxFormBuilder, we can write them by hand in the derived class.

If this is going to make it into the wxWidgets mainline tree (likely under the 'utils' folder) where it should be, it can't be done with any RAD tools. It needs to be written by hand with integration into the existing build bakefiles just like the samples and HelpView utility.

This is actually going to be the hard part since we need someone experienced with wxWidgets build system to set up a minimal project for us. Francesco, I know you're fairly familiar with Bakefile, is this something you can do, or do we need to request some help from Vaclav or Vadim?

[Utensil]

Use RAD or not, the codes are codes themselves. What I concern is so far what we can do. Backfiles will be easy since there won't be complicated dependencies, that can wait. We can have the program built under the three target platforms first.

IMHO, the discussion of the standards might be the priority now, everything waits for that.

-Utensil

[Auria]

A concern I have towards such a tool, is that on wxMac, Blitting screen captures with DCs is totally broken (screen DC just doesn't work, client DC gives grey and pale results), so unless it was fixed in trunk such tool will probably not work on all platforms anyway

[frm]

Hi Utensil,
your basic strategy seems good at first glance and if you can write it, it would be great.

BTW before taking care of details like:
- bakefiles (not really a problem at all - I can set up one in few minutes for a new wx util)
- which labels to show for which control: just don't harcode them in the sourcecode (i.e. create a header which contains all UI messages so they are all in the same file). The text we'll actually use can be decided later

About the RAD thing: I think using XRC, possibly created with an open source RAD designer, is the best choice for this util.
It definitively benefits the code maintainace to separe the GUI code from the control code.

The most important thing probably is that if you're going to write it:
1) you do it trying to write clear, commented code which follows wx conventions

2) keep it configurable in regards to
- styles used for the controls to screenshot
- labels for those same controls

3) make sure that in the near future the wxMac problem mentioned by Auria will be fixed... you can ask this on wx-dev.

BTW if you start writing this tool, you'd better leave a note about it in the wiki page.

Keep us informed! Thanks a lot!

[tierra]

A concern I have towards such a tool, is that on wxMac, Blitting screen captures with DCs is totally broken (screen DC just doesn't work, client DC gives grey and pale results), so unless it was fixed in trunk such tool will probably not work on all platforms anyway

Stefan has mentioned that there is no longer a common screen buffer under Quartz, so yes, this couldn't be done with a wxScreenDC on Mac with wxMAC_USE_CORE_GRAPHICS = 1.

I can't find any bug reports or mailing list discussions in regards to wxClientDC on Mac OS X returning greyscaled results. In fact, the only place I see any mention of this is in one of your own posts. If I run into this, I'm sure I can either come up with something, or we can fallback to wxMAC_USE_CORE_GRAPHICS = 0 for this utility. We are looking for screenshots of controls, not device contexts, so I don't think it will matter with this off on Mac OS X.

And if that doesn't work, we could still use the Utility on Mac OS X, and just take screenshots by hand. Either way, the utility will still come in handy on all platforms, and should work great on GTK+ and MSW.