diff --git a/doc/ChangeLog b/doc/ChangeLog index 10bd10eaa..167c2ae73 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2004-07-11 John Luke + + * en/Vte*: some Vte docs + 2004-07-07 Jasper Van Putten * en/Gtk/*.xml : docs for Notebook and RadioButton. diff --git a/doc/en/Vte.xml b/doc/en/Vte.xml new file mode 100644 index 000000000..a7e455b8d --- /dev/null +++ b/doc/en/Vte.xml @@ -0,0 +1,9 @@ + + + + A terminal widget implementation. + + + + + diff --git a/doc/en/Vte/Reaper.xml b/doc/en/Vte/Reaper.xml index c64a7f3d1..07f2d1447 100644 --- a/doc/en/Vte/Reaper.xml +++ b/doc/en/Vte/Reaper.xml @@ -10,8 +10,8 @@ Gtk# is thread aware, but not thread safe; See the Gtk# Thread Programming for details. - To be added - To be added + A singleton object which catches SIGCHLD signals and converts them into GObject-style "child-exited" signals. + Because an application may need to be notified when child processes exit, and because there is only one SIGCHLD handler, the widget relies on a to watch for SIGCHLD notifications and retrieve the exit status of child processes which have exited. GLib.Object @@ -34,7 +34,7 @@ - To be added + Finds the address of the global object, creating the object if necessary. a To be added diff --git a/doc/en/Vte/Terminal.xml b/doc/en/Vte/Terminal.xml index a5ac890f6..21408eb88 100644 --- a/doc/en/Vte/Terminal.xml +++ b/doc/en/Vte/Terminal.xml @@ -12,7 +12,117 @@ A terminal widget implementation. - A is a terminal emulator implemented as a + + + A is a terminal emulator implemented as a . + + + + +using System; +using System.Collections; +using Gtk; +using Gnome; +using Vte; + +class T +{ + static void Main (string[] args) + { + new T (args); + } + + T (string[] args) + { + Program program = new Program ("vte-sharp-test", "0.0", Modules.UI, args); + App app = new App ("vte-sharp-test", "Test for vte widget"); + app.SetDefaultSize (600, 450); + app.DeleteEvent += new DeleteEventHandler (OnAppDelete); + + HBox hbox = new HBox (); + Terminal term = new Terminal (); + term.EncodingChanged += new EventHandler (OnEncodingChanged); + term.CursorBlinks = true; + term.MouseAutohide = true; + term.ScrollOnKeystroke = true; + term.DeleteBinding = TerminalEraseBinding.Auto; + term.BackspaceBinding = TerminalEraseBinding.Auto; + term.Encoding = "UTF-8"; + term.FontFromString = "Monospace 12"; + term.TextDeleted += new EventHandler (OnTextDeleted); + term.ChildExited += new EventHandler (OnChildExited); + + VScrollbar vscroll = new VScrollbar (term.Adjustment); + hbox.PackStart (term); + hbox.PackStart (vscroll); + + Gdk.Color white = new Gdk.Color (); + Gdk.Color.Parse ("white", ref white); + + Gdk.Color black = new Gdk.Color (); + Gdk.Color.Parse ("black", ref black); + term.SetColors (black, white, white, 16); + + string[] argv = Environment.GetCommandLineArgs (); + // wants an array of "variable=value" + string[] envv = new string [Environment.GetEnvironmentVariables ().Count]; + int i = 0; + foreach (DictionaryEntry e in Environment.GetEnvironmentVariables ()) + { + if (e.Key == "" || e.Value == "") + continue; + string tmp = String.Format ("{0}={1}", e.Key, e.Value); + envv[i] = tmp; + i ++; + } + + int pid = term.ForkCommand ( + Environment.GetEnvironmentVariable ("SHELL"), + argv, + envv, + Environment.CurrentDirectory, + false, + true, + true); + Console.WriteLine ("Child pid: {0}", pid); + + app.Contents = hbox; + app.ShowAll (); + program.Run (); + } + + private void OnTextDeleted (object o, EventArgs args) + { + Console.WriteLine ("text deleted"); + } + + private void OnEncodingChanged (object o, EventArgs args) + { + Console.WriteLine ("encoding changed"); + } + + private void OnTextInserted (object o, EventArgs args) + { + Console.WriteLine ("text inserted"); + } + + private void OnChildExited (object o, EventArgs args) + { + // optionally we could just reset instead of quitting + Console.WriteLine ("child exited"); + Application.Quit (); + } + + private void OnAppDelete (object o, DeleteEventArgs args) + { + Application.Quit (); + } +} + + + + + Gtk.Widget @@ -416,9 +526,9 @@ - To be added + Appends menu items for various input methods to the given menu. a - To be added + The user can select one of these items to modify the input method used by the terminal. @@ -432,10 +542,12 @@ - To be added - a - a - To be added + Resets as much of the terminal's internal state as possible. + + to reset tabstops + + to empty the terminal's scrollback buffer + Resets as much of the terminal's internal state as possible, discarding any unprocessed input data, resetting character attributes, cursor state, national character set state, status line, terminal modes (insert/delete), selection state, and encoding. @@ -450,12 +562,12 @@ - To be added - a - a - a + Extracts a view of the visible part of the terminal. + a callback + user data to be passed to the callback + location for storing text attributes a - To be added + If is not , characters will only be read if returns after being passed the column and row, respectively. A structure is added to attributes for each byte added to the returned string detailing the character's position, colors, and other characteristics. @@ -483,8 +595,8 @@ - To be added - To be added + Places the selected text in the terminal in the GDK_SELECTION_PRIMARY selection. + @@ -500,12 +612,19 @@ - To be added - a - a - a - a - To be added + Change the colors of the + the new foreground color, or + the new background color, or + the color palette + the number of entries in + + + The terminal widget uses a 28-color model comprised of the default foreground and background colors, the bold foreground color, the dim foreground color, an eight color palette, and bold versions of the eight color palette, and a dim version of the the eight color palette. + + + must be either 0, 8, 16, or 24. If is and is greater than 0, the new foreground color is taken from palette[7]. If is and is greater than 0, the new background color is taken from palette[0]. If is 8 or 16, the third (dim) and possibly second (bold) 8-color palette is extrapolated from the new background color and the items in palette. + + @@ -519,10 +638,10 @@ - To be added - a - a - To be added + Reads the location of the insertion cursor and returns it. + long which will hold the column + long which will hold the row + The row coordinate is absolute. @@ -536,10 +655,10 @@ - To be added - a - a - To be added + Determines the amount of additional space the widget is using to pad the edges of its visible area. + a in which to store left/right-edge padding + a in which to store top/bottom-edge ypadding + This is necessary for cases where characters in the selected font do not themselves include a padding area and the text itself would be contiguous with the window border. Applications which use the widget's row_count, column_count, char_height, and char_width fields to set geometry hints using gtk_window_set_geometry_hints() will need to add this value to the base size. The values returned in xpad and ypad are the total padding used in each direction, and do not need to be doubled. @@ -550,8 +669,8 @@ - To be added - To be added + Places the selected text in the terminal in the GDK_SELECTION_CLIPBOARD selection. + @@ -566,12 +685,12 @@ - To be added - a - a - a - a - To be added + Checks if the text in and around the specified position matches any of the regular expressions previously set using . + the text column + the text row + pointer to an integer + a string which matches one of the previously set regular expressions + If a match exists, the text string is returned and if is not , the number associated with the matched regular expression will be stored in tag. If more than one regular expression has been set with , then expressions are checked in the order in which they were added. @@ -590,16 +709,16 @@ - To be added - a - a - a - a - a - a - a + Extracts a view of the visible part of the string. + first row to search for data + first column to search for data + last row to search for data + last column to search for data + a callback + user data to be passed to the callback + location for storing text attributes a - To be added + If is not , characters will only be read if returns after being passed the column and row, respectively. A structure is added to attributes for each byte added to the returned string detailing the character's position, colors, and other characteristics. The entire scrollback buffer is scanned, so it is possible to read the entire contents of the buffer using this function. @@ -610,8 +729,8 @@ - To be added - To be added + Clears the list of regular expressions the terminal uses to highlight text when the user moves the mouse cursor. + @@ -624,10 +743,10 @@ - To be added - a - a - To be added + Adds a regular expression to the list of matching expressions. + a regular expression + an integer associated with this expression + When the user moves the mouse cursor over a section of displayed text which matches this expression, the text will be highlighted. @@ -640,9 +759,9 @@ - To be added + Sends a block of UTF-8 text to the child as if it were entered by the user at the keyboard. a - To be added + @@ -655,9 +774,9 @@ - To be added - a - To be added + Removes the regular expression which is associated with the given from the list of expressions which the terminal will highlight when the user moves the mouse cursor over matching text. + the tag of the regex to remove + @@ -668,8 +787,8 @@ - To be added - To be added + Reset the terminal palette to reasonable compiled-in defaults. + @@ -683,10 +802,10 @@ - To be added - a - a - To be added + Attempts to change the terminal's size in terms of rows and columns. + the desired number of columns + the desired number of rows + If the attempt succeeds, the widget will resize itself to the proper size. @@ -697,8 +816,8 @@ - To be added - To be added + Sends the contents of the GDK_SELECTION_CLIPBOARD selection to the terminal's child. + If necessary, the data is converted from UTF-8 to the terminal's current encoding. @@ -709,8 +828,8 @@ - To be added - To be added + Sends the contents of the GDK_SELECTION_PRIMARY selection to the terminal's child. + If necessary, the data is converted from UTF-8 to the terminal's current encoding. The terminal will call also paste the GDK_SELECTION_PRIMARY selection when the user clicks with the the second mouse button. @@ -723,9 +842,9 @@ - To be added + Interprets as if it were data received from a child process. a - To be added + This can either be used to drive the terminal without a child process, or just to mess with your users. @@ -788,9 +907,9 @@ - To be added - a - To be added + An accessor function provided for the benefit of language bindings. + the contents of terminal's char_ascent field + @@ -801,9 +920,9 @@ - To be added - a - To be added + An accessor function provided for the benefit of language bindings. + the contents of terminal's adjustment field + @@ -814,9 +933,9 @@ - To be added - a - To be added + An accessor function provided for the benefit of language bindings. + the contents of terminal's column_count field + @@ -826,9 +945,9 @@ Gdk.Color - To be added - a - To be added + Sets the background color for text which does not have a specific background color assigned. + the new background color + Only has effect when no background image is set and when the terminal is not transparent. @@ -838,9 +957,10 @@ System.Boolean - To be added - a - To be added + Controls whether or not the terminal will forcibly scroll to the bottom of the viewable history when the user presses a key. + + if the terminal should scroll on keystrokes + Modifier keys do not trigger this behavior. @@ -851,9 +971,9 @@ - To be added + An accessor function provided for the benefit of language bindings. a - To be added + the contents of terminal's char_width field @@ -864,9 +984,9 @@ - To be added - a - To be added + An accessor function provided for the benefit of language bindings. + the contents of terminal's char_descent field + @@ -877,9 +997,10 @@ - To be added - a - To be added + Controls whether or not the terminal will present a visible bell to the user when the child outputs the "bl" sequence. + + if visible bell is enabled, if not + The terminal will clear itself to the default foreground color and then repaint itself. @@ -889,9 +1010,10 @@ System.Boolean - To be added - a - To be added + Sets whether or not the cursor will blink. + + if the cursor should blink + The length of the blinking cycle is controlled by the "gtk-cursor-blink-time" GTK+ setting. @@ -901,9 +1023,9 @@ System.String - To be added - a - To be added + A convenience function which converts name into a PangoFontDescription and passes it to . + A string describing the font. + @@ -914,9 +1036,9 @@ - To be added - a - To be added + Sets what type of terminal the widget attempts to emulate by scanning for control sequences defined in the system's termcap file. + the name of a terminal description + Unless you are interested in this feature, always use "xterm". @@ -927,9 +1049,10 @@ - To be added - a - To be added + Whether a is using Xft to draw text. + + if the terminal is using Xft to render, if the terminal is using Pango or Xlib. + This function allows an application to determine which mode the widget is in. This setting cannot be changed by the caller, but in practice usually matches the behavior of Gtk itself. @@ -939,9 +1062,9 @@ Vte.TerminalEraseBinding - To be added - a - To be added + Modifies the terminal's backspace key binding, which controls what string or control sequence the terminal sends to its child when the user presses the backspace key. + a for the backspace key + @@ -952,9 +1075,9 @@ - To be added - a - To be added + An accessor function provided for the benefit of language bindings. + the contents of terminal's icon_title field + @@ -964,9 +1087,10 @@ System.Boolean - To be added - a - To be added + Controls whether or not the terminal will forcibly scroll to the bottom of the viewable history when the new data is received from the child. + + if the terminal should scroll on output + @@ -976,9 +1100,10 @@ System.Boolean - To be added - a - To be added + Sets the terminal's background image to the pixmap stored in the root window, adjusted so that if there are no windows below your application, the widget will appear to be transparent. + + if the terminal should fake transparency + @@ -1000,9 +1125,9 @@ Vte.TerminalEraseBinding - To be added - a - To be added + Modifies the terminal's delete key binding, which controls what string or control sequence the terminal sends to its child when the user presses the delete key. + a for the delete key + @@ -1013,9 +1138,9 @@ - To be added - a - To be added + The encoding the terminal will expect data from the child to be encoded with. + a valid gconv target + For certain terminal types, applications executing in the terminal can change the encoding. The default encoding is defined by the application's locale settings. @@ -1026,9 +1151,10 @@ - To be added - a - To be added + Controls whether or not the terminal will attempt to draw bold text by repainting text with a different offset. + + if the terminal should attempt to draw bold text + @@ -1038,9 +1164,10 @@ Gdk.Pixbuf - To be added - a - To be added + Sets a background image for the widget. + + to use, or to cancel + Text which would otherwise be drawn using the default background color will instead be drawn over the specified image. If necessary, the image will be tiled to cover the widget's entire visible area. @@ -1050,9 +1177,14 @@ System.String - To be added - a - To be added + When the user double-clicks to start selection, the terminal will extend the selection on word boundaries. + a specification + + When the user double-clicks to start selection, the terminal will extend the selection on word boundaries. It will treat characters passed in as parts of words, and all other characters as word separators. Ranges of characters can be specified by separating them with a hyphen. + + As a special case, if set to or the empty string, the terminal will treat all graphic non-punctuation characters as word characters. + + @@ -1063,9 +1195,9 @@ - To be added - a - To be added + An accessor function provided for the benefit of language bindings. + the contents of terminal's row_count field + @@ -1076,9 +1208,9 @@ - To be added - a - To be added + Some terminal emulations specify a status line which is separate from the main display area, and define a means for applications to move the cursor to the status line and back. + The current contents of the terminal's status line. For terminals like "xterm", this will usually be the empty string. The string must not be modified or freed by the caller. + @@ -1100,9 +1232,9 @@ Gdk.Color - To be added - a - To be added + Sets the color used to draw dim text in the default foreground color. + the new dim color + @@ -1112,9 +1244,9 @@ System.Int64 - To be added - a - To be added + Sets the length of the scrollback buffer used by the terminal. + the length of the history buffer + The size of the scrollback buffer will be set to the larger of this value and the number of visible rows the widget can display, so 0 can safely be used to disable scrollback. Note that this setting only affects the normal screen buffer. For terminal types which have an alternate screen buffer, no scrollback is allowed. @@ -1125,9 +1257,9 @@ - To be added - a - To be added + An accessor function provided for the benefit of language bindings. + the contents of terminal's char_height field + @@ -1137,9 +1269,12 @@ System.String - To be added + Sets a background image for the widget. a - To be added + If specified by , the terminal will make its in-memory copy of the image darker for its own use. + +This is a convenience wrapper for . If your application intends to create multiple terminal widgets using the same background, performing this step yourself and just using will reduce memory consumption. + @@ -1149,9 +1284,9 @@ Gdk.Color - To be added - a - To be added + Sets the color used to draw bold text in the default foreground color. + the new bold color + @@ -1161,9 +1296,14 @@ System.Double - To be added + Adjust the brightness of the background image. a - To be added + + If a background image has been set using , , or , the terminal will adjust the brightness of the image before drawing the image. To do so, the terminal will create a copy of the background image (or snapshot of the root window) and modify its pixel values. + + If your application intends to create multiple terminal widgets with the same settings, performing this step yourself and just using will save memory. + + @@ -1174,9 +1314,9 @@ - To be added - a - To be added + An accessor function provided for the benefit of language bindings. + the contents of terminal's window_title field + the contents of terminal's window_title field @@ -1187,9 +1327,10 @@ - To be added - a - To be added + The value of the terminal's mouse autohide setting. + + if the autohide should be enabled + When autohiding is enabled, the mouse cursor will be hidden when the user presses a key and shown when the user moves the mouse. @@ -1199,9 +1340,9 @@ Gdk.Color - To be added - a - To be added + Sets the foreground color used to draw normal text + the new foreground color + @@ -1212,9 +1353,10 @@ - To be added + Controls whether or not the terminal will beep when the child outputs the "bl" sequence. a - To be added + + if the terminal should beep @@ -1225,9 +1367,10 @@ - To be added - a - To be added + Checks if the terminal currently contains selected text. + + if part of the text in the terminal is selected. + Note that this is different from determining if the terminal is the owner of any items. @@ -1238,8 +1381,8 @@ - To be added - To be added + Emitted at the child application's request. + @@ -1250,8 +1393,8 @@ - To be added - To be added + Emitted at the child application's request. + @@ -1262,8 +1405,8 @@ - To be added - To be added + Emitted at the child application's request. + @@ -1274,8 +1417,8 @@ - To be added - To be added + Emitted when the user hits the '+' key while holding the Control key. + @@ -1286,8 +1429,8 @@ - To be added - To be added + An internal signal used for communication between the terminal and its accessibility peer. + May not be emitted under certain circumstances. @@ -1298,8 +1441,8 @@ - To be added - To be added + Emitted at the child application's request. + @@ -1310,8 +1453,8 @@ - To be added - To be added + An internal signal used for communication between the terminal and its accessibility peer. + May not be emitted under certain circumstances. @@ -1322,8 +1465,8 @@ - To be added - To be added + Emitted whenever the contents of the status line are modified or cleared. + @@ -1334,8 +1477,8 @@ - To be added - To be added + Emitted at the child application's request. + @@ -1346,8 +1489,8 @@ - To be added - To be added + This signal is emitted when the terminal detects that a child started using has exited. + @@ -1358,8 +1501,8 @@ - To be added - To be added + An internal signal used for communication between the terminal and its accessibility peer. + May not be emitted under certain circumstances. @@ -1370,8 +1513,8 @@ - To be added - To be added + Emitted at the child application's request. + @@ -1382,8 +1525,8 @@ - To be added - To be added + Emitted at the child application's request. + @@ -1394,8 +1537,8 @@ - To be added - To be added + Emitted at the child application's request. + @@ -1406,8 +1549,8 @@ - To be added - To be added + Emitted when the terminal's icon_title field is modified. + @@ -1418,8 +1561,8 @@ - To be added - To be added + Emitted when the user hits the '-' key while holding the Control key. + @@ -1430,8 +1573,8 @@ - To be added - To be added + An internal signal used for communication between the terminal and its accessibility peer. + May not be emitted under certain circumstances. @@ -1442,8 +1585,8 @@ - To be added - To be added + Emitted whenever selection of a new font causes the values of the char_width or char_height fields to change. + @@ -1454,8 +1597,8 @@ - To be added - To be added + Emitted when the terminals encoding type is changed. + @@ -1466,8 +1609,8 @@ - To be added - To be added + Emitted when the terminal's window_title field is modified. + @@ -1478,8 +1621,8 @@ - To be added - To be added + Emitted whenever the visible appearance of the terminal has changed. + Used primarily by . @@ -1490,8 +1633,8 @@ - To be added - To be added + Emitted whenever the cursor moves to a new character cell. + Used primarily by . @@ -1502,8 +1645,8 @@ - To be added - To be added + Emitted whenever the contents of terminal's selection changes. + @@ -1515,7 +1658,7 @@ To be added - To be added + @@ -1526,8 +1669,8 @@ - To be added - To be added + Emitted when the terminal emulation type is changed. + @@ -1538,8 +1681,8 @@ - To be added - To be added + Emitted at the child application's request. + @@ -1550,8 +1693,8 @@ - To be added - To be added + Emitted whenever the terminal receives input from the user and prepares to send it to the child process. + The signal is emitted even when there is no child process. @@ -1562,9 +1705,9 @@ - To be added - a - To be added + The font used for rendering all text displayed by the terminal, overriding any fonts set using . + The of the desired font. + The terminal will immediately attempt to load the desired font, retrieve its metrics, and attempts to resize itself to keep the same number of rows and columns. @@ -1583,16 +1726,19 @@ - To be added - a - a - a - a - a - a - a - a - To be added + Starts the specified command under a newly-allocated control pseudo-terminal. + the name of a binary to run + the argument list to be passed to + a list of environment variables to be added to the environment before starting + the name of a directory the command should start in, or + + if the session should be logged to the lastlog + + if the session should be logged to the utmp/utmpx log + + if the session should be logged to the wtmp/wtmpx log + the ID of the new process + TERM is automatically set to reflect the terminal widget's emulation setting. If lastlog, utmp, or wtmp are , logs the session to the specified system log files. diff --git a/doc/en/Vte/TerminalAccessible.xml b/doc/en/Vte/TerminalAccessible.xml index e375c96d3..ee7d0fce0 100644 --- a/doc/en/Vte/TerminalAccessible.xml +++ b/doc/en/Vte/TerminalAccessible.xml @@ -10,7 +10,7 @@ Gtk# is thread aware, but not thread safe; See the Gtk# Thread Programming for details. - To be added + Accessibility peer of . To be added @@ -580,10 +580,10 @@ - To be added + Creates a new accessibility peer for the terminal widget. a a - To be added + diff --git a/doc/en/Vte/TerminalEraseBinding.xml b/doc/en/Vte/TerminalEraseBinding.xml index 3ab7714d6..d650c6190 100644 --- a/doc/en/Vte/TerminalEraseBinding.xml +++ b/doc/en/Vte/TerminalEraseBinding.xml @@ -10,8 +10,8 @@ Gtk# is thread aware, but not thread safe; See the Gtk# Thread Programming for details. - To be added - To be added + Controls what string or control sequence the terminal sends to its child when the user presses the backspace or delete keys. + System.Enum @@ -38,7 +38,7 @@ - To be added + For backspace, attempt to determine the right value from the terminal's IO settings. For delete, use the control sequence. @@ -52,7 +52,7 @@ - To be added + Send an ASCII backspace character (0x08). @@ -66,7 +66,7 @@ - To be added + Send an ASCII delete character (0x7F). @@ -80,7 +80,7 @@ - To be added + Send the "7" control sequence.