1 /* 2 * GNT - The GLib Ncurses Toolkit 3 * 4 * GNT is the legal property of its developers, whose names are too numerous 5 * to list here. Please refer to the COPYRIGHT file distributed with this 6 * source distribution. 7 * 8 * This library is free software; you can redistribute it and/or modify 9 * it under the terms of the GNU General Public License as published by 10 * the Free Software Foundation; either version 2 of the License, or 11 * (at your option) any later version. 12 * 13 * This program is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 * GNU General Public License for more details. 17 * 18 * You should have received a copy of the GNU General Public License 19 * along with this program; if not, write to the Free Software 20 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA 21 */ 22 23 #ifndef GNT_UTILS_H 24 #define GNT_UTILS_H 25 /** 26 * SECTION:gntutils 27 * @section_id: libgnt-gntutils 28 * @title: Utility functions 29 * @short_description: Various internal utility functions 30 */ 31 32 #include <glib.h> 33 34 #include "gnt.h" 35 #include "gnttextview.h" 36 #include "gntwidget.h" 37 38 typedef gpointer (*GDupFunc)(gconstpointer data); 39 40 /** 41 * gnt_util_get_text_bound: 42 * @text: The text to be displayed. 43 * @width: The width required is set here, if not %NULL. 44 * @height: The height required is set here, if not %NULL. 45 * 46 * Compute the width and height required to view the text on the screen. 47 */ 48 void gnt_util_get_text_bound(const char *text, int *width, int *height); 49 50 /* excluding *end */ 51 /** 52 * gnt_util_onscreen_width: 53 * @start: The beginning of the string. 54 * @end: The end of the string. The width returned is the width 55 * upto (but not including) end. If end is NULL, then start 56 * is considered as a %NULL-terminated string. 57 * 58 * Get the onscreen width of a string, or a substring. 59 * 60 * Returns: The on-screen width of the string. 61 */ 62 int gnt_util_onscreen_width(const char *start, const char *end); 63 64 /** 65 * gnt_util_onscreen_width_to_pointer: 66 * @str: The string. 67 * @len: The length to consider. If non-positive, the entire screenlength is used. 68 * @w: The actual width of the string upto the returned offset, if not %NULL. 69 * 70 * Computes and returns the string after a specific number of onscreen characters. 71 * 72 * Returns: The string after len offset. 73 */ 74 const char *gnt_util_onscreen_width_to_pointer(const char *str, int len, int *w); 75 76 /** 77 * gnt_util_onscreen_fit_string: 78 * @string: The string. 79 * @maxw: The width that the string should fit into. If maxw is <= 0, 80 * then the available maximum width is used. 81 * 82 * Inserts newlines in 'string' where necessary so that its onscreen width is 83 * no more than 'maxw'. 84 * 85 * Returns: A newly allocated string that needs to be freed by the caller. 86 */ 87 char * gnt_util_onscreen_fit_string(const char *string, int maxw); 88 89 /** 90 * g_hash_table_duplicate: 91 * @src: The source hashtable. 92 * @hash: (scope call): The hash-function to use. 93 * @equal: The hash-equal function to use. 94 * @key_d: The key-destroy function to use. 95 * @value_d: The value-destroy function to use. 96 * @key_dup: (scope call): The function to use to duplicate the key. 97 * @value_dup: (scope call): The function to use to duplicate the value. 98 * 99 * Duplicate the contents of a hastable. 100 * 101 * Returns: (transfer full): The new hashtable. 102 */ 103 GHashTable * g_hash_table_duplicate(GHashTable *src, GHashFunc hash, GEqualFunc equal, GDestroyNotify key_d, GDestroyNotify value_d, GDupFunc key_dup, GDupFunc value_dup); 104 105 /** 106 * gnt_boolean_handled_accumulator: 107 * 108 * To be used with g_signal_new. Look in the key_pressed signal-definition in 109 * gntwidget.c for usage. 110 * 111 * Deprecated: 2.14.0: Use g_signal_accumulator_true_handled() instead. 112 */ 113 #ifndef GNT_DISABLE_DEPRECATED 114 gboolean gnt_boolean_handled_accumulator(GSignalInvocationHint *ihint, 115 GValue *return_accu, 116 const GValue *handler_return, 117 gpointer dummy) G_GNUC_DEPRECATED; 118 #endif 119 120 /** 121 * gnt_widget_bindings_view: 122 * @widget: The widget to get bindings for. 123 * 124 * Get a helpful display about the bindings of a widget. 125 * 126 * Returns: (transfer full): Returns a GntTree populated with "key" -> "binding" 127 * for the widget. 128 * 129 * Deprecated: 2.14.0: Use gnt_bindable_bindings_view() instead. 130 */ 131 #ifndef GNT_DISABLE_DEPRECATED 132 GntWidget *gnt_widget_bindings_view(GntWidget *widget) G_GNUC_DEPRECATED; 133 #endif 134 135 /** 136 * gnt_util_parse_widgets: 137 * @string: The XML string. 138 * @num: The number of widgets to return, followed by 'num' GntWidget ** 139 * 140 * Parse widgets from an XML description. For example, 141 * 142 * <programlisting> 143 * GntWidget *win, *button; 144 * gnt_util_parse_widgets("\ 145 * <vwindow id='0' fill='0' align='2'> \ 146 * <label>This is a test</label> \ 147 * <button id='1'>OK</button> \ 148 * </vwindow>", 149 * 2, &win, &button); 150 * </programlisting> 151 */ 152 void gnt_util_parse_widgets(const char *string, int num, ...); 153 154 /** 155 * gnt_util_parse_xhtml_to_textview: 156 * @string: The XHTML string 157 * @tv: The GntTextView 158 * 159 * Parse an XHTML string and add it in a GntTextView with 160 * appropriate text flags. 161 * 162 * Returns: %TRUE if the string was added to the textview properly, %FALSE otherwise. 163 * 164 * Since: 2.2.0 165 */ 166 gboolean gnt_util_parse_xhtml_to_textview(const char *string, GntTextView *tv); 167 168 /** 169 * gnt_util_set_trigger_widget: 170 * @widget: The widget 171 * @key: The key to trigger the button 172 * @button: The button to trigger 173 * 174 * Make some keypress activate a button when some key is pressed with 'wid' in focus. 175 * 176 * Since: 2.1.0 177 */ 178 void gnt_util_set_trigger_widget(GntWidget *widget, const char *key, GntWidget *button); 179 180 #endif /* GNT_UTILS_H */ 181