This is a class for managing the lifetime of top level widgets. More...
|GtkWindow *||get_win () const|
|WinBase (const char *caption=0, GdkPixbuf *icon=0, bool modal=false, GtkWindow *parent=0, GtkWindow *window=0)|
|virtual int||get_exec_val () const|
|virtual void||on_delete_event ()|
This is a class for managing the lifetime of top level widgets.
This class provides a base class for lifetime management of top level windows which can make GTK+ exception safe. It would be possible to use GTK+ to control the lifetime of the contained GTK+ window object, through the delete event handler and the destroy signal. However in the case of a blocking window (say a dialog) this would result in an invalid object remaining in scope. It is better to use the C++ lifetime handling mechanisms to control object status, and this class does that. Where a Cgu::WinBase object is created as an auto (local) object its contained GTK+ top level window object will be valid while it remains in scope. For a Cgu::WinBase object which is not blocking (on which exec() is not called) and which is therefore created on free store the WinBase class will delete its own memory and destroy its contained GTK+ top level window object when it is closed (see below about the close() function).
If a NULL pointer is passed as the last argument of its constructor, a new window object will be created with gtk_window_new(GTK_WINDOW_TOPLEVEL). However, alternatively a pre-formed object deriving from GtkWindow (such as a GtkDialog or GtkMessageDialog object) can be passed as that argument, in which case the class will manage that object.
A window will block with a call to exec(), which returns an int value. The exec() method obtains its return value by calling the virtual protected function get_exec_val(), which by default returns 0 but can be overridden to return something more meaningful. If something other than an int needs to be returned, it will be necessary for a derived class to provide an extractor function to obtain the data from the object after exec() has returned.
A convenience virtual protected on_delete_event() method is provided for any derived class which needs to respond to that signal. It does not return a value (it does not cause a destroy event to be emitted as in the case of a GTK+ delete event handler returning false).
If the class is constructed on free store and exec() has not been called on it, it self-destroys and any memory allocated to it freed by calling the protected close() function. If exec() has been called for an object, a call to close() will only terminate the window event loop (that is, cause exec() to unblock), which is correct for an auto (local) object as it will destroy itself when it goes out of scope. By default (that is, if not overridden by any derived classes) on_delete_event() calls close().
No special memory management for GTK+ widgets contained in the WinBase object (or in an object of a class derived from WinBase) is needed. The GTK+ object system takes care of that, and they will be released when the life of the WinBase object finishes. For this reason, the WinBase class can be used to make GTK+ exception safe: as its constructor does not throw, exceptions thrown in the constructors of classes derived from it will be correctly dealt with without causing GTK+ to leak memory if a widget is put into its container in the derived class's constructor immediately after creation on a "top down" basis, or it is placed in another widget class derived from MainWidgetBase.
If a C string is passed to the caption argument of the constructor, then the window will display that text as its caption. A NULL pointer can be passed if no caption is required. Likewise if a pointer to a GdkPixbuf object is passed as the second parameter, it will be used to set a window icon in the window bar (if the user's window manager supports this).
The constructor of WinBase does not call gtk_widget_show() because the constructor of a derived class may want to do things which require the window not to be visible. Accordingly the constructor of the derived class (or the library user) should call the WinBase::show_all() method(), or call gtk_widget_show()/gtk_widget_show_all() via WinBase::get_win().
See Writing multi-threaded programs using c++-gtk-utils for particulars about GTK+ thread safety (and so WinBase thread safety).
A small compilable example is as follows:
See Callbacks with C linkage for further discussion of the message_button_clicked() callback.
This class is not compiled into the library if the library is built with the --without-gtk configuration option.
|Cgu::WinBase::WinBase||(||const char *||caption =
|GdkPixbuf *||icon =
|GtkWindow *||parent =
|GtkWindow *||window =
The constructor will not throw.
|caption||Window caption (optional).|
|icon||A pixbuf which will comprise the window icon (optional).|
|modal||Whether the window is to be modal. If this argument is false and the window is a dialog, the user may want to consider calling gtk_window_set_type_hint() and possibly gtk_window_set_transient_for() before it becomes visible.|
|parent||The parent of a modal dialog or NULL. This argument is only acted on where the modal argument is true. The parent will be made insensitive while the modal dialog is in existence, and automatically made sensitive again when the modal dialog is finished with. gtk_window_set_transient_for() is also called, which means that the dialog will normally be kept on top of its parent and/or centered over it by the window manager. If the user does not want the parent to appear as insensitive, pass NULL to this argument and call gtk_window_set_transient_for() in the derived class's constructor.|
|window||A preformed GtkWindow object (such as a GtkDialog object), or NULL. If NULL, gtk_window_new(GTK_WINDOW_TOPLEVEL) will be called.|
The destructor will not throw assuming, in a case where the Cgu::WinBase object has been added to a Cgu::Application object, that merely iterating through a list does not throw (as it would not on any sane implementation). Amongst other things, the destructor calls gtk_widget_destroy() on the managed top level window object.
A function for the use of derived classes which will cause the window to unblock if exec() has been called. If it is not a blocking window (ie exec() has not been called so it has been constructed on freestore), this function will cause the window to delete itself. By default it is called by on_delete_event(). This method will not throw (assuming, in a case where the Cgu::WinBase object has been added to a Cgu::Application object, that merely iterating through a list does not throw, as it would not on any sane implementation), unless a derived class's destructor throws, which it should not do.
Makes the window block. Calls gtk_main(). It is usually a bad idea to call this method (and so have nested loops) on a non-modal dialog. To cause the window to unblock, call close(). Although the call to gtk_main() made by this method causes the nested main loop to block, callbacks such as timeouts, iowatches and similar events will continue to be triggered. This method will not throw.
Provides the value to be returned by exec(). This method will not throw (unless it is overridden by a derived class's method which throws).
Returns the GtkWindow object managed by this class. This method will not throw.
A convenience function which calls gtk_widget_show_all((GtkWidget*)get_win()). For classes which are intended to be derived from, it may be undesirable to call gtk_widget_show_all() in the class's constructor (a derived class may add widgets of its own in a way which requires the base class's widgets not to be realized). In such a case, calling gtk_widget_show_all() should be left to the user code. This is a function which makes that less verbose. It will not throw.