1/* -*- Mode: C; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2/* ***** BEGIN LICENSE BLOCK *****
3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 *
5 * The contents of this file are subject to the Mozilla Public License Version
6 * 1.1 (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 * http://www.mozilla.org/MPL/
9 *
10 * Software distributed under the License is distributed on an "AS IS" basis,
11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 * for the specific language governing rights and limitations under the
13 * License.
14 *
15 * The Original Code is mozilla.org code.
16 *
17 * The Initial Developer of the Original Code is
18 * Netscape Communications Corporation.
19 * Portions created by the Initial Developer are Copyright (C) 2002
20 * the Initial Developer. All Rights Reserved.
21 *
22 * Contributor(s):
23 *  Brian Ryner <bryner@brianryner.com>  (Original Author)
24 *
25 * Alternatively, the contents of this file may be used under the terms of
26 * either the GNU General Public License Version 2 or later (the "GPL"), or
27 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
28 * in which case the provisions of the GPL or the LGPL are applicable instead
29 * of those above. If you wish to allow use of your version of this file only
30 * under the terms of either the GPL or the LGPL, and not to allow others to
31 * use your version of this file under the terms of the MPL, indicate your
32 * decision by deleting the provisions above and replace them with the notice
33 * and other provisions required by the GPL or the LGPL. If you do not delete
34 * the provisions above, a recipient may use your version of this file under
35 * the terms of any one of the MPL, the GPL or the LGPL.
36 *
37 * ***** END LICENSE BLOCK ***** */
38
39/**
40 * gtkdrawing.h: GTK widget rendering utilities
41 *
42 * gtkdrawing provides an API for rendering GTK widgets in the
43 * current theme to a pixmap or window, without requiring an actual
44 * widget instantiation, similar to the Macintosh Appearance Manager
45 * or Windows XP's DrawThemeBackground() API.
46 */
47
48#ifndef _GTK_DRAWING_H_
49#define _GTK_DRAWING_H_
50
51#include <gtk/gtk.h>
52
53#ifdef __cplusplus
54extern "C" {
55#endif /* __cplusplus */
56
57/*** type definitions ***/
58typedef struct {
59  guint8 active;
60  guint8 focused;
61  guint8 inHover;
62  guint8 disabled;
63  guint8 isDefault;
64  guint8 canDefault;
65  /* The depressed state is for buttons which remain active for a longer period:
66   * activated toggle buttons or buttons showing a popup menu. */
67  guint8 depressed;
68  gint32 curpos; /* curpos and maxpos are used for scrollbars */
69  gint32 maxpos;
70} GtkWidgetState;
71
72typedef struct {
73  gint slider_width;
74  gint trough_border;
75  gint stepper_size;
76  gint stepper_spacing;
77  gint min_slider_size;
78} MozGtkScrollbarMetrics;
79
80typedef struct _GtkThemeParts {
81    GdkColormap* colormap;
82    GtkWidget* protoWindow;
83    GtkWidget* protoLayout;
84    GtkWidget* buttonWidget;
85    GtkWidget* toggleButtonWidget;
86    GtkWidget* buttonArrowWidget;
87    GtkWidget* checkboxWidget;
88    GtkWidget* radiobuttonWidget;
89    GtkWidget* horizScrollbarWidget;
90    GtkWidget* vertScrollbarWidget;
91    GtkWidget* spinWidget;
92    GtkWidget* hScaleWidget;
93    GtkWidget* vScaleWidget;
94    GtkWidget* entryWidget;
95    GtkWidget* comboBoxWidget;
96    GtkWidget* comboBoxButtonWidget;
97    GtkWidget* comboBoxArrowWidget;
98    GtkWidget* comboBoxSeparatorWidget;
99    GtkWidget* comboBoxEntryWidget;
100    GtkWidget* comboBoxEntryTextareaWidget;
101    GtkWidget* comboBoxEntryButtonWidget;
102    GtkWidget* comboBoxEntryArrowWidget;
103    GtkWidget* handleBoxWidget;
104    GtkWidget* toolbarWidget;
105    GtkWidget* frameWidget;
106    GtkWidget* statusbarWidget;
107    GtkWidget* progresWidget;
108    GtkWidget* tabWidget;
109    GtkWidget* tooltipWidget;
110    GtkWidget* menuBarWidget;
111    GtkWidget* menuBarItemWidget;
112    GtkWidget* menuPopupWidget;
113    GtkWidget* menuItemWidget;
114    GtkWidget* imageMenuItemWidget;
115    GtkWidget* checkMenuItemWidget;
116    GtkWidget* treeViewWidget;
117    GtkTreeViewColumn* middleTreeViewColumn;
118    GtkWidget* treeHeaderCellWidget;
119    GtkWidget* treeHeaderSortArrowWidget;
120    GtkWidget* expanderWidget;
121    GtkWidget* toolbarSeparatorWidget;
122    GtkWidget* menuSeparatorWidget;
123    GtkWidget* hpanedWidget;
124    GtkWidget* vpanedWidget;
125    GtkWidget* scrolledWindowWidget;
126} GtkThemeParts;
127
128typedef enum {
129  MOZ_GTK_STEPPER_DOWN        = 1 << 0,
130  MOZ_GTK_STEPPER_BOTTOM      = 1 << 1,
131  MOZ_GTK_STEPPER_VERTICAL    = 1 << 2
132} GtkScrollbarButtonFlags;
133
134/** flags for tab state **/
135typedef enum {
136  /* first eight bits are used to pass a margin */
137  MOZ_GTK_TAB_MARGIN_MASK     = 0xFF,
138  /* bottom tabs */
139  MOZ_GTK_TAB_BOTTOM          = 1 << 8,
140  /* the first tab in the group */
141  MOZ_GTK_TAB_FIRST           = 1 << 9,
142  /* the selected tab */
143  MOZ_GTK_TAB_SELECTED        = 1 << 10
144} GtkTabFlags;
145
146/** flags for menuitems **/
147typedef enum {
148  /* menuitem is part of the menubar */
149  MOZ_TOPLEVEL_MENU_ITEM      = 1 << 0
150} GtkMenuItemFlags;
151
152/* function type for moz_gtk_enable_style_props */
153typedef gint (*style_prop_t)(GtkStyle*, const gchar*, gint);
154
155/*** result/error codes ***/
156#define MOZ_GTK_SUCCESS 0
157#define MOZ_GTK_UNKNOWN_WIDGET -1
158#define MOZ_GTK_UNSAFE_THEME -2
159
160/*** checkbox/radio flags ***/
161#define MOZ_GTK_WIDGET_CHECKED 1
162#define MOZ_GTK_WIDGET_INCONSISTENT (1 << 1)
163
164/*** widget type constants ***/
165typedef enum {
166  /* Paints a GtkButton. flags is a GtkReliefStyle. */
167  MOZ_GTK_BUTTON,
168  /* Paints a GtkCheckButton. flags is a boolean, 1=checked, 0=not checked. */
169  MOZ_GTK_CHECKBUTTON,
170  /* Paints a GtkRadioButton. flags is a boolean, 1=checked, 0=not checked. */
171  MOZ_GTK_RADIOBUTTON,
172  /**
173   * Paints the button of a GtkScrollbar. flags is a GtkArrowType giving
174   * the arrow direction.
175   */
176  MOZ_GTK_SCROLLBAR_BUTTON,
177  /* Paints the trough (track) of a GtkScrollbar. */
178  MOZ_GTK_SCROLLBAR_TRACK_HORIZONTAL,
179  MOZ_GTK_SCROLLBAR_TRACK_VERTICAL,
180  /* Paints the slider (thumb) of a GtkScrollbar. */
181  MOZ_GTK_SCROLLBAR_THUMB_HORIZONTAL,
182  MOZ_GTK_SCROLLBAR_THUMB_VERTICAL,
183  /* Paints a GtkScale. */
184  MOZ_GTK_SCALE_HORIZONTAL,
185  MOZ_GTK_SCALE_VERTICAL,
186  /* Paints a GtkScale thumb. */
187  MOZ_GTK_SCALE_THUMB_HORIZONTAL,
188  MOZ_GTK_SCALE_THUMB_VERTICAL,
189  /* Paints a GtkSpinButton */
190  MOZ_GTK_SPINBUTTON,
191  MOZ_GTK_SPINBUTTON_UP,
192  MOZ_GTK_SPINBUTTON_DOWN,
193  MOZ_GTK_SPINBUTTON_ENTRY,
194  /* Paints the gripper of a GtkHandleBox. */
195  MOZ_GTK_GRIPPER,
196  /* Paints a GtkEntry. */
197  MOZ_GTK_ENTRY,
198  /* Paints the native caret (or in GTK-speak: insertion cursor) */
199  MOZ_GTK_ENTRY_CARET,
200  /* Paints a GtkOptionMenu. */
201  MOZ_GTK_DROPDOWN,
202  /* Paints a dropdown arrow (a GtkButton containing a down GtkArrow). */
203  MOZ_GTK_DROPDOWN_ARROW,
204  /* Paints an entry in an editable option menu */
205  MOZ_GTK_DROPDOWN_ENTRY,
206  /* Paints the container part of a GtkCheckButton. */
207  MOZ_GTK_CHECKBUTTON_CONTAINER,
208  /* Paints the container part of a GtkRadioButton. */
209  MOZ_GTK_RADIOBUTTON_CONTAINER,
210  /* Paints the label of a GtkCheckButton (focus outline) */
211  MOZ_GTK_CHECKBUTTON_LABEL,
212  /* Paints the label of a GtkRadioButton (focus outline) */
213  MOZ_GTK_RADIOBUTTON_LABEL,
214  /* Paints the background of a GtkHandleBox. */
215  MOZ_GTK_TOOLBAR,
216  /* Paints a toolbar separator */
217  MOZ_GTK_TOOLBAR_SEPARATOR,
218  /* Paints a GtkToolTip */
219  MOZ_GTK_TOOLTIP,
220  /* Paints a GtkFrame (e.g. a status bar panel). */
221  MOZ_GTK_FRAME,
222  /* Paints a resize grip for a GtkWindow */
223  MOZ_GTK_RESIZER,
224  /* Paints a GtkProgressBar. */
225  MOZ_GTK_PROGRESSBAR,
226  /* Paints a progress chunk of a GtkProgressBar. */
227  MOZ_GTK_PROGRESS_CHUNK,
228  /* Paints a tab of a GtkNotebook. flags is a GtkTabFlags, defined above. */
229  MOZ_GTK_TAB,
230  /* Paints the background and border of a GtkNotebook. */
231  MOZ_GTK_TABPANELS,
232  /* Paints a GtkArrow for a GtkNotebook. flags is a GtkArrowType. */
233  MOZ_GTK_TAB_SCROLLARROW,
234  /* Paints the background and border of a GtkTreeView */
235  MOZ_GTK_TREEVIEW,
236  /* Paints treeheader cells */
237  MOZ_GTK_TREE_HEADER_CELL,
238  /* Paints sort arrows in treeheader cells */
239  MOZ_GTK_TREE_HEADER_SORTARROW,
240  /* Paints an expander for a GtkTreeView */
241  MOZ_GTK_TREEVIEW_EXPANDER,
242  /* Paints a GtkExpander */
243  MOZ_GTK_EXPANDER,
244  /* Paints the background of the menu bar. */
245  MOZ_GTK_MENUBAR,
246  /* Paints the background of menus, context menus. */
247  MOZ_GTK_MENUPOPUP,
248  /* Paints the arrow of menuitems that contain submenus */
249  MOZ_GTK_MENUARROW,
250  /* Paints an arrow that points down */
251  MOZ_GTK_TOOLBARBUTTON_ARROW,
252  /* Paints items of menubar and popups. */
253  MOZ_GTK_MENUITEM,
254  MOZ_GTK_CHECKMENUITEM,
255  MOZ_GTK_RADIOMENUITEM,
256  MOZ_GTK_MENUSEPARATOR,
257  /* Paints a GtkVPaned separator */
258  MOZ_GTK_SPLITTER_HORIZONTAL,
259  /* Paints a GtkHPaned separator */
260  MOZ_GTK_SPLITTER_VERTICAL,
261  /* Paints the background of a window, dialog or page. */
262  MOZ_GTK_WINDOW
263} GtkThemeWidgetType;
264
265/*** General library functions ***/
266/**
267 * Initializes the drawing library.  You must call this function
268 * prior to using any other functionality.
269 * returns: MOZ_GTK_SUCCESS if there were no errors
270 *          MOZ_GTK_UNSAFE_THEME if the current theme engine is known
271 *                               to crash with gtkdrawing.
272 */
273gint moz_gtk_init();
274
275/**
276 * Instruct the drawing library to do all rendering based on
277 * the given collection of theme parts. If any members of the
278 * GtkThemeParts struct are NULL, they will be created lazily.
279 */
280void
281moz_gtk_use_theme_parts(GtkThemeParts* parts);
282
283/**
284 * Enable GTK+ 1.2.9+ theme enhancements. You must provide a pointer
285 * to the GTK+ 1.2.9+ function "gtk_style_get_prop_experimental".
286 * styleGetProp:  pointer to gtk_style_get_prop_experimental
287 *
288 * returns: MOZ_GTK_SUCCESS if there was no error, an error code otherwise
289 */
290gint moz_gtk_enable_style_props(style_prop_t styleGetProp);
291
292/**
293 * Perform cleanup of the drawing library. You should call this function
294 * when your program exits, or you no longer need the library.
295 *
296 * returns: MOZ_GTK_SUCCESS if there was no error, an error code otherwise
297 */
298gint moz_gtk_shutdown();
299
300/**
301 * Destroy the widgets in the given GtkThemeParts, which should
302 * be destroyed before the GtkThemeParts can be freed.
303 */
304void moz_gtk_destroy_theme_parts_widgets(GtkThemeParts* parts);
305
306/*** Widget drawing ***/
307/**
308 * Paint a widget in the current theme.
309 * widget:    a constant giving the widget to paint
310 * rect:      the bounding rectangle for the widget
311 * cliprect:  a clipprect rectangle for this painting operation
312 * state:     the state of the widget.  ignored for some widgets.
313 * flags:     widget-dependant flags; see the GtkThemeWidgetType definition.
314 * direction: the text direction, to draw the widget correctly LTR and RTL.
315 */
316gint
317moz_gtk_widget_paint(GtkThemeWidgetType widget, GdkDrawable* drawable,
318                     GdkRectangle* rect, GdkRectangle* cliprect,
319                     GtkWidgetState* state, gint flags,
320                     GtkTextDirection direction);
321
322
323/*** Widget metrics ***/
324/**
325 * Get the border size of a widget
326 * left/right:  [OUT] the widget's left/right border
327 * top/bottom:  [OUT] the widget's top/bottom border
328 * direction:   the text direction for the widget
329 * inhtml:      boolean indicating whether this widget will be drawn as a HTML form control,
330 *              in order to workaround a size issue (MOZ_GTK_BUTTON only, ignored otherwise)
331 *
332 * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
333 */
334gint moz_gtk_get_widget_border(GtkThemeWidgetType widget, gint* left, gint* top,
335                               gint* right, gint* bottom, GtkTextDirection direction,
336                               gboolean inhtml);
337
338/**
339 * Get the desired size of a GtkCheckButton
340 * indicator_size:     [OUT] the indicator size
341 * indicator_spacing:  [OUT] the spacing between the indicator and its
342 *                     container
343 *
344 * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
345 */
346gint
347moz_gtk_checkbox_get_metrics(gint* indicator_size, gint* indicator_spacing);
348
349/**
350 * Get the desired size of a GtkRadioButton
351 * indicator_size:     [OUT] the indicator size
352 * indicator_spacing:  [OUT] the spacing between the indicator and its
353 *                     container
354 *
355 * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
356 */
357gint
358moz_gtk_radio_get_metrics(gint* indicator_size, gint* indicator_spacing);
359
360/**
361 * Get the inner-border value for a GtkButton widget (button or tree header)
362 * widget:             [IN]  the widget to get the border value for
363 * inner_border:       [OUT] the inner border
364 *
365 * returns:   MOZ_GTK_SUCCESS if there was no error, an error code otherwise
366 */
367gint
368moz_gtk_button_get_inner_border(GtkWidget* widget, GtkBorder* inner_border);
369
370/** Get the focus metrics for a treeheadercell, button, checkbox, or radio button.
371 * widget:             [IN]  the widget to get the focus metrics for
372 * interior_focus:     [OUT] whether the focus is drawn around the
373 *                           label (TRUE) or around the whole container (FALSE)
374 * focus_width:        [OUT] the width of the focus line
375 * focus_pad:          [OUT] the padding between the focus line and children
376 *
377 * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
378 */
379gint
380moz_gtk_widget_get_focus(GtkWidget* widget, gboolean* interior_focus,
381                         gint* focus_width, gint* focus_pad);
382
383/**
384 * Get the desired size of a GtkScale thumb
385 * orient:           [IN] the scale orientation
386 * thumb_length:     [OUT] the length of the thumb
387 * thumb_height:     [OUT] the height of the thumb
388 *
389 * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
390 */
391gint
392moz_gtk_get_scalethumb_metrics(GtkOrientation orient, gint* thumb_length, gint* thumb_height);
393
394/**
395 * Get the desired metrics for a GtkScrollbar
396 * metrics:          [IN]  struct which will contain the metrics
397 *
398 * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
399 */
400gint
401moz_gtk_get_scrollbar_metrics(MozGtkScrollbarMetrics* metrics);
402
403/**
404 * Get the desired size of a dropdown arrow button
405 * width:   [OUT] the desired width
406 * height:  [OUT] the desired height
407 *
408 * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
409 */
410gint moz_gtk_get_combo_box_entry_button_size(gint* width, gint* height);
411
412/**
413 * Get the desired size of a scroll arrow widget
414 * width:   [OUT] the desired width
415 * height:  [OUT] the desired height
416 *
417 * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
418 */
419gint moz_gtk_get_tab_scroll_arrow_size(gint* width, gint* height);
420
421/**
422 * Get the desired size of a toolbar button dropdown arrow
423 * width:   [OUT] the desired width
424 * height:  [OUT] the desired height
425 *
426 * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
427 */
428gint moz_gtk_get_downarrow_size(gint* width, gint* height);
429
430/**
431 * Get the desired size of a toolbar separator
432 * size:    [OUT] the desired width
433 *
434 * returns: MOZ_GTK_SUCCESS if there was no error, an error code otherwise
435 */
436gint moz_gtk_get_toolbar_separator_width(gint* size);
437
438/**
439 * Get the size of a regular GTK expander that shows/hides content
440 * size:    [OUT] the size of the GTK expander, size = width = height.
441 *
442 * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
443 */
444gint moz_gtk_get_expander_size(gint* size);
445
446/**
447 * Get the size of a treeview's expander (we call them twisties)
448 * size:    [OUT] the size of the GTK expander, size = width = height.
449 *
450 * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
451 */
452gint moz_gtk_get_treeview_expander_size(gint* size);
453
454/**
455 * Get the desired height of a menu separator
456 * size:    [OUT] the desired height
457 *
458 * returns: MOZ_GTK_SUCCESS if there was no error, an error code otherwise
459 */
460gint moz_gtk_get_menu_separator_height(gint* size);
461
462/**
463 * Get the desired size of a splitter
464 * orientation:   [IN]  GTK_ORIENTATION_HORIZONTAL or GTK_ORIENTATION_VERTICAL
465 * size:          [OUT] width or height of the splitter handle
466 *
467 * returns:    MOZ_GTK_SUCCESS if there was no error, an error code otherwise
468 */
469gint moz_gtk_splitter_get_metrics(gint orientation, gint* size);
470
471/**
472 * Retrieve an actual GTK scrollbar widget for style analysis. It will not
473 * be modified.
474 */
475GtkWidget* moz_gtk_get_scrollbar_widget(void);
476
477/**
478 * Get the YTHICKNESS of a tab (notebook extension).
479 */
480gint moz_gtk_get_tab_thickness(void);
481
482/**
483 * Get a boolean which indicates whether or not to use images in menus.
484 * If TRUE, use images in menus.
485 */
486gboolean moz_gtk_images_in_menus(void);
487
488#ifdef __cplusplus
489}
490#endif /* __cplusplus */
491
492#endif
493