Mercurial > pidgin.yaz
comparison pidgin/gtkutils.h @ 15374:5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
author | Sean Egan <seanegan@gmail.com> |
---|---|
date | Sat, 20 Jan 2007 02:32:10 +0000 |
parents | |
children | e6b40365930c |
comparison
equal
deleted
inserted
replaced
15373:f79e0f4df793 | 15374:5fe8042783c1 |
---|---|
1 /** | |
2 * @file gtkutils.h GTK+ utility functions | |
3 * @ingroup gtkui | |
4 * | |
5 * gaim | |
6 * | |
7 * Gaim is the legal property of its developers, whose names are too numerous | |
8 * to list here. Please refer to the COPYRIGHT file distributed with this | |
9 * source distribution. | |
10 * | |
11 * This program is free software; you can redistribute it and/or modify | |
12 * it under the terms of the GNU General Public License as published by | |
13 * the Free Software Foundation; either version 2 of the License, or | |
14 * (at your option) any later version. | |
15 * | |
16 * This program is distributed in the hope that it will be useful, | |
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
19 * GNU General Public License for more details. | |
20 * | |
21 * You should have received a copy of the GNU General Public License | |
22 * along with this program; if not, write to the Free Software | |
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
24 */ | |
25 #ifndef _GAIM_GTKUTILS_H_ | |
26 #define _GAIM_GTKUTILS_H_ | |
27 | |
28 #include "gtkconv.h" | |
29 #include "gtkgaim.h" | |
30 #include "prpl.h" | |
31 #include "util.h" | |
32 | |
33 typedef enum | |
34 { | |
35 GAIM_BUTTON_HORIZONTAL, | |
36 GAIM_BUTTON_VERTICAL | |
37 | |
38 } GaimButtonOrientation; | |
39 | |
40 typedef enum | |
41 { | |
42 GAIM_BUTTON_NONE = 0, | |
43 GAIM_BUTTON_TEXT, | |
44 GAIM_BUTTON_IMAGE, | |
45 GAIM_BUTTON_TEXT_IMAGE | |
46 | |
47 } GaimButtonStyle; | |
48 | |
49 #ifndef _WIN32 | |
50 typedef enum | |
51 { | |
52 GAIM_BROWSER_DEFAULT = 0, | |
53 GAIM_BROWSER_CURRENT, | |
54 GAIM_BROWSER_NEW_WINDOW, | |
55 GAIM_BROWSER_NEW_TAB | |
56 | |
57 } GaimBrowserPlace; | |
58 #endif /* _WIN32 */ | |
59 | |
60 /** | |
61 * Sets up a gtkimhtml widget, loads it with smileys, and sets the | |
62 * default signal handlers. | |
63 * | |
64 * @param imhtml The gtkimhtml widget to setup. | |
65 */ | |
66 void gaim_setup_imhtml(GtkWidget *imhtml); | |
67 | |
68 /** | |
69 * Create an GtkIMHtml widget and associated GtkIMHtmlToolbar widget. This | |
70 * functions puts both widgets in a nice GtkFrame. They're separate by an | |
71 * attractive GtkSeparator. | |
72 * | |
73 * @param editable @c TRUE if this imhtml should be editable. If this is @c FALSE, | |
74 * then the toolbar will NOT be created. If this imthml should be | |
75 * read-only at first, but may become editable later, then pass in | |
76 * @c TRUE here and then manually call gtk_imhtml_set_editable() later. | |
77 * @param imhtml_ret A pointer to a pointer to a GtkWidget. This pointer | |
78 * will be set to the imhtml when this function exits. | |
79 * @param toolbar_ret A pointer to a pointer to a GtkWidget. If editable is | |
80 * TRUE then this will be set to the toolbar when this function exits. | |
81 * Otherwise this will be set to @c NULL. | |
82 * @param sw_ret This will be filled with a pointer to the scrolled window | |
83 * widget which contains the imhtml. | |
84 * @return The GtkFrame containing the toolbar and imhtml. | |
85 */ | |
86 GtkWidget *gaim_gtk_create_imhtml(gboolean editable, GtkWidget **imhtml_ret, GtkWidget **toolbar_ret, GtkWidget **sw_ret); | |
87 | |
88 /** | |
89 * Toggles the sensitivity of a widget. | |
90 * | |
91 * @param widget @c NULL. Used for signal handlers. | |
92 * @param to_toggle The widget to toggle. | |
93 */ | |
94 void gaim_gtk_toggle_sensitive(GtkWidget *widget, GtkWidget *to_toggle); | |
95 | |
96 /** | |
97 * Checks if text has been entered into a GtkTextEntry widget. If | |
98 * so, the GTK_RESPONSE_OK on the given dialog is set to TRUE. | |
99 * Otherwise GTK_RESPONSE_OK is set to FALSE. | |
100 * | |
101 * @param entry The text entry widget. | |
102 * @param dialog The dialog containing the text entry widget. | |
103 */ | |
104 void gaim_gtk_set_sensitive_if_input(GtkWidget *entry, GtkWidget *dialog); | |
105 | |
106 /** | |
107 * Toggles the sensitivity of all widgets in a pointer array. | |
108 * | |
109 * @param w @c NULL. Used for signal handlers. | |
110 * @param data The array containing the widgets to toggle. | |
111 */ | |
112 void gaim_gtk_toggle_sensitive_array(GtkWidget *w, GPtrArray *data); | |
113 | |
114 /** | |
115 * Toggles the visibility of a widget. | |
116 * | |
117 * @param widget @c NULL. Used for signal handlers. | |
118 * @param to_toggle The widget to toggle. | |
119 */ | |
120 void gaim_gtk_toggle_showhide(GtkWidget *widget, GtkWidget *to_toggle); | |
121 | |
122 /** | |
123 * Adds a separator to a menu. | |
124 * | |
125 * @param menu The menu to add a separator to. | |
126 */ | |
127 void gaim_separator(GtkWidget *menu); | |
128 | |
129 /** | |
130 * Creates a menu item. | |
131 * | |
132 * @param menu The menu to which to append the menu item. | |
133 * @param str The title to use for the newly created menu item. | |
134 * | |
135 * @return The newly created menu item. | |
136 */ | |
137 GtkWidget *gaim_new_item(GtkWidget *menu, const char *str); | |
138 | |
139 /** | |
140 * Creates a check menu item. | |
141 * | |
142 * @param menu The menu to which to append the check menu item. | |
143 * @param str The title to use for the newly created menu item. | |
144 * @param sf A function to call when the menu item is activated. | |
145 * @param data Data to pass to the signal function. | |
146 * @param checked The initial state of the check item | |
147 * | |
148 * @return The newly created menu item. | |
149 */ | |
150 GtkWidget *gaim_new_check_item(GtkWidget *menu, const char *str, | |
151 GtkSignalFunc sf, gpointer data, gboolean checked); | |
152 | |
153 /** | |
154 * Creates a menu item. | |
155 * | |
156 * @param menu The menu to which to append the menu item. | |
157 * @param str The title for the menu item. | |
158 * @param icon An icon to place to the left of the menu item, | |
159 * or @c NULL for no icon. | |
160 * @param sf A function to call when the menu item is activated. | |
161 * @param data Data to pass to the signal function. | |
162 * @param accel_key Something. | |
163 * @param accel_mods Something. | |
164 * @param mod Something. | |
165 * | |
166 * @return The newly created menu item. | |
167 */ | |
168 GtkWidget *gaim_new_item_from_stock(GtkWidget *menu, const char *str, | |
169 const char *icon, GtkSignalFunc sf, | |
170 gpointer data, guint accel_key, | |
171 guint accel_mods, char *mod); | |
172 | |
173 /** | |
174 * Creates a button with the specified text and stock icon. | |
175 * | |
176 * @param text The text for the button. | |
177 * @param icon The stock icon name. | |
178 * @param style The orientation of the button. | |
179 * | |
180 * @return The button. | |
181 */ | |
182 GtkWidget *gaim_pixbuf_button_from_stock(const char *text, const char *icon, | |
183 GaimButtonOrientation style); | |
184 | |
185 /** | |
186 * Creates a toolbar button with the stock icon. | |
187 * | |
188 * @param stock The stock icon name. | |
189 * | |
190 * @return The button. | |
191 */ | |
192 GtkWidget *gaim_pixbuf_toolbar_button_from_stock(const char *stock); | |
193 | |
194 /** | |
195 * Creates a HIG preferences frame. | |
196 * | |
197 * @param parent The widget to put the frame into. | |
198 * @param title The title for the frame. | |
199 * | |
200 * @return The vbox to put things into. | |
201 */ | |
202 GtkWidget *gaim_gtk_make_frame(GtkWidget *parent, const char *title); | |
203 | |
204 /** | |
205 * Creates a drop-down option menu filled with protocols. | |
206 * | |
207 * @param id The protocol to select by default. | |
208 * @param cb The callback to call when a protocol is selected. | |
209 * @param user_data Data to pass to the callback function. | |
210 * | |
211 * @return The drop-down option menu. | |
212 */ | |
213 GtkWidget *gaim_gtk_protocol_option_menu_new(const char *id, | |
214 GCallback cb, | |
215 gpointer user_data); | |
216 | |
217 /** | |
218 * Creates a drop-down option menu filled with accounts. | |
219 * | |
220 * @param default_account The account to select by default. | |
221 * @param show_all Whether or not to show all accounts, or just | |
222 * active accounts. | |
223 * @param cb The callback to call when an account is selected. | |
224 * @param filter_func A function for checking if an account should | |
225 * be shown. This can be NULL. | |
226 * @param user_data Data to pass to the callback function. | |
227 * | |
228 * @return The drop-down option menu. | |
229 */ | |
230 GtkWidget *gaim_gtk_account_option_menu_new(GaimAccount *default_account, | |
231 gboolean show_all, GCallback cb, | |
232 GaimFilterAccountFunc filter_func, gpointer user_data); | |
233 | |
234 /** | |
235 * Gets the currently selected account from an account drop down box. | |
236 * | |
237 * @param optmenu The GtkOptionMenu created by | |
238 * gaim_gtk_account_option_menu_new. | |
239 * @return Returns the GaimAccount that is currently selected. | |
240 */ | |
241 GaimAccount *gaim_gtk_account_option_menu_get_selected(GtkWidget *optmenu); | |
242 | |
243 /** | |
244 * Sets the currently selected account for an account drop down box. | |
245 * | |
246 * @param optmenu The GtkOptionMenu created by | |
247 * gaim_gtk_account_option_menu_new. | |
248 * @param account The GaimAccount to select. | |
249 */ | |
250 void gaim_gtk_account_option_menu_set_selected(GtkWidget *optmenu, GaimAccount *account); | |
251 | |
252 /** | |
253 * Add autocompletion of screenames to an entry. | |
254 * | |
255 * @param entry The GtkEntry on which to setup autocomplete. | |
256 * @param optmenu A menu for accounts, returned by gaim_gtk_account_option_menu_new(). | |
257 * If @a optmenu is not @c NULL, it'll be updated when a screenname is chosen | |
258 * from the autocomplete list. | |
259 * @param all Whether to include screennames from disconnected accounts. | |
260 */ | |
261 void gaim_gtk_setup_screenname_autocomplete(GtkWidget *entry, GtkWidget *optmenu, gboolean all); | |
262 | |
263 /** | |
264 * Check if the given path is a directory or not. If it is, then modify | |
265 * the given GtkFileSelection dialog so that it displays the given path. | |
266 * If the given path is not a directory, then do nothing. | |
267 * | |
268 * @param path The path entered in the file selection window by the user. | |
269 * @param filesel The file selection window. | |
270 * | |
271 * @return TRUE if given path is a directory, FALSE otherwise. | |
272 */ | |
273 gboolean gaim_gtk_check_if_dir(const char *path, GtkFileSelection *filesel); | |
274 | |
275 /** | |
276 * Sets up GtkSpell for the given GtkTextView, reporting errors | |
277 * if encountered. | |
278 * | |
279 * This does nothing if Gaim is not compiled with GtkSpell support. | |
280 * | |
281 * @param textview The textview widget to setup spellchecking for. | |
282 */ | |
283 void gaim_gtk_setup_gtkspell(GtkTextView *textview); | |
284 | |
285 /** | |
286 * Save menu accelerators callback | |
287 */ | |
288 void gaim_gtk_save_accels_cb(GtkAccelGroup *accel_group, guint arg1, | |
289 GdkModifierType arg2, GClosure *arg3, | |
290 gpointer data); | |
291 | |
292 /** | |
293 * Save menu accelerators | |
294 */ | |
295 gboolean gaim_gtk_save_accels(gpointer data); | |
296 | |
297 /** | |
298 * Load menu accelerators | |
299 */ | |
300 void gaim_gtk_load_accels(void); | |
301 | |
302 /** | |
303 * Parses an application/x-im-contact MIME message and returns the | |
304 * data inside. | |
305 * | |
306 * @param msg The MIME message. | |
307 * @param all_accounts If TRUE, check all compatible accounts, online or | |
308 * offline. If FALSE, check only online accounts. | |
309 * @param ret_account The best guess at a compatible protocol, | |
310 * based on ret_protocol. If NULL, no account was found. | |
311 * @param ret_protocol The returned protocol type. | |
312 * @param ret_username The returned username. | |
313 * @param ret_alias The returned alias. | |
314 * | |
315 * @return TRUE if the message was parsed for the minimum necessary data. | |
316 * FALSE otherwise. | |
317 */ | |
318 gboolean gaim_gtk_parse_x_im_contact(const char *msg, gboolean all_accounts, | |
319 GaimAccount **ret_account, | |
320 char **ret_protocol, char **ret_username, | |
321 char **ret_alias); | |
322 | |
323 /** | |
324 * Sets an ATK name for a given widget. Also sets the labelled-by | |
325 * and label-for ATK relationships. | |
326 * | |
327 * @param w The widget that we want to name. | |
328 * @param l A GtkLabel that we want to use as the ATK name for the widget. | |
329 */ | |
330 void gaim_set_accessible_label(GtkWidget *w, GtkWidget *l); | |
331 | |
332 /** | |
333 * A valid GtkMenuPositionFunc. This is used to determine where | |
334 * to draw context menu's when the menu is activated with the | |
335 * keyboard (shift+F10). If the menu is activated with the mouse, | |
336 * then you should just use GTK's built-in position function, | |
337 * because it does a better job of positioning the menu. | |
338 * | |
339 * @param menu The menu we are positioning. | |
340 * @param x Address of the gint representing the horizontal position | |
341 * where the menu shall be drawn. This is an output parameter. | |
342 * @param y Address of the gint representing the vertical position | |
343 * where the menu shall be drawn. This is an output parameter. | |
344 * @param push_in This is an output parameter? | |
345 * @param user_data Not used by this particular position function. | |
346 */ | |
347 void gaim_gtk_treeview_popup_menu_position_func(GtkMenu *menu, | |
348 gint *x, | |
349 gint *y, | |
350 gboolean *push_in, | |
351 gpointer user_data); | |
352 | |
353 /** | |
354 * Manages drag'n'drop of files. | |
355 * | |
356 * @param sd GtkSelectionData for managing drag'n'drop | |
357 * @param account Account to be used (may be NULL if conv is not NULL) | |
358 * @param who Buddy name (may be NULL if conv is not NULL) | |
359 */ | |
360 void gaim_dnd_file_manage(GtkSelectionData *sd, GaimAccount *account, const char *who); | |
361 | |
362 /** | |
363 * Convenience wrapper for gaim_buddy_icon_get_scale_size | |
364 */ | |
365 void gaim_gtk_buddy_icon_get_scale_size(GdkPixbuf *buf, GaimBuddyIconSpec *spec, GaimIconScaleRules rules, int *width, int *height); | |
366 | |
367 /** | |
368 * Returns the base image to represent the account, based on | |
369 * the currently selected theme. | |
370 * | |
371 * @param account The account. | |
372 * @param scale_factor The amount to scale to the original image. | |
373 * The default size is 32x32 pixels. A scale | |
374 * factor of 1 means no scaling will be done. | |
375 * A scale factor of 0.5 means the length | |
376 * and width will be 16 pixels each. | |
377 * | |
378 * @return A newly-created pixbuf with a reference count of 1, | |
379 * or NULL if any of several error conditions occurred: | |
380 * the file could not be opened, there was no loader | |
381 * for the file's format, there was not enough memory | |
382 * to allocate the image buffer, or the image file | |
383 * contained invalid data. | |
384 */ | |
385 GdkPixbuf *gaim_gtk_create_prpl_icon(GaimAccount *account, double scale_factor); | |
386 | |
387 /** | |
388 * Create a protocol icon with the status emblem overlayed in | |
389 * the lower right corner. | |
390 * | |
391 * @param account The account. | |
392 * @param status_type The status type of the emblem to overlay. | |
393 * @param scale_factor The amount to scale to the original image. | |
394 * The default size is 32x32 pixels. A scale | |
395 * factor of 1 means no scaling will be done. | |
396 * A scale factor of 0.5 means the length | |
397 * and width will be 16 pixels each. | |
398 * | |
399 * @return A newly-created pixbuf with a reference count of 1, | |
400 * or NULL if any of several error conditions occurred: | |
401 * the file could not be opened, there was no loader | |
402 * for the file's format, there was not enough memory | |
403 * to allocate the image buffer, or the image file | |
404 * contained invalid data. | |
405 */ | |
406 GdkPixbuf *gaim_gtk_create_prpl_icon_with_status(GaimAccount *account, GaimStatusType *status_type, double scale_factor); | |
407 | |
408 /** | |
409 * Create a Gaim running-man icon with the status emblem overlayed | |
410 * in the lower right corner. | |
411 * | |
412 * @param primitive The status type to set the emblem for. | |
413 * @param scale_factor The amount to scale to the original image. | |
414 * The default size is 32x32 pixels. A scale | |
415 * factor of 1 means no scaling will be done. | |
416 * A scale factor of 0.5 means the length | |
417 * and width will be 16 pixels each. | |
418 * | |
419 * @return A newly-created pixbuf with a reference count of 1, | |
420 * or NULL if any of several error conditions occurred: | |
421 * the file could not be opened, there was no loader for | |
422 * the file's format, there was not enough memory to | |
423 * allocate the image buffer, or the image file contained | |
424 * invalid data. | |
425 */ | |
426 GdkPixbuf *gaim_gtk_create_gaim_icon_with_status(GaimStatusPrimitive primitive, double scale_factor); | |
427 | |
428 | |
429 /** | |
430 * Append a GaimMenuAction to a menu. | |
431 * | |
432 * @param menu The menu to append to. | |
433 * @param act The GaimMenuAction to append. | |
434 * @param gobject The object to be passed to the action callback. | |
435 */ | |
436 void gaim_gtk_append_menu_action(GtkWidget *menu, GaimMenuAction *act, | |
437 gpointer gobject); | |
438 | |
439 /** | |
440 * Sets the mouse pointer for a GtkWidget. | |
441 * | |
442 * After setting the cursor, the display is flushed, so the change will | |
443 * take effect immediately. | |
444 * | |
445 * If the window for @a widget is @c NULL, this function simply returns. | |
446 * | |
447 * @param widget The widget for which to set the mouse pointer | |
448 * @param cursor_type The type of cursor to set | |
449 */ | |
450 void gaim_gtk_set_cursor(GtkWidget *widget, GdkCursorType cursor_type); | |
451 | |
452 /** | |
453 * Sets the mouse point for a GtkWidget back to that of its parent window. | |
454 * | |
455 * If @a widget is @c NULL, this function simply returns. | |
456 * | |
457 * If the window for @a widget is @c NULL, this function simply returns. | |
458 * | |
459 * @note The display is not flushed from this function. | |
460 */ | |
461 void gaim_gtk_clear_cursor(GtkWidget *widget); | |
462 | |
463 /** | |
464 * Creates a File Selection widget for choosing a buddy icon | |
465 * | |
466 * @param parent The parent window | |
467 * @param callback The callback to call when the window is closed. If the user chose an icon, the char* argument will point to its path | |
468 * @param data Data to pass to @callback | |
469 * @return The file dialog | |
470 */ | |
471 GtkWidget *gaim_gtk_buddy_icon_chooser_new(GtkWindow *parent, void(*callback)(const char*,gpointer), gpointer data); | |
472 | |
473 /** | |
474 * Converts a buddy icon to the required size and format | |
475 * | |
476 * @param plugin The prpl to conver the icon | |
477 * @param path The path of a buddy icon to convert | |
478 * @return The name of a new buddy icon | |
479 */ | |
480 char* gaim_gtk_convert_buddy_icon(GaimPlugin *plugin, const char *path); | |
481 | |
482 #if !GTK_CHECK_VERSION(2,6,0) | |
483 /** | |
484 * Creates a new pixbuf by loading an image from a file. The image will | |
485 * be scaled to fit in the requested size, optionally preserving the image's | |
486 * aspect ratio. | |
487 */ | |
488 GdkPixbuf *gdk_pixbuf_new_from_file_at_scale(const char *filename, int width, int height, | |
489 gboolean preserve_aspect_ratio, | |
490 GError **error); | |
491 #endif | |
492 | |
493 /** | |
494 * Set or unset a custom buddyicon for a user. | |
495 * | |
496 * @param account The account the user belongs to. | |
497 * @param who The name of the user. | |
498 * @param filename The path of the custom icon. If this is @c NULL, then any | |
499 * previously set custom buddy icon for the user is removed. | |
500 */ | |
501 void gaim_gtk_set_custom_buddy_icon(GaimAccount *account, const char *who, const char *filename); | |
502 | |
503 /** | |
504 * Converts "->" and "<-" in strings to Unicode arrow characters, for use in referencing | |
505 * menu items. | |
506 * | |
507 * @param str The text to convert | |
508 * @return A newly allocated string with unicode arrow characters | |
509 */ | |
510 char *gaim_gtk_make_pretty_arrows(const char *str); | |
511 | |
512 /** | |
513 * Creates a "mini-dialog" suitable for embedding in the buddy list scrollbook | |
514 * | |
515 * @param handle A handle | |
516 * @param primary The primary text | |
517 * @param secondary The secondary text | |
518 * @param user_data Data to pass to the callbacks | |
519 * @param ... a NULL-terminated list of button labels and callbacks | |
520 */ | |
521 void *gaim_gtk_make_mini_dialog(GaimConnection *handle, const char* stock_id, | |
522 const char *primary, const char *secondary, | |
523 void *user_data, ...); | |
524 | |
525 /** | |
526 * This is a callback function to be used for Ctrl+F searching in treeviews. | |
527 * Sample Use: | |
528 * gtk_tree_view_set_search_equal_func(treeview, | |
529 * gaim_gtk_tree_view_search_equal_func, | |
530 * search_data, search_data_destroy_cb); | |
531 * | |
532 */ | |
533 gboolean gaim_gtk_tree_view_search_equal_func(GtkTreeModel *model, gint column, | |
534 const gchar *key, GtkTreeIter *iter, gpointer data); | |
535 | |
536 /** | |
537 * Sets or resets a window to 'urgent,' by setting the URGENT hint in X | |
538 * or blinking in the win32 taskbar | |
539 * | |
540 * @param window The window to draw attention to | |
541 * @param urgent Whether to set the urgent hint or not | |
542 */ | |
543 void gaim_gtk_set_urgent(GtkWindow *window, gboolean urgent); | |
544 | |
545 #if !GTK_CHECK_VERSION(2,2,0) | |
546 /** | |
547 * This is copied from Gtk to support Gtk 2.0 | |
548 * | |
549 * Creates a new path with @first_index and @varargs as indices. | |
550 * | |
551 * @param first_index first integer | |
552 * @param varargs list of integers terminated by -1 | |
553 * | |
554 * @return A newly created GtkTreePath. | |
555 * | |
556 */ | |
557 GtkTreePath *gtk_tree_path_new_from_indices (gint first_index, ...); | |
558 #endif | |
559 | |
560 #endif /* _GAIM_GTKUTILS_H_ */ | |
561 |