gnt.h

   1 /**
   2  * @defgroup gnt GNT (GLib Ncurses Toolkit)
   3  *
   4  * GNT is an ncurses toolkit for creating text-mode graphical user interfaces
   5  * in a fast and easy way.
   6  */
   7 /**
   8  * @file gnt.h GNT API
   9  * @ingroup gnt
  10  */
  11 /*
  12  * GNT - The GLib Ncurses Toolkit
  13  *
  14  * GNT is the legal property of its developers, whose names are too numerous
  15  * to list here.  Please refer to the COPYRIGHT file distributed with this
  16  * source distribution.
  17  *
  18  * This library is free software; you can redistribute it and/or modify
  19  * it under the terms of the GNU General Public License as published by
  20  * the Free Software Foundation; either version 2 of the License, or
  21  * (at your option) any later version.
  22  *
  23  * This program is distributed in the hope that it will be useful,
  24  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  25  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  26  * GNU General Public License for more details.
  27  *
  28  * You should have received a copy of the GNU General Public License
  29  * along with this program; if not, write to the Free Software
  30  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  31  */
  32
  33 #ifndef GNT_H
  34 #define GNT_H
  35
  36 #include <glib.h>
  37 #include "gntwidget.h"
  38 #include "gntclipboard.h"
  39 #include "gntcolors.h"
  40 #include "gntkeys.h"
  41
  42 /**
  43  * Get things to compile in Glib < 2.8
  44  */
  45 #if !GLIB_CHECK_VERSION(2,8,0)
  46         #define G_PARAM_STATIC_NAME  G_PARAM_PRIVATE
  47         #define G_PARAM_STATIC_NICK  G_PARAM_PRIVATE
  48         #define G_PARAM_STATIC_BLURB  G_PARAM_PRIVATE
  49 #endif
  50
  51 /**
  52  * Initialize GNT.
  53  */
  54 void gnt_init(void);
  55
  56 /**
  57  * Start running the mainloop for gnt.
  58  */
  59 void gnt_main(void);
  60
  61 /**
  62  * Check whether the terminal is capable of UTF8 display.
  63  *
  64  * @return  @c FALSE if the terminal is capable of drawing UTF-8, @c TRUE otherwise.
  65  */
  66 gboolean gnt_ascii_only(void);
  67
  68 /**
  69  * Present a window. If the event was triggered because of user interaction,
  70  * the window is moved to the foreground. Otherwise, the Urgent hint is set.
  71  *
  72  * @param window   The window the present.
  73  *
  74  * @since 2.0.0 (gnt), 2.1.0 (pidgin)
  75  */
  76 void gnt_window_present(GntWidget *window);
  77
  78 /**
  79  * @internal
  80  * Use #gnt_widget_show instead.
  81  */
  82 void gnt_screen_occupy(GntWidget *widget);
  83
  84 /**
  85  * @internal
  86  * Use #gnt_widget_hide instead.
  87  */
  88 void gnt_screen_release(GntWidget *widget);
  89
  90 /**
  91  * @internal
  92  * Use #gnt_widget_draw instead.
  93  */
  94 void gnt_screen_update(GntWidget *widget);
  95
  96 /**
  97  * Resize a widget.
  98  *
  99  * @param widget  The widget to resize.
 100  * @param width   The desired width.
 101  * @param height  The desired height.
 102  */
 103 void gnt_screen_resize_widget(GntWidget *widget, int width, int height);
 104
 105 /**
 106  * Move a widget.
 107  *
 108  * @param widget The widget to move.
 109  * @param x      The desired x-coordinate.
 110  * @param y      The desired y-coordinate.
 111  */
 112 void gnt_screen_move_widget(GntWidget *widget, int x, int y);
 113
 114 /**
 115  * Rename a widget.
 116  *
 117  * @param widget  The widget to rename.
 118  * @param text    The new name for the widget.
 119  */
 120 void gnt_screen_rename_widget(GntWidget *widget, const char *text);
 121
 122 /**
 123  * Check whether a widget has focus.
 124  *
 125  * @param widget  The widget.
 126  *
 127  * @return  @c TRUE if the widget has the current focus, @c FALSE otherwise.
 128  */
 129 gboolean gnt_widget_has_focus(GntWidget *widget);
 130
 131 /**
 132  * Set the URGENT hint for a widget.
 133  *
 134  * @param widget  The widget to set the URGENT hint for.
 135  */
 136 void gnt_widget_set_urgent(GntWidget *widget);
 137
 138 /**
 139  * Register a global action.
 140  *
 141  * @param label      The user-visible label for the action.
 142  * @param callback   The callback function for the action.
 143  */
 144 void gnt_register_action(const char *label, void (*callback)(void));
 145
 146 /**
 147  * Show a menu.
 148  *
 149  * @param menu  The menu to display.
 150  *
 151  * @return @c TRUE if the menu is displayed, @c FALSE otherwise (e.g., if another menu is currently displayed).
 152  */
 153 gboolean gnt_screen_menu_show(gpointer menu);
 154
 155 /**
 156  * Terminate the mainloop of gnt.
 157  */
 158 void gnt_quit(void);
 159
 160 /**
 161  * Get the global clipboard.
 162  *
 163  * @return  The clipboard.
 164  */
 165 GntClipboard * gnt_get_clipboard(void);
 166
 167 /**
 168  * Get the string in the clipboard.
 169  *
 170  * @return A copy of the string in the clipboard. The caller must @c g_free the string.
 171  */
 172 gchar * gnt_get_clipboard_string(void);
 173
 174 /**
 175  * Set the contents of the global clipboard.
 176  *
 177  * @param string  The new content of the new clipboard.
 178  */
 179 void gnt_set_clipboard_string(const gchar *string);
 180
 181 /**
 182  * Spawn a different application that will consume the console.
 183  *
 184  * @param wd    The working directory for the new application.
 185  * @param argv  The argument vector.
 186  * @param envp  The environment, or @c NULL.
 187  * @param stin  Location to store the child's stdin, or @c NULL.
 188  * @param stout Location to store the child's stdout, or @c NULL.
 189  * @param sterr Location to store the child's stderr, or @c NULL.
 190  * @param callback   The callback to call after the child exits.
 191  * @param data  The data to pass to the callback.
 192  *
 193  * @return  @c TRUE if the child was successfully spawned, @c FALSE otherwise.
 194  */
 195 gboolean gnt_giveup_console(const char *wd, char **argv, char **envp,
 196                 gint *stin, gint *stout, gint *sterr,
 197                 void (*callback)(int status, gpointer data), gpointer data);
 198
 199 /**
 200  * Check whether a child process is in control of the current terminal.
 201  *
 202  * @return @c TRUE if a child process (eg., PAGER) is occupying the current
 203  *         terminal, @c FALSE otherwise.
 204  */
 205 gboolean gnt_is_refugee(void);
 206
 207 #endif /* GNT_H */