Re: Creating a GTK Cheat Sheet Poster

["David Necas (Yeti)" <yeti physics muni cz>]

On Sat, Dec 31, 2005 at 02:07:08AM +0100, Mikael Olenfalk wrote:
> I just started working on creating a poster-sized (A0, approx 120x90
> cm) cheat sheet for GTK development. My plan is to show an application
> window in the middle of the poster with all widgets in it and then
> list the classes for each widget around this window.
> 
> I think this will make development much easier for newbies (like
> myself), especially because code completion often is too overwhelming
> for using as a TIP for which function to use; and it doesn't describe
> signals as well.

I have a few comments, I could have more if I had a better
idea how is it supposed to be used, that is how it intends
to complement API (and other) documentation.

In my opinion one should primarily optimize the access to
full documentation: if I already have a symbol or class
and I am more than one keystroke away from its documentation,
something is wrong.  If I know it approximately, I should be
still able to get the best match by approximate search or
get to the list of all symbols in the correct class quickly.
What is not covered so well:

- I want a method that does.../the name of signal emitted
  when...  If skimming of the method/signal/... list [in
  full documentation I have one keystroke away] fails,
  fulltext search helps a lot (though I recall I was unable
  to find the method to set GtkFileChooser's directory
  because its description only talks about folders, not
  mentioning directory).  The cheatsheet could help if it
  tried to group the methods by topic, because now the order
  is arbitrary like in the API docs.  But again, I would
  prefer less arbitrary method order in API docs too.

- I want a widget that does.../looks like...  Something
  between Widget Gallery and Widgets and Objects chapter TOC
  in API documetation -- only better -- would help.  This is
  something you could focus on: to enable to find the
  essential information quickly instead of listing hordes of
  incomprehensible parameters that people need to look up in
  full documetation anyway.

- I have a conceptual problem, need to learn some programming
  idiom, a particular tweak, ...  A cheatsheet is not the
  right place for these.

> So I have started creating an initial design of the GtkWindow class,
> which you can have a look at at this address:
> 
> https://mikael.is-a-geek.org/shared/public/gtk-window-test-001.png
> 
> It would be great if some of you could give feedback on this,

It obviously misses one thing: parent class and implemented
interfaces (maybe childs too).  People have problems finding
inherited features even in API documetation that explicitely
links to parents and lists implemented interfaces.  You can
mitigate the confusion by logical grouping of e.g. GtkHBox,
GtkVBox, and GtkBox together, but not fully.

>   - the "Functions" section is overwhelming and actually useless for a
> fast-glance look up of any function; should I remove it completely or
> just remove all uncommon functions from it? As you can see I have
> already removed some functions (all functions for set/getting the
> properties, as well as some functions for framebuffer gtk) I am a
> complete GTK newbie so I do not know which functions are uncommon; if
> you have suggestions, they are very welcome.

I supposte you do not want to just print copies of Gtk+
header files to A0 poster.  Therefore I would only keep the
commonly needed.  I agree it is not always clear which are
which.

>   - I am thinking about removing the "GtkWindow *window" parameter in
> all functions in favour of an icon for the instance

Redundant information:
- The first argument of each signal is the instance, the last
  is always user data.
- The first argument of each method is the instance
  (functions that are not methods, or are static methods,
  can be listed separately)
- Method names of GtkSomething always start with gtk_something_.

Most of these are only consequences of object system
implemented in the language instead of being part of the
language.  I am not sure how confusing it would be if you
removed all the gtk_something_ prefixes and `self' arguments
(for me not at all because I only add these decorations
because of C, I think about them the OOP way, but YMMV).

Yeti


--
That's enough.