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