Re: Creating a GTK Cheat Sheet Poster

[Mikael Olenfalk <mikael olenfalk gmail com>]

Hi David,

I have incorporated some of your ideas and come up with another
design, which hopefully is more useful; please let me know what you
think.

https://mikael.is-a-geek.org/shared/public/gtk-window-test-002.png

Regards,

Mikael



On 12/31/05, David Necas (Yeti) <yeti physics muni cz> wrote:
> 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.
>