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
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif /* __cplusplus */
  24
  25 /*** type definitions ***/
  26 typedef struct {
  27   guint8 active;
  28   guint8 focused;
  29   guint8 inHover;
  30   guint8 disabled;
  31   guint8 isDefault;
  32   guint8 canDefault;
  33   /* The depressed state is for buttons which remain active for a longer period:
  34    * activated toggle buttons or buttons showing a popup menu. */
  35   guint8 depressed;
  36   gint32 curpos; /* curpos and maxpos are used for scrollbars */
  37   gint32 maxpos;
  38 } GtkWidgetState;
  39
  40 typedef struct {
  41   gint slider_width;
  42   gint trough_border;
  43   gint stepper_size;
  44   gint stepper_spacing;
  45   gint min_slider_size;
  46 } MozGtkScrollbarMetrics;
  47
  48 typedef enum {
  49   MOZ_GTK_STEPPER_DOWN        = 1 << 0,
  50   MOZ_GTK_STEPPER_BOTTOM      = 1 << 1,
  51   MOZ_GTK_STEPPER_VERTICAL    = 1 << 2
  52 } GtkScrollbarButtonFlags;
  53
  54 /** flags for tab state **/
  55 typedef enum {
  56   /* first eight bits are used to pass a margin */
  57   MOZ_GTK_TAB_MARGIN_MASK     = 0xFF,
  58   /* bottom tabs */
  59   MOZ_GTK_TAB_BOTTOM          = 1 << 8,
  60   /* the first tab in the group */
  61   MOZ_GTK_TAB_FIRST           = 1 << 9,
  62   /* the selected tab */
  63   MOZ_GTK_TAB_SELECTED        = 1 << 10
  64 } GtkTabFlags;
  65
  66 /** flags for menuitems **/
  67 typedef enum {
  68   /* menuitem is part of the menubar */
  69   MOZ_TOPLEVEL_MENU_ITEM      = 1 << 0
  70 } GtkMenuItemFlags;
  71
  72 /* function type for moz_gtk_enable_style_props */
  73 typedef gint (*style_prop_t)(GtkStyle*, const gchar*, gint);
  74
  75 /*** result/error codes ***/
  76 #define MOZ_GTK_SUCCESS 0
  77 #define MOZ_GTK_UNKNOWN_WIDGET -1
  78 #define MOZ_GTK_UNSAFE_THEME -2
  79
  80 /*** checkbox/radio flags ***/
  81 #define MOZ_GTK_WIDGET_CHECKED 1
  82 #define MOZ_GTK_WIDGET_INCONSISTENT (1 << 1)
  83
  84 /*** widget type constants ***/
  85 typedef enum {
  86   /* Paints a GtkButton. flags is a GtkReliefStyle. */
  87   MOZ_GTK_BUTTON,
  88   /* Paints a GtkCheckButton. flags is a boolean, 1=checked, 0=not checked. */
  89   MOZ_GTK_CHECKBUTTON,
  90   /* Paints a GtkRadioButton. flags is a boolean, 1=checked, 0=not checked. */
  91   MOZ_GTK_RADIOBUTTON,
  92   /**
  93    * Paints the button of a GtkScrollbar. flags is a GtkArrowType giving
  94    * the arrow direction.
  95    */
  96   MOZ_GTK_SCROLLBAR_BUTTON,
  97   /* Paints the trough (track) of a GtkScrollbar. */
  98   MOZ_GTK_SCROLLBAR_TRACK_HORIZONTAL,
  99   MOZ_GTK_SCROLLBAR_TRACK_VERTICAL,
 100   /* Paints the slider (thumb) of a GtkScrollbar. */
 101   MOZ_GTK_SCROLLBAR_THUMB_HORIZONTAL,
 102   MOZ_GTK_SCROLLBAR_THUMB_VERTICAL,
 103   /* Paints a GtkScale. */
 104   MOZ_GTK_SCALE_HORIZONTAL,
 105   MOZ_GTK_SCALE_VERTICAL,
 106   /* Paints a GtkScale thumb. */
 107   MOZ_GTK_SCALE_THUMB_HORIZONTAL,
 108   MOZ_GTK_SCALE_THUMB_VERTICAL,
 109   /* Paints a GtkSpinButton */
 110   MOZ_GTK_SPINBUTTON,
 111   MOZ_GTK_SPINBUTTON_UP,
 112   MOZ_GTK_SPINBUTTON_DOWN,
 113   MOZ_GTK_SPINBUTTON_ENTRY,
 114   /* Paints the gripper of a GtkHandleBox. */
 115   MOZ_GTK_GRIPPER,
 116   /* Paints a GtkEntry. */
 117   MOZ_GTK_ENTRY,
 118   /* Paints a GtkOptionMenu. */
 119   MOZ_GTK_DROPDOWN,
 120   /* Paints a dropdown arrow (a GtkButton containing a down GtkArrow). */
 121   MOZ_GTK_DROPDOWN_ARROW,
 122   /* Paints an entry in an editable option menu */
 123   MOZ_GTK_DROPDOWN_ENTRY,
 124   /* Paints the container part of a GtkCheckButton. */
 125   MOZ_GTK_CHECKBUTTON_CONTAINER,
 126   /* Paints the container part of a GtkRadioButton. */
 127   MOZ_GTK_RADIOBUTTON_CONTAINER,
 128   /* Paints the label of a GtkCheckButton (focus outline) */
 129   MOZ_GTK_CHECKBUTTON_LABEL,
 130   /* Paints the label of a GtkRadioButton (focus outline) */
 131   MOZ_GTK_RADIOBUTTON_LABEL,
 132   /* Paints the background of a GtkHandleBox. */
 133   MOZ_GTK_TOOLBAR,
 134   /* Paints a toolbar separator */
 135   MOZ_GTK_TOOLBAR_SEPARATOR,
 136   /* Paints a GtkToolTip */
 137   MOZ_GTK_TOOLTIP,
 138   /* Paints a GtkFrame (e.g. a status bar panel). */
 139   MOZ_GTK_FRAME,
 140   /* Paints a resize grip for a GtkWindow */
 141   MOZ_GTK_RESIZER,
 142   /* Paints a GtkProgressBar. */
 143   MOZ_GTK_PROGRESSBAR,
 144   /* Paints a progress chunk of a GtkProgressBar. */
 145   MOZ_GTK_PROGRESS_CHUNK,
 146   /* Paints a progress chunk of an indeterminated GtkProgressBar. */
 147   MOZ_GTK_PROGRESS_CHUNK_INDETERMINATE,
 148   /* Paints a progress chunk of a vertical indeterminated GtkProgressBar. */
 149   MOZ_GTK_PROGRESS_CHUNK_VERTICAL_INDETERMINATE,
 150   /* Paints a tab of a GtkNotebook. flags is a GtkTabFlags, defined above. */
 151   MOZ_GTK_TAB,
 152   /* Paints the background and border of a GtkNotebook. */
 153   MOZ_GTK_TABPANELS,
 154   /* Paints a GtkArrow for a GtkNotebook. flags is a GtkArrowType. */
 155   MOZ_GTK_TAB_SCROLLARROW,
 156   /* Paints the background and border of a GtkTreeView */
 157   MOZ_GTK_TREEVIEW,
 158   /* Paints treeheader cells */
 159   MOZ_GTK_TREE_HEADER_CELL,
 160   /* Paints sort arrows in treeheader cells */
 161   MOZ_GTK_TREE_HEADER_SORTARROW,
 162   /* Paints an expander for a GtkTreeView */
 163   MOZ_GTK_TREEVIEW_EXPANDER,
 164   /* Paints the background of the menu bar. */
 165   MOZ_GTK_MENUBAR,
 166   /* Paints the background of menus, context menus. */
 167   MOZ_GTK_MENUPOPUP,
 168   /* Paints the arrow of menuitems that contain submenus */
 169   MOZ_GTK_MENUARROW,
 170   /* Paints an arrow in a toolbar button. flags is a GtkArrowType. */
 171   MOZ_GTK_TOOLBARBUTTON_ARROW,
 172   /* Paints items of menubar and popups. */
 173   MOZ_GTK_MENUITEM,
 174   MOZ_GTK_CHECKMENUITEM,
 175   MOZ_GTK_RADIOMENUITEM,
 176   MOZ_GTK_MENUSEPARATOR,
 177   /* Paints a GtkVPaned separator */
 178   MOZ_GTK_SPLITTER_HORIZONTAL,
 179   /* Paints a GtkHPaned separator */
 180   MOZ_GTK_SPLITTER_VERTICAL,
 181   /* Paints the background of a window, dialog or page. */
 182   MOZ_GTK_WINDOW
 183 } GtkThemeWidgetType;
 184
 185 /*** General library functions ***/
 186 /**
 187  * Initializes the drawing library.  You must call this function
 188  * prior to using any other functionality.
 189  * returns: MOZ_GTK_SUCCESS if there were no errors
 190  *          MOZ_GTK_UNSAFE_THEME if the current theme engine is known
 191  *                               to crash with gtkdrawing.
 192  */
 193 gint moz_gtk_init();
 194
 195 /**
 196  * Enable GTK+ 1.2.9+ theme enhancements. You must provide a pointer
 197  * to the GTK+ 1.2.9+ function "gtk_style_get_prop_experimental".
 198  * styleGetProp:  pointer to gtk_style_get_prop_experimental
 199  *
 200  * returns: MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 201  */
 202 gint moz_gtk_enable_style_props(style_prop_t styleGetProp);
 203
 204 /**
 205  * Perform cleanup of the drawing library. You should call this function
 206  * when your program exits, or you no longer need the library.
 207  *
 208  * returns: MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 209  */
 210 gint moz_gtk_shutdown();
 211
 212 #if (MOZ_WIDGET_GTK == 2)
 213 /**
 214  * Retrieves the colormap to use for drawables passed to moz_gtk_widget_paint.
 215  */
 216 GdkColormap* moz_gtk_widget_get_colormap();
 217 #endif
 218
 219 /*** Widget drawing ***/
 220 #if (MOZ_WIDGET_GTK == 2)
 221 /**
 222  * Paint a widget in the current theme.
 223  * widget:    a constant giving the widget to paint
 224  * drawable:  the drawable to paint to;
 225  *            it's colormap must be moz_gtk_widget_get_colormap().
 226  * rect:      the bounding rectangle for the widget
 227  * cliprect:  a clipprect rectangle for this painting operation
 228  * state:     the state of the widget.  ignored for some widgets.
 229  * flags:     widget-dependant flags; see the GtkThemeWidgetType definition.
 230  * direction: the text direction, to draw the widget correctly LTR and RTL.
 231  */
 232 gint
 233 moz_gtk_widget_paint(GtkThemeWidgetType widget, GdkDrawable* drawable,
 234                      GdkRectangle* rect, GdkRectangle* cliprect,
 235                      GtkWidgetState* state, gint flags,
 236                      GtkTextDirection direction);
 237 #else
 238 gint
 239 moz_gtk_widget_paint(GtkThemeWidgetType widget, cairo_t *cr,
 240                      GdkRectangle* rect,
 241                      GtkWidgetState* state, gint flags,
 242                      GtkTextDirection direction);
 243 #endif
 244
 245
 246 /*** Widget metrics ***/
 247 /**
 248  * Get the border size of a widget
 249  * left/right:  [OUT] the widget's left/right border
 250  * top/bottom:  [OUT] the widget's top/bottom border
 251  * direction:   the text direction for the widget
 252  * inhtml:      boolean indicating whether this widget will be drawn as a HTML form control,
 253  *              in order to workaround a size issue (MOZ_GTK_BUTTON only, ignored otherwise)
 254  *
 255  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 256  */
 257 gint moz_gtk_get_widget_border(GtkThemeWidgetType widget, gint* left, gint* top,
 258                                gint* right, gint* bottom, GtkTextDirection direction,
 259                                gboolean inhtml);
 260
 261 /**
 262  * Get the border size of a notebook tab
 263  * left/right:  [OUT] the tab's left/right border
 264  * top/bottom:  [OUT] the tab's top/bottom border
 265  * direction:   the text direction for the widget
 266  * flags:       tab-dependant flags; see the GtkTabFlags definition.
 267  *
 268  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 269  */
 270 gint
 271 moz_gtk_get_tab_border(gint* left, gint* top, gint* right, gint* bottom,
 272                        GtkTextDirection direction, GtkTabFlags flags);
 273
 274 /**
 275  * Get the desired size of a GtkCheckButton
 276  * indicator_size:     [OUT] the indicator size
 277  * indicator_spacing:  [OUT] the spacing between the indicator and its
 278  *                     container
 279  *
 280  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 281  */
 282 gint
 283 moz_gtk_checkbox_get_metrics(gint* indicator_size, gint* indicator_spacing);
 284
 285 /**
 286  * Get the desired size of a GtkRadioButton
 287  * indicator_size:     [OUT] the indicator size
 288  * indicator_spacing:  [OUT] the spacing between the indicator and its
 289  *                     container
 290  *
 291  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 292  */
 293 gint
 294 moz_gtk_radio_get_metrics(gint* indicator_size, gint* indicator_spacing);
 295
 296 /**
 297  * Get the inner-border value for a GtkButton widget (button or tree header)
 298  * widget:             [IN]  the widget to get the border value for
 299  * inner_border:       [OUT] the inner border
 300  *
 301  * returns:   MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 302  */
 303 gint
 304 moz_gtk_button_get_inner_border(GtkWidget* widget, GtkBorder* inner_border);
 305
 306 /** Get the extra size for the focus ring for outline:auto.
 307  * widget:             [IN]  the widget to get the focus metrics for
 308  * focus_h_width:      [OUT] the horizontal width
 309  * focus_v_width:      [OUT] the vertical width
 310  *
 311  * returns:    MOZ_GTK_SUCCESS
 312  */
 313 gint
 314 moz_gtk_get_focus_outline_size(gint* focus_h_width, gint* focus_v_width);
 315
 316 /** Get the focus metrics for a treeheadercell, button, checkbox, or radio button.
 317  * widget:             [IN]  the widget to get the focus metrics for
 318  * interior_focus:     [OUT] whether the focus is drawn around the
 319  *                           label (TRUE) or around the whole container (FALSE)
 320  * focus_width:        [OUT] the width of the focus line
 321  * focus_pad:          [OUT] the padding between the focus line and children
 322  *
 323  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 324  */
 325 gint
 326 moz_gtk_widget_get_focus(GtkWidget* widget, gboolean* interior_focus,
 327                          gint* focus_width, gint* focus_pad);
 328
 329 /** Get the horizontal padding for the menuitem widget or checkmenuitem widget.
 330  * horizontal_padding: [OUT] The left and right padding of the menuitem or checkmenuitem
 331  *
 332  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 333  */
 334 gint
 335 moz_gtk_menuitem_get_horizontal_padding(gint* horizontal_padding);
 336
 337 gint
 338 moz_gtk_checkmenuitem_get_horizontal_padding(gint* horizontal_padding);
 339
 340 /**
 341  * Some GTK themes draw their indication for the default button outside
 342  * the button (e.g. the glow in New Wave). This gets the extra space necessary.
 343  *
 344  * border_top:  [OUT] extra space to add above
 345  * border_left:  [OUT] extra space to add to the left
 346  * border_bottom:  [OUT] extra space to add underneath
 347  * border_right:  [OUT] extra space to add to the right
 348  *
 349  * returns:   MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 350  */
 351 gint
 352 moz_gtk_button_get_default_overflow(gint* border_top, gint* border_left,
 353                                     gint* border_bottom, gint* border_right);
 354
 355 /**
 356  * Get the desired size of a GtkScale thumb
 357  * orient:           [IN] the scale orientation
 358  * thumb_length:     [OUT] the length of the thumb
 359  * thumb_height:     [OUT] the height of the thumb
 360  *
 361  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 362  */
 363 gint
 364 moz_gtk_get_scalethumb_metrics(GtkOrientation orient, gint* thumb_length, gint* thumb_height);
 365
 366 /**
 367  * Get the desired metrics for a GtkScrollbar
 368  * metrics:          [IN]  struct which will contain the metrics
 369  *
 370  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 371  */
 372 gint
 373 moz_gtk_get_scrollbar_metrics(MozGtkScrollbarMetrics* metrics);
 374
 375 /**
 376  * Get the desired size of a dropdown arrow button
 377  * width:   [OUT] the desired width
 378  * height:  [OUT] the desired height
 379  *
 380  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 381  */
 382 gint moz_gtk_get_combo_box_entry_button_size(gint* width, gint* height);
 383
 384 /**
 385  * Get the desired size of a scroll arrow widget
 386  * width:   [OUT] the desired width
 387  * height:  [OUT] the desired height
 388  *
 389  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 390  */
 391 gint moz_gtk_get_tab_scroll_arrow_size(gint* width, gint* height);
 392
 393 /**
 394  * Get the desired size of an arrow in a button
 395  * width:   [OUT] the desired width
 396  * height:  [OUT] the desired height
 397  *
 398  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 399  */
 400 gint moz_gtk_get_arrow_size(gint* width, gint* height);
 401
 402 /**
 403  * Get the desired size of a toolbar separator
 404  * size:    [OUT] the desired width
 405  *
 406  * returns: MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 407  */
 408 gint moz_gtk_get_toolbar_separator_width(gint* size);
 409
 410 /**
 411  * Get the size of a regular GTK expander that shows/hides content
 412  * size:    [OUT] the size of the GTK expander, size = width = height.
 413  *
 414  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 415  */
 416 gint moz_gtk_get_expander_size(gint* size);
 417
 418 /**
 419  * Get the size of a treeview's expander (we call them twisties)
 420  * size:    [OUT] the size of the GTK expander, size = width = height.
 421  *
 422  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 423  */
 424 gint moz_gtk_get_treeview_expander_size(gint* size);
 425
 426 /**
 427  * Get the desired height of a menu separator
 428  * size:    [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_menu_separator_height(gint* size);
 433
 434 /**
 435  * Get the desired size of a splitter
 436  * orientation:   [IN]  GTK_ORIENTATION_HORIZONTAL or GTK_ORIENTATION_VERTICAL
 437  * size:          [OUT] width or height of the splitter handle
 438  *
 439  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 440  */
 441 gint moz_gtk_splitter_get_metrics(gint orientation, gint* size);
 442
 443 /**
 444  * Retrieve an actual GTK scrollbar widget for style analysis. It will not
 445  * be modified.
 446  */
 447 GtkWidget* moz_gtk_get_scrollbar_widget(void);
 448
 449 /**
 450  * Get the YTHICKNESS of a tab (notebook extension).
 451  */
 452 gint moz_gtk_get_tab_thickness(void);
 453
 454 /**
 455  * Get a boolean which indicates whether or not to use images in menus.
 456  * If TRUE, use images in menus.
 457  */
 458 gboolean moz_gtk_images_in_menus(void);
 459
 460 /**
 461  * Get a boolean which indicates whether or not to use images in buttons.
 462  * If TRUE, use images in buttons.
 463  */
 464 gboolean moz_gtk_images_in_buttons(void);
 465
 466 #ifdef __cplusplus
 467 }
 468 #endif /* __cplusplus */
 469
 470 #endif