The Official GNOME 2 Developers Guide

3.2 Windows

There is a window in Section 3.1.3's example program; you can see that it is a container widget object of the GtkWindow class (type identifier: GTK_TYPE_WINDOW ).

To set a window's title, write a string into its title property. The user should be able to distinguish the window's title in a list of windows (for example, in a window manager menu). An application window's title ideally stems from the document currently in that window ” a filename, directory, or similar. If you insist on including the application name in the title, place it after the document name, but GNOME guidelines advise even against this. Any other information in the title bar is essentially a waste of space. ^[1]

Here are several versions of the same title and how they rank:

• Good: Order.mtx

• Not so great: Order.mtx - MiracleText

• Poor: MiracleText: Order.mtx

• Really bad: MiracleText 0.16.7 (CVS BUILD #1247)

If a window doesn't contain a document, the naming conventions are somewhat different:

• Application windows: Name of the application (LavaLamp).

• Property windows: Name of object - Properties (Table 3.1 - Properties).

• Preferences windows: Name of the application - Preferences (MiracleText - Preferences).

• Warnings: No title. Windows containing warnings should display their information as a short blurb inside the window; if you put the same thing in the title bar, it would show up twice on the screen and look a little confusing. Well, that's what the guidelines say, at least. My opinion is that a short title such as Warning or Info never hurt anyone . Furthermore, nameless windows look a little odd in a window manager's list. Section 3.10 covers dialog boxes and the titles that GTK+ may automatically supply.

• Druids (assistants): Name of the druid (Configure Coffee Machine); for more information on druids, see Section 4.3.15.

Significant GtkWindow properties and their types include the following:

• resizable ( gboolean ): If TRUE , the user may change the window's size .

  Note	It's practically never a good idea to set this property to FALSE , thereby making it impossible for users to adjust the window to their preferences. If you set up your container layout properly, the contents remain usable and in proper order at any size.

• modal ( gboolean ): When TRUE , this is a modal window. None of the application's other windows respond to input as long as the modal window exists.

  Warning

  In most modern applications, modal windows are completely unnecessary. You should try to do without modal windows, because users tend to become frustrated when a window ignores their input due to some hidden dialog box.

• window-position ( GtkWindowPosition ): This property determines where the window will appear on the display. The possible values are:

  • GTK_WIN_POS_NONE : Let the window manager decide where it wants to put the window. This is the default.

  • GTK_WIN_POS_CENTER_ON_PARENT : Place the window on top of the parent, using the parent's center as its center.

  • GTK_WIN_POS_CENTER : Put the window in the center of the monitor, at least as much as possible.

  • GTK_WIN_POS_CENTER_ALWAYS : Try to keep the window centered, even if the window size changes.

  • GTK_WIN_POS_MOUSE : Place the window as close to the mouse pointer as possible.

  All of these values assume that the window manager cooperates ” that is, it understands and follows NET_WM hints [XDG].

• default-width ( gint ): The default width, as seen in the previous example.

• default-height ( gint ): The default height.

  Note	If you decide to force the size of a window, at least use some sensible proportions : for example, a 1:1.6 ratio (the golden section).

• destroy-with-parent ( gboolean ): If TRUE , GTK+ will destroy this window upon the destruction of the window's parent.

• icon ( GdkPixBuf ; see Section 3.3.2): The window's icon. The icon should closely resemble that of its menu item or any other graphical means of starting the application.

3.2.1 Icons

In any polished application, you should outfit your window with an icon that appears in the window list and other places. These routines install icons:

• gboolean gtk_window_set_icon_from_file(GtkWindow * window , const char * filename , GError ** error )

  Sets the icon for window to the image in filename , returning TRUE upon success.

• void gtk_window_set_icon(GtkWindow * window , GdkPixbuf * pixbuf )

  Like the preceding function, but uses pixbuf instead of a filename and does not return a value.

• void gtk_window_set_icon_list(GtkWindow * window , GList * pixmap_list )

  Like the preceding function, but uses the first available pixmap in the pixmap_list .

• gboolean gtk_window_set_default_icon_from_file(const char * filename , GError ** error )

  Sets all of the current application's icons to the image in filename .

^[1] GNOME has functions to keep application window titles consistent ” see Section 4.3.1.