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