This is a class for managing the lifetime of top level widgets. More...
#include <c++-gtk-utils/window.h>
Public Member Functions | |
| WinBase (const WinBase &)=delete | |
| WinBase & | operator= (const WinBase &)=delete |
| GtkWindow * | get_win () const |
| int | exec () |
| void | show_all () |
| void | show () |
| WinBase (const char *caption=0, GdkPixbuf */const char *icon=0, bool modal=false, GtkWindow *parent=0, GtkWindow *window=0) | |
| virtual | ~WinBase () |
Protected Member Functions | |
| void | close () |
| virtual int | get_exec_val () const |
| virtual void | on_close_request () |
| virtual void | on_delete_event () |
Detailed Description
This is a class for managing the lifetime of top level widgets.
- See also
- MainWidgetBase Application
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).
WinBase objects can be used with widget heirarchies or top level windows created using GtkBuilder. See Using c++-gtk-utils with GtkBuilder for particulars about that.
A small compilable example is as follows:
See Callbacks with C linkage for further discussion of the message_button_clicked() callback.
- Note
- The WinBase class will work fine if a GtkDialog object is passed to the last argument of the class's constructor formed from a call to gtk_dialog_new()/gtk_dialog_new_with_buttons(), but a few points should be noted:
- 1. If the response signal has been connected to, a delete event (or with GTK-4 a close request) will cause a response signal to be emitted with the GTK_RESPONSE_DELETE_EVENT id, as well as causing the normal WinBase::on_delete_event() or WinBase::on_close_request() method to be called. If the response handler acts on the GTK_RESPONSE_DELETE_EVENT id by calling close(), then WinBase::on_delete_event() or WinBase::on_close_request() should normally be overridden to do nothing so that a double call to close() is not made (although c++-gtk-utils will check against and prevent such a double call of close() from a single delete/close event if that is not done).
- 2. It is usually best not to call gtk_dialog_run(). Instead, call WinBase::exec() for a blocking dialog, and override WinBase::get_exec_val() to return any required button response id.
- 3. If creating a GtkDialog object with gtk_dialog_new_with_buttons(), do not pass a GtkDialogFlags argument of GTK_DIALOG_DESTROY_WITH_PARENT. A GtkDialogFlags argument of GTK_DIALOG_MODAL can be passed, but alternatively to make the dialog modal the user can pass 'true' as the modal argument of the WinBase constructor and pass the parent widget to that constructor rather than to gtk_dialog_new_with_buttons() (so that GtkDialogFlags(0) is passed as the third argument of gtk_dialog_new_with_buttons()). Either approach will work, but the second has the advantage of consistency with the WinBase interface.
- 4. Likewise, if using gtk_dialog_new_with_buttons(), any dialog caption can be passed either to the title argument of that method or to the caption argument of the WinBase constructor.
- Similar principles apply to the management of objects derived from GtkDialog.
This class is not compiled into the library if the library is built with the --without-gtk configuration option.
Constructor & Destructor Documentation
◆ WinBase() [1/2]
|
delete |
This class cannot be copied. The copy constructor is deleted.
◆ WinBase() [2/2]
| Cgu::WinBase::WinBase | ( | const char * | caption = 0, |
| GdkPixbuf */const char * | icon = 0, |
||
| bool | modal = false, |
||
| GtkWindow * | parent = 0, |
||
| GtkWindow * | window = 0 |
||
| ) |
The constructor will not throw.
- Parameters
-
caption Window caption (optional). icon An icon which will comprise the window icon (optional - NULL or nullptr may be passed). For GTK-2 and GTK-3 this is of type GdkPixbuf*. For GTK-4 this is of type const char*, representing an icon theme name rather than the icon itself. 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.
◆ ~WinBase()
|
virtual |
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.
Member Function Documentation
◆ close()
|
protected |
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() or on_close_request(). 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.
◆ exec()
| int Cgu::WinBase::exec | ( | ) |
Makes the window block. Calls gtk_main() (or with GTK-4, g_main_loop_run()). 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() or g_main_loop_run() 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.
- Returns
- The value returned by get_exec_val().
- Note
- If this library is compiled against GTK-3 or GTK-4 and the WinBase object has been added to a Cgu::Application object, then this method returns immediately with a value of -1.
◆ get_exec_val()
|
protectedvirtual |
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
- By default returns 0. It is intended to be overridden by derived classes where relevant to provide a more meaningful value.
◆ get_win()
|
inline |
Returns the GtkWindow object managed by this class. This method will not throw.
- Returns
- The managed GtkWindow object.
◆ on_close_request()
|
protectedvirtual |
Called when there is a close request on the managed window. Unless overridden by derived classes it just calls close().
This function is only available with GTK-4. Where this library has been compiled against GTK-2 or GTK-3, use on_delete_event().
gtk_window_set_hide_on_close() has no effect for a window managed by this class. Instead, the action taken on a close request is determined by this method or its overrides.
Since 2.2.16
Reimplemented in Cgu::FilePrintDialog.
◆ on_delete_event()
|
protectedvirtual |
Called when there is a delete event on the managed window. Unless overridden by derived classes it just calls close().
This function is only available with GTK-2 and GTK-3. Where this library has been compiled against GTK-4, use on_close_request().
Reimplemented in Cgu::FilePrintDialog.
◆ operator=()
This class cannot be copied. The assignment operator is deleted.
◆ show()
|
inline |
A convenience function which calls gtk_widget_show((GtkWidget*)get_win()), so as to make calling that function less verbose. It will not throw.
Since 2.2.15
◆ show_all()
|
inline |
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.
This function is not available where this library is compiled against GTK-4 (gtk_widget_show_all() does not exist in GTK-4).
The documentation for this class was generated from the following file:
