14 June 2012

What's in a page?

A page of the O Beginners Tutorial for Gtk+ in Python, I mean...

First of all, there is an image of a window with the widget "in action".

Then there is the code to get exactly that example. Heavily commented: each line is explained (ok, the "here we set the width and the length of the window" is left out after a couple of examples).

In some cases, here there is a note to comment the code even further.

Then (thanks Jewelfox for the idea!) a series of "useful methods for this widget". I am thinking of writing this part as a list (one method for each bulletpoint), but in a relatively conversational style because a "plain" list could bore you and make you miss some parts while you skim over it. A great help in this is the tutorial by Sebastian Pölsterl, from which I already took an example (and that has been my Rosetta Stone between the C of the Gtk+3 Reference Manual and Python).

Finally, all the links to the pages in the Gtk+3 Reference Manual that I used to write the example.



Is there anything else you would like? Is there anything else you would do differently? If so, leave a comment...

And the Bigger Picture? The Tutorial Itself?

The main idea: one page, one widget; one widget, one page.

Then: a map! A graph to describe "from here you can go here, there, or there", and "to get here you will need what you learn there". And how would you do that? Only via hyperlinks on the page? Wouldn't they get lost in the variety of links described above - and wouldn't the bigger picture of the tutorial get lost in it? On the other hand: a "real" graph for all the examples needed for the tutorial could be a little too tangled...

[And: how's the work progressing? After a first very rough draft of many (but not all) widgets, so far I have written better pages for the window widgets (Gtk.Window, Gtk.ApplicationWindow, Gtk.Dialog, Gtk.AboutDialog, Gtk.MessageDialog) and I am now dealing with version 0.2 of the display widgets' pages (Gtk.Image, Gtk.Label, Gtk.Spinner, Gtk.Statusbar, Gtk.Progressbar). To come: buttons and toggles, numeric and text data entry, Gtk.TextView and more, including list and tree widgets (and therefore Gtk.ListStore and Gtk.TreeStore).]

6 comments :

  1. These are some interesting ideas!

    I hadn't thought of a "useful methods" section. I'd personally also want to show something about properties, so that people will know how to customize those. I also have to spend more time breaking the code sample down into little pieces, since JavaScript uses a lot of boilerplate. -_-

    When I did an example that showed things like "useful methods," it was the Statusbar. There were only a few interesting methods on it, so I just wrote up a new example that had a couple of extra buttons which used them. I'd probably have to just create a "useful methods" section for widgets that have a lot more methods and properties, though. Maybe with commented-out code, or with "replace this with this" code samples that have new screenshots to show what it looks like?

    Not sure! Part of me wants to spend a lot of time getting these samples just right since they're so important, but part of me also knows I need to finish some basic tutorials. It doesn't help that I had a lot of trouble trying to figure out TreeView, and still haven't succeeded. -_-

    ReplyDelete
    Replies
    1. I don't know about adding new screenshots in the same page. Maybe we could do new pages for the "more complex version" of some samples, like we should have a more simple and a more complex TreeView... Also Tiffany was thinking of having a page of exercises for each sample - we could try to "complicate things" for our reader there.

      And, speaking of TreeView: it is a mess. As I understand it: the model (TreeStore or ListStore) holds the data, that are seen in the TreeView (series of column, each with some rows) as rendered in each cell (intersection of row and column) by CellRenderer. And ComboBox is a variation on the theme, with ComboBox instead of TreeView.

      Delete
  2. Great to see progress on the Python dev docs!

    One suggestion would be to check all Python code with pep8 so that all code follows the Python code styleguide :)

    ReplyDelete
    Replies
    1. I try to keep the code as well as possible... I indent with spaces (4) and all that sort of things. But if you see something wrong, please tell me!

      Delete
  3. Nice! I think this is really needed. Unfortunately it's not that easy to get started on making apps for GNOME. There are some tutorials on the web, but not much on gnome.org (weirdly enough).

    Is it the plan to add different languages as well? Or is Python the recommended choice to start writing GNOME apps?

    ReplyDelete
    Replies
    1. Thank you! :-) Other languages for which tutorials are being written (in parallel) are C, by Monica Kochofar; JavaScript, by Taryn Fox; and Vala, by Tiffany Antopolski, who is also our mentor for the OPW. So you can start writing GNOME apps in your favourite language! More details here: https://live.gnome.org/DocumentationProject/Tasks/DeveloperDocs/BeginnerTutorials

      Delete