Mercurial > pidgin3 / file comparison

comparison: gtk/gtkutils.h

gtk/gtkutils.h

changeset 14253
b63ebf84c42b
parent 14195
0f7cb3b272b2
child 14290
f20819ff8d86
equal deleted inserted replaced
14252:d10dda2777a9 14253:b63ebf84c42b
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, 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 path of a new buddy icon
479 */
480 char* gaim_gtk_convert_buddy_icon(GaimPlugin *plugin, const char *path);
481
482 #endif /* _GAIM_GTKUTILS_H_ */

Mercurial Repository: pidgin3

mercurial