pidgin: gtkutils.h File Reference

pidgin 2.14.4

Loading...
Searching...
No Matches
Data Structures | Typedefs | Enumerations | Functions
gtkutils.h File Reference
Pidgin (GTK+ User Interface)

GTK+ utility functions. More...

`#include "gtkconv.h"`
`#include "pidgin.h"`
`#include "prpl.h"`
`#include "util.h"`

Go to the source code of this file.

## Data Structures
struct | PidginBuddyCompletionEntry

## Typedefs
typedef gboolean(* | PidginFilterBuddyCompletionEntryFunc) (const PidginBuddyCompletionEntry *completion_entry, gpointer user_data)
typedef void(* | PidginUtilMiniDialogCallback) (gpointer user_data, GtkButton *)
| The type of callbacks passed to pidgin_make_mini_dialog().

## Enumerations
enum | PidginButtonOrientation { PIDGIN_BUTTON_HORIZONTAL , PIDGIN_BUTTON_VERTICAL }
enum | PidginButtonStyle { PIDGIN_BUTTON_NONE = 0 , PIDGIN_BUTTON_TEXT , PIDGIN_BUTTON_IMAGE , PIDGIN_BUTTON_TEXT_IMAGE }
enum | PidginPrplIconSize { PIDGIN_PRPL_ICON_SMALL , PIDGIN_PRPL_ICON_MEDIUM , PIDGIN_PRPL_ICON_LARGE }
enum | PidginBrowserPlace { PIDGIN_BROWSER_DEFAULT = 0 , PIDGIN_BROWSER_CURRENT , PIDGIN_BROWSER_NEW_WINDOW , PIDGIN_BROWSER_NEW_TAB }

