Pileus Git - ~andy/gtk/blob - docs/reference/gtk/glossary.xml

   1 <glossary id="glossary">
   2   <title>Glossary</title>
   3
   4   <glossentry id="allocation">
   5     <glossterm>allocation</glossterm>
   6     <glossdef>
   7       <para>
   8         The final size of a <glossterm
   9         linkend="widget">widget</glossterm> within its <glossterm
  10         linkend="parent">parent</glossterm>.  For example, a widget
  11         may request a minimum size of 20&times;20 pixels, but its
  12         parent may decide to allocate 50&times;20 pixels for it
  13         instead.
  14       </para>
  15       <glossseealso>
  16         <glossterm linkend="requisition">requisition</glossterm>
  17       </glossseealso>
  18     </glossdef>
  19   </glossentry>
  20
  21   <glossentry id="bin">
  22     <glossterm>bin</glossterm>
  23     <glossdef>
  24       <para>
  25         A <glossterm linkend="container">container</glossterm> that
  26         can hold at most one child widget.  The base class for bins is
  27         <link linkend="GtkBin">GtkBin</link>.
  28       </para>
  29       <glossseealso>
  30         <glossterm linkend="container">container</glossterm>
  31       </glossseealso>
  32     </glossdef>
  33   </glossentry>
  34
  35   <glossentry id="child">
  36     <glossterm>child</glossterm>
  37     <glossdef>
  38       <para>
  39         A <glossterm linkend="container">container's</glossterm> child
  40         is a <glossterm linkend="widget">widget</glossterm> contained
  41         inside it.
  42       </para>
  43     </glossdef>
  44   </glossentry>
  45
  46   <glossentry id="column">
  47     <glossterm>column</glossterm>
  48     <glossdef>
  49       <para>
  50         GTK+ contains several widgets which display data in columns,
  51         e.g. the <link linkend="GtkTreeView">GtkTreeView</link>.
  52         These <glossterm linkend="view-column">view columns</glossterm> in
  53         the tree view are represented by
  54         <link linkend="GtkTreeViewColumn">GtkTreeViewColumn</link>
  55         objects inside GTK+. They should not be confused with
  56         <glossterm linkend="model-column">model columns</glossterm> which
  57         are used to organize the data in tree models.
  58       </para>
  59       <glossseealso>model-view widget</glossseealso>
  60     </glossdef>
  61   </glossentry>
  62
  63   <glossentry id="container">
  64     <glossterm>container</glossterm>
  65     <glossdef>
  66       <para>
  67         A <glossterm linkend="widget">widget</glossterm> that contains
  68         other widgets; in that case, the container is the
  69         <emphasis>parent</emphasis> of the <emphasis>child</emphasis>
  70         widgets.  Some containers don't draw anything on their own,
  71         but rather just organize their children's <glossterm
  72         linkend="geometry">geometry</glossterm>; for example, <link
  73         linkend="GtkVBox">GtkVBox</link> lays out its children
  74         vertically without painting anything on its own.  Other
  75         containers include decorative elements; for example, <link
  76         linkend="GtkFrame">GtkFrame</link> contains the frame's child
  77         and a label in addition to the shaded frame it draws.  The
  78         base class for containers is <link
  79         linkend="GtkContainer">GtkContainer</link>.
  80       </para>
  81       <glossseealso>
  82         <glossterm linkend="container">widget</glossterm>
  83         <glossterm linkend="container">geometry</glossterm>
  84       </glossseealso>
  85     </glossdef>
  86   </glossentry>
  87
  88   <glossentry id="display">
  89     <glossterm>display</glossterm>
  90     <glossdef>
  91       <para>
  92         GDK inherited the concept of display from the X window system,
  93         which considers a display to be the combination
  94         of a keyboard, a pointing device and one or more
  95         <glossterm linkend="screen">screens</glossterm>.
  96         Applications open a display to show windows and interact with the user.
  97         In GDK, a display is represented by a
  98         <link linkend="GdkDisplay">GdkDisplay</link>.
  99       </para>
 100     </glossdef>
 101   </glossentry>
 102
 103   <glossentry id="event">
 104     <glossterm>event</glossterm>
 105     <glossdef>
 106       <para>
 107         Events are the way in which GDK informs GTK+ about external events
 108         like pointer motion, button clicks, key presses, etc.
 109       </para>
 110     </glossdef>
 111   </glossentry>
 112
 113   <glossentry id="geometry">
 114     <glossterm>geometry</glossterm>
 115     <glossdef>
 116       <para>
 117         A <glossterm linkend="widget">widget's</glossterm> position
 118         and size.  Within its parent, this is called the widget's
 119         <glossterm linkend="allocation">allocation</glossterm>.
 120       </para>
 121     </glossdef>
 122   </glossentry>
 123
 124   <glossentry id="mapping">
 125     <glossterm>mapping</glossterm>
 126     <glossdef>
 127       <para>
 128         This is the step in a <glossterm
 129         linkend="widget">widget's</glossterm> life cycle where it
 130         actually shows the GdkWindows it created when it was
 131         <glossterm linkend="realization">realized</glossterm>.  When a
 132         widget is mapped, it must turn on its
 133         <constant>GTK_MAPPED</constant> <link
 134         linkend="GtkWidgetFlags">flag</link>.
 135       </para>
 136
 137       <para>
 138         Note that due to the asynchronous nature of the X window
 139         system, a widget's window may not appear on the screen
 140         immediatly after one calls <link
 141         linkend="gdk-window-show"><function>gdk_window_show()</function></link>:
 142         you must wait for the corresponding map <glossterm
 143         linkend="event">event</glossterm> to be received.  You can do
 144         this with the <link
 145         linkend="GtkWidget-map-event"><methodname>GtkWidget::map-event</methodname>
 146         signal</link>.
 147       </para>
 148     </glossdef>
 149   </glossentry>
 150
 151   <glossentry id="model-column">
 152     <glossterm>model column</glossterm>
 153     <glossdef>
 154       <para>
 155         A column in a tree model, holding data of a certain type.
 156         The types which can be stored in the columns of a model
 157         have to be specified when the model is constructed, see
 158         e.g. <link linkend="gtk-list-store-new">gtk_list_store_new()</link>.
 159       </para>
 160       <glossseealso>
 161         <glossterm linkend="view-column">view column</glossterm>
 162       </glossseealso>
 163     </glossdef>
 164   </glossentry>
 165
 166   <glossentry id="model-view">
 167     <glossterm>model-view widget</glossterm>
 168     <glossdef>
 169       <para>
 170         These widgets follow the well-known model-view pattern, which separates
 171         the data (the model) to be displayed from the component which does the
 172         actual visualization (the view). Examples of this pattern in GTK+ are
 173         the <link linkend="GtkTreeView">GtkTreeView</link>/<link linkend="GtkTreeModel">GtkTreeModel</link>
 174         and
 175         <link linkend="GtkTextView">GtkTextView</link>/<link linkend="GtkTextBuffer">GtkTextBuffer</link>
 176       </para>
 177       <para>
 178         One important advantage of this pattern is that it is possible to
 179         display the same model in multiple views; another one that the
 180         separation of the model allows a great deal of flexibility, as
 181         demonstrated by e.g.
 182         <link linkend="GtkTreeModelSort">GtkTreeModelSort</link> or
 183         <link linkend="GtkTreeModelFilter">GtkTreeModelFilter</link>.
 184       </para>
 185     </glossdef>
 186   </glossentry>
 187
 188   <glossentry id="no-window">
 189     <glossterm>no-window widget</glossterm>
 190     <glossdef>
 191       <para>
 192         A widget that does not have a GdkWindow of its own on which to
 193         draw its contents, but rather shares its <glossterm
 194         linkend="parent">parent's</glossterm>.  Such a widget has the
 195         <constant>GTK_NO_WINDOW</constant> <link
 196         linkend="GtkWidgetFlags">flag</link> set, and can be tested
 197         with the <link
 198         linkend="gtk-widget-no-window:caps"><function>GTK_WIDGET_NO_WINDOW()</function></link>
 199         macro.
 200       </para>
 201     </glossdef>
 202   </glossentry>
 203
 204   <glossentry id="parent">
 205     <glossterm>parent</glossterm>
 206     <glossdef>
 207       <para>
 208         A <glossterm linkend="widget">widget's</glossterm> parent is
 209         the <glossterm linkend="container">container</glossterm>
 210         inside which it resides.
 211       </para>
 212     </glossdef>
 213   </glossentry>
 214
 215   <glossentry id="realization">
 216     <glossterm>realization</glossterm>
 217     <glossdef>
 218       <para>
 219         This is the step in a <glossterm
 220         linkend="widget">widget's</glossterm> life cycle where it
 221         creates its own GdkWindow, or otherwise associates itself with
 222         its <glossterm linkend="parent">parent's</glossterm>
 223         GdkWindow.  If the widget has its own window, then it must
 224         also attach a <glossterm linkend="style">style</glossterm> to
 225         it.  A widget becomes unrealized by destroying its associated
 226         GdkWindow.  When a widget is realized, it must turn on its
 227         <constant>GTK_REALIZED</constant> <link
 228         linkend="GtkWidgetFlags">flag</link>.
 229       </para>
 230
 231       <para>
 232         Widgets that don't own the GdkWindow on which they draw are
 233         called <glossterm linkend="no-window">no-window
 234         widgets</glossterm>.  This can be tested with the <link
 235         linkend="gtk-widget-no-window:caps"><function>GTK_WIDGET_NO_WINDOW()</function></link>
 236         macro.  Normally, these widgets draw on their parent's
 237         GdkWindow.
 238       </para>
 239
 240       <para>
 241         Note that when a widget creates a window in its <link
 242         linkend="gtkwidget-realize"><methodname>::realize()</methodname></link>
 243         handler, it does not actually show the window.  That is, the
 244         window's structure is just created in memory.  The widget
 245         actually shows the window when it gets <glossterm
 246         linkend="mapping">mapped</glossterm>.
 247       </para>
 248     </glossdef>
 249   </glossentry>
 250
 251   <glossentry id="requisition">
 252     <glossterm>requisition</glossterm>
 253     <glossdef>
 254       <para>
 255         The size requisition of a <glossterm
 256         linkend="widget">widget</glossterm> is the minimum amount of
 257         space it requests from its <glossterm
 258         linkend="parent">parent</glossterm>.  Once the parent computes
 259         the widget's final size, it gives it its <glossterm
 260         linkend="allocation">size allocation</glossterm>.
 261       </para>
 262       <glossseealso>
 263         <glossterm linkend="allocation">allocation</glossterm>
 264       </glossseealso>
 265     </glossdef>
 266   </glossentry>
 267
 268   <glossentry id="screen">
 269     <glossterm>screen</glossterm>
 270     <glossdef>
 271       <para>
 272         GDK inherited the concept of screen from the X window system,
 273         which considers a screen to be a rectangular area, on which
 274         applications may place their windows. Screens under X may have
 275         quite dissimilar <glossterm linkend="visual">visuals</glossterm>.
 276         Each screen can stretch across multiple physical monitors.
 277       </para>
 278       <para>
 279         In GDK, screens are represented by
 280         <link linkend="GdkScreen">GdkScreen</link> objects.
 281       </para>
 282     </glossdef>
 283   </glossentry>
 284
 285   <glossentry id="style">
 286     <glossterm>style</glossterm>
 287     <glossdef>
 288       <para>
 289         A style encapsulates what GTK+ needs to know in order to draw
 290         a widget. Styles can be modified with
 291         <link linkend="gtk-Resource-Files">resource files</link>.
 292       </para>
 293     </glossdef>
 294   </glossentry>
 295
 296   <glossentry id="toplevel">
 297     <glossterm>toplevel</glossterm>
 298     <glossdef>
 299       <para>
 300         A <glossterm linkend="widget">widget</glossterm> that does not
 301         require a <glossterm linkend="parent">parent</glossterm>
 302         container.  The only toplevel widgets in GTK+ are <link
 303         linkend="GtkWindow">GtkWindow</link> and widgets derived from it.
 304       </para>
 305       <glossseealso>
 306         <glossterm linkend="container">container</glossterm>
 307       </glossseealso>
 308     </glossdef>
 309   </glossentry>
 310
 311   <glossentry id="unmap">
 312     <glossterm>unmap</glossterm>
 313     <glosssee><glossterm linkend="mapping">mapping</glossterm></glosssee>
 314   </glossentry>
 315
 316   <glossentry id="unrealize">
 317     <glossterm>unrealize</glossterm>
 318     <glosssee><glossterm linkend="realization">realization</glossterm></glosssee>
 319   </glossentry>
 320
 321   <glossentry id="view-column">
 322     <glossterm>view column</glossterm>
 323     <glossdef>
 324       <para>
 325         A displayed column in a tree view, represented by a
 326         <link linkend="GtkTreeViewColumn">GtkTreeViewColumn</link> object.
 327       </para>
 328       <glossseealso>
 329         <glossterm linkend="model-column">model column</glossterm>
 330       </glossseealso>
 331     </glossdef>
 332   </glossentry>
 333
 334   <glossentry id="visual">
 335     <glossterm>visual</glossterm>
 336     <glossdef>
 337       <para>
 338         A visual describes how color information is stored in pixels.
 339         A <glossterm linkend="screen">screen</glossterm> may support
 340         multiple visuals. On modern hardware, the most common visuals
 341         are truecolor visuals, which store a fixed number of bits
 342         (typically 8) for the red, green and blue components of a color.
 343       </para>
 344       <para>
 345         On ancient hardware, one may still meet indexed visuals, which
 346         store color information as an index into a color map, or even
 347         monochrome visuals.
 348       </para>
 349     </glossdef>
 350   </glossentry>
 351
 352   <glossentry id="widget">
 353     <glossterm>widget</glossterm>
 354     <glossdef>
 355       <para>
 356         A control in a graphical user interface.  Widgets can draw
 357         themselves and process events from the mouse and keyboard.
 358         Widget types include buttons, menus, text entry lines, and
 359         lists.  Widgets can be arranged into <glossterm
 360         linkend="container">containers</glossterm>, and these take
 361         care of assigning the <glossterm
 362         linkend="geometry">geometry</glossterm> of the widgets:  every
 363         widget thus has a parent except those widgets which are
 364         <glossterm linkend="toplevel">toplevels</glossterm>.  The base
 365         class for widgets is <link
 366         linkend="GtkWidget">GtkWidget</link>.
 367       </para>
 368       <glossseealso>
 369         <glossterm linkend="container">container</glossterm>
 370       </glossseealso>
 371     </glossdef>
 372   </glossentry>
 373 </glossary>
 374
 375 <!--
 376 Local variables:
 377 mode: sgml
 378 sgml-parent-document: ("gtk-docs.sgml" "book" "glossary")
 379 End:
 380 -->