Seal VTE when VTE_SEAL_ENABLE is given, not GSEAL_ENABLE
[vte.git] / src / vte.h
1 /*
2  * Copyright (C) 2001,2002,2003,2009,2010 Red Hat, Inc.
3  *
4  * This is free software; you can redistribute it and/or modify it under
5  * the terms of the GNU Library General Public License as published by
6  * the Free Software Foundation; either version 2 of the License, or
7  * (at your option) any later version.
8  *
9  * This program is distributed in the hope that it will be useful, but
10  * WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12  * General Public License for more details.
13  *
14  * You should have received a copy of the GNU Library General Public
15  * License along with this program; if not, write to the Free Software
16  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
17  */
18
19 #ifndef vte_vte_h_included
20 #define vte_vte_h_included
21
22 #include <glib.h>
23 #include <gio/gio.h>
24 #include <pango/pango.h>
25 #include <gtk/gtk.h>
26
27 #define __VTE_VTE_H_INSIDE__ 1
28
29 #include "vtepty.h"
30 #include "vtetypebuiltins.h"
31 #include "vteversion.h"
32
33 #undef __VTE_VTE_H_INSIDE__
34
35 G_BEGIN_DECLS
36
37 #ifdef VTE_SEAL_ENABLE
38 #define _VTE_SEAL(name) _vte_sealed__ ## name
39 #else
40 #define _VTE_SEAL(name) name
41 #endif
42
43 #ifdef VTE_DISABLE_DEPRECATED
44 #define _VTE_DEPRECATED(name) _vte_deprecated__ ## name
45 #else
46 #define _VTE_DEPRECATED(name) name
47 #endif
48
49 #define VTE_TYPE_TERMINAL            (vte_terminal_get_type())
50 #define VTE_TERMINAL(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), VTE_TYPE_TERMINAL, VteTerminal))
51 #define VTE_TERMINAL_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass),  VTE_TYPE_TERMINAL, VteTerminalClass))
52 #define VTE_IS_TERMINAL(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), VTE_TYPE_TERMINAL))
53 #define VTE_IS_TERMINAL_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass),  VTE_TYPE_TERMINAL))
54 #define VTE_TERMINAL_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj),  VTE_TYPE_TERMINAL, VteTerminalClass))
55
56 typedef struct _VteTerminal         VteTerminal;
57 typedef struct _VteTerminalPrivate  VteTerminalPrivate;
58 typedef struct _VteTerminalClass    VteTerminalClass;
59
60 /**
61  * VteTerminal:
62  *
63  * All of these fields should be considered read-only and deprecated.
64  */
65 struct _VteTerminal {
66         GtkWidget widget;
67         /*< private >*/
68         GtkAdjustment *_VTE_SEAL(adjustment);   /* Scrolling adjustment. */
69
70         /* Metric and sizing data. */
71         glong _VTE_SEAL(char_width), _VTE_SEAL(char_height);    /* dimensions of character cells */
72         glong _VTE_SEAL(char_ascent), _VTE_SEAL(char_descent); /* important font metrics */
73         glong _VTE_SEAL(row_count), _VTE_SEAL(column_count);    /* dimensions of the window */
74
75         /* Titles. */
76         char *_VTE_SEAL(window_title);
77         char *_VTE_SEAL(icon_title);
78
79         /*< private >*/
80         VteTerminalPrivate *pvt;
81 };
82
83 /**
84  * VteTerminalClass:
85  *
86  * All of these fields should be considered read-only, except for derived classes.
87  */
88 struct _VteTerminalClass {
89         /*< public > */
90         /* Inherited parent class. */
91         GtkWidgetClass parent_class;
92
93         /*< protected > */
94         /* Default signal handlers. */
95         void (*eof)(VteTerminal* terminal);
96         void (*child_exited)(VteTerminal* terminal);
97         void (*emulation_changed)(VteTerminal* terminal);
98         void (*encoding_changed)(VteTerminal* terminal);
99         void (*char_size_changed)(VteTerminal* terminal, guint char_width, guint char_height);
100         void (*window_title_changed)(VteTerminal* terminal);
101         void (*icon_title_changed)(VteTerminal* terminal);
102         void (*selection_changed)(VteTerminal* terminal);
103         void (*contents_changed)(VteTerminal* terminal);
104         void (*cursor_moved)(VteTerminal* terminal);
105         void (*status_line_changed)(VteTerminal* terminal);
106         void (*commit)(VteTerminal* terminal, const gchar *text, guint size);
107
108         void (*deiconify_window)(VteTerminal* terminal);
109         void (*iconify_window)(VteTerminal* terminal);
110         void (*raise_window)(VteTerminal* terminal);
111         void (*lower_window)(VteTerminal* terminal);
112         void (*refresh_window)(VteTerminal* terminal);
113         void (*restore_window)(VteTerminal* terminal);
114         void (*maximize_window)(VteTerminal* terminal);
115         void (*resize_window)(VteTerminal* terminal, guint width, guint height);
116         void (*move_window)(VteTerminal* terminal, guint x, guint y);
117
118         void (*increase_font_size)(VteTerminal* terminal);
119         void (*decrease_font_size)(VteTerminal* terminal);
120
121         void (*text_modified)(VteTerminal* terminal);
122         void (*text_inserted)(VteTerminal* terminal);
123         void (*text_deleted)(VteTerminal* terminal);
124         void (*text_scrolled)(VteTerminal* terminal, gint delta);
125         void (*copy_clipboard)(VteTerminal* terminal);
126         void (*paste_clipboard)(VteTerminal* terminal);
127
128         void (* set_scroll_adjustments) (GtkWidget *widget,
129                                          GtkAdjustment *hadjustment,
130                                          GtkAdjustment *vadjustment);
131
132         void (*beep)(VteTerminal* terminal);
133
134         /* Padding for future expansion. */
135         void (*vte_reserved3)(void);
136         void (*vte_reserved4)(void);
137
138         /*< private > */
139         /* Signals we might emit. */
140         guint _VTE_DEPRECATED(eof_signal);
141         guint _VTE_DEPRECATED(child_exited_signal);
142         guint _VTE_DEPRECATED(emulation_changed_signal);
143         guint _VTE_DEPRECATED(encoding_changed_signal);
144         guint _VTE_DEPRECATED(char_size_changed_signal);
145         guint _VTE_DEPRECATED(window_title_changed_signal);
146         guint _VTE_DEPRECATED(icon_title_changed_signal);
147         guint _VTE_DEPRECATED(selection_changed_signal);
148         guint _VTE_DEPRECATED(contents_changed_signal);
149         guint _VTE_DEPRECATED(cursor_moved_signal);
150         guint _VTE_DEPRECATED(status_line_changed_signal);
151         guint _VTE_DEPRECATED(commit_signal);
152         guint _VTE_DEPRECATED(deiconify_window_signal);
153         guint _VTE_DEPRECATED(iconify_window_signal);
154         guint _VTE_DEPRECATED(raise_window_signal);
155         guint _VTE_DEPRECATED(lower_window_signal);
156         guint _VTE_DEPRECATED(refresh_window_signal);
157         guint _VTE_DEPRECATED(restore_window_signal);
158         guint _VTE_DEPRECATED(maximize_window_signal);
159         guint _VTE_DEPRECATED(resize_window_signal);
160         guint _VTE_DEPRECATED(move_window_signal);
161         guint _VTE_DEPRECATED(increase_font_size_signal);
162         guint _VTE_DEPRECATED(decrease_font_size_signal);
163         guint _VTE_DEPRECATED(text_modified_signal);
164         guint _VTE_DEPRECATED(text_inserted_signal);
165         guint _VTE_DEPRECATED(text_deleted_signal);
166         guint _VTE_DEPRECATED(text_scrolled_signal);
167         guint _VTE_DEPRECATED(reserved1);
168         guint _VTE_DEPRECATED(reserved2);
169         guint _VTE_DEPRECATED(reserved3);
170         guint _VTE_DEPRECATED(reserved4);
171         guint _VTE_DEPRECATED(reserved5);
172         guint _VTE_DEPRECATED(reserved6);
173 };
174
175 /**
176  * VteTerminalEraseBinding:
177  * @VTE_ERASE_AUTO: For backspace, attempt to determine the right value from the terminal's IO settings.  For delete, use the control sequence.
178  * @VTE_ERASE_ASCII_BACKSPACE: Send an ASCII backspace character (0x08).
179  * @VTE_ERASE_ASCII_DELETE: Send an ASCII delete character (0x7F).
180  * @VTE_ERASE_DELETE_SEQUENCE: Send the "@@7" control sequence.
181  * @VTE_ERASE_TTY: Send terminal's "erase" setting.
182  *
183  * An enumerated type which can be used to indicate which string the terminal
184  * should send to an application when the user presses the Delete or Backspace
185  * keys.
186  */
187 typedef enum {
188         VTE_ERASE_AUTO,
189         VTE_ERASE_ASCII_BACKSPACE,
190         VTE_ERASE_ASCII_DELETE,
191         VTE_ERASE_DELETE_SEQUENCE,
192         VTE_ERASE_TTY
193 } VteTerminalEraseBinding;
194
195 /**
196  * VteTerminalCursorBlinkMode:
197  * @VTE_CURSOR_BLINK_SYSTEM: Follow GTK+ settings for cursor blinking.
198  * @VTE_CURSOR_BLINK_ON: Cursor blinks.
199  * @VTE_CURSOR_BLINK_OFF: Cursor does not blink.
200  *
201  * An enumerated type which can be used to indicate the cursor blink mode
202  * for the terminal.
203  */
204 typedef enum {
205         VTE_CURSOR_BLINK_SYSTEM,
206         VTE_CURSOR_BLINK_ON,
207         VTE_CURSOR_BLINK_OFF
208 } VteTerminalCursorBlinkMode;
209
210 /**
211  * VteTerminalCursorShape:
212  * @VTE_CURSOR_SHAPE_BLOCK: Draw a block cursor.  This is the default.
213  * @VTE_CURSOR_SHAPE_IBEAM: Draw a vertical bar on the left side of character.
214  * This is similar to the default cursor for other GTK+ widgets.
215  * @VTE_CURSOR_SHAPE_UNDERLINE: Draw a horizontal bar below the character.
216  *
217  * An enumerated type which can be used to indicate what should the terminal
218  * draw at the cursor position.
219  */
220 typedef enum {
221         VTE_CURSOR_SHAPE_BLOCK,
222         VTE_CURSOR_SHAPE_IBEAM,
223         VTE_CURSOR_SHAPE_UNDERLINE
224 } VteTerminalCursorShape;
225
226 /* The structure we return as the supplemental attributes for strings. */
227 struct _VteCharAttributes {
228         /*< private >*/
229         long row, column;
230         GdkColor fore, back;
231         guint underline:1, strikethrough:1;
232 };
233 typedef struct _VteCharAttributes VteCharAttributes;
234
235 /* The name of the same structure in the 0.10 series, for API compatibility. */
236 struct vte_char_attributes {
237         /*< private >*/
238         long row, column;
239         GdkColor fore, back;
240         guint underline:1, strikethrough:1;
241 };
242
243 typedef gboolean (*VteSelectionFunc)(VteTerminal *terminal,
244                                      glong column,
245                                      glong row,
246                                      gpointer data);
247
248 /* The widget's type. */
249 GType vte_terminal_get_type(void);
250
251 GtkWidget *vte_terminal_new(void);
252
253 VtePty *vte_terminal_pty_new (VteTerminal *terminal,
254                               VtePtyFlags flags,
255                               GError **error);
256
257 void vte_terminal_watch_child (VteTerminal *terminal,
258                                GPid child_pid);
259
260 gboolean vte_terminal_fork_command_full(VteTerminal *terminal,
261                                         VtePtyFlags pty_flags,
262                                         const char *working_directory,
263                                         char **argv,
264                                         char **envv,
265                                         GSpawnFlags spawn_flags,
266                                         GSpawnChildSetupFunc child_setup,
267                                         gpointer child_setup_data,
268                                         GPid *child_pid /* out */,
269                                         GError **error);
270
271 /* Send data to the terminal to display, or to the terminal's forked command
272  * to handle in some way.  If it's 'cat', they should be the same. */
273 void vte_terminal_feed(VteTerminal *terminal, const char *data, glong length);
274 void vte_terminal_feed_child(VteTerminal *terminal, const char *text, glong length);
275 void vte_terminal_feed_child_binary(VteTerminal *terminal, const char *data, glong length);
276
277 /* Copy currently-selected text to the clipboard, or from the clipboard to
278  * the terminal. */
279 void vte_terminal_copy_clipboard(VteTerminal *terminal);
280 void vte_terminal_paste_clipboard(VteTerminal *terminal);
281 void vte_terminal_copy_primary(VteTerminal *terminal);
282 void vte_terminal_paste_primary(VteTerminal *terminal);
283
284 /* simple manipulation of selection */
285 void vte_terminal_select_all(VteTerminal *terminal);
286 void vte_terminal_select_none(VteTerminal *terminal);
287
288 /* Set the terminal's size. */
289 void vte_terminal_set_size(VteTerminal *terminal,
290                            glong columns, glong rows);
291
292 /* Set various on-off settings. */
293 void vte_terminal_set_audible_bell(VteTerminal *terminal, gboolean is_audible);
294 gboolean vte_terminal_get_audible_bell(VteTerminal *terminal);
295 void vte_terminal_set_visible_bell(VteTerminal *terminal, gboolean is_visible);
296 gboolean vte_terminal_get_visible_bell(VteTerminal *terminal);
297 void vte_terminal_set_scroll_background(VteTerminal *terminal, gboolean scroll);
298 void vte_terminal_set_scroll_on_output(VteTerminal *terminal, gboolean scroll);
299 void vte_terminal_set_scroll_on_keystroke(VteTerminal *terminal,
300                                           gboolean scroll);
301
302 /* Set the color scheme. */
303 void vte_terminal_set_color_dim(VteTerminal *terminal,
304                                 const GdkColor *dim);
305 void vte_terminal_set_color_bold(VteTerminal *terminal,
306                                  const GdkColor *bold);
307 void vte_terminal_set_color_foreground(VteTerminal *terminal,
308                                        const GdkColor *foreground);
309 void vte_terminal_set_color_background(VteTerminal *terminal,
310                                        const GdkColor *background);
311 void vte_terminal_set_color_cursor(VteTerminal *terminal,
312                                    const GdkColor *cursor_background);
313 void vte_terminal_set_color_highlight(VteTerminal *terminal,
314                                       const GdkColor *highlight_background);
315 void vte_terminal_set_colors(VteTerminal *terminal,
316                              const GdkColor *foreground,
317                              const GdkColor *background,
318                              const GdkColor *palette,
319                              glong palette_size);
320 void vte_terminal_set_default_colors(VteTerminal *terminal);
321
322 /* Background effects. */
323 void vte_terminal_set_background_image(VteTerminal *terminal, GdkPixbuf *image);
324 void vte_terminal_set_background_image_file(VteTerminal *terminal,
325                                             const char *path);
326 void vte_terminal_set_background_tint_color(VteTerminal *terminal,
327                                             const GdkColor *color);
328 void vte_terminal_set_background_saturation(VteTerminal *terminal,
329                                             double saturation);
330 void vte_terminal_set_background_transparent(VteTerminal *terminal,
331                                              gboolean transparent);
332 void vte_terminal_set_opacity(VteTerminal *terminal, guint16 opacity);
333
334 /* Set whether or not the cursor blinks. */
335 void vte_terminal_set_cursor_blink_mode(VteTerminal *terminal,
336                                         VteTerminalCursorBlinkMode mode);
337 VteTerminalCursorBlinkMode vte_terminal_get_cursor_blink_mode(VteTerminal *terminal);
338
339 /* Set cursor shape */
340 void vte_terminal_set_cursor_shape(VteTerminal *terminal,
341                                    VteTerminalCursorShape shape);
342 VteTerminalCursorShape vte_terminal_get_cursor_shape(VteTerminal *terminal);
343
344 /* Set the number of scrollback lines, above or at an internal minimum. */
345 void vte_terminal_set_scrollback_lines(VteTerminal *terminal, glong lines);
346
347 /* Append the input method menu items to a given shell. */
348 void vte_terminal_im_append_menuitems(VteTerminal *terminal,
349                                       GtkMenuShell *menushell);
350
351 /* Set or retrieve the current font. */
352 void vte_terminal_set_font(VteTerminal *terminal,
353                            const PangoFontDescription *font_desc);
354 void vte_terminal_set_font_from_string(VteTerminal *terminal, const char *name);
355 const PangoFontDescription *vte_terminal_get_font(VteTerminal *terminal);
356 void vte_terminal_set_allow_bold(VteTerminal *terminal, gboolean allow_bold);
357 gboolean vte_terminal_get_allow_bold(VteTerminal *terminal);
358
359 /* Check if the terminal is the current selection owner. */
360 gboolean vte_terminal_get_has_selection(VteTerminal *terminal);
361
362 /* Set the list of word chars, optionally using hyphens to specify ranges
363  * (to get a hyphen, place it first), and check if a character is in the
364  * range. */
365 void vte_terminal_set_word_chars(VteTerminal *terminal, const char *spec);
366 gboolean vte_terminal_is_word_char(VteTerminal *terminal, gunichar c);
367
368 /* Set what happens when the user strikes backspace or delete. */
369 void vte_terminal_set_backspace_binding(VteTerminal *terminal,
370                                         VteTerminalEraseBinding binding);
371 void vte_terminal_set_delete_binding(VteTerminal *terminal,
372                                      VteTerminalEraseBinding binding);
373
374 /* Manipulate the autohide setting. */
375 void vte_terminal_set_mouse_autohide(VteTerminal *terminal, gboolean setting);
376 gboolean vte_terminal_get_mouse_autohide(VteTerminal *terminal);
377
378 /* Reset the terminal, optionally clearing the tab stops and line history. */
379 void vte_terminal_reset(VteTerminal *terminal,
380                         gboolean clear_tabstops,
381                         gboolean clear_history);
382
383 /* Read the contents of the terminal, using a callback function to determine
384  * if a particular location on the screen (0-based) is interesting enough to
385  * include.  Each byte in the returned string will have a corresponding
386  * VteCharAttributes structure in the passed GArray, if the array was not %NULL.
387  * Note that it will have one entry per byte, not per character, so indexes
388  * should match up exactly. */
389 char *vte_terminal_get_text(VteTerminal *terminal,
390                             VteSelectionFunc is_selected,
391                             gpointer user_data,
392                             GArray *attributes);
393 char *vte_terminal_get_text_include_trailing_spaces(VteTerminal *terminal,
394                                                     VteSelectionFunc is_selected,
395                                                     gpointer user_data,
396                                                     GArray *attributes);
397 char *vte_terminal_get_text_range(VteTerminal *terminal,
398                                   glong start_row, glong start_col,
399                                   glong end_row, glong end_col,
400                                   VteSelectionFunc is_selected,
401                                   gpointer user_data,
402                                   GArray *attributes);
403 void vte_terminal_get_cursor_position(VteTerminal *terminal,
404                                       glong *column, glong *row);
405 /* Display string matching:  clear all matching expressions. */
406 void vte_terminal_match_clear_all(VteTerminal *terminal);
407
408 /* Add a matching expression, returning the tag the widget assigns to that
409  * expression. */
410 int vte_terminal_match_add_gregex(VteTerminal *terminal, GRegex *regex, GRegexMatchFlags flags);
411 /* Set the cursor to be used when the pointer is over a given match. */
412 void vte_terminal_match_set_cursor(VteTerminal *terminal, int tag,
413                                    GdkCursor *cursor);
414 void vte_terminal_match_set_cursor_type(VteTerminal *terminal,
415                                         int tag, GdkCursorType cursor_type);
416 void vte_terminal_match_set_cursor_name(VteTerminal *terminal,
417                                         int tag, const char *cursor_name);
418 /* Remove a matching expression by tag. */
419 void vte_terminal_match_remove(VteTerminal *terminal, int tag);
420
421 /* Check if a given cell on the screen contains part of a matched string.  If
422  * it does, return the string, and store the match tag in the optional tag
423  * argument. */
424 char *vte_terminal_match_check(VteTerminal *terminal,
425                                glong column, glong row,
426                                int *tag);
427
428 void      vte_terminal_search_set_gregex      (VteTerminal *terminal,
429                                                GRegex      *regex);
430 GRegex   *vte_terminal_search_get_gregex      (VteTerminal *terminal);
431 void      vte_terminal_search_set_wrap_around (VteTerminal *terminal,
432                                                gboolean     wrap_around);
433 gboolean  vte_terminal_search_get_wrap_around (VteTerminal *terminal);
434 gboolean  vte_terminal_search_find_previous   (VteTerminal *terminal);
435 gboolean  vte_terminal_search_find_next       (VteTerminal *terminal);
436
437
438 /* Set the emulation type.  Most of the time you won't need this. */
439 void vte_terminal_set_emulation(VteTerminal *terminal, const char *emulation);
440 const char *vte_terminal_get_emulation(VteTerminal *terminal);
441 const char *vte_terminal_get_default_emulation(VteTerminal *terminal);
442
443 /* Set the character encoding.  Most of the time you won't need this. */
444 void vte_terminal_set_encoding(VteTerminal *terminal, const char *codeset);
445 const char *vte_terminal_get_encoding(VteTerminal *terminal);
446
447 /* Get the contents of the status line. */
448 const char *vte_terminal_get_status_line(VteTerminal *terminal);
449
450 void vte_terminal_set_pty_object(VteTerminal *terminal, VtePty *pty);
451 VtePty *vte_terminal_get_pty_object(VteTerminal *terminal);
452
453 /* Accessors for bindings. */
454 GtkAdjustment *vte_terminal_get_adjustment(VteTerminal *terminal);
455 glong vte_terminal_get_char_width(VteTerminal *terminal);
456 glong vte_terminal_get_char_height(VteTerminal *terminal);
457 glong vte_terminal_get_row_count(VteTerminal *terminal);
458 glong vte_terminal_get_column_count(VteTerminal *terminal);
459 const char *vte_terminal_get_window_title(VteTerminal *terminal);
460 const char *vte_terminal_get_icon_title(VteTerminal *terminal);
461
462 int vte_terminal_get_child_exit_status(VteTerminal *terminal);
463
464
465 /* Writing contents out */
466
467 /**
468  * VteTerminalWriteFlags:
469  * @VTE_TERMINAL_WRITE_DEFAULT: Write contents as UTF-8 text.  This is the default.
470  *
471  * A flag type to determine how terminal contents should be written
472  * to an output stream.
473  */
474 typedef enum {
475   VTE_TERMINAL_WRITE_DEFAULT = 0
476 } VteTerminalWriteFlags;
477
478 gboolean vte_terminal_write_contents (VteTerminal *terminal,
479                                       GOutputStream *stream,
480                                       VteTerminalWriteFlags flags,
481                                       GCancellable *cancellable,
482                                       GError **error);
483
484 #undef _VTE_SEAL
485 #undef _VTE_DEPRECATED
486
487 G_END_DECLS
488
489 #ifndef VTE_DISABLE_DEPRECATED
490 #define __VTE_VTE_H_INSIDE__ 1
491 #include "vtedeprecated.h"
492 #undef __VTE_VTE_H_INSIDE__
493 #endif /* VTE_DISABLE_DEPRECATED */
494
495 #endif