Pileus Git - ~andy/gtk/blob - gtk/gtkcellareacontext.c

   1 /* gtkcellareacontext.c
   2  *
   3  * Copyright (C) 2010 Openismus GmbH
   4  *
   5  * Authors:
   6  *      Tristan Van Berkom <tristanvb@openismus.com>
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  20  */
  21
  22 /**
  23  * SECTION:gtkcellareacontext
  24  * @Short_Description: Stores geometrical information for a series of rows in a GtkCellArea
  25  * @Title: GtkCellAreaContext
  26  *
  27  * The #GtkCellAreaContext object is created by a given #GtkCellArea
  28  * implementation via its #GtkCellAreaClass.create_context() virtual
  29  * method and is used to store cell sizes and alignments for a series of
  30  * #GtkTreeModel rows that are requested and rendered in the same context.
  31  *
  32  * #GtkCellLayout widgets can create any number of contexts in which to
  33  * request and render groups of data rows. However, it's important that the
  34  * same context which was used to request sizes for a given #GtkTreeModel
  35  * row also be used for the same row when calling other #GtkCellArea APIs
  36  * such as gtk_cell_area_render() and gtk_cell_area_event().
  37  */
  38
  39 #include "config.h"
  40 #include "gtkintl.h"
  41 #include "gtkmarshalers.h"
  42 #include "gtkcellareacontext.h"
  43 #include "gtkprivate.h"
  44
  45 /* GObjectClass */
  46 static void gtk_cell_area_context_dispose       (GObject            *object);
  47 static void gtk_cell_area_context_get_property  (GObject            *object,
  48                                                  guint               prop_id,
  49                                                  GValue             *value,
  50                                                  GParamSpec         *pspec);
  51 static void gtk_cell_area_context_set_property  (GObject            *object,
  52                                                  guint               prop_id,
  53                                                  const GValue       *value,
  54                                                  GParamSpec         *pspec);
  55
  56 /* GtkCellAreaContextClass */
  57 static void gtk_cell_area_context_real_reset    (GtkCellAreaContext *context);
  58 static void gtk_cell_area_context_real_allocate (GtkCellAreaContext *context,
  59                                                  gint                width,
  60                                                  gint                height);
  61
  62 struct _GtkCellAreaContextPrivate
  63 {
  64   GtkCellArea *cell_area;
  65
  66   gint         min_width;
  67   gint         nat_width;
  68   gint         min_height;
  69   gint         nat_height;
  70   gint         alloc_width;
  71   gint         alloc_height;
  72 };
  73
  74 enum {
  75   PROP_0,
  76   PROP_CELL_AREA,
  77   PROP_MIN_WIDTH,
  78   PROP_NAT_WIDTH,
  79   PROP_MIN_HEIGHT,
  80   PROP_NAT_HEIGHT
  81 };
  82
  83 G_DEFINE_TYPE (GtkCellAreaContext, gtk_cell_area_context, G_TYPE_OBJECT);
  84
  85 static void
  86 gtk_cell_area_context_init (GtkCellAreaContext *context)
  87 {
  88   context->priv = G_TYPE_INSTANCE_GET_PRIVATE (context,
  89                                                GTK_TYPE_CELL_AREA_CONTEXT,
  90                                                GtkCellAreaContextPrivate);
  91 }
  92
  93 static void
  94 gtk_cell_area_context_class_init (GtkCellAreaContextClass *class)
  95 {
  96   GObjectClass     *object_class = G_OBJECT_CLASS (class);
  97
  98   /* GObjectClass */
  99   object_class->dispose      = gtk_cell_area_context_dispose;
 100   object_class->get_property = gtk_cell_area_context_get_property;
 101   object_class->set_property = gtk_cell_area_context_set_property;
 102
 103   /* GtkCellAreaContextClass */
 104   class->reset    = gtk_cell_area_context_real_reset;
 105   class->allocate = gtk_cell_area_context_real_allocate;
 106
 107   /**
 108    * GtkCellAreaContext:area:
 109    *
 110    * The #GtkCellArea this context was created by
 111    *
 112    * Since: 3.0
 113    */
 114   g_object_class_install_property (object_class,
 115                                    PROP_CELL_AREA,
 116                                    g_param_spec_object ("area",
 117                                                         P_("Area"),
 118                                                         P_("The Cell Area this context was created for"),
 119                                                         GTK_TYPE_CELL_AREA,
 120                                                         GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 121
 122   /**
 123    * GtkCellAreaContext:minimum-width:
 124    *
 125    * The minimum width for the #GtkCellArea in this context
 126    * for all #GtkTreeModel rows that this context was requested
 127    * for using gtk_cell_area_get_preferred_width().
 128    *
 129    * Since: 3.0
 130    */
 131   g_object_class_install_property (object_class,
 132                                    PROP_MIN_WIDTH,
 133                                    g_param_spec_int ("minimum-width",
 134                                                      P_("Minimum Width"),
 135                                                      P_("Minimum cached width"),
 136                                                      -1,
 137                                                      G_MAXINT,
 138                                                      -1,
 139                                                      G_PARAM_READABLE));
 140
 141   /**
 142    * GtkCellAreaContext:natural-width:
 143    *
 144    * The natural width for the #GtkCellArea in this context
 145    * for all #GtkTreeModel rows that this context was requested
 146    * for using gtk_cell_area_get_preferred_width().
 147    *
 148    * Since: 3.0
 149    */
 150   g_object_class_install_property (object_class,
 151                                    PROP_NAT_WIDTH,
 152                                    g_param_spec_int ("natural-width",
 153                                                      P_("Minimum Width"),
 154                                                      P_("Minimum cached width"),
 155                                                      -1,
 156                                                      G_MAXINT,
 157                                                      -1,
 158                                                      G_PARAM_READABLE));
 159
 160   /**
 161    * GtkCellAreaContext:minimum-height:
 162    *
 163    * The minimum height for the #GtkCellArea in this context
 164    * for all #GtkTreeModel rows that this context was requested
 165    * for using gtk_cell_area_get_preferred_height().
 166    *
 167    * Since: 3.0
 168    */
 169   g_object_class_install_property (object_class,
 170                                    PROP_MIN_HEIGHT,
 171                                    g_param_spec_int ("minimum-height",
 172                                                      P_("Minimum Height"),
 173                                                      P_("Minimum cached height"),
 174                                                      -1,
 175                                                      G_MAXINT,
 176                                                      -1,
 177                                                      G_PARAM_READABLE));
 178
 179   /**
 180    * GtkCellAreaContext:natural-height:
 181    *
 182    * The natural height for the #GtkCellArea in this context
 183    * for all #GtkTreeModel rows that this context was requested
 184    * for using gtk_cell_area_get_preferred_height().
 185    *
 186    * Since: 3.0
 187    */
 188   g_object_class_install_property (object_class,
 189                                    PROP_NAT_HEIGHT,
 190                                    g_param_spec_int ("natural-height",
 191                                                      P_("Minimum Height"),
 192                                                      P_("Minimum cached height"),
 193                                                      -1,
 194                                                      G_MAXINT,
 195                                                      -1,
 196                                                      G_PARAM_READABLE));
 197
 198   g_type_class_add_private (object_class, sizeof (GtkCellAreaContextPrivate));
 199 }
 200
 201 /*************************************************************
 202  *                      GObjectClass                         *
 203  *************************************************************/
 204 static void
 205 gtk_cell_area_context_dispose (GObject *object)
 206 {
 207   GtkCellAreaContext        *context = GTK_CELL_AREA_CONTEXT (object);
 208   GtkCellAreaContextPrivate *priv = context->priv;
 209
 210   if (priv->cell_area)
 211     {
 212       g_object_unref (priv->cell_area);
 213
 214       priv->cell_area = NULL;
 215     }
 216
 217   G_OBJECT_CLASS (gtk_cell_area_context_parent_class)->dispose (object);
 218 }
 219
 220 static void
 221 gtk_cell_area_context_set_property (GObject      *object,
 222                                     guint         prop_id,
 223                                     const GValue *value,
 224                                     GParamSpec   *pspec)
 225 {
 226   GtkCellAreaContext        *context = GTK_CELL_AREA_CONTEXT (object);
 227   GtkCellAreaContextPrivate *priv = context->priv;
 228
 229   switch (prop_id)
 230     {
 231     case PROP_CELL_AREA:
 232       priv->cell_area = g_value_dup_object (value);
 233       break;
 234     default:
 235       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 236       break;
 237     }
 238 }
 239
 240 static void
 241 gtk_cell_area_context_get_property (GObject     *object,
 242                                     guint        prop_id,
 243                                     GValue      *value,
 244                                     GParamSpec  *pspec)
 245 {
 246   GtkCellAreaContext        *context = GTK_CELL_AREA_CONTEXT (object);
 247   GtkCellAreaContextPrivate *priv = context->priv;
 248
 249   switch (prop_id)
 250     {
 251     case PROP_CELL_AREA:
 252       g_value_set_object (value, priv->cell_area);
 253       break;
 254     case PROP_MIN_WIDTH:
 255       g_value_set_int (value, priv->min_width);
 256       break;
 257     case PROP_NAT_WIDTH:
 258       g_value_set_int (value, priv->nat_width);
 259       break;
 260     case PROP_MIN_HEIGHT:
 261       g_value_set_int (value, priv->min_height);
 262       break;
 263     case PROP_NAT_HEIGHT:
 264       g_value_set_int (value, priv->nat_height);
 265       break;
 266     default:
 267       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 268       break;
 269     }
 270 }
 271
 272 /*************************************************************
 273  *                    GtkCellAreaContextClass                *
 274  *************************************************************/
 275 static void
 276 gtk_cell_area_context_real_reset (GtkCellAreaContext *context)
 277 {
 278   GtkCellAreaContextPrivate *priv = context->priv;
 279
 280   g_object_freeze_notify (G_OBJECT (context));
 281
 282   if (priv->min_width != 0)
 283     {
 284       priv->min_width = 0;
 285       g_object_notify (G_OBJECT (context), "minimum-width");
 286     }
 287
 288   if (priv->nat_width != 0)
 289     {
 290       priv->nat_width = 0;
 291       g_object_notify (G_OBJECT (context), "natural-width");
 292     }
 293
 294   if (priv->min_height != 0)
 295     {
 296       priv->min_height = 0;
 297       g_object_notify (G_OBJECT (context), "minimum-height");
 298     }
 299
 300   if (priv->nat_height != 0)
 301     {
 302       priv->nat_height = 0;
 303       g_object_notify (G_OBJECT (context), "natural-height");
 304     }
 305
 306   priv->alloc_width  = 0;
 307   priv->alloc_height = 0;
 308
 309   g_object_thaw_notify (G_OBJECT (context));
 310 }
 311
 312 static void
 313 gtk_cell_area_context_real_allocate (GtkCellAreaContext *context,
 314                                      gint                width,
 315                                      gint                height)
 316 {
 317   GtkCellAreaContextPrivate *priv = context->priv;
 318
 319   priv->alloc_width  = width;
 320   priv->alloc_height = height;
 321 }
 322
 323 /*************************************************************
 324  *                            API                            *
 325  *************************************************************/
 326 /**
 327  * gtk_cell_area_context_get_area:
 328  * @context: a #GtkCellAreaContext
 329  *
 330  * Fetches the #GtkCellArea this @context was created by.
 331  *
 332  * This is generally unneeded by layouting widgets; however,
 333  * it is important for the context implementation itself to
 334  * fetch information about the area it is being used for.
 335  *
 336  * For instance at #GtkCellAreaContextClass.allocate() time
 337  * it's important to know details about any cell spacing
 338  * that the #GtkCellArea is configured with in order to
 339  * compute a proper allocation.
 340  *
 341  * Return value: (transfer none): the #GtkCellArea this context was created by.
 342  *
 343  * Since: 3.0
 344  */
 345 GtkCellArea *
 346 gtk_cell_area_context_get_area (GtkCellAreaContext *context)
 347 {
 348   GtkCellAreaContextPrivate *priv;
 349
 350   g_return_val_if_fail (GTK_IS_CELL_AREA_CONTEXT (context), NULL);
 351
 352   priv = context->priv;
 353
 354   return priv->cell_area;
 355 }
 356
 357 /**
 358  * gtk_cell_area_context_reset:
 359  * @context: a #GtkCellAreaContext
 360  *
 361  * Resets any previously cached request and allocation
 362  * data.
 363  *
 364  * When underlying #GtkTreeModel data changes its
 365  * important to reset the context if the content
 366  * size is allowed to shrink. If the content size
 367  * is only allowed to grow (this is usually an option
 368  * for views rendering large data stores as a measure
 369  * of optimization), then only the row that changed
 370  * or was inserted needs to be (re)requested with
 371  * gtk_cell_area_get_preferred_width().
 372  *
 373  * When the new overall size of the context requires
 374  * that the allocated size changes (or whenever this
 375  * allocation changes at all), the variable row
 376  * sizes need to be re-requested for every row.
 377  *
 378  * For instance, if the rows are displayed all with
 379  * the same width from top to bottom then a change
 380  * in the allocated width necessitates a recalculation
 381  * of all the displayed row heights using
 382  * gtk_cell_area_get_preferred_height_for_width().
 383  *
 384  * Since 3.0
 385  */
 386 void
 387 gtk_cell_area_context_reset (GtkCellAreaContext *context)
 388 {
 389   g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context));
 390
 391   GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->reset (context);
 392 }
 393
 394 /**
 395  * gtk_cell_area_context_allocate:
 396  * @context: a #GtkCellAreaContext
 397  * @width: the allocated width for all #GtkTreeModel rows rendered
 398  *     with @context, or -1.
 399  * @height: the allocated height for all #GtkTreeModel rows rendered
 400  *     with @context, or -1.
 401  *
 402  * Allocates a width and/or a height for all rows which are to be
 403  * rendered with @context.
 404  *
 405  * Usually allocation is performed only horizontally or sometimes
 406  * vertically since a group of rows are usually rendered side by
 407  * side vertically or horizontally and share either the same width
 408  * or the same height. Sometimes they are allocated in both horizontal
 409  * and vertical orientations producing a homogeneous effect of the
 410  * rows. This is generally the case for #GtkTreeView when
 411  * #GtkTreeView:fixed-height-mode is enabled.
 412  *
 413  * Since 3.0
 414  */
 415 void
 416 gtk_cell_area_context_allocate (GtkCellAreaContext *context,
 417                                 gint                width,
 418                                 gint                height)
 419 {
 420   g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context));
 421
 422   GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->allocate (context, width, height);
 423 }
 424
 425 /**
 426  * gtk_cell_area_context_get_preferred_width:
 427  * @context: a #GtkCellAreaContext
 428  * @minimum_width: (out) (allow-none): location to store the minimum width,
 429  *     or %NULL
 430  * @natural_width: (out) (allow-none): location to store the natural width,
 431  *     or %NULL
 432  *
 433  * Gets the accumulative preferred width for all rows which have been
 434  * requested with this context.
 435  *
 436  * After gtk_cell_area_context_reset() is called and/or before ever
 437  * requesting the size of a #GtkCellArea, the returned values are 0.
 438  *
 439  * Since: 3.0
 440  */
 441 void
 442 gtk_cell_area_context_get_preferred_width (GtkCellAreaContext *context,
 443                                            gint               *minimum_width,
 444                                            gint               *natural_width)
 445 {
 446   GtkCellAreaContextPrivate *priv;
 447
 448   g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context));
 449
 450   priv = context->priv;
 451
 452   if (minimum_width)
 453     *minimum_width = priv->min_width;
 454
 455   if (natural_width)
 456     *natural_width = priv->nat_width;
 457 }
 458
 459 /**
 460  * gtk_cell_area_context_get_preferred_height:
 461  * @context: a #GtkCellAreaContext
 462  * @minimum_height: (out) (allow-none): location to store the minimum height,
 463  *     or %NULL
 464  * @natural_height: (out) (allow-none): location to store the natural height,
 465  *     or %NULL
 466  *
 467  * Gets the accumulative preferred height for all rows which have been
 468  * requested with this context.
 469  *
 470  * After gtk_cell_area_context_reset() is called and/or before ever
 471  * requesting the size of a #GtkCellArea, the returned values are 0.
 472  *
 473  * Since: 3.0
 474  */
 475 void
 476 gtk_cell_area_context_get_preferred_height (GtkCellAreaContext *context,
 477                                             gint               *minimum_height,
 478                                             gint               *natural_height)
 479 {
 480   GtkCellAreaContextPrivate *priv;
 481
 482   g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context));
 483
 484   priv = context->priv;
 485
 486   if (minimum_height)
 487     *minimum_height = priv->min_height;
 488
 489   if (natural_height)
 490     *natural_height = priv->nat_height;
 491 }
 492
 493 /**
 494  * gtk_cell_area_context_get_preferred_height_for_width:
 495  * @context: a #GtkCellAreaContext
 496  * @width: a proposed width for allocation
 497  * @minimum_height: (out) (allow-none): location to store the minimum height,
 498  *     or %NULL
 499  * @natural_height: (out) (allow-none): location to store the natural height,
 500  *     or %NULL
 501  *
 502  * Gets the accumulative preferred height for @width for all rows
 503  * which have been requested for the same said @width with this context.
 504  *
 505  * After gtk_cell_area_context_reset() is called and/or before ever
 506  * requesting the size of a #GtkCellArea, the returned values are -1.
 507  *
 508  * Since: 3.0
 509  */
 510 void
 511 gtk_cell_area_context_get_preferred_height_for_width (GtkCellAreaContext *context,
 512                                                       gint                width,
 513                                                       gint               *minimum_height,
 514                                                       gint               *natural_height)
 515 {
 516   g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context));
 517
 518   if (GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->get_preferred_height_for_width)
 519     GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->get_preferred_height_for_width (context,
 520                                                                                width,
 521                                                                                minimum_height,
 522                                                                                natural_height);
 523 }
 524
 525 /**
 526  * gtk_cell_area_context_get_preferred_width_for_height:
 527  * @context: a #GtkCellAreaContext
 528  * @height: a proposed height for allocation
 529  * @minimum_width: (out) (allow-none): location to store the minimum width,
 530  *     or %NULL
 531  * @natural_width: (out) (allow-none): location to store the natural width,
 532  *     or %NULL
 533  *
 534  * Gets the accumulative preferred width for @height for all rows which
 535  * have been requested for the same said @height with this context.
 536  *
 537  * After gtk_cell_area_context_reset() is called and/or before ever
 538  * requesting the size of a #GtkCellArea, the returned values are -1.
 539  *
 540  * Since: 3.0
 541  */
 542 void
 543 gtk_cell_area_context_get_preferred_width_for_height (GtkCellAreaContext *context,
 544                                                       gint                height,
 545                                                       gint               *minimum_width,
 546                                                       gint               *natural_width)
 547 {
 548   g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context));
 549
 550   if (GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->get_preferred_width_for_height)
 551     GTK_CELL_AREA_CONTEXT_GET_CLASS (context)->get_preferred_width_for_height (context,
 552                                                                                height,
 553                                                                                minimum_width,
 554                                                                                natural_width);
 555 }
 556
 557 /**
 558  * gtk_cell_area_context_get_allocation:
 559  * @context: a #GtkCellAreaContext
 560  * @width: (out) (allow-none): location to store the allocated width, or %NULL
 561  * @height: (out) (allow-none): location to store the allocated height, or %NULL
 562  *
 563  * Fetches the current allocation size for @context.
 564  *
 565  * If the context was not allocated in width or height, or if the
 566  * context was recently reset with gtk_cell_area_context_reset(),
 567  * the returned value will be -1.
 568  *
 569  * Since: 3.0
 570  */
 571 void
 572 gtk_cell_area_context_get_allocation (GtkCellAreaContext *context,
 573                                       gint               *width,
 574                                       gint               *height)
 575 {
 576   GtkCellAreaContextPrivate *priv;
 577
 578   g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context));
 579
 580   priv = context->priv;
 581
 582   if (width)
 583     *width = priv->alloc_width;
 584
 585   if (height)
 586     *height = priv->alloc_height;
 587 }
 588
 589 /**
 590  * gtk_cell_area_context_push_preferred_width:
 591  * @context: a #GtkCellAreaContext
 592  * @minimum_width: the proposed new minimum width for @context
 593  * @natural_width: the proposed new natural width for @context
 594  *
 595  * Causes the minimum and/or natural width to grow if the new
 596  * proposed sizes exceed the current minimum and natural width.
 597  *
 598  * This is used by #GtkCellAreaContext implementations during
 599  * the request process over a series of #GtkTreeModel rows to
 600  * progressively push the requested width over a series of
 601  * gtk_cell_area_get_preferred_width() requests.
 602  *
 603  * Since: 3.0
 604  */
 605 void
 606 gtk_cell_area_context_push_preferred_width (GtkCellAreaContext *context,
 607                                             gint                minimum_width,
 608                                             gint                natural_width)
 609 {
 610   GtkCellAreaContextPrivate *priv;
 611
 612   g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context));
 613
 614   priv = context->priv;
 615
 616   g_object_freeze_notify (G_OBJECT (context));
 617
 618   if (minimum_width > priv->min_width)
 619     {
 620       priv->min_width = minimum_width;
 621
 622       g_object_notify (G_OBJECT (context), "minimum-width");
 623     }
 624
 625   if (natural_width > priv->nat_width)
 626     {
 627       priv->nat_width = natural_width;
 628
 629       g_object_notify (G_OBJECT (context), "natural-width");
 630     }
 631
 632   g_object_thaw_notify (G_OBJECT (context));
 633 }
 634
 635 /**
 636  * gtk_cell_area_context_push_preferred_height:
 637  * @context: a #GtkCellAreaContext
 638  * @minimum_height: the proposed new minimum height for @context
 639  * @natural_height: the proposed new natural height for @context
 640  *
 641  * Causes the minimum and/or natural height to grow if the new
 642  * proposed sizes exceed the current minimum and natural height.
 643  *
 644  * This is used by #GtkCellAreaContext implementations during
 645  * the request process over a series of #GtkTreeModel rows to
 646  * progressively push the requested height over a series of
 647  * gtk_cell_area_get_preferred_height() requests.
 648  *
 649  * Since: 3.0
 650  */
 651 void
 652 gtk_cell_area_context_push_preferred_height (GtkCellAreaContext *context,
 653                                              gint                minimum_height,
 654                                              gint                natural_height)
 655 {
 656   GtkCellAreaContextPrivate *priv;
 657
 658   g_return_if_fail (GTK_IS_CELL_AREA_CONTEXT (context));
 659
 660   priv = context->priv;
 661
 662   g_object_freeze_notify (G_OBJECT (context));
 663
 664   if (minimum_height > priv->min_height)
 665     {
 666       priv->min_height = minimum_height;
 667
 668       g_object_notify (G_OBJECT (context), "minimum-height");
 669     }
 670
 671   if (natural_height > priv->nat_height)
 672     {
 673       priv->nat_height = natural_height;
 674
 675       g_object_notify (G_OBJECT (context), "natural-height");
 676     }
 677
 678   g_object_thaw_notify (G_OBJECT (context));
 679 }