comparison pidgin/gtkutils.h @ 32692:0f94ec89f0bc

merged from im.pidgin.pidgin

32438:55e678325bda

 * @return The GtkFrame containing the toolbar and imhtml.
 */
GtkWidget *pidgin_create_imhtml(gboolean editable, GtkWidget **imhtml_ret, GtkWidget **toolbar_ret, GtkWidget **sw_ret);

/**
 * Creates a small button
 *
 * @param  image   A button image.
 *
 * @return   A GtkButton created from the image.
 * @since 2.7.0
 */
GtkWidget *pidgin_create_small_button(GtkWidget *image);

/**
 * Creates a new window
 *
 * @param title        The window title, or @c NULL
 * @param border_width The window's desired border width
 * @param role         A string indicating what the window is responsible for doing, or @c NULL
 * @param resizable    Whether the window should be resizable (@c TRUE) or not (@c FALSE)
 *
 * @since 2.1.0
 */
GtkWidget *pidgin_create_window(const char *title, guint border_width, const char *role, gboolean resizable);

/**
 * Creates a new dialog window
 *
 * @param title        The window title, or @c NULL
 * @param border_width The window's desired border width
 * @param role         A string indicating what the window is responsible for doing, or @c NULL
 * @param resizable    Whether the window should be resizable (@c TRUE) or not (@c FALSE)
 *
 * @since 2.4.0
 */
GtkWidget *pidgin_create_dialog(const char *title, guint border_width, const char *role, gboolean resizable);

/**
 * Retrieves the main content box (vbox) from a pidgin dialog window
 *
 * @param dialog       The dialog window
 * @param homogeneous  TRUE if all children are to be given equal space allotments.
 * @param spacing      the number of pixels to place by default between children
 *
 * @since 2.4.0
 */
GtkWidget *pidgin_dialog_get_vbox_with_properties(GtkDialog *dialog, gboolean homogeneous, gint spacing);

/**
 * Retrieves the main content box (vbox) from a pidgin dialog window
 *
 * @param dialog       The dialog window
 *
 * @since 2.4.0
 */
GtkWidget *pidgin_dialog_get_vbox(GtkDialog *dialog);

/**
 * Add a button to a dialog created by #pidgin_create_dialog.

 * @param label          The stock-id or the label for the button
 * @param callback       The callback function for the button
 * @param callbackdata   The user data for the callback function
 *
 * @return The created button.
 * @since 2.4.0
 */
GtkWidget *pidgin_dialog_add_button(GtkDialog *dialog, const char *label,
		GCallback callback, gpointer callbackdata);

/**
 * Retrieves the action area (button box) from a pidgin dialog window
 *
 * @param dialog       The dialog window
 *
 * @since 2.4.0
 */
GtkWidget *pidgin_dialog_get_action_area(GtkDialog *dialog);

/**
 * Toggles the sensitivity of a widget.

/**
 * Get information about a user. Show immediate feedback.
 *
 * @param conn   The connection to get information from.
 * @param name   The user to get information about.
 *
 * @since 2.1.0
 */
void pidgin_retrieve_user_info(PurpleConnection *conn, const char *name);

/**
 * Get information about a user in a chat. Show immediate feedback.
 *
 * @param conn   The connection to get information from.
 * @param name   The user to get information about.
 * @param chatid The chat id.
 *
 * @since 2.1.0
 */
void pidgin_retrieve_user_info_in_chat(PurpleConnection *conn, const char *name, int chatid);

/**
 * Parses an application/x-im-contact MIME message and returns the

/**
 * Sets the labelled-by and label-for ATK relationships.
 *
 * @param w The widget that we want to label.
 * @param l A GtkLabel that we want to use as the label for the widget.
 *
 * @since 2.2.0
 */
void pidgin_set_accessible_relations(GtkWidget *w, GtkWidget *l);

