Re: libglade frustration
On Tue, Feb 13, 2007 at 04:32:19PM -0800, Rick Jones wrote: I'm not really interested in how library call foo is implemented, I just want to know how to call it do get my work done. So you want to know how to use it and you intentionally avoid one of the most efficient ways to learn it. Well, if it works for you... Yeti -- Whatever. ___ gtk-app-devel-list mailing list gtk-app-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-app-devel-list
Re: libglade frustration
So you want to know how to use it and you intentionally avoid one of the most efficient ways to learn it. Well, if it works for you... What is so inefficient about taking an example (that already exists) and including it in the HTML/online documentation that more people read than source code in tarballs? ___ gtk-app-devel-list mailing list gtk-app-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-app-devel-list
Re: libglade frustration
On Wed, 2007-02-14 at 12:56 -0300, Claudio Saavedra wrote: If at least the guy complaining would have given more information about the problems he had, we could have directed him in the right direction, which would've been much more productive than this where do we put examples for the lazy one thread. Yes sorry I'm responsable for dragging out this thread, I knew it wasnt going anywhere when I started it and I know its not going anywhere now, nevertheless I was still intrigued to hear a little of what people thought on that matter - as this particular question seems to keep popping up (the libglade example thing...) anyway I dont need to vent about this or anything (I'm thoroughly satisfied with my venting now thankyou :D haha...) Cheers, -Tristan ___ gtk-app-devel-list mailing list gtk-app-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-app-devel-list
Re: GObject docs improvements
Hi, the G_DEFINE_TYPE stuff is on the list since the very beginning. In part I (Concepts) we will explain it the long way, but mention G_DEFINE_TYPE. In part IV (Tutorial) we will use G_DEFINE_TYPE. You should always use it if it fits. Stefan Quoting Freddie Unpenstein [EMAIL PROTECTED]: A point I miss in the tutorial is to mention the G_DEFINE_TYPE()-like macros which should be prefered over manually defining a _get_type() function whenever possible. I never did get that G_DEFINE_TYPE() stuff at all... It'd be good to see some clear documentation on it. The G_DEFINE_TYPE() stuff is a macro that expands to the common boilerplate code. If you have this and are able to write the boilerplate code manually, what other documentation is needed? How about a real-world example, and a note on advantages (other than less typing) and disadvantages compared to doing it the long-winded way (spelling out the whole lot of boilerplate code). What are the cases where the G_DEFINE_TYPE() macros are commonly useful, for what common cases AREN'T they useful (but might look useful at for glance, for example), and where applicable, notes on how to get around certain limitations of the macro (eg. there's a lot of NULLs in the type info structure shown in the documentation) and why or why not to do it that way. That kind of thing might be helpful... Fredderic ___ Join Excite! - http://www.excite.com The most personalized portal on the Web! ___ gtk-app-devel-list mailing list gtk-app-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-app-devel-list ___ gtk-app-devel-list mailing list gtk-app-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-app-devel-list
Re: GObject docs improvements
I'm trying to understand the Signals in GObject and I have lot of questions not covered by the doc: 1) The text when they register a closure to be invoked upon the signal emission is not clear what is it a closure or what is the diference with a callback 2) if a signature for a callback is: return_type function_callback (gpointer instance, ... , gpointer user_data); How do I know If is it correct to have callback declaration: void function_callback (GObjectMyObject *object, gboolen val, MyType type), and how to create a new signal that sends the data needed by my callback 3) There's no more information about c_marshaller parameter, where they are defined or witch I can use on a given situation. Does I need to select a marshalled that fits my callback declaration to get the correct data? 4) On the Detail section the text: Their detailed_signal parameter is a string which identifies the name of the signal to connect to, then when I create (g_signal_new) a signal name do I need to use a form: signal_name::detail not just signal_name? what about the text signal named notify::cursor_position will actually connect to the signal named notify with the cursor_position name, this is redundant and unclear, what will be the correct name of my signal? 2007/2/8, Stefan Kost [EMAIL PROTECTED]: hi, yesterday I committed a first batch of cleanups to the GObject docs. http://developer.gnome.org/doc/API/2.0/gobject/index.html IMHO this is a crucial documentation for the GNOME platform and it can be improved further. Marc-Andre Lureau and Zeeshan Ali already joined in the quest to improve this. What I like to ask you is to reply to this mail and tell us what you don't understand yet, point out parts that can be improved, let us know if there are some nagging concerns about the way GObject works. Are there details that should be explained by a picture? If possible then please checkout the latest version and base your feedback on that one: svn co http://svn.gnome.org/svn/glib/trunk glib cd glib ./autogen.sh --prefix=$HOME/test make cd docs/reference/gobject evince html/index.html you don't need to install it. Thanks! Stefan ___ gtk-app-devel-list mailing list gtk-app-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-app-devel-list -- Trabajar, la mejor arma para tu superación de grano en grano, se hace la arena (R) (entrámite, pero para los cuates: LIBRE) ___ gtk-app-devel-list mailing list gtk-app-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-app-devel-list
Re: GObject docs improvements
On Wed, Feb 14, 2007 at 02:52:02PM -0600, Daniel Espinosa wrote: 1) The text when they register a closure to be invoked upon the signal emission is not clear what is it a closure... Not even when reading the tutorial in order and therefore getting to this just after reading a whole section on closures? 2) if a signature for a callback is: return_type function_callback (gpointer instance, ... , gpointer user_data); How do I know If is it correct to have callback declaration: void function_callback (GObjectMyObject *object, gboolen val, MyType type), Iff `...' is a signle gboolean argument and MyType is a pointer. In other words, you can call a function only with arguments that match the function signature. Though I agree the text should be more specific about what `...' stands for here. and how to create a new signal that sends the data needed by my callback user data is always a single pointer (of course, you can write closures and marshallers to generically pass arbitrary data through this pointer and then unpack/transform it somehow when calling the callback -- and language bindings do this -- but this is unrelated to the signal definition). If you really mean a signal with more arguments such as GtkTreeModel::row-changed, then by passing the number of specific arguments as n_params, their types as `...' (the list of parameter types) and the corresponding marshaller as c_marshaller. 3) There's no more information about c_marshaller parameter, where they are defined or witch I can use on a given situation. Does I need to select a marshalled that fits my callback declaration to get the correct data? This is explained in the reference part, section Closures. Maybe some text should be moved one direction or another? I'd personally prefer moving most of the implementation details material from the intro to the reference, but maybe it's just me... 4) On the Detail section the text: Their detailed_signal parameter is a string which identifies the name of the signal to connect to, ^ ++ There's something like `and the detail' missing here-+ then when I create (g_signal_new) a signal name do I need to use a form: signal_name::detail not just signal_name? what about the text signal named notify::cursor_position will actually connect to the signal named notify with the cursor_position name, this is ^ +--+ redundant and unclear, what will be the correct name of my signal? | | There's something like `detail' missing here--+ Hopefully it will start making sense then. And seeing this: The intro should consistently use dashes: signal-name, property-name (not signal_name, property_name). Yeti -- Whatever. ___ gtk-app-devel-list mailing list gtk-app-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-app-devel-list
Re: libglade frustration
On Wed, Feb 14, 2007 at 01:28:23PM -0800, Rick Jones wrote: Well, I didn't go tearing-down the engine and transmission in my car, but I still learned how to drive it :) If your have no idea why the car does what it does when you turn the steering wheel or change gear, I just hope you live in a very distant part of the world and will stay there. The difference between driving a car (or using a compiler or linker) and programming with a library such a Gtk+ is that most of Gtk+ library code is no different from Gtk+ application code. You can directly apply what you see there. Whereas in the former case you still need a good mental model, but studying the implementation -- which is on a different level -- might not be useful directly. Yeti -- Whatever. ___ gtk-app-devel-list mailing list gtk-app-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-app-devel-list
Re: libglade frustration
I just love this car analogy! CARS The technical service manual is available for those that need to service the car. It doesn't come with the assembled car. Maybe it comes with the car if you buy it in kit form. Your repair mechanic needs to refer to it, but if the car's well-made, the user shouldn't need to know about it. --but-- The users manual should be provided with every car. The user's manual should provide sufficient instruction on how to drive the car. If a driver finds himself needing to refer to the technical service manual to drive the car, the user's manual is inferior and should be amended with sufficient user instructions, including examples of where to find the fluid fill caps, the dome light switch and the overdrive button. LIBGLADE The source code is available for those that need to modify libglade. It doesn't come with the packaged distribution. It is available from the same web site as libglade binary packages. A libglade extension writer needs to refer to it, but if libglade's user manual is sufficient the user shouldn't need to look at the source. --but-- The users manual should be provided with every copy of a packaged distribution. The user's manual should provide sufficient instruction on how to operate libglade. If a developer finds himself needing to refer to the source to run libglade, the user's manual is inferior and should be amended with sufficient user instructions, including examples of deriving from classes that implement interfaces, using signals in GObject, etc. // Wally On Wed, 2007-02-14 at 16:55 -0500, Tristan Van Berkom wrote: On Wed, 2007-02-14 at 13:28 -0800, Rick Jones wrote: [...] So you want to know how to use it and you intentionally avoid one of the most efficient ways to learn it. Well, if it works for you... Well, I didn't go tearing-down the engine and transmission in my car, but I still learned how to drive it :) I agree that if one really, Really, REALLY wants to know not just how something works, but why it works that way, source code is best. Still, that hasn't meant that I was or continue to be able to just tell people asking about netperf to read the source, I still either explain things to them, or make sure I ammend the manual. I'm going to have to bite my tongue soon and just drop this, only I'm getting the impression that your still arguing that people should remain too lazy to consult the tarball, which is fine, I'm just going to try - again - to change your mind. So lets continue to speak in metaphores since it happens to suit me today. Lets say that you downloaded your new car from your local dealership, and still have a hard time figuring out how to use this new car, maybe the dealership wasnt responsable enough to provide you with the box manual that the manifacturer distributed with the new car, maybe the dealership decided that that part of the car was irrelevent. Even if the box didnt come with a complete set of blueprints on how the car was made, it might come with a manual and/or a set of tips, those tips might be usefull to you even if the dealership didnt think so. The tarball is the complete package that comes from the manifacturer, if the manifacturer wanted you to have something that was just a side dish to the main meal (like an example program), then look in the package for additional information, thats where it comes from, thats where to look for. Ammending the documentation is one thing, people actually pulling the documentation out the box and reading it is another thing entirely. Cheers, -Tristan ___ gtk-app-devel-list mailing list gtk-app-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-app-devel-list -- [EMAIL PROTECTED] Office: 619.278.2084 Cell: 619.990.2286 ___ gtk-app-devel-list mailing list gtk-app-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-app-devel-list
Re: libglade frustration
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On Thu, Feb 15, 2007 at 12:00:37AM +0100, David Nečas (Yeti) wrote: On Wed, Feb 14, 2007 at 02:44:21PM -0800, [EMAIL PROTECTED] wrote: [...] libglade developers do not produce any binary packages. Their product does come with examples. Requiring that the examples have to be included in full in the text of the manual instead of in a compilable form as standalone files is silly. You took it back to the point. I think metaphors don't help much here. The question is whether usage examples belong to the documentation or not. As we see, this question is debatable. Personally, I'd side clearly with the yes side. Regards - -- tomás -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.1 (GNU/Linux) iD8DBQFF0/XYBcgs9XrR2kYRAi3BAJ4g3E/refaqwbtgEX921oO6UwLWagCZAeUe BHC3UYcdCnaVUBJ4vGi3Zq8= =36mv -END PGP SIGNATURE- ___ gtk-app-devel-list mailing list gtk-app-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-app-devel-list