## Functions
void | pidgin_setup_imhtml (GtkWidget *imhtml)
| Sets up a gtkimhtml widget, loads it with smileys, and sets the default signal handlers.
GtkWidget * | pidgin_create_imhtml (gboolean editable, GtkWidget **imhtml_ret, GtkWidget **toolbar_ret, GtkWidget **sw_ret)
| Create an GtkIMHtml widget and associated GtkIMHtmlToolbar widget.
GtkWidget * | pidgin_create_small_button (GtkWidget *image)
| Creates a small button.
GtkWidget * | pidgin_create_window (const char *title, guint border_width, const char *role, gboolean resizable)
| Creates a new window.
GtkWidget * | pidgin_create_dialog (const char *title, guint border_width, const char *role, gboolean resizable)
| Creates a new dialog window.
GtkWidget * | pidgin_dialog_get_vbox_with_properties (GtkDialog *dialog, gboolean homogeneous, gint spacing)
| Retrieves the main content box (vbox) from a pidgin dialog window.
GtkWidget * | pidgin_dialog_get_vbox (GtkDialog *dialog)
| Retrieves the main content box (vbox) from a pidgin dialog window.
GtkWidget * | pidgin_dialog_add_button (GtkDialog *dialog, const char *label, GCallback callback, gpointer callbackdata)
| Add a button to a dialog created by pidgin_create_dialog.
GtkWidget * | pidgin_dialog_get_action_area (GtkDialog *dialog)
| Retrieves the action area (button box) from a pidgin dialog window.
void | pidgin_toggle_sensitive (GtkWidget *widget, GtkWidget *to_toggle)
| Toggles the sensitivity of a widget.
void | pidgin_set_sensitive_if_input (GtkWidget *entry, GtkWidget *dialog)
| Checks if text has been entered into a GtkTextEntry widget.
void | pidgin_toggle_sensitive_array (GtkWidget *w, GPtrArray *data)
| Toggles the sensitivity of all widgets in a pointer array.
void | pidgin_toggle_showhide (GtkWidget *widget, GtkWidget *to_toggle)
| Toggles the visibility of a widget.
GtkWidget * | pidgin_separator (GtkWidget *menu)
| Adds a separator to a menu.
GtkWidget * | pidgin_new_item (GtkWidget *menu, const char *str)
| Creates a menu item.
GtkWidget * | pidgin_new_check_item (GtkWidget *menu, const char *str, GCallback cb, gpointer data, gboolean checked)
| Creates a check menu item.
GtkWidget * | pidgin_new_item_from_stock (GtkWidget *menu, const char *str, const char *icon, GCallback cb, gpointer data, guint accel_key, guint accel_mods, char *mod)
| Creates a menu item.
GtkWidget * | pidgin_pixbuf_button_from_stock (const char *text, const char *icon, PidginButtonOrientation style)
| Creates a button with the specified text and stock icon.
GtkWidget * | pidgin_pixbuf_toolbar_button_from_stock (const char *stock)
| Creates a toolbar button with the stock icon.
GtkWidget * | pidgin_make_frame (GtkWidget *parent, const char *title)
| Creates a HIG preferences frame.
GtkWidget * | pidgin_protocol_option_menu_new (const char *id, GCallback cb, gpointer user_data)
| Creates a drop-down option menu filled with protocols.
const char * | pidgin_protocol_option_menu_get_selected (GtkWidget *optmenu)
| Gets the currently selected protocol from a protocol drop down box.
GtkWidget * | pidgin_account_option_menu_new (PurpleAccount *default_account, gboolean show_all, GCallback cb, PurpleFilterAccountFunc filter_func, gpointer user_data)
| Creates a drop-down option menu filled with accounts.
PurpleAccount * | pidgin_account_option_menu_get_selected (GtkWidget *optmenu)
| Gets the currently selected account from an account drop down box.
void | pidgin_account_option_menu_set_selected (GtkWidget *optmenu, PurpleAccount *account)
| Sets the currently selected account for an account drop down box.
void | pidgin_setup_screenname_autocomplete_with_filter (GtkWidget *entry, GtkWidget *optmenu, PidginFilterBuddyCompletionEntryFunc filter_func, gpointer user_data)
| Add autocompletion of screenames to an entry, supporting a filtering function.
gboolean | pidgin_screenname_autocomplete_default_filter (const PidginBuddyCompletionEntry *completion_entry, gpointer all_accounts)
| The default filter function for username autocomplete.
void | pidgin_setup_screenname_autocomplete (GtkWidget *entry, GtkWidget *optmenu, gboolean all)
| Add autocompletion of screenames to an entry.
gboolean | pidgin_check_if_dir (const char *path, GtkFileSelection *filesel)
| Check if the given path is a directory or not.
void | pidgin_setup_gtkspell (GtkTextView *textview)
| Sets up GtkSpell for the given GtkTextView, reporting errors if encountered.
void | pidgin_save_accels_cb (GtkAccelGroup *accel_group, guint arg1, GdkModifierType arg2, GClosure *arg3, gpointer data)
| Save menu accelerators callback.
gboolean | pidgin_save_accels (gpointer data)
| Save menu accelerators.
void | pidgin_load_accels (void)
| Load menu accelerators.
void | pidgin_retrieve_user_info (PurpleConnection *conn, const char *name)
| Get information about a user.
void | pidgin_retrieve_user_info_in_chat (PurpleConnection *conn, const char *name, int chatid)
| Get information about a user in a chat.
gboolean | pidgin_parse_x_im_contact (const char *msg, gboolean all_accounts, PurpleAccount **ret_account, char **ret_protocol, char **ret_username, char **ret_alias)
| Parses an application/x-im-contact MIME message and returns the data inside.
void | pidgin_set_accessible_label (GtkWidget *w, GtkWidget *l)
| Sets an ATK name for a given widget.
void | pidgin_set_accessible_relations (GtkWidget *w, GtkWidget *l)
| Sets the labelled-by and label-for ATK relationships.
void | pidgin_menu_position_func_helper (GtkMenu *menu, gint *x, gint *y, gboolean *push_in, gpointer data)
| A helper function for GtkMenuPositionFuncs.
void | pidgin_treeview_popup_menu_position_func (GtkMenu *menu, gint *x, gint *y, gboolean *push_in, gpointer user_data)
| A valid GtkMenuPositionFunc.
void | pidgin_dnd_file_manage (GtkSelectionData *sd, PurpleAccount *account, const char *who)
| Manages drag'n'drop of files.
void | pidgin_buddy_icon_get_scale_size (GdkPixbuf *buf, PurpleBuddyIconSpec *spec, PurpleIconScaleRules rules, int *width, int *height)
| Convenience wrapper for purple_buddy_icon_get_scale_size.
GdkPixbuf * | pidgin_create_prpl_icon (PurpleAccount *account, PidginPrplIconSize size)
| Returns the base image to represent the account, based on the currently selected theme.
GdkPixbuf * | pidgin_create_status_icon (PurpleStatusPrimitive primitive, GtkWidget *w, const char *size)
| Creates a status icon for a given primitve.
const char * | pidgin_stock_id_from_status_primitive (PurpleStatusPrimitive prim)
| Returns an appropriate stock-id for a status primitive.
const char * | pidgin_stock_id_from_presence (PurplePresence *presence)
| Returns an appropriate stock-id for a PurplePresence.
GtkWidget * | pidgin_append_menu_action (GtkWidget *menu, PurpleMenuAction *act, gpointer gobject)
| Append a PurpleMenuAction to a menu.
void | pidgin_set_cursor (GtkWidget *widget, GdkCursorType cursor_type)
| Sets the mouse pointer for a GtkWidget.
void | pidgin_clear_cursor (GtkWidget *widget)
| Sets the mouse point for a GtkWidget back to that of its parent window.
GtkWidget * | pidgin_buddy_icon_chooser_new (GtkWindow *parent, void(*callback)(const char *, gpointer), gpointer data)
| Creates a File Selection widget for choosing a buddy icon.
gpointer | pidgin_convert_buddy_icon (PurplePlugin *plugin, const char *path, size_t *len)
| Converts a buddy icon to the required size and format.
void | pidgin_set_custom_buddy_icon (PurpleAccount *account, const char *who, const char *filename)
| Set or unset a custom buddyicon for a user.
char * | pidgin_make_pretty_arrows (const char *str)
| Converts "->" and "<-" in strings to Unicode arrow characters, for use in referencing menu items.
GtkWidget * | pidgin_make_mini_dialog (PurpleConnection *handle, const char *stock_id, const char *primary, const char *secondary, void *user_data,...) G_GNUC_NULL_TERMINATED
| Creates a PidginMiniDialog, tied to a PurpleConnection, suitable for embedding in the buddy list scrollbook with pidgin_blist_add_alert().
GtkWidget * | pidgin_make_mini_dialog_with_custom_icon (PurpleConnection *gc, GdkPixbuf *custom_icon, const char *primary, const char *secondary, void *user_data,...) G_GNUC_NULL_TERMINATED
| Does exactly what pidgin_make_mini_dialog() does, except you can specify a custom icon for the dialog.
gboolean | pidgin_tree_view_search_equal_func (GtkTreeModel *model, gint column, const gchar *key, GtkTreeIter *iter, gpointer data)
| This is a callback function to be used for Ctrl+F searching in treeviews.
void | pidgin_set_urgent (GtkWindow *window, gboolean urgent)
| Sets or resets a window to 'urgent,' by setting the URGENT hint in X or blinking in the win32 taskbar.
gboolean | pidgin_gdk_pixbuf_is_opaque (GdkPixbuf *pixbuf)
| Returns TRUE if the GdkPixbuf is opaque, as determined by no alpha at any of the edge pixels.
void | pidgin_gdk_pixbuf_make_round (GdkPixbuf *pixbuf)
| Rounds the corners of a 32x32 GdkPixbuf in place.
const char * | pidgin_get_dim_grey_string (GtkWidget *widget)
| Returns an HTML-style color string for use as a dim grey string.
GtkWidget * | pidgin_text_combo_box_entry_new (const char *default_item, GList *items)
| Create a simple text GtkComboBoxEntry equivalent.
const char * | pidgin_text_combo_box_entry_get_text (GtkWidget *widget)
| Retrieve the text from the entry of the simple text GtkComboBoxEntry equivalent.
void | pidgin_text_combo_box_entry_set_text (GtkWidget *widget, const char *text)
| Set the text in the entry of the simple text GtkComboBoxEntry equivalent.
gboolean | pidgin_auto_parent_window (GtkWidget *window)
| Automatically make a window transient to a suitable parent window.
GtkWidget * | pidgin_add_widget_to_vbox (GtkBox *vbox, const char *widget_label, GtkSizeGroup *sg, GtkWidget *widget, gboolean expand, GtkWidget **p_label)
| Add a labelled widget to a GtkVBox.
GdkPixbuf * | pidgin_pixbuf_from_data (const guchar *buf, gsize count)
| Create a GdkPixbuf from a chunk of image data.
GdkPixbufAnimation * | pidgin_pixbuf_anim_from_data (const guchar *buf, gsize count)
| Create a GdkPixbufAnimation from a chunk of image data.
GdkPixbuf * | pidgin_pixbuf_from_imgstore (PurpleStoredImage *image)
| Create a GdkPixbuf from a PurpleStoredImage.
GdkPixbuf * | pidgin_pixbuf_new_from_file (const char *filename)
| Helper function that calls gdk_pixbuf_new_from_file() and checks both the return code and the GError and returns NULL if either one failed.
GdkPixbuf * | pidgin_pixbuf_new_from_file_at_size (const char *filename, int width, int height)
| Helper function that calls gdk_pixbuf_new_from_file_at_size() and checks both the return code and the GError and returns NULL if either one failed.
GdkPixbuf * | pidgin_pixbuf_new_from_file_at_scale (const char *filename, int width, int height, gboolean preserve_aspect_ratio)
| Helper function that calls gdk_pixbuf_new_from_file_at_scale() and checks both the return code and the GError and returns NULL if either one failed.
GtkWidget * | pidgin_make_scrollable (GtkWidget *child, GtkPolicyType hscrollbar_policy, GtkPolicyType vscrollbar_policy, GtkShadowType shadow_type, int width, int height)
| Add scrollbars to a widget.
void | pidgin_utils_init (void)
| Initialize some utility functions.
void | pidgin_utils_uninit (void)
| Uninitialize some utility functions.

