Mercurial > pidgin3 / file comparison

comparison: pidgin/gtkutils.h

pidgin/gtkutils.h

branch
cpw.khc.msnp14
changeset 20478
46933dc62880
parent 20472
6a6d2ef151e6
parent 16002
cfe27ea3397b
child 20481
65485e2ed8a3
equal deleted inserted replaced
20476:198222e01a7d 20478:46933dc62880
1 /**
2 * @file gtkutils.h GTK+ utility functions
3 * @ingroup gtkui
4 *
5 * pidgin
6 *
7 * Pidgin 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 _PIDGINUTILS_H_
26 #define _PIDGINUTILS_H_
27
28 #include "gtkconv.h"
29 #include "pidgin.h"
30 #include "prpl.h"
31 #include "util.h"
32
33 typedef enum
34 {
35 PIDGIN_BUTTON_HORIZONTAL,
36 PIDGIN_BUTTON_VERTICAL
37
38 } PidginButtonOrientation;
39
40 typedef enum
41 {
42 PIDGIN_BUTTON_NONE = 0,
43 PIDGIN_BUTTON_TEXT,
44 PIDGIN_BUTTON_IMAGE,
45 PIDGIN_BUTTON_TEXT_IMAGE
46
47 } PidginButtonStyle;
48
49 typedef enum
50 {
51 PIDGIN_PRPL_ICON_SMALL,
52 PIDGIN_PRPL_ICON_MEDIUM,
53 PIDGIN_PRPL_ICON_LARGE
54 } PidginPrplIconSize;
55
56 #ifndef _WIN32
57 typedef enum
58 {
59 PIDGIN_BROWSER_DEFAULT = 0,
60 PIDGIN_BROWSER_CURRENT,
61 PIDGIN_BROWSER_NEW_WINDOW,
62 PIDGIN_BROWSER_NEW_TAB
63
64 } PidginBrowserPlace;
65 #endif /* _WIN32 */
66
67 /**
68 * Sets up a gtkimhtml widget, loads it with smileys, and sets the
69 * default signal handlers.
70 *
71 * @param imhtml The gtkimhtml widget to setup.
72 */
73 void pidgin_setup_imhtml(GtkWidget *imhtml);
74
75 /**
76 * Create an GtkIMHtml widget and associated GtkIMHtmlToolbar widget. This
77 * functions puts both widgets in a nice GtkFrame. They're separate by an
78 * attractive GtkSeparator.
79 *
80 * @param editable @c TRUE if this imhtml should be editable. If this is @c FALSE,
81 * then the toolbar will NOT be created. If this imthml should be
82 * read-only at first, but may become editable later, then pass in
83 * @c TRUE here and then manually call gtk_imhtml_set_editable() later.
84 * @param imhtml_ret A pointer to a pointer to a GtkWidget. This pointer
85 * will be set to the imhtml when this function exits.
86 * @param toolbar_ret A pointer to a pointer to a GtkWidget. If editable is
87 * TRUE then this will be set to the toolbar when this function exits.
88 * Otherwise this will be set to @c NULL.
89 * @param sw_ret This will be filled with a pointer to the scrolled window
90 * widget which contains the imhtml.
91 * @return The GtkFrame containing the toolbar and imhtml.
92 */
93 GtkWidget *pidgin_create_imhtml(gboolean editable, GtkWidget **imhtml_ret, GtkWidget **toolbar_ret, GtkWidget **sw_ret);
94
95 /**
96 * Toggles the sensitivity of a widget.
97 *
98 * @param widget @c NULL. Used for signal handlers.
99 * @param to_toggle The widget to toggle.
100 */
101 void pidgin_toggle_sensitive(GtkWidget *widget, GtkWidget *to_toggle);
102
103 /**
104 * Checks if text has been entered into a GtkTextEntry widget. If
105 * so, the GTK_RESPONSE_OK on the given dialog is set to TRUE.
106 * Otherwise GTK_RESPONSE_OK is set to FALSE.
107 *
108 * @param entry The text entry widget.
109 * @param dialog The dialog containing the text entry widget.
110 */
111 void pidgin_set_sensitive_if_input(GtkWidget *entry, GtkWidget *dialog);
112
113 /**
114 * Toggles the sensitivity of all widgets in a pointer array.
115 *
116 * @param w @c NULL. Used for signal handlers.
117 * @param data The array containing the widgets to toggle.
118 */
119 void pidgin_toggle_sensitive_array(GtkWidget *w, GPtrArray *data);
120
121 /**
122 * Toggles the visibility of a widget.
123 *
124 * @param widget @c NULL. Used for signal handlers.
125 * @param to_toggle The widget to toggle.
126 */
127 void pidgin_toggle_showhide(GtkWidget *widget, GtkWidget *to_toggle);
128
129 /**
130 * Adds a separator to a menu.
131 *
132 * @param menu The menu to add a separator to.
133 */
134 void pidgin_separator(GtkWidget *menu);
135
136 /**
137 * Creates a menu item.
138 *
139 * @param menu The menu to which to append the menu item.
140 * @param str The title to use for the newly created menu item.
141 *
142 * @return The newly created menu item.
143 */
144 GtkWidget *pidgin_new_item(GtkWidget *menu, const char *str);
145
146 /**
147 * Creates a check menu item.
148 *
149 * @param menu The menu to which to append the check menu item.
150 * @param str The title to use for the newly created menu item.
151 * @param sf A function to call when the menu item is activated.
152 * @param data Data to pass to the signal function.
153 * @param checked The initial state of the check item
154 *
155 * @return The newly created menu item.
156 */
157 GtkWidget *pidgin_new_check_item(GtkWidget *menu, const char *str,
158 GtkSignalFunc sf, gpointer data, gboolean checked);
159
160 /**
161 * Creates a menu item.
162 *
163 * @param menu The menu to which to append the menu item.
164 * @param str The title for the menu item.
165 * @param icon An icon to place to the left of the menu item,
166 * or @c NULL for no icon.
167 * @param sf A function to call when the menu item is activated.
168 * @param data Data to pass to the signal function.
169 * @param accel_key Something.
170 * @param accel_mods Something.
171 * @param mod Something.
172 *
173 * @return The newly created menu item.
174 */
175 GtkWidget *pidgin_new_item_from_stock(GtkWidget *menu, const char *str,
176 const char *icon, GtkSignalFunc sf,
177 gpointer data, guint accel_key,
178 guint accel_mods, char *mod);
179
180 /**
181 * Creates a button with the specified text and stock icon.
182 *
183 * @param text The text for the button.
184 * @param icon The stock icon name.
185 * @param style The orientation of the button.
186 *
187 * @return The button.
188 */
189 GtkWidget *pidgin_pixbuf_button_from_stock(const char *text, const char *icon,
190 PidginButtonOrientation style);
191
192 /**
193 * Creates a toolbar button with the stock icon.
194 *
195 * @param stock The stock icon name.
196 *
197 * @return The button.
198 */
199 GtkWidget *pidgin_pixbuf_toolbar_button_from_stock(const char *stock);
200
201 /**
202 * Creates a HIG preferences frame.
203 *
204 * @param parent The widget to put the frame into.
205 * @param title The title for the frame.
206 *
207 * @return The vbox to put things into.
208 */
209 GtkWidget *pidgin_make_frame(GtkWidget *parent, const char *title);
210
211 /**
212 * Creates a drop-down option menu filled with protocols.
213 *
214 * @param id The protocol to select by default.
215 * @param cb The callback to call when a protocol is selected.
216 * @param user_data Data to pass to the callback function.
217 *
218 * @return The drop-down option menu.
219 */
220 GtkWidget *pidgin_protocol_option_menu_new(const char *id,
221 GCallback cb,
222 gpointer user_data);
223
224 /**
225 * Creates a drop-down option menu filled with accounts.
226 *
227 * @param default_account The account to select by default.
228 * @param show_all Whether or not to show all accounts, or just
229 * active accounts.
230 * @param cb The callback to call when an account is selected.
231 * @param filter_func A function for checking if an account should
232 * be shown. This can be NULL.
233 * @param user_data Data to pass to the callback function.
234 *
235 * @return The drop-down option menu.
236 */
237 GtkWidget *pidgin_account_option_menu_new(PurpleAccount *default_account,
238 gboolean show_all, GCallback cb,
239 PurpleFilterAccountFunc filter_func, gpointer user_data);
240
241 /**
242 * Gets the currently selected account from an account drop down box.
243 *
244 * @param optmenu The GtkOptionMenu created by
245 * pidgin_account_option_menu_new.
246 * @return Returns the PurpleAccount that is currently selected.
247 */
248 PurpleAccount *pidgin_account_option_menu_get_selected(GtkWidget *optmenu);
249
250 /**
251 * Sets the currently selected account for an account drop down box.
252 *
253 * @param optmenu The GtkOptionMenu created by
254 * pidgin_account_option_menu_new.
255 * @param account The PurpleAccount to select.
256 */
257 void pidgin_account_option_menu_set_selected(GtkWidget *optmenu, PurpleAccount *account);
258
259 /**
260 * Add autocompletion of screenames to an entry.
261 *
262 * @param entry The GtkEntry on which to setup autocomplete.
263 * @param optmenu A menu for accounts, returned by pidgin_account_option_menu_new().
264 * If @a optmenu is not @c NULL, it'll be updated when a screenname is chosen
265 * from the autocomplete list.
266 * @param all Whether to include screennames from disconnected accounts.
267 */
268 void pidgin_setup_screenname_autocomplete(GtkWidget *entry, GtkWidget *optmenu, gboolean all);
269
270 /**
271 * Check if the given path is a directory or not. If it is, then modify
272 * the given GtkFileSelection dialog so that it displays the given path.
273 * If the given path is not a directory, then do nothing.
274 *
275 * @param path The path entered in the file selection window by the user.
276 * @param filesel The file selection window.
277 *
278 * @return TRUE if given path is a directory, FALSE otherwise.
279 */
280 gboolean pidgin_check_if_dir(const char *path, GtkFileSelection *filesel);
281
282 /**
283 * Sets up GtkSpell for the given GtkTextView, reporting errors
284 * if encountered.
285 *
286 * This does nothing if Pidgin is not compiled with GtkSpell support.
287 *
288 * @param textview The textview widget to setup spellchecking for.
289 */
290 void pidgin_setup_gtkspell(GtkTextView *textview);
291
292 /**
293 * Save menu accelerators callback
294 */
295 void pidgin_save_accels_cb(GtkAccelGroup *accel_group, guint arg1,
296 GdkModifierType arg2, GClosure *arg3,
297 gpointer data);
298
299 /**
300 * Save menu accelerators
301 */
302 gboolean pidgin_save_accels(gpointer data);
303
304 /**
305 * Load menu accelerators
306 */
307 void pidgin_load_accels(void);
308
309 /**
310 * Parses an application/x-im-contact MIME message and returns the
311 * data inside.
312 *
313 * @param msg The MIME message.
314 * @param all_accounts If TRUE, check all compatible accounts, online or
315 * offline. If FALSE, check only online accounts.
316 * @param ret_account The best guess at a compatible protocol,
317 * based on ret_protocol. If NULL, no account was found.
318 * @param ret_protocol The returned protocol type.
319 * @param ret_username The returned username.
320 * @param ret_alias The returned alias.
321 *
322 * @return TRUE if the message was parsed for the minimum necessary data.
323 * FALSE otherwise.
324 */
325 gboolean pidgin_parse_x_im_contact(const char *msg, gboolean all_accounts,
326 PurpleAccount **ret_account,
327 char **ret_protocol, char **ret_username,
328 char **ret_alias);
329
330 /**
331 * Sets an ATK name for a given widget. Also sets the labelled-by
332 * and label-for ATK relationships.
333 *
334 * @param w The widget that we want to name.
335 * @param l A GtkLabel that we want to use as the ATK name for the widget.
336 */
337 void pidgin_set_accessible_label(GtkWidget *w, GtkWidget *l);
338
339 /**
340 * A valid GtkMenuPositionFunc. This is used to determine where
341 * to draw context menu's when the menu is activated with the
342 * keyboard (shift+F10). If the menu is activated with the mouse,
343 * then you should just use GTK's built-in position function,
344 * because it does a better job of positioning the menu.
345 *
346 * @param menu The menu we are positioning.
347 * @param x Address of the gint representing the horizontal position
348 * where the menu shall be drawn. This is an output parameter.
349 * @param y Address of the gint representing the vertical position
350 * where the menu shall be drawn. This is an output parameter.
351 * @param push_in This is an output parameter?
352 * @param user_data Not used by this particular position function.
353 */
354 void pidgin_treeview_popup_menu_position_func(GtkMenu *menu,
355 gint *x,
356 gint *y,
357 gboolean *push_in,
358 gpointer user_data);
359
360 /**
361 * Manages drag'n'drop of files.
362 *
363 * @param sd GtkSelectionData for managing drag'n'drop
364 * @param account Account to be used (may be NULL if conv is not NULL)
365 * @param who Buddy name (may be NULL if conv is not NULL)
366 */
367 void pidgin_dnd_file_manage(GtkSelectionData *sd, PurpleAccount *account, const char *who);
368
369 /**
370 * Convenience wrapper for purple_buddy_icon_get_scale_size
371 */
372 void pidgin_buddy_icon_get_scale_size(GdkPixbuf *buf, PurpleBuddyIconSpec *spec, PurpleIconScaleRules rules, int *width, int *height);
373
374 /**
375 * Returns the base image to represent the account, based on
376 * the currently selected theme.
377 *
378 * @param account The account.
379 * @param size The size of the icon to return.
380 *
381 * @return A newly-created pixbuf with a reference count of 1,
382 * or NULL if any of several error conditions occurred:
383 * the file could not be opened, there was no loader
384 * for the file's format, there was not enough memory
385 * to allocate the image buffer, or the image file
386 * contained invalid data.
387 */
388 GdkPixbuf *pidgin_create_prpl_icon(PurpleAccount *account, PidginPrplIconSize size);
389
390 /**
391 * Creates a status icon for a given primitve
392 *
393 * @param primitive The status primitive
394 * @param w The widget to render this
395 * @param size The icon size to render at
396 * @return A GdkPixbuf, created from stock
397 */
398 GdkPixbuf * pidgin_create_status_icon(PurpleStatusPrimitive primitive, GtkWidget *w, const char *size);
399
400
401 /**
402 * Append a PurpleMenuAction to a menu.
403 *
404 * @param menu The menu to append to.
405 * @param act The PurpleMenuAction to append.
406 * @param gobject The object to be passed to the action callback.
407 */
408 void pidgin_append_menu_action(GtkWidget *menu, PurpleMenuAction *act,
409 gpointer gobject);
410
411 /**
412 * Sets the mouse pointer for a GtkWidget.
413 *
414 * After setting the cursor, the display is flushed, so the change will
415 * take effect immediately.
416 *
417 * If the window for @a widget is @c NULL, this function simply returns.
418 *
419 * @param widget The widget for which to set the mouse pointer
420 * @param cursor_type The type of cursor to set
421 */
422 void pidgin_set_cursor(GtkWidget *widget, GdkCursorType cursor_type);
423
424 /**
425 * Sets the mouse point for a GtkWidget back to that of its parent window.
426 *
427 * If @a widget is @c NULL, this function simply returns.
428 *
429 * If the window for @a widget is @c NULL, this function simply returns.
430 *
431 * @note The display is not flushed from this function.
432 */
433 void pidgin_clear_cursor(GtkWidget *widget);
434
435 /**
436 * Creates a File Selection widget for choosing a buddy icon
437 *
438 * @param parent The parent window
439 * @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
440 * @param data Data to pass to @callback
441 * @return The file dialog
442 */
443 GtkWidget *pidgin_buddy_icon_chooser_new(GtkWindow *parent, void(*callback)(const char*,gpointer), gpointer data);
444
445 /**
446 * Converts a buddy icon to the required size and format
447 *
448 * @param plugin The prpl to conver the icon
449 * @param path The path of a buddy icon to convert
450 * @return The name of a new buddy icon
451 */
452 char* pidgin_convert_buddy_icon(PurplePlugin *plugin, const char *path);
453
454 #if !GTK_CHECK_VERSION(2,6,0)
455 /**
456 * Creates a new pixbuf by loading an image from a file. The image will
457 * be scaled to fit in the requested size, optionally preserving the image's
458 * aspect ratio.
459 */
460 GdkPixbuf *gdk_pixbuf_new_from_file_at_scale(const char *filename, int width, int height,
461 gboolean preserve_aspect_ratio,
462 GError **error);
463 #endif
464
465 /**
466 * Set or unset a custom buddyicon for a user.
467 *
468 * @param account The account the user belongs to.
469 * @param who The name of the user.
470 * @param filename The path of the custom icon. If this is @c NULL, then any
471 * previously set custom buddy icon for the user is removed.
472 */
473 void pidgin_set_custom_buddy_icon(PurpleAccount *account, const char *who, const char *filename);
474
475 /**
476 * Converts "->" and "<-" in strings to Unicode arrow characters, for use in referencing
477 * menu items.
478 *
479 * @param str The text to convert
480 * @return A newly allocated string with unicode arrow characters
481 */
482 char *pidgin_make_pretty_arrows(const char *str);
483
484 /**
485 * Creates a "mini-dialog" suitable for embedding in the buddy list scrollbook
486 *
487 * @param handle A handle
488 * @param primary The primary text
489 * @param secondary The secondary text
490 * @param user_data Data to pass to the callbacks
491 * @param ... a NULL-terminated list of button labels and callbacks
492 */
493 void *pidgin_make_mini_dialog(PurpleConnection *handle, const char* stock_id,
494 const char *primary, const char *secondary,
495 void *user_data, ...);
496
497 /**
498 * This is a callback function to be used for Ctrl+F searching in treeviews.
499 * Sample Use:
500 * gtk_tree_view_set_search_equal_func(treeview,
501 * pidgin_tree_view_search_equal_func,
502 * search_data, search_data_destroy_cb);
503 *
504 */
505 gboolean pidgin_tree_view_search_equal_func(GtkTreeModel *model, gint column,
506 const gchar *key, GtkTreeIter *iter, gpointer data);
507
508 /**
509 * Sets or resets a window to 'urgent,' by setting the URGENT hint in X
510 * or blinking in the win32 taskbar
511 *
512 * @param window The window to draw attention to
513 * @param urgent Whether to set the urgent hint or not
514 */
515 void pidgin_set_urgent(GtkWindow *window, gboolean urgent);
516
517 /**
518 * Returns TRUE if the GdkPixbuf is opaque, as determined by no
519 * alpha at any of the edge pixels.
520 *
521 * @param pixbuf The pixbug
522 * @return TRUE if the pixbuf is opaque around the edges, FALSE otherwise
523 */
524 gboolean pidgin_gdk_pixbuf_is_opaque(GdkPixbuf *pixbuf);
525
526 #if !GTK_CHECK_VERSION(2,2,0)
527 /**
528 * This is copied from Gtk to support Gtk 2.0
529 *
530 * Creates a new path with @first_index and @varargs as indices.
531 *
532 * @param first_index first integer
533 * @param varargs list of integers terminated by -1
534 *
535 * @return A newly created GtkTreePath.
536 *
537 */
538 GtkTreePath *gtk_tree_path_new_from_indices (gint first_index, ...);
539 #endif
540
541 #endif /* _PIDGINUTILS_H_ */
542

Mercurial Repository: pidgin3

mercurial