/**
 * A helper function for GtkMenuPositionFuncs. This ensures the menu will

 *        where the menu shall be drawn. This is an output parameter.
 * @param y Address of the gint representing the vertical position
 *        where the menu shall be drawn. This is an output parameter.
 * @param push_in This is an output parameter?
 * @param data Not used by this particular position function.
 *
 * @since 2.1.0
 */
void pidgin_menu_position_func_helper(GtkMenu *menu, gint *x, gint *y,
										gboolean *push_in, gpointer data);

/**

 * Returns an appropriate stock-id for a status primitive.
 *
 * @param prim   The status primitive
 *
 * @return The stock-id
 *
 * @since 2.6.0
 */
const char *pidgin_stock_id_from_status_primitive(PurpleStatusPrimitive prim);

/**
 * Returns an appropriate stock-id for a PurplePresence.
 *
 * @param presence   The presence.
 *
 * @return The stock-id
 *
 * @since 2.6.0
 */
const char *pidgin_stock_id_from_presence(PurplePresence *presence);

/**
 * Append a PurpleMenuAction to a menu.

 * @param default_item   Initial contents of GtkEntry
 * @param items          GList containing strings to add to GtkComboBox
 *
 * @return               A newly created text GtkComboBox containing a GtkEntry
 *                       child.
 *
 * @since 2.2.0
 */
GtkWidget *pidgin_text_combo_box_entry_new(const char *default_item, GList *items);

/**
 * Retrieve the text from the entry of the simple text GtkComboBoxEntry equivalent
 *
 * @param widget         The simple text GtkComboBoxEntry equivalent widget
 *
 * @return               The text in the widget's entry. It must not be freed
 *
 * @since 2.2.0
 */
const char *pidgin_text_combo_box_entry_get_text(GtkWidget *widget);

/**
 * Set the text in the entry of the simple text GtkComboBoxEntry equivalent
 *
 * @param widget         The simple text GtkComboBoxEntry equivalent widget
 * @param text           The text to set
 *
 * @since 2.2.0
 */
void pidgin_text_combo_box_entry_set_text(GtkWidget *widget, const char *text);

/**
 * Automatically make a window transient to a suitable parent window.
 *
 * @param window    The window to make transient.
 *
 * @return Whether the window was made transient or not.
 *
 * @since 2.4.0
 */
gboolean pidgin_auto_parent_window(GtkWidget *window);

/**
 * Add a labelled widget to a GtkVBox

 * @param widget       The GtkWidget to add.
 * @param expand       Whether to expand the widget horizontally.
 * @param p_label      Place to store a pointer to the GtkLabel, or @c NULL if you don't care.
 *
 * @return  A GtkHBox already added to the GtkVBox containing the GtkLabel and the GtkWidget.
 * @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

 *
 * @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

 * @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

 * @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
 * @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
 */
GtkWidget *pidgin_make_scrollable(GtkWidget *child, GtkPolicyType hscrollbar_policy, GtkPolicyType vscrollbar_policy, GtkShadowType shadow_type, int width, int height);

/**
 * Initialize some utility functions.
 *
 * @since 2.6.0
 */
void pidgin_utils_init(void);

/**
 * Uninitialize some utility functions.
 *
 * @since 2.6.0
 */
void pidgin_utils_uninit(void);

gchar *pidgin_gtk_ellipsis_text(GtkWidget *widget, const char *text, gint min_width, gchar *ellipsis);

32692:0f94ec89f0bc

 * @return The GtkFrame containing the toolbar and imhtml.
 */
GtkWidget *pidgin_create_imhtml(gboolean editable, GtkWidget **imhtml_ret, GtkWidget **toolbar_ret, GtkWidget **sw_ret);