## Detailed Description

GTK+ utility functions.

Definition in file gtkutils.h.

## Typedef Documentation

## ◆ PidginFilterBuddyCompletionEntryFunc

typedef gboolean(* PidginFilterBuddyCompletionEntryFunc) (const PidginBuddyCompletionEntry *completion_entry, gpointer user_data)

Definition at line 80 of file gtkutils.h.

## ◆ PidginUtilMiniDialogCallback

typedef void(* PidginUtilMiniDialogCallback) (gpointer user_data, GtkButton *)

The type of callbacks passed to pidgin_make_mini_dialog().

Definition at line 689 of file gtkutils.h.

## Enumeration Type Documentation

## ◆ PidginBrowserPlace

enum PidginBrowserPlace

Definition at line 62 of file gtkutils.h.

## ◆ PidginButtonOrientation

enum PidginButtonOrientation

Definition at line 38 of file gtkutils.h.

## ◆ PidginButtonStyle

enum PidginButtonStyle

Definition at line 45 of file gtkutils.h.

## ◆ PidginPrplIconSize

enum PidginPrplIconSize

Definition at line 54 of file gtkutils.h.

## Function Documentation

## ◆ pidgin_account_option_menu_get_selected()

PurpleAccount * pidgin_account_option_menu_get_selected | ( | GtkWidget * | optmenu | ) |

Gets the currently selected account from an account drop down box.

Parameters

  optmenu | The drop-down option menu created by pidgin_account_option_menu_new.

Returns
  Returns the PurpleAccount that is currently selected.

## ◆ pidgin_account_option_menu_new()

GtkWidget * pidgin_account_option_menu_new | ( | PurpleAccount * | default_account,
|  | gboolean | show_all,
|  | GCallback | cb,
|  | PurpleFilterAccountFunc | filter_func,
|  | gpointer | user_data
| ) |  |

Creates a drop-down option menu filled with accounts.

Parameters

  default_account | The account to select by default.
  show_all | Whether or not to show all accounts, or just active accounts.
  cb | The callback to call when an account is selected.
  filter_func | A function for checking if an account should be shown. This can be NULL.
  user_data | Data to pass to the callback function.

Returns
  The drop-down option menu.

## ◆ pidgin_account_option_menu_set_selected()

void pidgin_account_option_menu_set_selected | ( | GtkWidget * | optmenu,
|  | PurpleAccount * | account
| ) |  |

Sets the currently selected account for an account drop down box.

Parameters

  optmenu | The GtkOptionMenu created by pidgin_account_option_menu_new.
  account | The PurpleAccount to select.

## ◆ pidgin_add_widget_to_vbox()

GtkWidget * pidgin_add_widget_to_vbox | ( | GtkBox * | vbox,
|  | const char * | widget_label,
|  | GtkSizeGroup * | sg,
|  | GtkWidget * | widget,
|  | gboolean | expand,
|  | GtkWidget ** | p_label
| ) |  |

Add a labelled widget to a GtkVBox.

Parameters

  vbox | The GtkVBox to add the widget to.
  widget_label | The label to give the widget, can be `NULL`.
  sg | The GtkSizeGroup to add the label to, can be `NULL`.
  widget | The GtkWidget to add.
  expand | Whether to expand the widget horizontally.
  p_label | Place to store a pointer to the GtkLabel, or `NULL` if you don't care.

Returns
  A GtkHBox already added to the GtkVBox containing the GtkLabel and the GtkWidget.

Since
  2.4.0

## ◆ pidgin_append_menu_action()

GtkWidget * pidgin_append_menu_action | ( | GtkWidget * | menu,
|  | PurpleMenuAction * | act,
|  | gpointer | gobject
| ) |  |

Append a PurpleMenuAction to a menu.

Parameters

  menu | The menu to append to.
  act | The PurpleMenuAction to append.
  gobject | The object to be passed to the action callback.

Returns
  The menuitem added.

## ◆ pidgin_auto_parent_window()

gboolean pidgin_auto_parent_window | ( | GtkWidget * | window | ) |

Automatically make a window transient to a suitable parent window.

Parameters

  window | The window to make transient.

Returns
  Whether the window was made transient or not.

Since
  2.4.0

## ◆ pidgin_buddy_icon_chooser_new()

