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@xxxxxxxxxxxxxxx> 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. > _______________________________________________ gtk-list@xxxxxxxxx http://mail.gnome.org/mailman/listinfo/gtk-list