/**
 * Create an GtkWebView widget and associated GtkIMHtmlToolbar widget.  This
 * function puts both widgets in a nice GtkFrame.  They're separated by an
 * attractive GtkSeparator.
 * TODO WEBKIT: editable isn't supported yet
 *
 * @param editable @c TRUE if this webview should be editable.  If this is
 *        @c FALSE, then the toolbar will NOT be created.  If this webview
 *        should be read-only at first, but may become editable later, then
 *        pass in @c TRUE here and then manually call gtk_webview_set_editable()
 *        later.
 * @param webview_ret A pointer to a pointer to a GtkWidget.  This pointer
 *        will be set to the webview when this function exits.
 * @param 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 @c NULL.
 * @param sw_ret This will be filled with a pointer to the scrolled window
 *        widget which contains the webview.
 *
 * @return The GtkFrame containing the toolbar and webview.
 */
GtkWidget *pidgin_create_webview(gboolean editable, GtkWidget **webview_ret, GtkWidget **toolbar_ret, GtkWidget **sw_ret);

/**
 * Creates a small button
 *
 * @param  image   A button image.
 *
 * @return   A GtkButton created from the image.
 */
GtkWidget *pidgin_create_small_button(GtkWidget *image);

/**
 * Creates a new window
 *
 * @param title        The window title, or @c NULL
 * @param border_width The window's desired border width
 * @param role         A string indicating what the window is responsible for doing, or @c NULL
 * @param resizable    Whether the window should be resizable (@c TRUE) or not (@c FALSE)
 */
GtkWidget *pidgin_create_window(const char *title, guint border_width, const char *role, gboolean resizable);

/**
 * Creates a new dialog window
 *
 * @param title        The window title, or @c NULL
 * @param border_width The window's desired border width
 * @param role         A string indicating what the window is responsible for doing, or @c NULL
 * @param resizable    Whether the window should be resizable (@c TRUE) or not (@c FALSE)
 */
GtkWidget *pidgin_create_dialog(const char *title, guint border_width, const char *role, gboolean resizable);

/**
 * Retrieves the main content box (vbox) from a pidgin dialog window
 *
 * @param dialog       The dialog window
 * @param homogeneous  TRUE if all children are to be given equal space allotments.
 * @param spacing      the number of pixels to place by default between children
 */
GtkWidget *pidgin_dialog_get_vbox_with_properties(GtkDialog *dialog, gboolean homogeneous, gint spacing);

/**
 * Retrieves the main content box (vbox) from a pidgin dialog window
 *
 * @param dialog       The dialog window
 */
GtkWidget *pidgin_dialog_get_vbox(GtkDialog *dialog);

/**
 * Add a button to a dialog created by #pidgin_create_dialog.

 * @param label          The stock-id or the label for the button
 * @param callback       The callback function for the button
 * @param callbackdata   The user data for the callback function
 *
 * @return The created button.
 */
GtkWidget *pidgin_dialog_add_button(GtkDialog *dialog, const char *label,
		GCallback callback, gpointer callbackdata);

/**
 * Retrieves the action area (button box) from a pidgin dialog window
 *
 * @param dialog       The dialog window
 */
GtkWidget *pidgin_dialog_get_action_area(GtkDialog *dialog);

/**
 * Toggles the sensitivity of a widget.

/**
 * Get information about a user. Show immediate feedback.
 *
 * @param conn   The connection to get information from.
 * @param name   The user to get information about.
 */
void pidgin_retrieve_user_info(PurpleConnection *conn, const char *name);

/**
 * Get information about a user in a chat. Show immediate feedback.
 *
 * @param conn   The connection to get information from.
 * @param name   The user to get information about.
 * @param chatid The chat id.
 */
void pidgin_retrieve_user_info_in_chat(PurpleConnection *conn, const char *name, int chatid);

/**
 * Parses an application/x-im-contact MIME message and returns the

/**
 * Sets the labelled-by and label-for ATK relationships.
 *
 * @param w The widget that we want to label.
 * @param l A GtkLabel that we want to use as the label for the widget.
 */
