pidgin/pidgin

Use Meson summary() function.

2021-07-27, Elliott Sales de Andrade
cb640ea0f315
Use Meson summary() function.

Now that we require at least 0.52, we can use Meson's builtin summary printing to display the results of configuration.

Testing Done:
Configured with defaults, and with pixmaps disabled to trigger the warning: https://asciinema.org/a/mV2oxOoVCJNdmrPwgqqUJ3mkU?t=17

Reviewed at https://reviews.imfreedom.org/r/848/
/* pidgin
*
* Pidgin is the legal property of its developers, whose names are too numerous
* to list here. Please refer to the COPYRIGHT file distributed with this
* source distribution.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
*/
#if !defined(PIDGIN_GLOBAL_HEADER_INSIDE) && !defined(PIDGIN_COMPILATION)
# error "only <pidgin.h> may be included directly"
#endif
#ifndef _PIDGINUTILS_H_
#define _PIDGINUTILS_H_
/**
* SECTION:gtkutils
* @section_id: pidgin-gtkutils
* @short_description: <filename>gtkutils.h</filename>
* @title: Utility functions
*/
#include "gtkconv.h"
#include <purple.h>
typedef enum
{
PIDGIN_BUTTON_HORIZONTAL,
PIDGIN_BUTTON_VERTICAL
} PidginButtonOrientation;
typedef enum
{
PIDGIN_PROTOCOL_ICON_SMALL,
PIDGIN_PROTOCOL_ICON_MEDIUM,
PIDGIN_PROTOCOL_ICON_LARGE
} PidginProtocolIconSize;
typedef struct {
gboolean is_buddy;
union {
PurpleBuddy *buddy;
PurpleLogSet *logged_buddy;
} entry;
} PidginBuddyCompletionEntry;
typedef gboolean (*PidginFilterBuddyCompletionEntryFunc) (const PidginBuddyCompletionEntry *completion_entry, gpointer user_data);
G_BEGIN_DECLS
/**
* pidgin_dialog_get_vbox_with_properties:
* @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
*
* Retrieves the main content box (vbox) from a pidgin dialog window
*
* Returns: (transfer none): The main vbox from @dialog.
*/
GtkWidget *pidgin_dialog_get_vbox_with_properties(GtkDialog *dialog, gboolean homogeneous, gint spacing);
/**
* pidgin_dialog_get_vbox:
* @dialog: The dialog window
*
* Retrieves the main content box (vbox) from a pidgin dialog window
*
* Returns: (transfer none): the main vbox from @dialog.
*/
GtkWidget *pidgin_dialog_get_vbox(GtkDialog *dialog);
/**
* pidgin_dialog_add_button:
* @dialog: The dialog window
* @label: The label for the button
* @callback: (scope call): The callback function for the button
* @callbackdata: The user data for the callback function
*
* Add a button to a dialog created by #pidgin_create_dialog.
*
* Returns: (transfer full): The created button.
*/
GtkWidget *pidgin_dialog_add_button(GtkDialog *dialog, const char *label,
GCallback callback, gpointer callbackdata);
/**
* pidgin_dialog_get_action_area:
* @dialog: The dialog window
*
* Retrieves the action area (button box) from a pidgin dialog window
*
* Returns: (transfer none): The action area (button box) from @dialog.
*/
GtkWidget *pidgin_dialog_get_action_area(GtkDialog *dialog);
/**
* pidgin_separator:
* @menu: The menu to add a separator to.
*
* Adds a separator to a menu.
*
* Returns: (transfer full): The separator.
*/
GtkWidget *pidgin_separator(GtkWidget *menu);
/**
* pidgin_new_check_item:
* @menu: The menu to which to append the check menu item.
* @str: The title to use for the newly created menu item.
* @cb: (scope call): 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
*
* Creates a check menu item.
*
* Returns: (transfer full): The newly created menu item.
*/
GtkWidget *pidgin_new_check_item(GtkWidget *menu, const char *str,
GCallback cb, gpointer data, gboolean checked);
/**
* pidgin_new_menu_item:
* @menu: The menu to which to append the menu item.
* @mnemonic: The title for the menu item.
* @icon: An icon to place to the left of the menu item,
* or %NULL for no icon.
* @cb: (scope call): A function to call when the menu item is activated.
* @data: Data to pass to the signal function.
*
* Creates a menu item.
*
* Returns: (transfer full): The newly created menu item.
*/
GtkWidget *pidgin_new_menu_item(GtkWidget *menu, const char *mnemonic,
const char *icon, GCallback cb, gpointer data);
/**
* pidgin_make_frame:
* @parent: The widget to put the frame into.
* @title: The title for the frame.
*
* Creates a HIG preferences frame.
*
* Returns: (transfer full): The vbox to put things into.
*/
GtkWidget *pidgin_make_frame(GtkWidget *parent, const char *title);
/**
* pidgin_setup_screenname_autocomplete:
* @entry: The GtkEntry on which to setup autocomplete.
* @chooser: A menu for accounts, returned by pidgin_account_chooser_new(). If
* @chooser is not %NULL, it'll be updated when a username is chosen
* from the autocomplete list.
* @filter_func: (scope call): 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.
*
* Add autocompletion of screenames to an entry, supporting a filtering
* function.
*/
void pidgin_setup_screenname_autocomplete(
GtkWidget *entry, GtkWidget *chooser,
PidginFilterBuddyCompletionEntryFunc filter_func, gpointer user_data);
/**
* pidgin_screenname_autocomplete_default_filter:
* @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.
*
* The default filter function for username autocomplete.
*
* Returns: Returns %TRUE if the autocompletion entry is filtered.
*/
gboolean pidgin_screenname_autocomplete_default_filter(const PidginBuddyCompletionEntry *completion_entry, gpointer all_accounts);
/**
* pidgin_save_accels_cb:
*
* Save menu accelerators callback
*/
void pidgin_save_accels_cb(GtkAccelGroup *accel_group, guint arg1,
GdkModifierType arg2, GClosure *arg3,
gpointer data);
/**
* pidgin_save_accels:
*
* Save menu accelerators
*/
gboolean pidgin_save_accels(gpointer data);
/**
* pidgin_load_accels:
*
* Load menu accelerators
*/
void pidgin_load_accels(void);
/**
* pidgin_retrieve_user_info:
* @conn: The connection to get information from.
* @name: The user to get information about.
*
* Get information about a user. Show immediate feedback.
*/
void pidgin_retrieve_user_info(PurpleConnection *conn, const char *name);
/**
* pidgin_retrieve_user_info_in_chat:
* @conn: The connection to get information from.
* @name: The user to get information about.
* @chatid: The chat id.
*
* Get information about a user in a chat. Show immediate feedback.
*/
void pidgin_retrieve_user_info_in_chat(PurpleConnection *conn, const char *name, int chatid);
/**
* pidgin_parse_x_im_contact:
* @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.
*
* Parses an application/x-im-contact MIME message and returns the
* data inside.
*
* Returns: TRUE if the message was parsed for the minimum necessary data.
* FALSE otherwise.
*/
gboolean pidgin_parse_x_im_contact(const char *msg, gboolean all_accounts,
PurpleAccount **ret_account,
char **ret_protocol, char **ret_username,
char **ret_alias);
/**
* pidgin_set_accessible_label:
* @w: The widget that we want to name.
* @l: A GtkLabel that we want to use as the ATK name for the widget.
*
* Sets an ATK name for a given widget. Also sets the labelled-by
* and label-for ATK relationships.
*/
void pidgin_set_accessible_label(GtkWidget *w, GtkLabel *l);
/**
* pidgin_set_accessible_relations:
* @w: The widget that we want to label.
* @l: A GtkLabel that we want to use as the label for the widget.
*
* Sets the labelled-by and label-for ATK relationships.
*/
void pidgin_set_accessible_relations(GtkWidget *w, GtkLabel *l);
/**
* pidgin_menu_popup_at_treeview_selection:
* @menu: The menu to show.
* @treeview: The treeview to use for positioning.
*
* Open a menu popup at the position determined by the selection of a given
* treeview. This function is similar to @gtk_menu_popup_at_pointer, but should
* be used when the menu is activated via a keyboard shortcut.
*/
void pidgin_menu_popup_at_treeview_selection(GtkWidget *menu, GtkWidget *treeview);
/**
* pidgin_dnd_file_manage:
* @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)
*
* Manages drag'n'drop of files.
*/
void pidgin_dnd_file_manage(GtkSelectionData *sd, PurpleAccount *account, const char *who);
/**
* pidgin_buddy_icon_get_scale_size:
*
* Convenience wrapper for purple_buddy_icon_spec_get_scaled_size
*/
void pidgin_buddy_icon_get_scale_size(GdkPixbuf *buf, PurpleBuddyIconSpec *spec, PurpleBuddyIconScaleFlags rules, int *width, int *height);
/**
* pidgin_create_protocol_icon:
* @account: The account.
* @size: The size of the icon to return.
*
* Returns the base image to represent the account, based on
* the currently selected theme.
*
* Returns: (transfer full): 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.
*/
GdkPixbuf *pidgin_create_protocol_icon(PurpleAccount *account, PidginProtocolIconSize size);
/**
* pidgin_create_icon_from_protocol:
* @protocol: The #PurpleProtocol instance.
* @size: The size of the icon to return.
* @account: (nullable): An optional #PurpleAccount to use.
*
* Returns the base image to represent @protocol based on the currently
* selected theme. If @account is not %NULL then the returned icon will
* represent the account.
*
* Returns: (transfer full): 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.
*
* Since: 3.0.0
*/
GdkPixbuf *pidgin_create_icon_from_protocol(PurpleProtocol *protocol, PidginProtocolIconSize size, PurpleAccount *account);
/**
* pidgin_stock_id_from_status_primitive:
* @prim: The status primitive
*
* Returns an appropriate stock-id for a status primitive.
*
* Returns: The stock-id
*/
const char *pidgin_stock_id_from_status_primitive(PurpleStatusPrimitive prim);
/**
* pidgin_append_menu_action:
* @menu: The menu to append to.
* @act: The PurpleActionMenu to append.
* @gobject: The object to be passed to the action callback.
*
* Append a PurpleActionMenu to a menu.
*
* Returns: (transfer full): The menuitem added.
*/
GtkWidget *pidgin_append_menu_action(GtkWidget *menu, PurpleActionMenu *act,
gpointer gobject);
/**
* pidgin_set_cursor:
* @widget: The widget for which to set the mouse pointer
* @cursor_type: The type of cursor to set
*
* 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.
*/
void pidgin_set_cursor(GtkWidget *widget, GdkCursorType cursor_type);
/**
* pidgin_clear_cursor:
*
* 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.
*/
void pidgin_clear_cursor(GtkWidget *widget);
/**
* pidgin_buddy_icon_chooser_new:
* @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
*
* Creates a File Selection widget for choosing a buddy icon
*
* Returns: (transfer full): The file dialog
*/
GtkFileChooserNative *pidgin_buddy_icon_chooser_new(
GtkWindow *parent, void (*callback)(const char *, gpointer),
gpointer data);
/**
* pidgin_convert_buddy_icon:
* @protocol: The protocol 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.
*
* Converts a buddy icon to the required size and format
*
* Returns: The converted image data, or %NULL if an error occurred.
*/
gpointer pidgin_convert_buddy_icon(PurpleProtocol *protocol, const char *path, size_t *len);
/**
* pidgin_tree_view_search_equal_func:
*
* 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);
*
*/
gboolean pidgin_tree_view_search_equal_func(GtkTreeModel *model, gint column,
const gchar *key, GtkTreeIter *iter, gpointer data);
/**
* pidgin_get_dim_grey_string:
* @widget: The widget to return dim grey for
*
* Returns an HTML-style color string for use as a dim grey
* string
*
* Returns: The dim grey string
*/
const char *pidgin_get_dim_grey_string(GtkWidget *widget);
/**
* pidgin_text_combo_box_entry_new:
* @default_item: Initial contents of GtkEntry
* @items: (element-type utf8): GList containing strings to add to GtkComboBox
*
* Create a simple text GtkComboBoxEntry equivalent
*
* Returns: (transfer full): A newly created text GtkComboBox containing a GtkEntry
* child.
*/
GtkWidget *pidgin_text_combo_box_entry_new(const char *default_item, GList *items);
/**
* pidgin_text_combo_box_entry_get_text:
* @widget: The simple text GtkComboBoxEntry equivalent widget
*
* Retrieve the text from the entry of the simple text GtkComboBoxEntry equivalent
*
* Returns: The text in the widget's entry. It must not be freed
*/
const char *pidgin_text_combo_box_entry_get_text(GtkWidget *widget);
/**
* pidgin_auto_parent_window:
* @window: The window to make transient.
*
* Automatically make a window transient to a suitable parent window.
*
* Returns: Whether the window was made transient or not.
*/
gboolean pidgin_auto_parent_window(GtkWidget *window);
/**
* pidgin_add_widget_to_vbox:
* @vbox: The vertically-oriented GtkBox 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.
*
* Add a labelled widget to a GtkBox
*
* Returns: (transfer full): A GtkBox already added to the GtkBox 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);
/**
* pidgin_pixbuf_from_data:
* @buf: The raw binary image data.
* @count: The length of buf in bytes.
*
* Create a GdkPixbuf from a chunk of image data.
*
* Returns: (transfer full): 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);
/**
* pidgin_pixbuf_anim_from_data:
* @buf: The raw binary image data.
* @count: The length of buf in bytes.
*
* Create a GdkPixbufAnimation from a chunk of image data.
*
* Returns: (transfer full): 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);
/**
* pidgin_pixbuf_from_image:
* @image: a PurpleImage.
*
* Create a GdkPixbuf from a PurpleImage.
*
* Returns: (transfer full): a GdkPixbuf created from the @image.
*/
GdkPixbuf *
pidgin_pixbuf_from_image(PurpleImage *image);
/**
* pidgin_pixbuf_new_from_file:
* @filename: Name of file to load, in the GLib file name encoding
*
* 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.
*
* Returns: (transfer full): The GdkPixbuf if successful. Otherwise NULL is returned and
* a warning is logged.
*/
GdkPixbuf *pidgin_pixbuf_new_from_file(const char *filename);
/**
* pidgin_pixbuf_new_from_file_at_size:
* @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
*
* 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.
*
* Returns: (transfer full): 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);
/**
* pidgin_pixbuf_new_from_file_at_scale:
* @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
*
* 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.
*
* Returns: (transfer full): 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);
/**
* pidgin_pixbuf_scale_down:
* @src: The source image.
* @max_width: Maximum width in px.
* @max_height: Maximum height in px.
* @interp_type: Interpolation method.
* @preserve_ratio: %TRUE to preserve image's aspect ratio.
*
* Scales the image to the desired dimensions. If image is smaller, it will be
* returned without modifications.
*
* If new image is created, @src reference cound will be decreased and new image
* with a ref count of 1 will be returned.
*
* Returns: (transfer full): The image with proper sizing. %NULL in case of error.
*/
GdkPixbuf *
pidgin_pixbuf_scale_down(GdkPixbuf *src, guint max_width, guint max_height,
GdkInterpType interp_type, gboolean preserve_ratio);
/**
* pidgin_make_scrollable:
* @child: The child widget
* @hscrollbar_policy: Horizontal scrolling policy
* @vscrollbar_policy: Vertical scrolling policy
* @shadow_type: Shadow type
* @width: Desired widget width, or -1 for default
* @height: Desired widget height, or -1 for default
*
* Add scrollbars to a widget
*
* Returns: (transfer full): A scrolled window with @child packed inside of it.
*/
GtkWidget *pidgin_make_scrollable(GtkWidget *child, GtkPolicyType hscrollbar_policy, GtkPolicyType vscrollbar_policy, GtkShadowType shadow_type, int width, int height);
G_END_DECLS
#endif /* _PIDGINUTILS_H_ */