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 desired size of a GtkCheckButton
 263  * indicator_size:     [OUT] the indicator size
 264  * indicator_spacing:  [OUT] the spacing between the indicator and its
 265  *                     container
 266  *
 267  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 268  */
 269 gint
 270 moz_gtk_checkbox_get_metrics(gint* indicator_size, gint* indicator_spacing);
 271
 272 /**
 273  * Get the desired size of a GtkRadioButton
 274  * indicator_size:     [OUT] the indicator size
 275  * indicator_spacing:  [OUT] the spacing between the indicator and its
 276  *                     container
 277  *
 278  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 279  */
 280 gint
 281 moz_gtk_radio_get_metrics(gint* indicator_size, gint* indicator_spacing);
 282
 283 /**
 284  * Get the inner-border value for a GtkButton widget (button or tree header)
 285  * widget:             [IN]  the widget to get the border value for
 286  * inner_border:       [OUT] the inner border
 287  *
 288  * returns:   MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 289  */
 290 gint
 291 moz_gtk_button_get_inner_border(GtkWidget* widget, GtkBorder* inner_border);
 292
 293 /** Get the focus metrics for a treeheadercell, button, checkbox, or radio button.
 294  * widget:             [IN]  the widget to get the focus metrics for
 295  * interior_focus:     [OUT] whether the focus is drawn around the
 296  *                           label (TRUE) or around the whole container (FALSE)
 297  * focus_width:        [OUT] the width of the focus line
 298  * focus_pad:          [OUT] the padding between the focus line and children
 299  *
 300  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 301  */
 302 gint
 303 moz_gtk_widget_get_focus(GtkWidget* widget, gboolean* interior_focus,
 304                          gint* focus_width, gint* focus_pad);
 305
 306 /** Get the horizontal padding for the menuitem widget or checkmenuitem widget.
 307  * horizontal_padding: [OUT] The left and right padding of the menuitem or checkmenuitem
 308  *
 309  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 310  */
 311 gint
 312 moz_gtk_menuitem_get_horizontal_padding(gint* horizontal_padding);
 313
 314 gint
 315 moz_gtk_checkmenuitem_get_horizontal_padding(gint* horizontal_padding);
 316
 317 /**
 318  * Some GTK themes draw their indication for the default button outside
 319  * the button (e.g. the glow in New Wave). This gets the extra space necessary.
 320  *
 321  * border_top:  [OUT] extra space to add above
 322  * border_left:  [OUT] extra space to add to the left
 323  * border_bottom:  [OUT] extra space to add underneath
 324  * border_right:  [OUT] extra space to add to the right
 325  *
 326  * returns:   MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 327  */
 328 gint
 329 moz_gtk_button_get_default_overflow(gint* border_top, gint* border_left,
 330                                     gint* border_bottom, gint* border_right);
 331
 332 /**
 333  * Get the desired size of a GtkScale thumb
 334  * orient:           [IN] the scale orientation
 335  * thumb_length:     [OUT] the length of the thumb
 336  * thumb_height:     [OUT] the height of the thumb
 337  *
 338  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 339  */
 340 gint
 341 moz_gtk_get_scalethumb_metrics(GtkOrientation orient, gint* thumb_length, gint* thumb_height);
 342
 343 /**
 344  * Get the desired metrics for a GtkScrollbar
 345  * metrics:          [IN]  struct which will contain the metrics
 346  *
 347  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 348  */
 349 gint
 350 moz_gtk_get_scrollbar_metrics(MozGtkScrollbarMetrics* metrics);
 351
 352 /**
 353  * Get the desired size of a dropdown arrow button
 354  * width:   [OUT] the desired width
 355  * height:  [OUT] the desired height
 356  *
 357  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 358  */
 359 gint moz_gtk_get_combo_box_entry_button_size(gint* width, gint* height);
 360
 361 /**
 362  * Get the desired size of a scroll arrow widget
 363  * width:   [OUT] the desired width
 364  * height:  [OUT] the desired height
 365  *
 366  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 367  */
 368 gint moz_gtk_get_tab_scroll_arrow_size(gint* width, gint* height);
 369
 370 /**
 371  * Get the desired size of an arrow in a button
 372  * width:   [OUT] the desired width
 373  * height:  [OUT] the desired height
 374  *
 375  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 376  */
 377 gint moz_gtk_get_arrow_size(gint* width, gint* height);
 378
 379 /**
 380  * Get the desired size of a toolbar separator
 381  * size:    [OUT] the desired width
 382  *
 383  * returns: MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 384  */
 385 gint moz_gtk_get_toolbar_separator_width(gint* size);
 386
 387 /**
 388  * Get the size of a regular GTK expander that shows/hides content
 389  * size:    [OUT] the size of the GTK expander, size = width = height.
 390  *
 391  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 392  */
 393 gint moz_gtk_get_expander_size(gint* size);
 394
 395 /**
 396  * Get the size of a treeview's expander (we call them twisties)
 397  * size:    [OUT] the size of the GTK expander, size = width = height.
 398  *
 399  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 400  */
 401 gint moz_gtk_get_treeview_expander_size(gint* size);
 402
 403 /**
 404  * Get the desired height of a menu separator
 405  * size:    [OUT] the desired height
 406  *
 407  * returns: MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 408  */
 409 gint moz_gtk_get_menu_separator_height(gint* size);
 410
 411 /**
 412  * Get the desired size of a splitter
 413  * orientation:   [IN]  GTK_ORIENTATION_HORIZONTAL or GTK_ORIENTATION_VERTICAL
 414  * size:          [OUT] width or height of the splitter handle
 415  *
 416  * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
 417  */
 418 gint moz_gtk_splitter_get_metrics(gint orientation, gint* size);
 419
 420 /**
 421  * Retrieve an actual GTK scrollbar widget for style analysis. It will not
 422  * be modified.
 423  */
 424 GtkWidget* moz_gtk_get_scrollbar_widget(void);
 425
 426 /**
 427  * Get the YTHICKNESS of a tab (notebook extension).
 428  */
 429 gint moz_gtk_get_tab_thickness(void);
 430
 431 /**
 432  * Get a boolean which indicates whether or not to use images in menus.
 433  * If TRUE, use images in menus.
 434  */
 435 gboolean moz_gtk_images_in_menus(void);
 436
 437 /**
 438  * Get a boolean which indicates whether or not to use images in buttons.
 439  * If TRUE, use images in buttons.
 440  */
 441 gboolean moz_gtk_images_in_buttons(void);
 442
 443 #ifdef __cplusplus
 444 }
 445 #endif /* __cplusplus */
 446
 447 #endif