comparison pidgin/gtkutils.h @ 32667:e2a1510da13d

propagate from branch 'im.pidgin.pidgin' (head 5da91575f92c8c13d7a85eef338ec6da55e6fb26) to branch 'im.pidgin.cpw.qulogic.gtk3' (head 53d36fd22e482079303664b9f3e13fa2a4b6f9b2)

32666:974722699032

 * @return Returns @c TRUE if the autocompletion entry is filtered.
 */
gboolean pidgin_screenname_autocomplete_default_filter(const PidginBuddyCompletionEntry *completion_entry, gpointer all_accounts);

/**
 * Add autocompletion of screenames to an entry.
 *
 * @deprecated
 *   For new code, use the equivalent:
 *   #pidgin_setup_screenname_autocomplete_with_filter(@a entry, @a optmenu,
 *   #pidgin_screenname_autocomplete_default_filter, <tt>GINT_TO_POINTER(@a
 *   all)</tt>)
 *
 * @param entry     The GtkEntry on which to setup autocomplete.
 * @param optmenu   A menu for accounts, returned by
 *                  pidgin_account_option_menu_new().  If @a optmenu is not @c
 *                  NULL, it'll be updated when a username is chosen from the
 *                  autocomplete list.
 * @param all       Whether to include usernames from disconnected accounts.
 */
void pidgin_setup_screenname_autocomplete(GtkWidget *entry, GtkWidget *optmenu, gboolean all);

/**
 * Sets up GtkSpell for the given GtkTextView, reporting errors
 * if encountered.
 *
 * This does nothing if Pidgin is not compiled with GtkSpell support.
 *

 * @param len        If not @c NULL, the length of the returned data will be set here.
 *
 * @return           The converted image data, or @c NULL if an error occurred.
 */
gpointer pidgin_convert_buddy_icon(PurplePlugin *plugin, const char *path, size_t *len);

#if !(defined PIDGIN_DISABLE_DEPRECATED) || (defined _PIDGIN_GTKUTILS_C_)
/**
 * Set or unset a custom buddyicon for a user.
 *
 * @param account   The account the user belongs to.
 * @param who       The name of the user.
 * @param filename  The path of the custom icon. If this is @c NULL, then any
 *                  previously set custom buddy icon for the user is removed.
 * @deprecated See purple_buddy_icons_node_set_custom_icon_from_file()
 */
void pidgin_set_custom_buddy_icon(PurpleAccount *account, const char *who, const char *filename);
#endif

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

 * @since 2.4.0
 */
GtkWidget *pidgin_add_widget_to_vbox(GtkBox *vbox, const char *widget_label, GtkSizeGroup *sg, GtkWidget *widget, gboolean expand, GtkWidget **p_label);

/**
 * Create a GdkPixbuf from a PurpleStoredImage.
 *
 * @param  image   A PurpleStoredImage.
 *
 * @return   A GdkPixbuf created from the stored image.
 *
 * @since 2.5.0
 */
GdkPixbuf *pidgin_pixbuf_from_imgstore(PurpleStoredImage *image);

/**
 * Add scrollbars to a widget
 * @param widget      The child widget
 * @hscrollbar_policy Horizontal scrolling policy

32667:e2a1510da13d

 * @return Returns @c TRUE if the autocompletion entry is filtered.
 */
gboolean pidgin_screenname_autocomplete_default_filter(const PidginBuddyCompletionEntry *completion_entry, gpointer all_accounts);

/**
 * Sets up GtkSpell for the given GtkTextView, reporting errors
 * if encountered.
 *
 * This does nothing if Pidgin is not compiled with GtkSpell support.
 *

 * @param len        If not @c NULL, the length of the returned data will be set here.
 *
 * @return           The converted image data, or @c NULL if an error occurred.
 */
gpointer pidgin_convert_buddy_icon(PurplePlugin *plugin, const char *path, size_t *len);

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

 * @since 2.4.0
 */
GtkWidget *pidgin_add_widget_to_vbox(GtkBox *vbox, const char *widget_label, GtkSizeGroup *sg, GtkWidget *widget, gboolean expand, GtkWidget **p_label);

/**
 * Create a GdkPixbuf from a chunk of image data.
 *
 * @param buf The raw binary image data.
 * @param count The length of buf in bytes.
 *
 * @return A GdkPixbuf created from the image data, or NULL if
 *         there was an error parsing the data.
 *
 * @since 2.9.0
 */
GdkPixbuf *pidgin_pixbuf_from_data(const guchar *buf, gsize count);

/**
 * Create a GdkPixbufAnimation from a chunk of image data.
 *
 * @param buf The raw binary image data.
 * @param count The length of buf in bytes.
 *
 * @return A GdkPixbufAnimation created from the image data, or NULL if
 *         there was an error parsing the data.
 *
 * @since 2.9.0
 */
GdkPixbufAnimation *pidgin_pixbuf_anim_from_data(const guchar *buf, gsize count);

/**
 * Create a GdkPixbuf from a PurpleStoredImage.
 *
 * @param  image   A PurpleStoredImage.
 *
 * @return   A GdkPixbuf created from the stored image.
 *
 * @since 2.5.0
 */
GdkPixbuf *pidgin_pixbuf_from_imgstore(PurpleStoredImage *image);

/**
 * 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.
 *
 * @param filename Name of file to load, in the GLib file name encoding
 *
 * @return The GdkPixbuf if successful.  Otherwise NULL is returned and
 *         a warning is logged.
 *
 * @since 2.9.0
 */
GdkPixbuf *pidgin_pixbuf_new_from_file(const char *filename);

/**
 * 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.
 *
 * @param filename Name of file to load, in the GLib file name encoding
 * @param width The width the image should have or -1 to not constrain the width
 * @param height The height the image should have or -1 to not constrain the height
 *
 * @return The GdkPixbuf if successful.  Otherwise NULL is returned and
 *         a warning is logged.
 *
 * @since 2.9.0
 */
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_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.
 *
 * @param filename Name of file to load, in the GLib file name encoding
 * @param width The width the image should have or -1 to not constrain the width
 * @param height The height the image should have or -1 to not constrain the height
 * @param preserve_aspect_ratio TRUE to preserve the image's aspect ratio
 *
 * @return The GdkPixbuf if successful.  Otherwise NULL is returned and
 *         a warning is logged.
 *
 * @since 2.9.0
 */
GdkPixbuf *pidgin_pixbuf_new_from_file_at_scale(const char *filename, int width, int height, gboolean preserve_aspect_ratio);

/**
 * Add scrollbars to a widget
 * @param widget      The child widget
 * @hscrollbar_policy Horizontal scrolling policy