Re: Creating a GTK Cheat Sheet Poster

[Mikael Olenfalk <mikael olenfalk gmail com>]

Sorry, but I forgot to mention that the little grey boxes with "i" and
"u" in them are icons for "Instance" and "Userdata" I have to figure
out more obvious icons though...

/Mikael



On 1/3/06, Mikael Olenfalk <mikael olenfalk gmail com> wrote:
> 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.
> >
>