GtkWidget * pidgin_buddy_icon_chooser_new | ( | GtkWindow * | parent,
|  | void(*)(const char *, gpointer) | callback,
|  | gpointer | data
| ) |  |

Creates a File Selection widget for choosing a buddy icon.

Parameters

  parent | The parent window
  callback | The callback to call when the window is closed. If the user chose an icon, the char* argument will point to its path
  data | Data to pass to callback

Returns
  The file dialog

## ◆ pidgin_check_if_dir()

gboolean pidgin_check_if_dir | ( | const char * | path,
|  | GtkFileSelection * | filesel
| ) |  |

Check if the given path is a directory or not.

If it is, then modify the given GtkFileSelection dialog so that it displays the given path. If the given path is not a directory, then do nothing.

Parameters

  path | The path entered in the file selection window by the user.
  filesel | The file selection window.

Returns
  TRUE if given path is a directory, FALSE otherwise.

Deprecated:
  Pidgin no longer uses GtkFileSelection internally. It has also been deprecated by GTK+. Use GtkFileChooser instead and ignore this function.

## ◆ pidgin_clear_cursor()

void pidgin_clear_cursor | ( | GtkWidget * | widget | ) |

Sets the mouse point for a GtkWidget back to that of its parent window.

If widget is `NULL`, this function simply returns.

If the window for widget is `NULL`, this function simply returns.

Note
  The display is not flushed from this function.

## ◆ pidgin_convert_buddy_icon()

gpointer pidgin_convert_buddy_icon | ( | PurplePlugin * | plugin,
|  | const char * | path,
|  | size_t * | len
| ) |  |

Converts a buddy icon to the required size and format.

Parameters

  plugin | The prpl to convert the icon
  path | The path of a file to convert
  len | If not `NULL`, the length of the returned data will be set here.

Returns
  The converted image data, or `NULL` if an error occurred.

## ◆ pidgin_create_dialog()

GtkWidget * pidgin_create_dialog | ( | const char * | title,
|  | guint | border_width,
|  | const char * | role,
|  | gboolean | resizable
| ) |  |

Creates a new dialog window.

Parameters

  title | The window title, or `NULL`
  border_width | The window's desired border width
  role | A string indicating what the window is responsible for doing, or `NULL`
  resizable | Whether the window should be resizable (`TRUE`) or not (`FALSE`)

Since
  2.4.0

## ◆ pidgin_create_imhtml()

GtkWidget * pidgin_create_imhtml | ( | gboolean | editable,
|  | GtkWidget ** | imhtml_ret,
|  | GtkWidget ** | toolbar_ret,
|  | GtkWidget ** | sw_ret
| ) |  |

Create an GtkIMHtml widget and associated GtkIMHtmlToolbar widget.

This functions puts both widgets in a nice GtkFrame. They're separate by an attractive GtkSeparator.

Parameters

  editable | `TRUE` if this imhtml should be editable. If this is `FALSE`, then the toolbar will NOT be created. If this imthml should be read-only at first, but may become editable later, then pass in `TRUE` here and then manually call gtk_imhtml_set_editable() later.
  imhtml_ret | A pointer to a pointer to a GtkWidget. This pointer will be set to the imhtml when this function exits.
  toolbar_ret | A pointer to a pointer to a GtkWidget. If editable is TRUE then this will be set to the toolbar when this function exits. Otherwise this will be set to `NULL`.
  sw_ret | This will be filled with a pointer to the scrolled window widget which contains the imhtml.

Returns
  The GtkFrame containing the toolbar and imhtml.

## ◆ pidgin_create_prpl_icon()

GdkPixbuf * pidgin_create_prpl_icon | ( | PurpleAccount * | account,
|  | PidginPrplIconSize | size
| ) |  |

Returns the base image to represent the account, based on the currently selected theme.

Parameters

  account | The account.
  size | The size of the icon to return.

Returns
  A newly-created pixbuf with a reference count of 1, or NULL if any of several error conditions occurred: the file could not be opened, there was no loader for the file's format, there was not enough memory to allocate the image buffer, or the image file contained invalid data.

## ◆ pidgin_create_small_button()

GtkWidget * pidgin_create_small_button | ( | GtkWidget * | image | ) |

Creates a small button.

Parameters

  image | A button image.

Returns
  A GtkButton created from the image.

Since
  2.7.0

## ◆ pidgin_create_status_icon()

GdkPixbuf * pidgin_create_status_icon | ( | PurpleStatusPrimitive | primitive,
|  | GtkWidget * | w,
|  | const char * | size
| ) |  |

Creates a status icon for a given primitve.

Parameters

  primitive | The status primitive
  w | The widget to render this
  size | The icon size to render at

Returns
  A GdkPixbuf, created from stock

## ◆ pidgin_create_window()

GtkWidget * pidgin_create_window | ( | const char * | title,
|  | guint | border_width,
|  | const char * | role,
|  | gboolean | resizable
| ) |  |

Creates a new window.

Parameters

  title | The window title, or `NULL`
  border_width | The window's desired border width
  role | A string indicating what the window is responsible for doing, or `NULL`
  resizable | Whether the window should be resizable (`TRUE`) or not (`FALSE`)

Since
  2.1.0

## ◆ pidgin_dialog_add_button()

GtkWidget * pidgin_dialog_add_button | ( | GtkDialog * | dialog,
|  | const char * | label,
|  | GCallback | callback,
|  | gpointer | callbackdata
| ) |  |

Add a button to a dialog created by pidgin_create_dialog.

Parameters

  dialog | The dialog window
  label | The stock-id or the label for the button
  callback | The callback function for the button
  callbackdata | The user data for the callback function

Returns
  The created button.

Since
  2.4.0

## ◆ pidgin_dialog_get_action_area()

GtkWidget * pidgin_dialog_get_action_area | ( | GtkDialog * | dialog | ) |

Retrieves the action area (button box) from a pidgin dialog window.

Parameters

  dialog | The dialog window

Since
  2.4.0

## ◆ pidgin_dialog_get_vbox()

GtkWidget * pidgin_dialog_get_vbox | ( | GtkDialog * | dialog | ) |

Retrieves the main content box (vbox) from a pidgin dialog window.

Parameters

  dialog | The dialog window

Since
  2.4.0

## ◆ pidgin_dialog_get_vbox_with_properties()

GtkWidget * pidgin_dialog_get_vbox_with_properties | ( | GtkDialog * | dialog,
|  | gboolean | homogeneous,
|  | gint | spacing
| ) |  |

Retrieves the main content box (vbox) from a pidgin dialog window.

Parameters

  dialog | The dialog window
  homogeneous | TRUE if all children are to be given equal space allotments.
  spacing | the number of pixels to place by default between children

Since
  2.4.0

## ◆ pidgin_dnd_file_manage()

void pidgin_dnd_file_manage | ( | GtkSelectionData * | sd,
|  | PurpleAccount * | account,
|  | const char * | who
| ) |  |

Manages drag'n'drop of files.

Parameters

  sd | GtkSelectionData for managing drag'n'drop
  account | Account to be used (may be NULL if conv is not NULL)
  who | Buddy name (may be NULL if conv is not NULL)

## ◆ pidgin_gdk_pixbuf_is_opaque()

gboolean pidgin_gdk_pixbuf_is_opaque | ( | GdkPixbuf * | pixbuf | ) |

Returns TRUE if the GdkPixbuf is opaque, as determined by no alpha at any of the edge pixels.

Parameters

  pixbuf | The pixbug

Returns
  TRUE if the pixbuf is opaque around the edges, FALSE otherwise

## ◆ pidgin_gdk_pixbuf_make_round()

void pidgin_gdk_pixbuf_make_round | ( | GdkPixbuf * | pixbuf | ) |

Rounds the corners of a 32x32 GdkPixbuf in place.

Parameters

  pixbuf | The buddy icon to transform

## ◆ pidgin_get_dim_grey_string()

const char * pidgin_get_dim_grey_string | ( | GtkWidget * | widget | ) |

Returns an HTML-style color string for use as a dim grey string.

Parameters

  widget | The widget to return dim grey for

Returns
  The dim grey string

## ◆ pidgin_make_frame()

GtkWidget * pidgin_make_frame | ( | GtkWidget * | parent,
|  | const char * | title
| ) |  |

Creates a HIG preferences frame.

Parameters

  parent | The widget to put the frame into.
  title | The title for the frame.

Returns
  The vbox to put things into.

## ◆ pidgin_make_mini_dialog()

GtkWidget * pidgin_make_mini_dialog | ( | PurpleConnection * | handle,
|  | const char * | stock_id,
|  | const char * | primary,
|  | const char * | secondary,
|  | void * | user_data,
|  |  | ...
| ) |  |

Creates a PidginMiniDialog, tied to a PurpleConnection, suitable for embedding in the buddy list scrollbook with pidgin_blist_add_alert().

Parameters

  handle | The PurpleConnection to which this mini-dialog refers, or `NULL` if it does not refer to a connection. If handle is supplied, the mini-dialog will be automatically removed and destroyed when the connection signs off.
  stock_id | The ID of a stock image to use in the mini dialog.
  primary | The primary text
  secondary | The secondary text, or `NULL` for no description.
  user_data | Data to pass to the callbacks
  ... | a `NULL`-terminated list of button labels (`char *`) and callbacks (PidginUtilMiniDialogCallback). user_data will be passed as the first argument. (Callbacks may lack a second argument, or be `NULL` to take no action when the corresponding button is pressed.) When a button is pressed, the callback (if any) will be called; when the callback returns the dialog will be destroyed.

Returns
  A PidginMiniDialog, suitable for passing to pidgin_blist_add_alert().

See also
  pidginstock.h

## ◆ pidgin_make_pretty_arrows()

char * pidgin_make_pretty_arrows | ( | const char * | str | ) |

Converts "->" and "<-" in strings to Unicode arrow characters, for use in referencing menu items.

Parameters

  str | The text to convert

Returns
  A newly allocated string with unicode arrow characters

## ◆ pidgin_make_scrollable()

GtkWidget * pidgin_make_scrollable | ( | GtkWidget * | child,
|  | GtkPolicyType | hscrollbar_policy,
|  | GtkPolicyType | vscrollbar_policy,
|  | GtkShadowType | shadow_type,
|  | int | width,
|  | int | height
| ) |  |

Add scrollbars to a widget.

Parameters

  widget | The child widget @hscrollbar_policy Horizontal scrolling policy @vscrollbar_policy Vertical scrolling policy @shadow Shadow type @width Desired widget width, or -1 for default @height Desired widget height, or -1 for default

Since
  2.8.0

## ◆ pidgin_menu_position_func_helper()

void pidgin_menu_position_func_helper | ( | GtkMenu * | menu,
|  | gint * | x,
|  | gint * | y,
|  | gboolean * | push_in,
|  | gpointer | data
| ) |  |

A helper function for GtkMenuPositionFuncs.

This ensures the menu will be kept on screen if possible.

Parameters

  menu | The menu we are positioning.
  x | Address of the gint representing the horizontal position where the menu shall be drawn. This is an output parameter.
  y | Address of the gint representing the vertical position where the menu shall be drawn. This is an output parameter.
  push_in | This is an output parameter?
  data | Not used by this particular position function.

Since
  2.1.0

## ◆ pidgin_new_check_item()

GtkWidget * pidgin_new_check_item | ( | GtkWidget * | menu,
|  | const char * | str,
|  | GCallback | cb,
|  | gpointer | data,
|  | gboolean | checked
| ) |  |

Creates a check menu item.

Parameters

  menu | The menu to which to append the check menu item.
  str | The title to use for the newly created menu item.
  cb | A function to call when the menu item is activated.
  data | Data to pass to the signal function.
  checked | The initial state of the check item

Returns
  The newly created menu item.

## ◆ pidgin_new_item()

GtkWidget * pidgin_new_item | ( | GtkWidget * | menu,
|  | const char * | str
| ) |  |

Creates a menu item.

Parameters

  menu | The menu to which to append the menu item.
  str | The title to use for the newly created menu item.

Returns
  The newly created menu item.

## ◆ pidgin_new_item_from_stock()

