Widgets
Widgets are the reason for GTK+'s existence. Widgets are subclasses of GtkWidget, which is in turn a subclass of GtkObject. A widget represents a rectangular region on the screen, and may be purely decorative, an interactive control, or a container controlling the arrangement of child widgets. the chapter called GTK+ Basics introduces GTK+ and thus widgets; the chapter called Writing a GtkWidget covers widget implementation and concepts in more detail.
GtkWidget
Library
GTK+
Header File
gtk/gtkwidget.h
Description
GtkWidget is the parent class of all widgets. Chapters the chapter called GTK+ Basics and the chapter called Writing a GtkWidget describe widgets in general terms.
GtkWidget is an abstract base class.
GtkContainer
Library
GTK+
Header File
gtk/gtkcontainer.h
Description
GtkContainer is the abstract base class for widgets that can contain other widgets. the section called Containers And Widget Layout in the chapter called GTK+ Basics describes containers in some detail; the chapter called Writing a GtkWidget includes information on container widget implementation.
GtkBin
Library
GTK+
Header File
gtk/gtkbin.h
Description
GtkBin is an abstract base class for containers with one child. It provides default implementions of the GtkContainer interface, so it is very easy to subclass. the chapter called Writing a GtkWidget describes how to implement a GtkBin subclass.
GtkWindow
Library
GTK+
Header File
gtk/gtkwindow.h
Description
GtkWindow represents a toplevel dialog or application window. As the primary toplevel widget in GTK+, it has many special responsibilities; for example, it maintains the current keyboard focus and determines its own size allocation (rather than receiving one from a parent widget).
Gnome applications typically use GnomeApp for main application windows, to take advantage of its added features; for dialogs, you should use GnomeDialog with Gnome and GtkDialog with GTK+. Of course there are several specialized dialog subclasses available as well. If none of GtkWindow's subclasses seem appropriate to your application, GtkWindow can also be used directly.
A danger worthy of note: GtkWindow is automatically destroyed if it receives a "delete_event" signal. To prevent this, you must install the last signal handler to run, and your signal handler must return TRUE. This is a very common GTK+ programming mistake; see the section called Window Change Events in the chapter called GDK Basics for details. GnomeDialog will help you handle this situation; see the chapter called User Communication: Dialogs.
It is a good idea to make GtkWindow the last container you call gtk_widget_show() on. Most widgets are not actually mapped (placed onscreen) until their parent container is; but GtkWindow has no parent, and appears immediately. So if you show its children after you've shown the window, you will see some flicker.
GnomeDialog
Library
Gnome
Header File
libgnomeui/gnome-dialog.h
Description
GnomeDialog (or a subclass) should be used for all dialogs in a Gnome program. the chapter called User Communication: Dialogs describes the GnomeDialog interface.
If you aren't using Gnome, GnomeDialog is still useful --- because it implements all the basic features a dialog really must have. Studying the GnomeDialog source is highly recommended (you can even cut-and-paste if your application is under the GPL).
GnomeAbout
Library
Gnome
Header File
libgnomeui/gnome-about.h
Description
GnomeAbout is an about dialog, giving Gnome about dialogs a consistent look-and-feel. the section called GnomeAbout in the chapter called User Communication: Dialogs covers the interface.
GnomeMessageBox
Library
Gnome
Header File
libgnomeui/gnome-messagebox.h
Description
GnomeMessageBox is simply a GnomeDialog with a label and a small icon pre-packed inside. The icon corresponds to a "message box type," such as a warning message, an error, or a question. This helps users rapidly determine the dialog's purpose. the section called GnomeMessageBox in the chapter called User Communication: Dialogs explains the use of this widget.
GnomePropertyBox
Library
Gnome
Header File
libgnomeui/gnome-propertybox.h
Description
GnomePropertyBox is a dialog for application preferences or the properties of some user-visible object in your program. It has "apply", "OK", "close", and "help" buttons; "OK" is equivalent to "apply" followed by "close." the section called GnomePropertyBox in the chapter called User Communication: Dialogs describes it in more detail.
GnomeScores
Library
Gnome
Header File
libgnomeui/gnome-scores.h
Description
GnomeScores keeps track of and displays a high scores list. Most Gnome games use it.
GnomeApp
Library
Gnome
Header File
libgnomeui/gnome-app.h
Description
GnomeApp is a GtkWidget subclass specialized for main application windows. It has spaces for an optional toolbar, menubar, and statusbar. The application's "document" goes in a special slot in the center of the widget. the section called The GnomeApp Widget in the chapter called The Main Window: GnomeApp describes this widget.
GtkDialog
Library
GTK+
Header File
gtk/gtkdialog.h
Description
GtkDialog is a GtkWindow with three widgets pre-packed: a GtkVBox for the dialog contents, a GtkSeparator, and a GtkHBox for the dialog's buttons. GtkDialog is not very useful; all Gnome programs should use GnomeDialog instead.
GnomeFontSelector
Library
Gnome
Header File
libgnomeui/gnome-font-selector.h
Description
GnomeFontSelector is an obsolete font selection dialog, replaced by GtkFontSelectionDialog. GtkFontSelectionDialog contains a GtkFontSelection. Gnome programs should really use a GtkFontSelection inside a GnomeDialog, because GtkFontSelectionDialog does not use GnomeDialog and thus its look-and-feel is slightly wrong. GnomeFontSelector should not be used.
GtkInputDialog
Library
GTK+
Header File
gtk/gtkinputdialog.h
Description
GtkInputDialog is a dialog for selecting and setting up devices that use the X Input Extension (such as drawing tablets). It predates Gnome and is not a GnomeDialog so it looks a little funny in Gnome applications, but there is no reasonable workaround without rewriting the widget.
GtkColorSelectionDialog
Library
GTK+
Header File
gtk/gtkcolorsel.h
Description
GtkColorSelectionDialog is a dialog containing a GtkColorSelection. Gnome applications should manually place the GtkColorSelection in a GnomeDialog, or use GnomeColorPicker.
GtkFileSelection
Library
GTK+
Header File
gtk/gtkfilesel.h
Description
GtkFileSelection is a file selection dialog (unlike most of the other widgets ending in "Selection", which are composite widgets meant to be placed inside a dialog). Unfortunately, there is no Gnome replacement for this dialog, so Gnome applications typically use it, despite its somewhat inconsistent look.
GtkFontSelectionDialog
Library
GTK+
Header File
gtk/gtkfontsel.h
Description
GtkFontSelectionDialog is a dialog containing a GtkFontSelection. Gnome applications should use a GnomeDialog containing a GtkFontSelection instead.
GtkPlug
Library
GTK+
Header File
gtk/gtkplug.h
Description
GtkPlug is a toplevel window that can be embedded in a GtkSocket widget running in a separate application. In other words, GtkSocket is a "hole" in one process that can contain a GtkPlug widget from another.
GtkButton
Library
GTK+
Header File
gtk/gtkbutton.h
Description
GtkButton is a simple rectangular button. It's a container with one child; usually it contains text or a pixmap, but it can contain any widget.
GnomeColorPicker
Library
Gnome
Header File
libgnomeui/gnome-color-picker.h
Description
GnomeColorPicker is a button containing a small colored square indicating the currently selected color. When clicked, it creates a color selection dialog to change the selected color.
GnomeFontPicker
Library
Gnome
Header File
libgnomeui/gnome-font-picker.h
Description
GnomeFontPicker is analagous to GnomeColorPicker; it's a button showing the currently selected font, which pops up a font selection dialog when clicked.
GnomeHRef
Library
Gnome
Header File
libgnomeui/gnome-href.h
Description
GnomeHRef is a borderless button with a hyperlink displayed on it. When the button is clicked, Gnome points the user's browser at the hyperlink's target URL, or launches a new browser instance. The command used to go to the URL is globally configurable from the Gnome control center.
GtkToggleButton
Library
GTK+
Header File
gtk/gtktogglebutton.h
Description
GtkToggleButton looks much like a regular GtkButton. However, it is intended to reflect a toggleable state; when the toggle is "active," the button appears to be depressed. GtkCheckButton should often be used instead of the toggle button; the check button usually looks nicer than GtkToggleButton, and gives the user a better idea that the button represents a toggleable state.
GtkCheckButton
Library
GTK+
Header File
gtk/gtkcheckbutton.h
Description
The GtkCheckButton widget works just like the GtkToggleButton, but looks different (it looks like a label with a small button to the left). In most cases, the check button is a better choice than the toggle button, because the toggle button does not give the user a visual hint that it represents a toggleable state.
GtkRadioButton
Library
GTK+
Header File
gtk/gtkradiobutton.h
Description
A radio button represents one of several mutually-exclusive options. Radio buttons are placed in "groups"; only one button in a group can be active at a given time. GtkOptionMenu can also be used to represent mutually exclusive options; an option menu is typically a better choice if there are more than a few options. A GtkList or GtkCList might be appropriate if there are a truly large number of options.
GtkOptionMenu
Library
GTK+
Header File
gtk/gtkoptionmenu.h
Description
GtkOptionMenu displays the currently active item from among a number of options; when clicked, it pops up a menu to allow the user to make a new item active. The option menu is slightly broken; it does not take the size of the menu items into account when requesting its size. If you have menu items containing labels in the option menu, the labels will often be truncated. The best workaround is to give the option menu more space than it requests, by setting appropriate options on its parent container.
GnomeDockItem
Library
Gnome
Header File
libgnomeui/gnome-dock-item.h
Description
GnomeDockItem is a container that allows its child to appear on a GnomeDock. Dock items can be detached from their parent window and placed anywhere on the desktop; they can also be moved around within the dock. GnomeDock lets users rearrange Gnome toolbars. GnomeDockItem provides the "handle" for dragging its child. GnomeApp uses GnomeDock internally, so Gnome toolbars are all repositionable.
GtkAlignment
Library
GTK+
Header File
gtk/gtkalignment.h
Description
GtkAlignment is an invisible container used to align a child widget within some space. It lets you set two factors, each in both the X and Y direction; the alignment is 0.0 for left-justified (or top-justified) and 1.0 for right-justified (or bottom-justified). An alignment of 0.5 centers the child in that direction. The scale factor determines how the child fills extra space it did not request; if 0.0, the child fills only its requisition. A scale of 1.0 means that the child always expands to fill all the available space. (Clearly, a 1.0 scale factor makes the alignment factor irrelevant.)
GtkFrame
Library
GTK+
Header File
gtk/gtkframe.h
Description
The frame widget draws a decorative frame around its child. It has an optional title describing the contents of the frame. To turn off the title, set it to NULL. It also has a configurable shadow style; the four possibilities are shown in Figure 10. GTK_SHADOW_NONE is a fifth acceptable value for the shadow type; it turns the shadow off.
GtkAspectFrame
Library
GTK+
Header File
gtk/gtkaspectframe.h
Description
GtkAspectFrame is used to control the aspect ratio of its child. It also allows you to justify the child in both directions, similar to GtkAlignment. You can specify an aspect ratio, or require that the ratio of the child's size request be preserved. Visually, GtkAspectFrame looks exactly like GtkFrame.
GtkItem
Library
GTK+
Header File
gtk/gtkitem.h
Description
GtkItem is an abstract base class for list items, tree items, and menu items. Items are widgets that can be "selected," "deselected," and "toggled."
GtkMenuItem
Library
GTK+
Header File
gtk/gtkmenuitem.h
Description
A menu item is an invisible container; it is the only kind of widget that can appear in a GtkMenu. Typically, a label or a label and a pixmap are placed in the menu item to indicate its function. If a menu item has no child widget, it draws a separator line instead. This saves the overhead of adding a GtkSeparator to the menu item.
GtkCheckMenuItem
Library
GTK+
Header File
gtk/gtkcheckmenuitem.h
Description
GtkCheckMenuItem is a menu item that works like a GtkCheckButton; it has a small button next to its child widget, which is either "active" or "inactive." Because it's a subclass of GtkMenuItem, it can appear in menus.
GtkRadioMenuItem
Library
GTK+
Header File
gtk/gtkradiomenuitem.h
Description
A radio menu item works like GtkRadioButton; it allows the user to choose from a set of mutually exclusive options. Because it's a subclass of GtkMenuItem, it can appear in menus.
GtkPixmapMenuItem
Library
Gnome
Header File
libgnomeui/gtkpixmapmenuitem.h
Description
GtkPixmapMenuItem is a Gnome widget despite its name. This widget solves a very specific problem: namely, if a menu contains check or radio menu items, GTK+ indents the child widget of all the menu items in the menu to make room for the check or radio buttons. Gnome uses pixmaps next to some menu items; GtkPixmapMenuItem indents pixmaps in the same way GTK+ indents check or radio buttons. If you simply added a pixmap and a label to a GtkMenuItem, the pixmap would be incorrectly aligned with the plain labels in other menu items. This widget is not really pixmap-specific; any widget can be placed in the unindented "pixmap" slot. Usually GtkPixmapMenuItem is created implicitly with the Gnome menu creation functions.
GtkTearoffMenuItem
Library
GTK+
Header File
gtk/gtktearoffmenuitem.h
Description
GtkTearoffMenuItem is a "perforation" representing a spot where a menu can be "torn off" (kept visible in a toplevel window for easy access). Gnome menus all include a tearoff menu item by default, but users can globally disable them using the Gnome control center.
GtkListItem
Library
GTK+
Header File
gtk/gtklistitem.h
Description
GtkListItem is an invisible container that allows its child to appear in a GtkList. That is, only list items can appear in a list.
GtkTreeItem
Library
GTK+
Header File
gtk/gtktreeitem.h
Description
GtkTreeItem is an invisible container that gives its child the ability to appear in a GtkTree. Only tree items can be placed in the tree widget.
GtkEventBox
Library
GTK+
Header File
gtk/gtkeventbox.h
Description
The event box widget may be the simplest container in GTK+; its only purpose is to have a GdkWindow. Certain operations only work on widgets with windows (such as setting the background color, or capturing events); if you want to perform these operations on a windowless widget, you can place the widget in an event box and perform the operations on the event box, achieving much the same effect.
GtkHandleBox
Library
GTK+
Header File
gtk/gtkhandlebox.h
Description
The handle box widget can be adds a handle to a child widget; by dragging on the handle, the child can be removed from the window and positioned elsewhere on the user's desktop. The handle box is often used for toolbars. GnomeDock and GnomeDockItem offer a more flexible (but more elaborate) alternative.
GtkScrolledWindow
Library
GTK+
Header File
gtk/gtkscrolledwindow.h
Description
GtkScrolledWindow provides horizontal and vertical scrollbars for its child widget. Optionally, the scrollbars are hidden when the entire child is visible. If a child widget has a set_scroll_adjustments_signal in its GtkWidgetClas (see the section called Overridable Signals in the chapter called Writing a GtkWidget), the scrolled window uses them as the adjustments for the scrollbars. Otherwise, the scrolled window scrolls the entire widget using a GtkViewport. (Consider GtkCList for example; the column titles aren't scrolled, only the list contents. Thus GtkCList provides scroll adjustment signals.)
GtkViewport
Library
GTK+
Header File
gtk/gtkviewport.h
Description
GtkViewport is more or less an implementation detail of GtkScrolledWindow. It contains a widget that does not provide a set_scroll_adjustments_signal, and provides such a signal on the child widget's behalf. See GtkScrolledWindow for more details.
GtkBox
Library
GTK+
Header File
gtk/gtkbox.h
Description
GtkBox is an abstract base class for GtkVBox, GtkHBox, and GtkButtonBox. It's an invisible layout container; the chapter called GTK+ Basics describes it in some detail.
GtkHBox
Library
GTK+
Header File
gtk/gtkhbox.h
Description
GtkHBox is a GtkBox that packs widgets from left to right. The left side is considered the "start" of the box.
GnomeAppBar
Library
Gnome
Header File
libgnomeui/gnome-appbar.h
Description
GnomeAppBar is a simple status bar with an optional progress meter. It does not have "contexts" like GtkStatusbar. the section called GnomeAppBar in the chapter called The Main Window: GnomeApp gives more details.
GnomeDateEdit
Library
Gnome
Header File
libgnomeui/gnome-dateedit.h
Description
GnomeDateEdit allows the user to edit a date and time. The time-editing part can be turned off if you are only interested in the date.
GtkCombo
Library
GTK+
Header File
gtk/gtkcombo.h
Description
GtkCombo is a text entry box with a drop-down menu "quick choices." If you want to limit the user to a fixed set of options, a GtkOptionMenu is more appropriate. GtkCombo allows the user to type in anything, but offers some suggestions as well. GnomeEntry is a combo box that adds items the user types in to the list of choices in the drop-down menu, and automatically remembers the list from session to session.
GnomeEntry
Library
Gnome
Header File
libgnomeui/gnome-entry.h
Description
GnomeEntry is a GtkCombo extension that uses the drop-down menu as a history. If the user types something which isn't in the history already, GnomeEntry adds it and saves it in a configuration file to be loaded next time the application starts up.
GnomeFileEntry
Library
Gnome
Header File
libgnomeui/gnome-file-entry.h
Description
GnomeFileEntry is a GnomeEntry that keeps file names in its history. It also has a "Browse" button which pops up a GtkFileSelection. It has a "directories only" mode as well.
GnomeNumberEntry
Library
Gnome
Header File
libgnomeui/gnome-number-entry.h
Description
GnomeNumberEntry allows the user to enter a number; it keeps a history of numbers entered in its drop-down menu. It also has a "Calculator" button to pop up a GnomeCalculator.
GnomeProcBar
Library
Gnome
Header File
libgnomeui/gnome-procbar.h
Description
GnomeProcBar is used in a Gnome panel applet that displays CPU and memory load, and in the GTop application (a graphical top clone). It displays a colored bar that can change length; it could be used to display any kind of constantly-changing value.
GtkStatusbar
Library
GTK+
Header File
gtk/gtk.h
Description
GtkStatusbar is described in the section called GtkStatusbar in the chapter called The Main Window: GnomeApp. It's a status bar widget; it displays a line of text at the bottom of a window.
GtkVBox
Library
GTK+
Header File
gtk/gtkvbox.h
Description
GtkVBox is a GtkBox that packs widgets from top to bottom. The top is considered the "start" of the box.
GnomeCalculator
Library
Gnome
Header File
libgnomeui/gnome-calculator.h
Description
GnomeCalculator is a simple calculator, implemented as a GtkWidget.
GnomeGuru
Library
Gnome
Header File
libgnomeui/gnome-guru.h
Description
GnomeGuru was an attempt to implement a "wizard" widget (a series of pages representing steps in a task that the user can step through). It is an immature interface and should not be used; at press time, it appears that a new widget called GnomeDruid will replace it in the next version of Gnome. GnomeDruide will most likely be available as an add-on module before that, so look for it if you need a wizard widget.
GnomeIconEntry
Library
Gnome
Header File
libgnomeui/gnome-icon-entry.h
Description
GnomeIconEntry is similar to GnomeColorPicker and GnomeFontPicker. It's a button displaying a currently-selected icon; when the button is clicked, an icon browser dialog allows the user to set a new icon. The widget used to have a text entry for typing an icon filename, thus it is called GnomeIconEntry rather than GnomeIconPicker.
GnomeIconSelection
Library
Gnome
Header File
libgnomeui/gnome-icon-sel.h
Description
GnomeIconSelection browses icon files; it's used by GnomeIconEntry but can also be used directly.
GnomeLess
Library
Gnome
Header File
libgnomeui/gnome-less.h
Description
GnomeLess is a simple extension of GtkText that loads text from a file or file descriptor and displays it. It is probably a good idea to avoid this widget; because it isn't very useful, it is likely to disappear from future versions of Gnome.
GnomePaperSelector
Library
Gnome
Header File
libgnomeui/gnome-paper-selector.h
Description
GnomePaperSelector is another widget worth avoiding; in the 1.0 release, it is strictly experimental. It allows the user to select the paper size for printing.
GnomePixmapEntry
Library
Gnome
Header File
libgnomeui/gnome-pixmap-entry.h
Description
GnomePixmapEntry has essentially the same purpose as GnomeIconEntry; it allows the user to select a pixmap. The only reason you might prefer one to the other is that GnomeIconEntry scales images to the standard Gnome icon size.
GnomeSpell
Library
Gnome
Header File
libgnomeui/gnome-spell.h
Description
GnomeSpell is a spell-checker interface; it uses the ispell program internally. This widget should be considered experimental and avoided in production code.
GtkColorSelection
Library
GTK+
Header File
gtk/gtkcolorsel.h
Description
GtkColorSelection allows the user to specify a color, using a color wheel or sliders. It makes up the contents of GtkColorSelectionDialog (Figure 1 in the section called Description).
GtkGammaCurve
Library
GTK+
Header File
gtk/gtkgamma.h
Description
GtkGammaCurve allows the user to edit a curve; it's a very specialized widget used in the Gimp. Few applications will have a use for it.
GtkButtonBox
Library
GTK+
Header File
gtk/gtkbbox.h
Description
GtkButtonBox is a special kind of GtkBox designed to store the buttons of a dialog. It has horizontal and vertical variants. GnomeDialog creates a button box for you, so there is no need to use this widget directly when programming with Gnome.
GtkHButtonBox
Library
GTK+
Header File
gtk/gtkhbbox.h
Description
GtkHButtonBox is the horizontal variant of GtkButtonBox.
GtkVButtonBox
Library
GTK+
Header File
gtk/gtk.h
Description
GtkVButtonBox is the vertical variant of GtkButtonBox.
GtkLayout
Library
GTK+
Header File
gtk/gtklayout.h
Description
GtkLayout creates the illusion of a container with infinite size. Because X windows are limited to 32,768 pixels in size (2^15), most widgets also have a 32,768-pixel size limit (and child widgets must be positioned within the parent's X window). Naive widgets scroll by simply moving their GdkWindow. GtkLayout is more intelligent about this.
GnomeCanvas
Library
Gnome
Header File
libgnomeui/gnome-canvas.h
Description
GnomeCanvas is extensively discussed in the chapter called GnomeCanvas. It renders flicker-free structured graphics, and is ideal for custom displays.
GnomeIconList
Library
Gnome
Header File
libgnomeui/gnome-icon-list.h
Description
GnomeIconList is used in the Gnome file manager. It displays icons and their names; users can select groups of icons by rubberbanding.
GnomeDockBand
Library
Gnome
Header File
libgnomeui/gnome-dock-band.h
Description
GnomeDockBand contains one row or column of GnomeDockItems; a GnomeDock in turn contains one or more GnomeDockBands. See the GnomeDockItem entry for details and a screenshot.
GnomeDock
Library
Gnome
Header File
libgnomeui/gnome-dock.h
Description
GnomeDock collects GnomeDockBands which in turn hold GnomeDockItems. GnomeDock allows users to reposition toolbars and other application components. See the GnomeDockItem entry for details and a screenshot.
GtkCList
Library
GTK+
Header File
gtk/gtkclist.h
Description
GtkCList is a list-with-columns widget; it is also the base class for GtkCTree. GtkCList displays text and/or a pixmap in each cell; it cannot hold child widgets in its cells. GtkCList is only a container because it uses widgets for the column headings. You may prefer GtkList, which can have child widgets as list items, but is less efficient and has a maximum list size of 32,768 pixels.
GtkCTree
Library
GTK+
Header File
gtk/gtkctree.h
Description
GtkCTree is similar to GtkCList, but (unsurprisingly) displays a tree with expandable nodes instead of a simple list. GtkTree is a more flexible tree widget (it can have arbitrary widgets in the tree cells), but it is less efficient and limited to 32,768 pixels.
GtkFixed
Library
GTK+
Header File
gtk/gtkfixed.h
Description
The GtkFixed container allows you to position child widgets at absolute coordinates, and always gives child widgets exactly their requested size. This widget is for masochists; it doesn't do anything automatically. You should almost always use another layout widget instead (if you think you need the fixed widget, consider asking for help; most likely a real layout widget can be made to work better).
GtkNotebook
Library
GTK+
Header File
gtk/gtknotebook.h
Description
A notebook widget presents the user with several "pages"; the user can move a page to the top by selecting its "tab." Each child added to GtkNotebook becomes a page; you can also specify widgets to use for the tab labels. It is generally considered bad practice to have more than a single row of tabs, but GtkNotebook does allow it. It is also possible to position the tabs on the left, right, or bottom of the notebook, but you should always leave them on top for interface consistency.
GtkFontSelection
Library
GTK+
Header File
gtk/gtkfontsel.h
Description
GtkFontSelection is a composite widget that allows the user to select a font from among the fonts available on the system. GtkFontSelectionDialog contains an instance of GtkFontSelection. Gnome applications should place a GtkFontSelection in a GnomeDialog.
GtkPaned
Library
GTK+
Header File
gtk/gtkpaned.h
Description
The GtkPaned widget divides an area into two user-resizable sections. It has horizontal and vertical variants.
GtkHPaned
Library
GTK+
Header File
gtk/gtkhpaned.h
Description
GtkHPaned is the horizontal variant of GtkPaned; it allows the user to divide a horizontal space between the GtkHPaned's two child widgets.
GtkVPaned
Library
GTK+
Header File
gtk/gtkvpaned.h
Description
GtkVPaned is the vertical variant of GtkPaned; it allows the user to divide a vertical space between the GtkVPaned's two child widgets.
GtkList
Library
GTK+
Header File
gtk/gtklist.h
Description
GtkList displays a list of items. Each item is a GtkListItem; GtkListItem is a container that can hold any kind of widget. The size of a GtkList is limited, because list items are placed at fixed coordinates in the list's GdkWindow, and scrolling is achieved by moving the GdkWindow; GdkWindow has a maximum size of 32,768 pixels, and any list item positioned outside that range is invisible. GtkCList overcomes this limitation, but is unable to contain arbitrary widgets.
GtkMenuShell
Library
GTK+
Header File
gtk/gtkmenushell.h
Description
GtkMenuShell is an abstract base class for widgets that contain GtkMenuItems. Its two subclasses are GtkMenu and GtkMenuBar.
GtkMenuBar
Library
GTK+
Header File
gtk/gtkmenubar.h
Description
GtkMenuBar is a menu bar. It contains one or more menu items; normally, each menu item will have a submenu (i.e., a GtkMenu with more menu items). For example, the menu bar might have a menu item called "File," with a submenu containing the menu items "Open" and "Quit."
GtkMenu
Library
GTK+
Header File
gtk/gtkmenu.h
Description
GtkMenu contains menu items. GtkMenu is unique because it should not be shown (with gtk_widget_show()) by the programmer; menus are popped up in response to user actions.
GtkPacker
Library
GTK+
Header File
gtk/gtkpacker.h
Description
GtkPacker is a layout container inspired by the Tk toolkit. If you're familiar with that toolkit, you may find it easier to use than the standard GTK+ layout containers.
GtkSocket
Library
GTK+
Header File
gtk/gtksocket.h
Description
GtkSocket is a "hole" in one application that allows a GtkPlug from a second application to be embedded.
GtkTable
Library
GTK+
Header File
gtk/gtktable.h
Description
the section called GtkTable in the chapter called GTK+ Basics desribes GtkTable in some detail. It's one of the most important GTK+ layout widgets.
GtkTed
Library
Gnome
Header File
libgnomeui/gtk-ted.h
Description
GtkTed is a relic from the early days of Gnome; "ted" stands for "table editor." It's a kind of primitive GUI builder. There are at least two advanced projects to write good GUI builders (Glade and GLE), so this widget should be ignored and will disappear in a future version of libgnomeui.
GtkToolbar
Library
GTK+
Header File
gtk/gtktoolbar.h
Description
No surprises here: GtkToolbar is a toolbar widget. Gnome applications will usually use the Gnome helper functions instead of creating a toolbar directly, as described in the chapter called The Main Window: GnomeApp.
GtkTree
Library
GTK+
Header File
gtk/gtktree.h
Description
GtkTree is to GtkCTree as GtkList is to GtkCList. That is, GtkTree is more flexible than GtkCTree---tree items can contain any widget--- but it's also a bit slower than GtkCTree and holds only a limited number of items. The maximum number of items depends on the height of the rows; the total row height must fit inside a GdkWindow, which means 32,768 pixels.
GnomeAnimator
Library
Gnome
Header File
libgnomeui/gnome-animator.h
Description
GnomeAnimator displays a series of images, creating an animation. It has a "loop mode" and a "play once" mode. The GnomeAnimator API is marked "immature" in Gnome 1.0 and may change incompatibly in future versions; this is an experimental widget.
GnomePixmap
Library
Gnome
Header File
libgnomeui/gnome-pixmap.h
Description
GnomePixmap should be preferred to GtkPixmap, though it has the same purpose. GnomePixmap is a bit smarter about visuals. It can also load images from many different formats, using Imlib, so it's more convenient to use.
GnomeStock
Library
Gnome
Header File
libgnomeui/gnome-stock.h
Description
GnomeStock is a container that wraps a GnomePixmap; it automatically creates "insensitive" and "focused" copies of the pixmap to reflect the widget state. It can be set to one of the Gnome stock pixmap macros, such as GNOME_STOCK_PIXMAP_CUT (small picture of scissors), GNOME_STOCK_PIXMAP_PRINT (a little printer), etc. You can also register new stock pixmaps specific to your application at runtime. Gnome uses this widget internally when creating menus and toolbars using a GnomeUIInfo template (see the section called Menus and Toolbars with GnomeUIInfo in the chapter called The Main Window: GnomeApp).
GtkMisc
Library
GTK+
Header File
gtk/gtkmisc.h
Description
The descriptively-named (or not) GtkMisc abstract base class allows you to set the "alignment" and "padding" of its subclasses. Alignment is a float between 0.0 and 1.0, where 0.0 is left-justified, 0.5 is centered, and 1.0 is right-justified. Alignment only matters if a GtkMisc receives a size allocation larger than its size request; the alignment locates the natural bounding box of the widget within its actual bounding box. Padding is a number of pixels to add to the widget's size request. The widget will then leave those pixels blank.
Widgets that do not derive from GtkMisc can be made "alignable" in the same way by placing them in a GtkAlignment container.
GtkLabel
Library
GTK+
Header File
gtk/gtklabel.h
Description
GtkLabel simply displays a text string. If the text string contains newlines, GtkLabel displays multiple lines. Labels honor the alignment parameter from their parent class (GtkMisc); you can use this to center the text, or move it to the left or right. Alignment is not the same as justification. Justification defines the position of multiple lines with respect to each other. Left-justified means each line starts in the same place, right-justified means each ends in the same place, center-justified means each is centered around the same imaginary line. Justification has no meaning for one-line labels. Alignment set with gtk_misc_set_alignment() positions the entire block of text within its size allocation; alignment only matters if the label receives more space than it requested (it will request just enough to hold the text block). Labels are GTK_NO_WINDOW widgets (which means they don't receive events and draw on their parent's background).
GtkAccelLabel
Library
GTK+
Header File
gtk/gtkaccellabel.h
Description
GtkAccelLabel is associated with some other widget, and displays the accelerator key for that widget as part of the label.
GtkClock
Library
Gnome
Header File
libgnomeui/gtk-clock.h
Description
GtkClock is a label that displays a time. It can optionally update the time periodically (just like a clock!).
GtkTipsQuery
Library
GTK+
Header File
gtk/gtktipsquery.h
Description
GtkTipsQuery is a label that displays tooltips. It also has "What's This?" functionality. You call gtk_tips_query_start() to switch to "query mode." In query mode, the cursor is changed to a question mark; as the mouse moves over widgets in the application, the GtkTipsQuery displays their tooltips. GtkTipsQuery emits a "widget_selected" signal if the user clicks on a widget; you can use this to display more extensive help for that widget. You might store the more extensive help as the "private" component of a GtkTooltip, or you might use gtk_object_set_data() to store some kind of application-specific help information.
GtkArrow
Library
GTK+
Header File
gtk/gtkarrow.h
Description
GtkArrow displays an arrow. It's a very simple GTK_NO_WINDOW widget and doesn't even receive events. In the default theme, an arrow is simply a triangle.
GtkImage
Library
GTK+
Header File
gtk/gtkimage.h
Description
GtkImage displays a GdkImage in a widget. It's only useful if you already have a GdkImage; to display a fixed image you usually want GnomePixmap.
GtkPixmap
Library
GTK+
Header File
gtk/gtkpixmap.h
Description
GtkPixmap displays a GdkPixmap. If you're using Gnome, prefer GnomePixmap for the reasons given in its description.
GtkCalendar
Library
GTK+
Header File
gtk/gtkcalendar.h
Description
GtkCalendar displays a calendar page (one month). It allows users to select a date. GnomeDateEdit uses GtkCalendar in a popup menu.
GtkDrawingArea
Library
GTK+
Header File
gtk/gtkdrawingarea.h
Description
GtkDrawingArea is a thin wrapper around GdkWindow; it gives you a blank area to draw on. Normally, you would connect to its "configure_event" signal to catch changes in the size of the area, and do your drawing in an "expose_event" handler. To eliminate flicker, you might keep a GdkPixmap equal in size to the drawing area, and draw to the pixmap; in your "expose_event" handler, simply copy the exposed region from the pixamp to the drawing area.
For high-level graphics, GnomeCanvas can be much more convenient to use.
GtkCurve
Library
GTK+
Header File
gtk/gtkcurve.h
Description
GtkCurve is used to display the curve in the GtkGammaCurve widget. It's a drawing area extension with curve-drawing abilities. Most likely you won't find a use for this widget.
GtkDial
Library
GTK+
Header File
gtk/gtkdial.h
Description
GtkDial is a "speedometer" display. By default, the user can drag the "needle" around, changing the dial's value. GtkDial also has a "view only" mode.
GtkEditable
Library
GTK+
Header File
gtk/gtkeditable.h
Description
GtkEditable is an abstract base class for widgets that allow the user to edit text. The base class interface allows cursor positioning, retrieving characters, and so on. It also includes the "changed" signal, which you can use to detect user input.
GtkEntry
Library
GTK+
Header File
gtk/gtkentry.h
Description
GtkEntry allows the user to enter a single line of text. It has a "password" mode; in "password" mode the text in the entry is replaced by asterisks.
GtkSpinButton
Library
GTK+
Header File
gtk/gtkspinbutton.h
Description
GtkSpinButton is a GtkEntry customized to allow the user to enter a number. Spin buttons add up and down arrows to the entry, so the user can rapidly spin through the possible values.
GtkText
Library
GTK+
Header File
gtk/gtktext.h
Description
GtkText is a text widget. It can display text, and offers simple text-editing facilities.
Two questions about the text widget are very frequently asked on the GTK+ mailing lists. These are:
-
Does the text widget support horizontal scrolling?
-
The text widget doesn't seem to be very powerful. Are there plans to replace it?
The text widget does not support horizontal scrolling; instead, it wraps lines. It is not very powerful, and the code is difficult to maintain; it will most likely be replaced in Gtk 1.4 as part of the move to Unicode.
GtkRuler
Library
GTK+
Header File
gtk/gtkruler.h
Description
GtkRuler is an abstract base class for the horizontal and vertical ruler widgets. The ruler widgets are used in the GIMP to display image dimensions.
GtkRange
Library
GTK+
Header File
gtk/gtkrange.h
Description
GtkRange is an abstract base class for "slider" widgets. These widgets modify some numeric value as a "slider" is moved in a "trough." The two subclasses of GtkRange are GtkScale, used to allow the user to enter a numeric value, and GtkScrollbar, the GTK+ scrollbar widget.
GtkScale
Library
GTK+
Header File
gtk/gtkscale.h
Description
GtkScale allows the user to enter a numeric value by moving a slider. It can display the current value above the slider; you can turn this off if the exact value isn't relevant, or you want to provide feedback in some other way. GtkScale is an abstract base class; you must instantiate its vertical or horizontal variant.
GtkHScale
Library
GTK+
Header File
gtk/gtkhscale.h
Description
GtkHScale is the horizontal variant of GtkScale.
GtkVScale
Library
GTK+
Header File
gtk/gtkvscale.h
Description
GtkVScale is the vertical variant of GtkScale.
GtkScrollbar
Library
GTK+
Header File
gtk/gtkscrollbar.h
Description
GtkScrollbar is an abstract base class, giving horizontal and vertical scrollbars a common interface.
GtkSeparator
Library
GTK+
Header File
gtk/gtkseparator.h
Description
The GtkSeparator widget is a divider line you can use to make your interface more attractive. For example, a GtkHSeparator is used to divide the contents of a GnomeDialog from its buttons.
GtkPreview
Library
GTK+
Header File
gtk/gtkpreview.h
Description
GtkPreview displays an RGB image; the GIMP uses it to display a preview of the effects of an image transformation.
GtkProgress
Library
GTK+
Header File
gtk/gtkprogress.h
Description
GtkProgress is an abstract base class for progress displays. In GTK+ 1.2 only one concrete subclass exists (GtkProgressBar). Future versions of GTK+ may add additional progress widgets.
GtkProgressBar
Library
GTK+
Header File
gtk/gtkprogressbar.h
Description
GtkProgressBar is a flexible progress bar widget. It can display text over the progress bar, and has an "activity" mode to indicate "activity, but unknown total task size." In "activity" mode a small block moves back and forth. GtkProgressBar is probably excessively configurable; you should try to use its default look-and-feel, for consistency with other applications.
ZvtTerm
Library
Zvt
Header File
zvt/zvtterm.h
Description
ZvtTerm comes with gnome-libs but is not in libgnomeui. It's in a separate libzvt. ZvtTerm is simply a terminal emulator; you can spawn a child process to run inside the widget and interact with the user. ZvtTerm provides all the functionality of the gnome-terminal program that comes with the Gnome desktop environment.
