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