GtkWidget * pidgin_new_item_from_stock | ( | GtkWidget * | menu,
|  | const char * | str,
|  | const char * | icon,
|  | GCallback | cb,
|  | gpointer | data,
|  | guint | accel_key,
|  | guint | accel_mods,
|  | char * | mod
| ) |  |

Creates a menu item.

Parameters

  menu | The menu to which to append the menu item.
  str | The title for the menu item.
  icon | An icon to place to the left of the menu item, or `NULL` for no icon.
  cb | A function to call when the menu item is activated.
  data | Data to pass to the signal function.
  accel_key | Something.
  accel_mods | Something.
  mod | Something.

Returns
  The newly created menu item.

## ◆ pidgin_parse_x_im_contact()

gboolean pidgin_parse_x_im_contact | ( | const char * | msg,
|  | gboolean | all_accounts,
|  | PurpleAccount ** | ret_account,
|  | char ** | ret_protocol,
|  | char ** | ret_username,
|  | char ** | ret_alias
| ) |  |

Parses an application/x-im-contact MIME message and returns the data inside.

Parameters

  msg | The MIME message.
  all_accounts | If TRUE, check all compatible accounts, online or offline. If FALSE, check only online accounts.
  ret_account | The best guess at a compatible protocol, based on ret_protocol. If NULL, no account was found.
  ret_protocol | The returned protocol type.
  ret_username | The returned username.
  ret_alias | The returned alias.

Returns
  TRUE if the message was parsed for the minimum necessary data. FALSE otherwise.

## ◆ pidgin_pixbuf_anim_from_data()

GdkPixbufAnimation * pidgin_pixbuf_anim_from_data | ( | const guchar * | buf,
|  | gsize | count
| ) |  |

Create a GdkPixbufAnimation from a chunk of image data.

Parameters

  buf | The raw binary image data.
  count | The length of buf in bytes.

Returns
  A GdkPixbufAnimation created from the image data, or NULL if there was an error parsing the data.

Since
  2.9.0

## ◆ pidgin_pixbuf_button_from_stock()

GtkWidget * pidgin_pixbuf_button_from_stock | ( | const char * | text,
|  | const char * | icon,
|  | PidginButtonOrientation | style
| ) |  |

Creates a button with the specified text and stock icon.

Parameters

  text | The text for the button.
  icon | The stock icon name.
  style | The orientation of the button.

Returns
  The button.

## ◆ pidgin_pixbuf_from_data()

GdkPixbuf * pidgin_pixbuf_from_data | ( | const guchar * | buf,
|  | gsize | count
| ) |  |

Create a GdkPixbuf from a chunk of image data.

Parameters

  buf | The raw binary image data.
  count | The length of buf in bytes.

Returns
  A GdkPixbuf created from the image data, or NULL if there was an error parsing the data.

Since
  2.9.0

## ◆ pidgin_pixbuf_from_imgstore()

GdkPixbuf * pidgin_pixbuf_from_imgstore | ( | PurpleStoredImage * | image | ) |

Create a GdkPixbuf from a PurpleStoredImage.

Parameters

  image | A PurpleStoredImage.

Returns
  A GdkPixbuf created from the stored image.

Since
  2.5.0

## ◆ pidgin_pixbuf_new_from_file()

GdkPixbuf * pidgin_pixbuf_new_from_file | ( | const char * | filename | ) |

Helper function that calls gdk_pixbuf_new_from_file() and checks both the return code and the GError and returns NULL if either one failed.

The gdk-pixbuf documentation implies that it is sufficient to check the return value of gdk_pixbuf_new_from_file() to determine whether the image was able to be loaded. However, this is not the case with gdk-pixbuf 2.23.3 and probably many earlier versions. In some cases a GdkPixbuf object is returned that will cause some operations (like gdk_pixbuf_scale_simple()) to rapidly consume memory in an infinite loop.

This function shouldn't be necessary once Pidgin requires a version of gdk-pixbuf where the aforementioned bug is fixed. However, it might be nice to keep this function around for the debug message that it logs.

Parameters

  filename | Name of file to load, in the GLib file name encoding

Returns
  The GdkPixbuf if successful. Otherwise NULL is returned and a warning is logged.

Since
  2.9.0

## ◆ pidgin_pixbuf_new_from_file_at_scale()

GdkPixbuf * pidgin_pixbuf_new_from_file_at_scale | ( | const char * | filename,
|  | int | width,
|  | int | height,
|  | gboolean | preserve_aspect_ratio
| ) |  |

Helper function that calls gdk_pixbuf_new_from_file_at_scale() and checks both the return code and the GError and returns NULL if either one failed.

The gdk-pixbuf documentation implies that it is sufficient to check the return value of gdk_pixbuf_new_from_file_at_scale() to determine whether the image was able to be loaded. However, this is not the case with gdk-pixbuf 2.23.3 and probably many earlier versions. In some cases a GdkPixbuf object is returned that will cause some operations (like gdk_pixbuf_scale_simple()) to rapidly consume memory in an infinite loop.

This function shouldn't be necessary once Pidgin requires a version of gdk-pixbuf where the aforementioned bug is fixed. However, it might be nice to keep this function around for the debug message that it logs.

Parameters

  filename | Name of file to load, in the GLib file name encoding
  width | The width the image should have or -1 to not constrain the width
  height | The height the image should have or -1 to not constrain the height
  preserve_aspect_ratio | TRUE to preserve the image's aspect ratio

Returns
  The GdkPixbuf if successful. Otherwise NULL is returned and a warning is logged.

Since
  2.9.0

## ◆ pidgin_pixbuf_new_from_file_at_size()

GdkPixbuf * pidgin_pixbuf_new_from_file_at_size | ( | const char * | filename,
|  | int | width,
|  | int | height
| ) |  |

Helper function that calls gdk_pixbuf_new_from_file_at_size() and checks both the return code and the GError and returns NULL if either one failed.

The gdk-pixbuf documentation implies that it is sufficient to check the return value of gdk_pixbuf_new_from_file_at_size() to determine whether the image was able to be loaded. However, this is not the case with gdk-pixbuf 2.23.3 and probably many earlier versions. In some cases a GdkPixbuf object is returned that will cause some operations (like gdk_pixbuf_scale_simple()) to rapidly consume memory in an infinite loop.

