28 June 2012

Theory and practice are always the same thing. In theory, not in practice.

Ok, I said: "The main idea: one page, one widget; one widget, one page." in the last post about the 0 Beginners Tutorial, two weeks ago. (My, how time flies and all that sort of things!)

Of course, since things are never going to be as planned, this is not what will happen.

First thought, about ten days ago: "It would be nice to talk a bit about strings and Unicode, on the model of what Sebastian Pölsterl does here". Then it occurred to me that also this page of his tutorial is a great model too.

So: three pages (strings, signals and callback functions, properties) that are not attached to a widget - but linked from some widgets' pages.

Then I was about to rewrite the TreeView widget documentation page, and the ComboBox documentation page... and here comes the idea to write a page about the Model/View/Controller design, about TreeModel and its implementations ListStore and TreeStore, so that the similarities of TreeView and ComboBox are clearer (and therefore it is easier to learn both - my opinion is that ComboBox is slightly easier, but difficulty is always subjective!). Also: in the plan for the tutorial there are two ComboBox examples and four TreeView examples. To repeat a long explanation on the M/V/C design and the methods for TreeModel & friends would make things more confused.

So, now: off to write the M/V/C design page! And then hopefully I will be able to write some code samples again... I miss my Python! (Sorry Mallard, nothing against you...)

As usual: your thoughts? Ideas?

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).]

8 June 2012

Yet another OPW update!

What, more than ten days have already passed from my last post? What was I thinking? What was I doing?

Oh, yes: I was writing! Code and documentation pages!

First look at the "samples needed" section in the Documentation Project page, then I look at the Gtk+ 3 Reference Manual. When I find a sample that is needed that sounds doable given my current knowledge, I write an example. If an example is already there in another language (usually Vala, thanks Tiffany!) I "translate" it in Python; otherwise I improvise.

Then there is the documentation: if the example is a first, I take a screenshot (Taryn explained here the magic of alt-prt sc - and much more; for the combobox the setting "take screenshot with some delay" was needed to capture the menu that was dropped down, and some Gimp was needed to delete drop shadows). Then I write a .page in Mallard on the model of the ones already there (thanks all the documentation team that wrote that page). The page so far is only composed of:
  • screenshot
  • short explanation of what the screenshot is
  • code used to obtain that screenshot (in the best cases, very commented along the lines of "here we do this; here we do that")
  • links to the Gtk+ 3 reference manual pages I looked at when I wrote the code (this part is missing in some pages, I promise to do it as soon as possible). I know: those pages are written for C programmers. Some of the methods don't work in Python. If anyone has any idea of something more Python-friendly I can link, please tell me!
Is there something else you would like? Is there something you would like to be different?

Finally, I commit with git my work, as explained - again - here.

Repeat for each sample...

[Final note, the usual: "things I would have done differently with hindsight": the combobox after the treeview was much easier. But maybe it is because the model is the same, so the problem was getting in the mindset...]

[Another final note: yes, the list was also because I wanted to see the little feet on my post on the Planet too.]

[Really-final note: I ask a lot of questions, I would love to hear from you in the comments. But: due to having an annoying internet stalker - long story, it even involved London's Metropolitan Police at one time - I have to moderate all my comments in all my blogs. So: I'm sorry for the delay, please bear with me while I approve your comment...]