widget/gtk/gtkdrawing.h

   1 /* -*- Mode: C; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /**
   7  * gtkdrawing.h: GTK widget rendering utilities
   8  *
   9  * gtkdrawing provides an API for rendering GTK widgets in the
  10  * current theme to a pixmap or window, without requiring an actual
  11  * widget instantiation, similar to the Macintosh Appearance Manager
  12  * or Windows XP's DrawThemeBackground() API.
  13  */
  14
  15 #ifndef _GTK_DRAWING_H_
  16 #define _GTK_DRAWING_H_
  17
  18 #include <gdk/gdk.h>
  19 #include <gtk/gtk.h>
  20 #include <algorithm>
  21 #include "mozilla/Span.h"
  22
  23 /*** type definitions ***/
  24 typedef struct {
  25   guint8 active;
  26   guint8 focused;
  27   guint8 selected;
  28   guint8 inHover;
  29   guint8 disabled;
  30   guint8 isDefault;
  31   guint8 canDefault;
  32   /* The depressed state is for buttons which remain active for a longer period:
  33    * activated toggle buttons or buttons showing a popup menu. */
  34   guint8 depressed;
  35   guint8 backdrop;
  36   gint32 curpos; /* curpos and maxpos are used for scrollbars */
  37   gint32 maxpos;
  38   gint32 image_scale; /* image scale */
  39 } GtkWidgetState;
  40
  41 /**
  42  * A size in the same GTK pixel units as GtkBorder and GdkRectangle.
  43  */
  44 struct MozGtkSize {
  45   gint width;
  46   gint height;
  47
  48   MozGtkSize& operator+=(const GtkBorder& aBorder) {
  49     width += aBorder.left + aBorder.right;
  50     height += aBorder.top + aBorder.bottom;
  51     return *this;
  52   }
  53   MozGtkSize operator+(const GtkBorder& aBorder) const {
  54     MozGtkSize result = *this;
  55     return result += aBorder;
  56   }
  57   bool operator<(const MozGtkSize& aOther) const {
  58     return (width < aOther.width && height <= aOther.height) ||
  59            (width <= aOther.width && height < aOther.height);
  60   }
  61   void Include(MozGtkSize aOther) {
  62     width = std::max(width, aOther.width);
  63     height = std::max(height, aOther.height);
  64   }
  65   void Rotate() {
  66     gint tmp = width;
  67     width = height;
  68     height = tmp;
  69   }
  70 };
  71
  72 typedef struct {
  73   bool initialized;
  74   MozGtkSize minSizeWithBorder;
  75   GtkBorder borderAndPadding;
  76 } ToggleGTKMetrics;
  77
  78 typedef struct {
  79   MozGtkSize minSizeWithBorder;
  80   gint iconXPosition;
  81   gint iconYPosition;
  82 } ToolbarButtonGTKMetrics;
  83
  84 #define TOOLBAR_BUTTONS 3
  85 typedef struct {
  86   bool initialized;
  87   ToolbarButtonGTKMetrics button[TOOLBAR_BUTTONS];
  88 } ToolbarGTKMetrics;
  89
  90 typedef struct {
  91   bool initialized;
  92   GtkBorder decorationSize;
  93 } CSDWindowDecorationSize;
  94
  95 /** flags for tab state **/
  96 typedef enum {
  97   /* first eight bits are used to pass a margin */
  98   MOZ_GTK_TAB_MARGIN_MASK = 0xFF,
  99   /* the first tab in the group */
 100   MOZ_GTK_TAB_FIRST = 1 << 9,
 101   /* the selected tab */
 102   MOZ_GTK_TAB_SELECTED = 1 << 10
 103 } GtkTabFlags;
 104
 105 /*** result/error codes ***/
 106 #define MOZ_GTK_SUCCESS 0
 107 #define MOZ_GTK_UNKNOWN_WIDGET -1
 108 #define MOZ_GTK_UNSAFE_THEME -2
 109
 110 /*** checkbox/radio flags ***/
 111 #define MOZ_GTK_WIDGET_CHECKED 1
 112 #define MOZ_GTK_WIDGET_INCONSISTENT (1 << 1)
 113
 114 /*** widget type constants ***/
 115 enum WidgetNodeType : int {
 116   /* Paints a GtkButton. flags is a GtkReliefStyle. */
 117   MOZ_GTK_BUTTON,
 118   /* Paints a button with image and no text */
 119   MOZ_GTK_TOOLBAR_BUTTON,
 120   /* Paints a toggle button */
 121   MOZ_GTK_TOGGLE_BUTTON,
 122   /* Paints a button arrow */
 123   MOZ_GTK_BUTTON_ARROW,
 124
 125   /* Paints the container part of a GtkCheckButton. */
 126   MOZ_GTK_CHECKBUTTON_CONTAINER,
 127   /* Paints a GtkCheckButton. flags is a boolean, 1=checked, 0=not checked. */
 128   MOZ_GTK_CHECKBUTTON,
 129
 130   /* Paints the container part of a GtkRadioButton. */
 131   MOZ_GTK_RADIOBUTTON_CONTAINER,
 132   /* Paints a GtkRadioButton. flags is a boolean, 1=checked, 0=not checked. */
 133   MOZ_GTK_RADIOBUTTON,
 134   /* Vertical GtkScrollbar counterparts */
 135   MOZ_GTK_SCROLLBAR_VERTICAL,
 136   MOZ_GTK_SCROLLBAR_CONTENTS_VERTICAL,
 137   MOZ_GTK_SCROLLBAR_TROUGH_VERTICAL,
 138   MOZ_GTK_SCROLLBAR_THUMB_VERTICAL,
 139
 140   /* Paints a GtkScale. */
 141   MOZ_GTK_SCALE_HORIZONTAL,
 142   MOZ_GTK_SCALE_VERTICAL,
 143   /* Paints a GtkScale trough. */
 144   MOZ_GTK_SCALE_CONTENTS_HORIZONTAL,
 145   MOZ_GTK_SCALE_CONTENTS_VERTICAL,
 146   MOZ_GTK_SCALE_TROUGH_HORIZONTAL,
 147   MOZ_GTK_SCALE_TROUGH_VERTICAL,
 148   /* Paints a GtkScale thumb. */
 149   MOZ_GTK_SCALE_THUMB_HORIZONTAL,
 150   MOZ_GTK_SCALE_THUMB_VERTICAL,
 151   /* Paints a GtkSpinButton */
 152   MOZ_GTK_INNER_SPIN_BUTTON,
 153   MOZ_GTK_SPINBUTTON,
 154   MOZ_GTK_SPINBUTTON_UP,
 155   MOZ_GTK_SPINBUTTON_DOWN,
 156   MOZ_GTK_SPINBUTTON_ENTRY,
 157   /* Paints a GtkEntry. */
 158   MOZ_GTK_ENTRY,
 159   /* Paints a GtkExpander. */
 160   MOZ_GTK_EXPANDER,
 161   /* Paints a GtkTextView or gets the style context corresponding to the
 162      root node of a GtkTextView. */
 163   MOZ_GTK_TEXT_VIEW,
 164   /* The "text" window or node of a GtkTextView */
 165   MOZ_GTK_TEXT_VIEW_TEXT,
 166   /* The "selection" node of a GtkTextView.text */
 167   MOZ_GTK_TEXT_VIEW_TEXT_SELECTION,
 168   /* Paints a GtkOptionMenu. */
 169   MOZ_GTK_DROPDOWN,
 170   /* Paints an entry in an editable option menu */
 171   MOZ_GTK_DROPDOWN_ENTRY,
 172
 173   /* Paints a GtkToolTip */
 174   MOZ_GTK_TOOLTIP,
 175   /* Paints a GtkBox from GtkToolTip  */
 176   MOZ_GTK_TOOLTIP_BOX,
 177   /* Paints a GtkLabel of GtkToolTip */
 178   MOZ_GTK_TOOLTIP_BOX_LABEL,
 179   /* Paints a GtkFrame (e.g. a status bar panel). */
 180   MOZ_GTK_FRAME,
 181   /* Paints the border of a GtkFrame */
 182   MOZ_GTK_FRAME_BORDER,
 183   /* Paints a resize grip for a GtkTextView */
 184   MOZ_GTK_RESIZER,
 185   /* Paints a GtkProgressBar. */
 186   MOZ_GTK_PROGRESSBAR,
 187   /* Paints a trough (track) of a GtkProgressBar */
 188   MOZ_GTK_PROGRESS_TROUGH,
 189   /* Paints a progress chunk of a GtkProgressBar. */
 190   MOZ_GTK_PROGRESS_CHUNK,
 191   /* Paints a progress chunk of an indeterminated GtkProgressBar. */
 192   MOZ_GTK_PROGRESS_CHUNK_INDETERMINATE,
 193   /* Paints a progress chunk of a vertical indeterminated GtkProgressBar. */
 194   MOZ_GTK_PROGRESS_CHUNK_VERTICAL_INDETERMINATE,
 195   /* Used as root style of whole GtkNotebook widget */
 196   MOZ_GTK_NOTEBOOK,
 197   /* Used as root style of active GtkNotebook area which contains tabs and
 198      arrows. */
 199   MOZ_GTK_NOTEBOOK_HEADER,
 200   /* Paints a tab of a GtkNotebook. flags is a GtkTabFlags, defined above. */
 201   MOZ_GTK_TAB_TOP,
 202   /* Paints a tab of a GtkNotebook. flags is a GtkTabFlags, defined above. */
 203   MOZ_GTK_TAB_BOTTOM,
 204   /* Paints the background and border of a GtkNotebook. */
 205   MOZ_GTK_TABPANELS,
 206   /* Paints a GtkArrow for a GtkNotebook. flags is a GtkArrowType. */
 207   MOZ_GTK_TAB_SCROLLARROW,
 208   /* Paints the expander and border of a GtkTreeView */
 209   MOZ_GTK_TREEVIEW,
 210   /* Paints the border of a GtkTreeView */
 211   MOZ_GTK_TREEVIEW_VIEW,
 212   /* Paints treeheader cells */
 213   MOZ_GTK_TREE_HEADER_CELL,
 214   /* Paints an expander for a GtkTreeView */
 215   MOZ_GTK_TREEVIEW_EXPANDER,
 216   /* Paints the background of menus, context menus. */
 217   MOZ_GTK_MENUPOPUP,
 218   /* Menubar for -moz-headerbar colors */
 219   MOZ_GTK_MENUBAR,
 220   /* Paints an arrow in a toolbar button. flags is a GtkArrowType. */
 221   MOZ_GTK_TOOLBARBUTTON_ARROW,
 222   /* Paints items of popup menus. */
 223   MOZ_GTK_MENUITEM,
 224   /* Menubar menuitem for foreground colors. */
 225   MOZ_GTK_MENUBARITEM,
 226   /* GtkVPaned base class */
 227   MOZ_GTK_SPLITTER_HORIZONTAL,
 228   /* GtkHPaned base class */
 229   MOZ_GTK_SPLITTER_VERTICAL,
 230   /* Paints a GtkVPaned separator */
 231   MOZ_GTK_SPLITTER_SEPARATOR_HORIZONTAL,
 232   /* Paints a GtkHPaned separator */
 233   MOZ_GTK_SPLITTER_SEPARATOR_VERTICAL,
 234   /* Paints the background of a window, dialog or page. */
 235   MOZ_GTK_WINDOW,
 236   /* Used only as a container for MOZ_GTK_HEADER_BAR. */
 237   MOZ_GTK_HEADERBAR_WINDOW,
 238   /* Used only as a container for MOZ_GTK_HEADER_BAR_MAXIMIZED. */
 239   MOZ_GTK_HEADERBAR_WINDOW_MAXIMIZED,
 240   /* Used only as a container for MOZ_GTK_HEADER_BAR. */
 241   MOZ_GTK_HEADERBAR_FIXED,
 242   /* Used only as a container for MOZ_GTK_HEADER_BAR_MAXIMIZED. */
 243   MOZ_GTK_HEADERBAR_FIXED_MAXIMIZED,
 244   /* Window container for all widgets */
 245   MOZ_GTK_WINDOW_CONTAINER,
 246   /* Used for widget tree construction. */
 247   MOZ_GTK_COMBOBOX,
 248   /* Paints a GtkComboBox button widget. */
 249   MOZ_GTK_COMBOBOX_BUTTON,
 250   /* Paints a GtkComboBox arrow widget. */
 251   MOZ_GTK_COMBOBOX_ARROW,
 252   /* Paints a GtkComboBox separator widget. */
 253   MOZ_GTK_COMBOBOX_SEPARATOR,
 254   /* Used for widget tree construction. */
 255   MOZ_GTK_COMBOBOX_ENTRY,
 256   /* Paints a GtkComboBox entry widget. */
 257   MOZ_GTK_COMBOBOX_ENTRY_TEXTAREA,
 258   /* Paints a GtkComboBox entry button widget. */
 259   MOZ_GTK_COMBOBOX_ENTRY_BUTTON,
 260   /* Paints a GtkComboBox entry arrow widget. */
 261   MOZ_GTK_COMBOBOX_ENTRY_ARROW,
 262   /* Used for scrolled window shell. */
 263   MOZ_GTK_SCROLLED_WINDOW,
 264   /* Paints a GtkHeaderBar */
 265   MOZ_GTK_HEADER_BAR,
 266   /* Paints a GtkHeaderBar in maximized state */
 267   MOZ_GTK_HEADER_BAR_MAXIMIZED,
 268   /* Paints GtkHeaderBar title buttons.
 269    * Keep the order here as MOZ_GTK_HEADER_BAR_BUTTON_* are processed
 270    * as an array from MOZ_GTK_HEADER_BAR_BUTTON_CLOSE to the last one.
 271    */
 272   MOZ_GTK_HEADER_BAR_BUTTON_CLOSE,
 273   MOZ_GTK_HEADER_BAR_BUTTON_MINIMIZE,
 274   MOZ_GTK_HEADER_BAR_BUTTON_MAXIMIZE,
 275
 276   /* MOZ_GTK_HEADER_BAR_BUTTON_MAXIMIZE_RESTORE is a state of
 277    * MOZ_GTK_HEADER_BAR_BUTTON_MAXIMIZE button and it's used as
 278    * an icon placeholder only.
 279    */
 280   MOZ_GTK_HEADER_BAR_BUTTON_MAXIMIZE_RESTORE,
 281
 282   /* Client-side window decoration node. Available on GTK 3.20+. */
 283   MOZ_GTK_WINDOW_DECORATION,
 284   MOZ_GTK_WINDOW_DECORATION_SOLID,
 285
 286   MOZ_GTK_WIDGET_NODE_COUNT
 287 };
 288
 289 /* ButtonLayout represents a GTK CSD button and whether its on the left or
 290  * right side of the tab bar */
 291 struct ButtonLayout {
 292   WidgetNodeType mType;
 293 };
 294
 295 /*** General library functions ***/
 296 /**
 297  * Initializes the drawing library.  You must call this function
 298  * prior to using any other functionality.
 299  * returns: MOZ_GTK_SUCCESS if there were no errors
 300  *          MOZ_GTK_UNSAFE_THEME if the current theme engine is known
 301  *                               to crash with gtkdrawing.
 302  */
 303 gint moz_gtk_init();
 304
 305 /**
 306  * Updates the drawing library when the theme changes.
 307  */
 308 void moz_gtk_refresh();
 309
 310 /**
 311  * Perform cleanup of the drawing library. You should call this function
 312  * when your program exits, or you no longer need the library.
 313  *
 314  * returns: MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 315  */
 316 gint moz_gtk_shutdown();
 317
 318 /*** Widget drawing ***/
 319 /**
 320  * Paint a widget in the current theme.
 321  * widget:    a constant giving the widget to paint
 322  * drawable:  the drawable to paint to;
 323  *            it's colormap must be moz_gtk_widget_get_colormap().
 324  * rect:      the bounding rectangle for the widget
 325  * state:     the state of the widget.  ignored for some widgets.
 326  * flags:     widget-dependant flags; see the WidgetNodeType definition.
 327  * direction: the text direction, to draw the widget correctly LTR and RTL.
 328  */
 329 gint moz_gtk_widget_paint(WidgetNodeType widget, cairo_t* cr,
 330                           GdkRectangle* rect, GtkWidgetState* state, gint flags,
 331                           GtkTextDirection direction);
 332
 333 /*** Widget metrics ***/
 334 /**
 335  * Get the border size of a widget
 336  * left/right:  [OUT] the widget's left/right border
 337  * top/bottom:  [OUT] the widget's top/bottom border
 338  * direction:   the text direction for the widget.  Callers depend on this
 339  *              being used only for MOZ_GTK_DROPDOWN widgets, and cache
 340  *              results for other widget types across direction values.
 341  *
 342  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 343  */
 344 gint moz_gtk_get_widget_border(WidgetNodeType widget, gint* left, gint* top,
 345                                gint* right, gint* bottom,
 346                                GtkTextDirection direction);
 347
 348 /**
 349  * Get the border size of a notebook tab
 350  * left/right:  [OUT] the tab's left/right border
 351  * top/bottom:  [OUT] the tab's top/bottom border
 352  * direction:   the text direction for the widget
 353  * flags:       tab-dependant flags; see the GtkTabFlags definition.
 354  * widget:      tab widget
 355  *
 356  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 357  */
 358 gint moz_gtk_get_tab_border(gint* left, gint* top, gint* right, gint* bottom,
 359                             GtkTextDirection direction, GtkTabFlags flags,
 360                             WidgetNodeType widget);
 361
 362 /**
 363  * Get the desired size of a GtkCheckButton
 364  * indicator_size:     [OUT] the indicator size
 365  * indicator_spacing:  [OUT] the spacing between the indicator and its
 366  *                     container
 367  *
 368  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 369  */
 370 gint moz_gtk_checkbox_get_metrics(gint* indicator_size,
 371                                   gint* indicator_spacing);
 372
 373 /**
 374  * Get metrics of the toggle (radio or checkbox)
 375  * isRadio:            [IN] true when requesting metrics for the radio button
 376  * returns:    pointer to ToggleGTKMetrics struct
 377  */
 378 const ToggleGTKMetrics* GetToggleMetrics(WidgetNodeType aWidgetType);
 379
 380 /**
 381  * Get the desired size of a GtkRadioButton
 382  * indicator_size:     [OUT] the indicator size
 383  * indicator_spacing:  [OUT] the spacing between the indicator and its
 384  *                     container
 385  *
 386  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 387  */
 388 gint moz_gtk_radio_get_metrics(gint* indicator_size, gint* indicator_spacing);
 389
 390 /**
 391  * Some GTK themes draw their indication for the default button outside
 392  * the button (e.g. the glow in New Wave). This gets the extra space necessary.
 393  *
 394  * border_top:  [OUT] extra space to add above
 395  * border_left:  [OUT] extra space to add to the left
 396  * border_bottom:  [OUT] extra space to add underneath
 397  * border_right:  [OUT] extra space to add to the right
 398  *
 399  * returns:   MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 400  */
 401 gint moz_gtk_button_get_default_overflow(gint* border_top, gint* border_left,
 402                                          gint* border_bottom,
 403                                          gint* border_right);
 404
 405 /**
 406  * Gets the minimum size of a GtkScale.
 407  * orient:           [IN] the scale orientation
 408  * scale_width:      [OUT] the width of the scale
 409  * scale_height:     [OUT] the height of the scale
 410  */
 411 void moz_gtk_get_scale_metrics(GtkOrientation orient, gint* scale_width,
 412                                gint* scale_height);
 413
 414 /**
 415  * Get the desired size of a GtkScale thumb
 416  * orient:           [IN] the scale orientation
 417  * thumb_length:     [OUT] the length of the thumb
 418  * thumb_height:     [OUT] the height of the thumb
 419  *
 420  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 421  */
 422 gint moz_gtk_get_scalethumb_metrics(GtkOrientation orient, gint* thumb_length,
 423                                     gint* thumb_height);
 424
 425 /**
 426  * Get the desired size of a scroll arrow widget
 427  * width:   [OUT] the desired width
 428  * height:  [OUT] the desired height
 429  *
 430  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 431  */
 432 gint moz_gtk_get_tab_scroll_arrow_size(gint* width, gint* height);
 433
 434 /**
 435  * Get the desired size of an arrow in a button
 436  *
 437  * widgetType: [IN]  the widget for which to get the arrow size
 438  * width:      [OUT] the desired width
 439  * height:     [OUT] the desired height
 440  */
 441 void moz_gtk_get_arrow_size(WidgetNodeType widgetType, gint* width,
 442                             gint* height);
 443
 444 /**
 445  * Get the minimum height of a entry widget
 446  * min_content_height:    [OUT] the minimum height of the content box.
 447  * border_padding_height: [OUT] the size of borders and paddings.
 448  */
 449 void moz_gtk_get_entry_min_height(gint* min_content_height,
 450                                   gint* border_padding_height);
 451
 452 /**
 453  * Get the desired size of a toolbar separator
 454  * size:    [OUT] the desired width
 455  *
 456  * returns: MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 457  */
 458 gint moz_gtk_get_toolbar_separator_width(gint* size);
 459
 460 /**
 461  * Get the size of a regular GTK expander that shows/hides content
 462  * size:    [OUT] the size of the GTK expander, size = width = height.
 463  *
 464  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 465  */
 466 gint moz_gtk_get_expander_size(gint* size);
 467
 468 /**
 469  * Get the size of a treeview's expander (we call them twisties)
 470  * size:    [OUT] the size of the GTK expander, size = width = height.
 471  *
 472  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 473  */
 474 gint moz_gtk_get_treeview_expander_size(gint* size);
 475
 476 /**
 477  * Get the desired size of a splitter
 478  * orientation:   [IN]  GTK_ORIENTATION_HORIZONTAL or GTK_ORIENTATION_VERTICAL
 479  * size:          [OUT] width or height of the splitter handle
 480  *
 481  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 482  */
 483 gint moz_gtk_splitter_get_metrics(gint orientation, gint* size);
 484
 485 /**
 486  * Get the YTHICKNESS of a tab (notebook extension).
 487  */
 488 gint moz_gtk_get_tab_thickness(WidgetNodeType aNodeType);
 489
 490 /**
 491  * Get ToolbarButtonGTKMetrics for recent theme.
 492  */
 493 const ToolbarButtonGTKMetrics* GetToolbarButtonMetrics(
 494     WidgetNodeType aAppearance);
 495
 496 /**
 497  * Get toolbar button layout.
 498  * aButtonLayout:  [OUT] An array which will be filled by ButtonLayout
 499  *                       references to visible titlebar buttons. Must contain at
 500  *                       least TOOLBAR_BUTTONS entries if non-empty.
 501  * aReversedButtonsPlacement: [OUT] True if the buttons are placed in opposite
 502  *                                  titlebar corner.
 503  *
 504  * returns:    Number of returned entries at aButtonLayout.
 505  */
 506 size_t GetGtkHeaderBarButtonLayout(mozilla::Span<ButtonLayout>,
 507                                    bool* aReversedButtonsPlacement);
 508
 509 /**
 510  * Get size of CSD window extents.
 511  *
 512  * aIsPopup: [IN] Get decoration size for popup or toplevel window.
 513  *
 514  * returns: Calculated (or estimated) decoration size of given aGtkWindow.
 515  */
 516 GtkBorder GetCSDDecorationSize(bool aIsPopup);
 517
 518 #endif