This function shouldn't be necessary once Pidgin requires a version of gdk-pixbuf where the aforementioned bug is fixed. However, it might be nice to keep this function around for the debug message that it logs.

Parameters

  filename | Name of file to load, in the GLib file name encoding
  width | The width the image should have or -1 to not constrain the width
  height | The height the image should have or -1 to not constrain the height

Returns
  The GdkPixbuf if successful. Otherwise NULL is returned and a warning is logged.

Since
  2.9.0

## ◆ pidgin_pixbuf_toolbar_button_from_stock()

GtkWidget * pidgin_pixbuf_toolbar_button_from_stock | ( | const char * | stock | ) |

Creates a toolbar button with the stock icon.

Parameters

  stock | The stock icon name.

Returns
  The button.

## ◆ pidgin_protocol_option_menu_get_selected()

const char * pidgin_protocol_option_menu_get_selected | ( | GtkWidget * | optmenu | ) |

Gets the currently selected protocol from a protocol drop down box.

Parameters

  optmenu | The drop-down option menu created by pidgin_account_option_menu_new.

Returns
  Returns the protocol ID that is currently selected.

## ◆ pidgin_protocol_option_menu_new()

GtkWidget * pidgin_protocol_option_menu_new | ( | const char * | id,
|  | GCallback | cb,
|  | gpointer | user_data
| ) |  |

Creates a drop-down option menu filled with protocols.

Parameters

  id | The protocol to select by default.
  cb | The callback to call when a protocol is selected.
  user_data | Data to pass to the callback function.

Returns
  The drop-down option menu.

## ◆ pidgin_retrieve_user_info()

void pidgin_retrieve_user_info | ( | PurpleConnection * | conn,
|  | const char * | name
| ) |  |

Get information about a user.

Show immediate feedback.

Parameters

  conn | The connection to get information from.
  name | The user to get information about.

Since
  2.1.0

## ◆ pidgin_retrieve_user_info_in_chat()

void pidgin_retrieve_user_info_in_chat | ( | PurpleConnection * | conn,
|  | const char * | name,
|  | int | chatid
| ) |  |

Get information about a user in a chat.

Show immediate feedback.

Parameters

  conn | The connection to get information from.
  name | The user to get information about.
  chatid | The chat id.

Since
  2.1.0

## ◆ pidgin_screenname_autocomplete_default_filter()

gboolean pidgin_screenname_autocomplete_default_filter | ( | const PidginBuddyCompletionEntry * | completion_entry,
|  | gpointer | all_accounts
| ) |  |

The default filter function for username autocomplete.

Parameters

  completion_entry | The completion entry to filter.
  all_accounts | If this is `FALSE`, only the autocompletion entries which belong to an online account will be filtered.

Returns
  Returns `TRUE` if the autocompletion entry is filtered.

## ◆ pidgin_separator()

GtkWidget * pidgin_separator | ( | GtkWidget * | menu | ) |

Adds a separator to a menu.

Parameters

  menu | The menu to add a separator to.

Returns
  The separator.

## ◆ pidgin_set_accessible_label()

void pidgin_set_accessible_label | ( | GtkWidget * | w,
|  | GtkWidget * | l
| ) |  |

Sets an ATK name for a given widget.

Also sets the labelled-by and label-for ATK relationships.

Parameters

  w | The widget that we want to name.
  l | A GtkLabel that we want to use as the ATK name for the widget.

## ◆ pidgin_set_accessible_relations()

void pidgin_set_accessible_relations | ( | GtkWidget * | w,
|  | GtkWidget * | l
| ) |  |

Sets the labelled-by and label-for ATK relationships.

Parameters

  w | The widget that we want to label.
  l | A GtkLabel that we want to use as the label for the widget.

Since
  2.2.0

## ◆ pidgin_set_cursor()

void pidgin_set_cursor | ( | GtkWidget * | widget,
|  | GdkCursorType | cursor_type
| ) |  |

Sets the mouse pointer for a GtkWidget.

After setting the cursor, the display is flushed, so the change will take effect immediately.

If the window for widget is `NULL`, this function simply returns.

Parameters

  widget | The widget for which to set the mouse pointer
  cursor_type | The type of cursor to set

## ◆ pidgin_set_custom_buddy_icon()

void pidgin_set_custom_buddy_icon | ( | PurpleAccount * | account,
|  | const char * | who,
|  | const char * | filename
| ) |  |

Set or unset a custom buddyicon for a user.

Parameters

  account | The account the user belongs to.
  who | The name of the user.
  filename | The path of the custom icon. If this is `NULL`, then any previously set custom buddy icon for the user is removed.

Deprecated:
  See purple_buddy_icons_node_set_custom_icon_from_file()

## ◆ pidgin_set_sensitive_if_input()

void pidgin_set_sensitive_if_input | ( | GtkWidget * | entry,
|  | GtkWidget * | dialog
| ) |  |

Checks if text has been entered into a GtkTextEntry widget.

If so, the GTK_RESPONSE_OK on the given dialog is set to TRUE. Otherwise GTK_RESPONSE_OK is set to FALSE.

Parameters

  entry | The text entry widget.
  dialog | The dialog containing the text entry widget.

## ◆ pidgin_set_urgent()

void pidgin_set_urgent | ( | GtkWindow * | window,
|  | gboolean | urgent
| ) |  |

Sets or resets a window to 'urgent,' by setting the URGENT hint in X or blinking in the win32 taskbar.

Parameters

  window | The window to draw attention to
  urgent | Whether to set the urgent hint or not

## ◆ pidgin_setup_gtkspell()

void pidgin_setup_gtkspell | ( | GtkTextView * | textview | ) |

Sets up GtkSpell for the given GtkTextView, reporting errors if encountered.

This does nothing if Pidgin is not compiled with GtkSpell support.

Parameters

  textview | The textview widget to setup spellchecking for.

## ◆ pidgin_setup_imhtml()

void pidgin_setup_imhtml | ( | GtkWidget * | imhtml | ) |