void pidgin_set_accessible_relations(GtkWidget *w, GtkWidget *l);

/**
 * A helper function for GtkMenuPositionFuncs. This ensures the menu will

 *        where the menu shall be drawn. This is an output parameter.
 * @param y Address of the gint representing the vertical position
 *        where the menu shall be drawn. This is an output parameter.
 * @param push_in This is an output parameter?
 * @param data Not used by this particular position function.
 */
void pidgin_menu_position_func_helper(GtkMenu *menu, gint *x, gint *y,
										gboolean *push_in, gpointer data);

/**

 * Returns an appropriate stock-id for a status primitive.
 *
 * @param prim   The status primitive
 *
 * @return The stock-id
 */
const char *pidgin_stock_id_from_status_primitive(PurpleStatusPrimitive prim);

/**
 * Returns an appropriate stock-id for a PurplePresence.
 *
 * @param presence   The presence.
 *
 * @return The stock-id
 */
const char *pidgin_stock_id_from_presence(PurplePresence *presence);

/**
 * Append a PurpleMenuAction to a menu.

 * @param default_item   Initial contents of GtkEntry
 * @param items          GList containing strings to add to GtkComboBox
 *
 * @return               A newly created text GtkComboBox containing a GtkEntry
 *                       child.
 */
GtkWidget *pidgin_text_combo_box_entry_new(const char *default_item, GList *items);

/**
 * Retrieve the text from the entry of the simple text GtkComboBoxEntry equivalent
 *
 * @param widget         The simple text GtkComboBoxEntry equivalent widget
 *
 * @return               The text in the widget's entry. It must not be freed
 */
const char *pidgin_text_combo_box_entry_get_text(GtkWidget *widget);

/**
 * Set the text in the entry of the simple text GtkComboBoxEntry equivalent
 *
 * @param widget         The simple text GtkComboBoxEntry equivalent widget
 * @param text           The text to set
 */
void pidgin_text_combo_box_entry_set_text(GtkWidget *widget, const char *text);

/**
 * Automatically make a window transient to a suitable parent window.
 *
 * @param window    The window to make transient.
 *
 * @return Whether the window was made transient or not.
 */
gboolean pidgin_auto_parent_window(GtkWidget *window);

/**
 * Add a labelled widget to a GtkVBox

 * @param widget       The GtkWidget to add.
 * @param expand       Whether to expand the widget horizontally.
 * @param p_label      Place to store a pointer to the GtkLabel, or @c NULL if you don't care.
 *
 * @return  A GtkHBox already added to the GtkVBox containing the GtkLabel and the GtkWidget.
 */
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.
 */
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.
 */
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.
 */
GdkPixbuf *pidgin_pixbuf_from_imgstore(PurpleStoredImage *image);

/**
 * Helper function that calls gdk_pixbuf_new_from_file() and checks both

 *
 * @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.
 */
GdkPixbuf *pidgin_pixbuf_new_from_file(const char *filename);

/**
 * Helper function that calls gdk_pixbuf_new_from_file_at_size() and checks

 * @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.
 */
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

 * @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.
 */
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 child              The child widget
 * @param hscrollbar_policy  Horizontal scrolling policy
 * @param vscrollbar_policy  Vertical scrolling policy
 * @param shadow_type        Shadow type
 * @param width              Desired widget width, or -1 for default
 * @param height             Desired widget height, or -1 for default
 */
GtkWidget *pidgin_make_scrollable(GtkWidget *child, GtkPolicyType hscrollbar_policy, GtkPolicyType vscrollbar_policy, GtkShadowType shadow_type, int width, int height);

/**
 * Initialize some utility functions.
 */
void pidgin_utils_init(void);

/**
 * Uninitialize some utility functions.
 */
void pidgin_utils_uninit(void);

gchar *pidgin_gtk_ellipsis_text(GtkWidget *widget, const char *text, gint min_width, gchar *ellipsis);