path: root/docs/reference/gtk/glossary.xml

<?xml version="1.0"?>
<!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>
<glossary id="glossary">
  <title>Glossary</title>

  <glossentry id="allocation">
    <glossterm>allocation</glossterm>
    <glossdef>
      <para>
	The final size of a <glossterm
	linkend="widget">widget</glossterm> within its <glossterm
	linkend="parent">parent</glossterm>.  For example, a widget
	may request a minimum size of 20&times;20 pixels, but its
	parent may decide to allocate 50&times;20 pixels for it
	instead.
      </para>
      <glossseealso>
	<glossterm linkend="requisition">requisition</glossterm>
      </glossseealso>
    </glossdef>
  </glossentry>

  <glossentry id="bin">
    <glossterm>bin</glossterm>
    <glossdef>
      <para>
	A <glossterm linkend="container">container</glossterm> that
	can hold at most one child widget.  The base class for bins is
	#GtkBin.
      </para>
      <glossseealso>
	<glossterm linkend="container">container</glossterm>
      </glossseealso>
    </glossdef>
  </glossentry>

  <glossentry id="child">
    <glossterm>child</glossterm>
    <glossdef>
      <para>
	A <glossterm linkend="container">container's</glossterm> child
	is a <glossterm linkend="widget">widget</glossterm> contained
	inside it.
      </para>
    </glossdef>
  </glossentry>

  <glossentry id="column">
    <glossterm>column</glossterm>
    <glossdef>
      <para>
	GTK+ contains several widgets which display data in columns,
        e.g. the #GtkTreeView. 
        These <glossterm linkend="view-column">view columns</glossterm> in 
        the tree view are represented by #GtkTreeViewColumn
        objects inside GTK+. They should not be confused with 
        <glossterm linkend="model-column">model columns</glossterm> which
        are used to organize the data in tree models.
      </para>
      <glossseealso>model-view widget</glossseealso>
    </glossdef>
  </glossentry>

  <glossentry id="container">
    <glossterm>container</glossterm>
    <glossdef>
      <para>
	A <glossterm linkend="widget">widget</glossterm> that contains
	other widgets; in that case, the container is the
	<emphasis>parent</emphasis> of the <emphasis>child</emphasis>
	widgets.  Some containers don't draw anything on their own,
	but rather just organize their children's <glossterm
	linkend="geometry">geometry</glossterm>; for example, #GtkVBox lays out 
        its children vertically without painting anything on its own.  Other
	containers include decorative elements; for example, #GtkFrame contains 
        the frame's child and a label in addition to the shaded frame it draws.  
        The base class for containers is #GtkContainer.
      </para>
      <glossseealso>
	<glossterm linkend="container">widget</glossterm>
	<glossterm linkend="container">geometry</glossterm>
      </glossseealso>
    </glossdef>
  </glossentry>

  <glossentry id="display">
    <glossterm>display</glossterm>
    <glossdef>
      <para>
        GDK inherited the concept of display from the X window system,
        which considers a display to be the combination
        of a keyboard, a pointing device and one or more 
        <glossterm linkend="screen">screens</glossterm>. 
        Applications open a display to show windows and interact with the user.
        In GDK, a display is represented by a #GdkDisplay.
      </para>
    </glossdef>
  </glossentry>

  <glossentry id="ellipsization">
    <glossdef>
      <para>
        Ellipsization is the process of replacing some part
        of a text by an ellipsis (usually "...") to make the
        text fit in a smaller space. Pango can ellipsize text
        at the beginning, at the end or in the middle.
      </para>
    </glossdef>
  </glossentry>

  <glossentry id="event">
    <glossterm>event</glossterm>
    <glossdef>
      <para>
        Events are the way in which GDK informs GTK+ about external events
        like pointer motion, button clicks, key presses, etc. 
      </para>
    </glossdef>
  </glossentry>

  <glossentry id="geometry">
    <glossterm>geometry</glossterm>
    <glossdef>
      <para>
	A <glossterm linkend="widget">widget's</glossterm> position
	and size.  Within its parent, this is called the widget's
	<glossterm linkend="allocation">allocation</glossterm>.
      </para>
    </glossdef>
  </glossentry>

  <glossentry id="mapping">
    <glossterm>mapping</glossterm>
    <glossdef>
      <para>
	This is the step in a <glossterm
	linkend="widget">widget's</glossterm> life cycle where it
	actually shows the GdkWindows it created when it was
	<glossterm linkend="realization">realized</glossterm>.  When a
	widget is mapped, it must turn on its
	%GTK_MAPPED <link linkend="GtkWidgetFlags">flag</link>.
      </para>

      <para>
	Note that due to the asynchronous nature of the X window
	system, a widget's window may not appear on the screen
	immediatly after one calls gdk_window_show():
	you must wait for the corresponding map <glossterm
	linkend="event">event</glossterm> to be received.  You can do
	this with the <link
	linkend="GtkWidget-map-event"><methodname>GtkWidget::map-event</methodname>
	signal</link>.
      </para>
    </glossdef>
  </glossentry>

  <glossentry id="model-column">
    <glossterm>model column</glossterm>
    <glossdef>
      <para>
        A column in a tree model, holding data of a certain type. 
        The types which can be stored in the columns of a model 
        have to be specified when the model is constructed, see 
        e.g. gtk_list_store_new().
      </para>
      <glossseealso>
	<glossterm linkend="view-column">view column</glossterm>
      </glossseealso>
    </glossdef>
  </glossentry>

  <glossentry id="model-view">
    <glossterm>model-view widget</glossterm>
    <glossdef>
      <para>
        These widgets follow the well-known model-view pattern, which separates
        the data (the model) to be displayed from the component which does the 
        actual visualization (the view). Examples of this pattern in GTK+ are 
        the #GtkTreeView/#GtkTreeModel and #GtkTextView/#GtkTextBuffer
      </para>
      <para>
        One important advantage of this pattern is that it is possible to 
        display the same model in multiple views; another one that the 
        separation of the model allows a great deal of flexibility, as 
        demonstrated by e.g. #GtkTreeModelSort or #GtkTreeModelFilter.
      </para>
    </glossdef>
  </glossentry>

  <glossentry id="no-window">
    <glossterm>no-window widget</glossterm>
    <glossdef>
      <para>
	A widget that does not have a GdkWindow of its own on which to
	draw its contents, but rather shares its <glossterm
	linkend="parent">parent's</glossterm>.  This can be tested with
	the gtk_widget_get_has_window() function.  See
	<xref linkend="window-no-window-widgets"/> for a detailed
	description of this flag.
      </para>
    </glossdef>
  </glossentry>

  <glossentry id="parent">
    <glossterm>parent</glossterm>
    <glossdef>
      <para>
	A <glossterm linkend="widget">widget's</glossterm> parent is
	the <glossterm linkend="container">container</glossterm>
	inside which it resides.
      </para>
    </glossdef>
  </glossentry>

  <glossentry id="realization">
    <glossterm>realization</glossterm>
    <glossdef>
      <para>
	This is the step in a <glossterm
	linkend="widget">widget's</glossterm> life cycle where it
	creates its own GdkWindow, or otherwise associates itself with
	its <glossterm linkend="parent">parent's</glossterm>
	GdkWindow.  If the widget has its own window, then it must
	also attach a <glossterm linkend="style">style</glossterm> to
	it.  A widget becomes unrealized by destroying its associated
	GdkWindow.  When a widget is realized, it must turn on its
	%GTK_REALIZED <link linkend="GtkWidgetFlags">flag</link>.
      </para>

      <para>
	Widgets that don't own the GdkWindow on which they draw are
	called <glossterm linkend="no-window">no-window widgets</glossterm>.  
        This can be tested with the gtk_widget_get_has_window() function.  Normally,
        these widgets draw on their parent's GdkWindow.
      </para>

      <para>
	Note that when a widget creates a window in its <link
	linkend="gtkwidget-realize"><methodname>::realize()</methodname></link>
	handler, it does not actually show the window.  That is, the
	window's structure is just created in memory.  The widget
	actually shows the window when it gets <glossterm
	linkend="mapping">mapped</glossterm>.
      </para>
    </glossdef>
  </glossentry>

  <glossentry id="requisition">
    <glossterm>requisition</glossterm>
    <glossdef>
      <para>
	The size requisition of a <glossterm
	linkend="widget">widget</glossterm> is the minimum amount of
	space it requests from its <glossterm
	linkend="parent">parent</glossterm>.  Once the parent computes
	the widget's final size, it gives it its <glossterm
	linkend="allocation">size allocation</glossterm>.
      </para>
      <glossseealso>
	<glossterm linkend="allocation">allocation</glossterm>
      </glossseealso>
    </glossdef>
  </glossentry>

  <glossentry id="screen">
    <glossterm>screen</glossterm>
    <glossdef>
      <para>
	GDK inherited the concept of screen from the X window system, 
        which considers a screen to be a rectangular area, on which 
        applications may place their windows. Screens under X may have 
        quite dissimilar <glossterm linkend="visual">visuals</glossterm>.
        Each screen can stretch across multiple physical monitors.
      </para>
      <para>
        In GDK, screens are represented by #GdkScreen objects.
      </para>
    </glossdef>
  </glossentry>

  <glossentry id="style">
    <glossterm>style</glossterm>
    <glossdef>
      <para>
        A style encapsulates what GTK+ needs to know in order to draw
        a widget. Styles can be modified with 
        <link linkend="gtk-Resource-Files">resource files</link>.
      </para>
    </glossdef>
  </glossentry>

  <glossentry id="toplevel">
    <glossterm>toplevel</glossterm>
    <glossdef>
      <para>
	A <glossterm linkend="widget">widget</glossterm> that does not
	require a <glossterm linkend="parent">parent</glossterm> container.  
        The only toplevel widgets in GTK+ are #GtkWindow and widgets derived from it.
      </para>
      <glossseealso>
	<glossterm linkend="container">container</glossterm>
      </glossseealso>
    </glossdef>
  </glossentry>

  <glossentry id="unmap">
    <glossterm>unmap</glossterm>
    <glosssee><glossterm linkend="mapping">mapping</glossterm></glosssee>
  </glossentry>

  <glossentry id="unrealize">
    <glossterm>unrealize</glossterm>
    <glosssee><glossterm linkend="realization">realization</glossterm></glosssee>
  </glossentry>

  <glossentry id="view-column">
    <glossterm>view column</glossterm>
    <glossdef>
      <para>
        A displayed column in a tree view, represented by a
        #GtkTreeViewColumn object.
      </para>
      <glossseealso>
	<glossterm linkend="model-column">model column</glossterm>
      </glossseealso>
    </glossdef>
  </glossentry>
 
  <glossentry id="visual">
    <glossterm>visual</glossterm>
    <glossdef>
      <para>
        A visual describes how color information is stored in pixels.
        A <glossterm linkend="screen">screen</glossterm> may support
        multiple visuals. On modern hardware, the most common visuals
        are truecolor visuals, which store a fixed number of bits 
        (typically 8) for the red, green and blue components of a color.
      </para>
      <para>
        On ancient hardware, one may still meet indexed visuals, which 
        store color information as an index into a color map, or even
        monochrome visuals. 
      </para>
    </glossdef>
  </glossentry>
 
  <glossentry id="widget">
    <glossterm>widget</glossterm>
    <glossdef>
      <para>
	A control in a graphical user interface.  Widgets can draw
	themselves and process events from the mouse and keyboard.
	Widget types include buttons, menus, text entry lines, and
	lists.  Widgets can be arranged into <glossterm
	linkend="container">containers</glossterm>, and these take
	care of assigning the <glossterm
	linkend="geometry">geometry</glossterm> of the widgets:  every
	widget thus has a parent except those widgets which are
	<glossterm linkend="toplevel">toplevels</glossterm>.  The base
	class for widgets is #GtkWidget.
      </para>
      <glossseealso>
	<glossterm linkend="container">container</glossterm>
      </glossseealso>
    </glossdef>
  </glossentry>
</glossary>

<!--
Local variables:
mode: sgml
sgml-parent-document: ("gtk-docs.sgml" "book" "glossary")
End:
-->