Sets up a gtkimhtml widget, loads it with smileys, and sets the default signal handlers.

Parameters

  imhtml | The gtkimhtml widget to setup.

## ◆ pidgin_setup_screenname_autocomplete()

void pidgin_setup_screenname_autocomplete | ( | GtkWidget * | entry,
|  | GtkWidget * | optmenu,
|  | gboolean | all
| ) |  |

Add autocompletion of screenames to an entry.

Deprecated:
  For new code, use the equivalent: pidgin_setup_screenname_autocomplete_with_filter(entry, optmenu, pidgin_screenname_autocomplete_default_filter, `GINT_TO_POINTER(all)`)

Parameters

  entry | The GtkEntry on which to setup autocomplete.
  optmenu | A menu for accounts, returned by pidgin_account_option_menu_new(). If optmenu is not `NULL`, it'll be updated when a username is chosen from the autocomplete list.
  all | Whether to include usernames from disconnected accounts.

## ◆ pidgin_setup_screenname_autocomplete_with_filter()

void pidgin_setup_screenname_autocomplete_with_filter | ( | GtkWidget * | entry,
|  | GtkWidget * | optmenu,
|  | PidginFilterBuddyCompletionEntryFunc | filter_func,
|  | gpointer | user_data
| ) |  |

Add autocompletion of screenames to an entry, supporting a filtering function.

Parameters

  entry | The GtkEntry on which to setup autocomplete.
  optmenu | A menu for accounts, returned by pidgin_account_option_menu_new(). If optmenu is not `NULL`, it'll be updated when a username is chosen from the autocomplete list.
  filter_func | A function for checking if an autocomplete entry should be shown. This can be `NULL`.
  user_data | The data to be passed to the filter_func function.

## ◆ pidgin_stock_id_from_presence()

const char * pidgin_stock_id_from_presence | ( | PurplePresence * | presence | ) |

Returns an appropriate stock-id for a PurplePresence.

Parameters

  presence | The presence.

Returns
  The stock-id

Since
  2.6.0

## ◆ pidgin_stock_id_from_status_primitive()

const char * pidgin_stock_id_from_status_primitive | ( | PurpleStatusPrimitive | prim | ) |

Returns an appropriate stock-id for a status primitive.

Parameters

  prim | The status primitive

Returns
  The stock-id

Since
  2.6.0

## ◆ pidgin_text_combo_box_entry_get_text()

const char * pidgin_text_combo_box_entry_get_text | ( | GtkWidget * | widget | ) |

Retrieve the text from the entry of the simple text GtkComboBoxEntry equivalent.

Parameters

  widget | The simple text GtkComboBoxEntry equivalent widget

Returns
  The text in the widget's entry. It must not be freed

Since
  2.2.0

## ◆ pidgin_text_combo_box_entry_new()

GtkWidget * pidgin_text_combo_box_entry_new | ( | const char * | default_item,
|  | GList * | items
| ) |  |

Create a simple text GtkComboBoxEntry equivalent.

Parameters

  default_item | Initial contents of GtkEntry
  items | GList containing strings to add to GtkComboBox

Returns
  A newly created text GtkComboBox containing a GtkEntry child.

Since
  2.2.0

## ◆ pidgin_text_combo_box_entry_set_text()

void pidgin_text_combo_box_entry_set_text | ( | GtkWidget * | widget,
|  | const char * | text
| ) |  |

Set the text in the entry of the simple text GtkComboBoxEntry equivalent.

Parameters

  widget | The simple text GtkComboBoxEntry equivalent widget
  text | The text to set

Since
  2.2.0

## ◆ pidgin_toggle_sensitive()

void pidgin_toggle_sensitive | ( | GtkWidget * | widget,
|  | GtkWidget * | to_toggle
| ) |  |

Toggles the sensitivity of a widget.

Parameters

  widget | `NULL`. Used for signal handlers.
  to_toggle | The widget to toggle.

## ◆ pidgin_toggle_sensitive_array()

void pidgin_toggle_sensitive_array | ( | GtkWidget * | w,
|  | GPtrArray * | data
| ) |  |

Toggles the sensitivity of all widgets in a pointer array.

Parameters

  w | `NULL`. Used for signal handlers.
  data | The array containing the widgets to toggle.

## ◆ pidgin_toggle_showhide()

void pidgin_toggle_showhide | ( | GtkWidget * | widget,
|  | GtkWidget * | to_toggle
| ) |  |

Toggles the visibility of a widget.

Parameters

  widget | `NULL`. Used for signal handlers.
  to_toggle | The widget to toggle.

## ◆ pidgin_tree_view_search_equal_func()

gboolean pidgin_tree_view_search_equal_func | ( | GtkTreeModel * | model,
|  | gint | column,
|  | const gchar * | key,
|  | GtkTreeIter * | iter,
|  | gpointer | data
| ) |  |

This is a callback function to be used for Ctrl+F searching in treeviews.

Sample Use: gtk_tree_view_set_search_equal_func(treeview, pidgin_tree_view_search_equal_func, search_data, search_data_destroy_cb);

## ◆ pidgin_treeview_popup_menu_position_func()

void pidgin_treeview_popup_menu_position_func | ( | GtkMenu * | menu,
|  | gint * | x,
|  | gint * | y,
|  | gboolean * | push_in,
|  | gpointer | user_data
| ) |  |

A valid GtkMenuPositionFunc.

This is used to determine where to draw context menus when the menu is activated with the keyboard (shift+F10). If the menu is activated with the mouse, then you should just use GTK's built-in position function, because it does a better job of positioning the menu.

Parameters

  menu | The menu we are positioning.
  x | Address of the gint representing the horizontal position where the menu shall be drawn. This is an output parameter.
  y | Address of the gint representing the vertical position where the menu shall be drawn. This is an output parameter.
  push_in | This is an output parameter?
  user_data | Not used by this particular position function.

## ◆ pidgin_utils_init()

void pidgin_utils_init | ( | void |  | ) |

Initialize some utility functions.

Since
  2.6.0

## ◆ pidgin_utils_uninit()

void pidgin_utils_uninit | ( | void |  | ) |

Uninitialize some utility functions.

Since
  2.6.0