From 0b36e34a80aa615c0e428c06314faa7217b01612 Mon Sep 17 00:00:00 2001 From: Eric Pouech Date: Mon, 10 Mar 2003 19:06:46 +0000 Subject: [PATCH] Put console documentation in sync with current console status. --- documentation/consoles.sgml | 533 +++++++++++------------------------ documentation/running.sgml | 299 +++++++++++++++++++- documentation/samples/config | 7 - 3 files changed, 456 insertions(+), 383 deletions(-) diff --git a/documentation/consoles.sgml b/documentation/consoles.sgml index 140f8a219ef..8b2e2391555 100644 --- a/documentation/consoles.sgml +++ b/documentation/consoles.sgml @@ -5,377 +5,176 @@ Consoles - Written by &name-john-richardson; &email-john-richardson; - Maintained by &name-joseph-pranevich; &email-joseph-pranevich; + Written by &name-eric-pouech; &email-eric-pouech + + + + As described in the Wine User Guide's CUI section, Wine + manipulates three kinds of "consoles" in order to support + properly the Win32 CUI API. - (Extracted from wine/documentation/console) + The following table describes the main implementation + differences between the three approaches. + + + Fonction consoles implementation comparison + + + + Function + Bare streams + Wineconsole & user backend + Wineconsole & curses backend + + + + + + Console as a Win32 Object (and associated + handles) + + + No specific Win32 object is used in this case. The + handles manipulated for the standard Win32 streams + are in fact "bare handles" to their corresponding + Unix streams. The mode manipulation functions + (GetConsoleMode / + SetConsoleMode) are not + supported. + + + Implemented in server, and a specific Winelib + program (wineconsole) is in charge of the + rendering and user input. The mode manipulation + functions behave as expected. + + + Implemented in server, and a specific Winelib + program (wineconsole) is in charge of the + rendering and user input. The mode manipulation + functions behave as expected. + + + + + Inheritance (including handling in + CreateProcess of + CREATE_DETACHED, + CREATE_NEW_CONSOLE flags). + + + Not supported. Every process child of a process + will inherit the Unix streams, so will also + inherit the Win32 standard streams. + + + Fully supported (each new console creation will be + handled by the creation of a new USER32 window) + + + Fully supported, except for the creation of a new + console, which will be rendered on the same Unix + terminal as the previous one, leading to + unpredictible results. + + + + ReadFile / WriteFile operations + Fully supported + Fully supported + Fully supported + + + + Screen-buffer manipulation (creation, deletion, resizing...) + + Not supported + Fully supported + + Partly supported (this won't work too well as we + don't control (so far) the size of underlying Unix + terminal + + + + + APIs for reading/writing screen-buffer content, + cursor position + + Not supported + Fully supported + Fully supported + + + + APIs for manipulating the rendering window size + + Not supported + Fully supported + + Partly supported (this won't work too well as we + don't control (so far) the size of underlying Unix + terminal + + + + + Signaling (in particular, Ctrl-C handling) + + + Nothing is done, which means that Ctrl-C will + generate (as usual) a SIGINT + which will terminate the program. + + + Partly supported (Ctrl-C behaves as expected, + however the other Win32 CUI signaling isn't + properly implemented). + + + Partly supported (Ctrl-C behaves as expected, + however the other Win32 CUI signaling isn't + properly implemented). + + + + +
+ - - Console - First Pass - - - Consoles are just xterms created with the - -Sxxn switch. A - pty is opened and the master goes - to the xterm side and the slave is held - by the wine side. The console itself is turned into a few - HANDLE32s and is set to the - STD_*_HANDLES. - - - It is possible to use the WriteFile and - ReadFile commands to write to a win32 - console. To accomplish this, all K32OBJs that - support I/O have a read and write function pointer. So, - WriteFile calls - K32OBJ_WriteFile which calls the - K32OBJ's write function pointer, which then - finally calls write. - - - [this paragraph is now out of date] If - the command line console is to be inherited or a process - inherits its parent's console (-- can that happen???), the - console is created at process init time via - PROCESS_InheritConsole. The - 0, 1, and - 2 file descriptors are duped to be the - STD_*_HANDLES in this case. Also in this - case a flag is set to indicate that the console comes from - the parent process or command line. - - - If a process doesn't have a console at all, its - pdb->console is set to - NULL. This helps indicate when it is - possible to create a new console (via - AllocConsole). - - - When FreeConsole is called, all handles that the process has - open to the console are closed. Like most K32OBJs, if the - console's refcount reaches zero, its K32OBJ destroy function - is called. The destroy kills the xterm if one was open. - - - Also like most k32 objects, we assume that - (K32OBJ) header is the first field so the - casting (from K32OBJ*to CONSOLE*) - works correctly. - - - FreeConsole is called on process exit - (in ExitProcess) if - pdb->console is not - NULL. - - - - - BUGS - - - Console processes do not inherit their parent's handles. I - think there needs to be two cases, one where they have to - inherit the stdin / - stdout / stderr - from unix, and one where they have to inherit from another - windows app. - - - SetConsoleMode -- UNIX only has - ICANON and various - ECHOs to play around with for - processing input. Win32 has line-at-a-time processing, - character processing, and echo. I'm putting together an - intermediate driver that will handle this (and hopefully - won't be any more buggy than the NT4 console - implementation). - - - - - Experimentation - - - experimentation with NT4 yields that: - - - - - WriteFile - - - - does not truncate file on 0 length write - - - - 0 length write or error on write changes - numcharswritten to - 0 - - - - 0 length write returns TRUE - - - works with console handles - - - - - - _lwrite - - - - does truncate/expand file at current position on 0 length write - - - returns 0 on a zero length write - - - works with console handles (typecasted) - - - - - - WriteConsole - - - - expects only console handles - - - - - - SetFilePointer - - - - returns -1 (err 6) when used with a console handle - - - - - - FreeConsole - - - - - even when all the handles to it are freed, the - win32 console stays visible, the only way I could - find to free it was via the FreeConsole - - - - - - - - - Is it possible to interrupt win32's - FileWrite? I'm not sure. It may not be - possible to interrupt any system calls. - - - - - DOS (Generic) Console Support - - - I. Command Line Configuration - - - DOS consoles must be configured either on the command line - or in a dot resource file (.console). - A typical configuration consists of a string of driver - keywords separated by plus ('+') signs. To change the - configuration on the command-line, use the - -console switch. - - - For example: - - -wine -console ncurses+xterm <application> - - - Possible drivers: - - - - - tty: - - Generic text-only support. Supports redirection. - - - - ncurses: - - Full-screen graphical support with color. - - - - xterm: - - - Load a new window to display the console in. Also - supports resizing windows. - - - - - - - - II. wine config file configuration - - - In the wine config file, you can create - a section called [console] that contains configuration - options that are respected by the assorted console - drivers. - - - Current Options: - - - - - XtermProg=<program> - - - Use this program instead of - xterm. This eliminates the need - for a recompile. See the table below for a - comparison of various terminals. - - - - - InitialRows=<number> - - - Attempt to start all drivers with this number of - rows. This causes xterms to be resized, for - instance. - - - - This information is passed on the command-line - with the -g switch. - - - - - - InitialColumns=<number> - - - Attempt to start all drivers with this number of - columns. This causes xterms to be resized, for - instance. - - - - This information is passed on the command-line - with the -g switch. - - - - - - TerminalType=<name> - - - Tell any driver that is interested (ncurses) which - termcap and/or terminfo type to use. The default is - xterm which is appropriate for most uses. - nxterm may give you better - support if you use that terminal. This can also be - changed to "linux" (or "console" on older systems) - if you manage to hack the ability to write to the - console into this driver. - - - - - - - - III. Terminal Types - - - There are a large number of potential terminals that can - be used with Wine, depending on what you are trying to do. - Unfortunately, I am still looking for the "best" driver - combination. - - - - 'slave' is required for use in Wine, currently. - - - - - - - - Program - Color? - Resizing? - Slave? - - - - - (linux console) - Y - N - ? - - - - - xterm - N - Y - Y - - - nxterm - Y - N - Y - - - rxvt - Y - ? - N - - - - - - - As X terminals typically use a 24x80 screen resolution - rather than the typical 25x80 one, it is necessary to - resize the screen to allow a DOS program to work - full-screen. There is a wine config file - option to work around this in some cases but run-time - resizing will be disabled. - - - + + Console creation + + + The Win32 objects behind a console can be created in several occasions: + + + + When the program is started from wineconsole, a new + console object is created and will be used (inherited) + by the process launched from wineconsole. + + + + + When a program, which isn't attached to a console, calls + AllocConsole, Wine then launches + wineconsole, and attaches the current program to this + console. In this mode, the USER32 mode is always + selected as Wine cannot tell the current state of the + Unix console. + + + + + + Please also note, that starting a child process with the + CREATE_NEW_CONSOLE flag, will end-up + calling AllocConsole in the child + process, hence creating a wineconsole with the USER32 backend. + diff --git a/documentation/running.sgml b/documentation/running.sgml index 03b2b1f788b..452433b106c 100644 --- a/documentation/running.sgml +++ b/documentation/running.sgml @@ -5,7 +5,7 @@ Written by &name-john-sheets; &email-john-sheets; - Extended by &name-mike-hearn; &email-mike-hearn; + Extended by &name-mike-hearn; &email-mike-hearn;, &name-eric-pouech; &email-eric-pouech; @@ -124,15 +124,9 @@ Options: (note the backslash-escaped "\" !) - - If you want to run a console program (aka a CUI executable), use - wineconsole instead of wine - to start it. It will display the program in a separate Window - (this requires X11 to be run). If you don't, you'll still be able - to run your program directly in the Unix console where you started it, - but with very limited capacities (so your program might work, - but your mileage may vary). This shall be improved in the future. + For details on running text mode (CUI) executables, read the + section below. @@ -361,6 +355,293 @@ winspoolwnetx11 + + Text mode programs (CUI: Console User Interface) + Text mode programs are program which output is only made + out of text (surprise!). In Windows terminolgy, they are + called CUI (Console User Interface) executables, by opposition + to GUI (Graphical User Interface) executables. Win32 API + provide a complete set of APIs to handle this situation, which + goes from basic features like text printing, up to high level + functionnalities (like full screen editing, color support, + cursor motion, mouse support), going through features like + line editing or raw/cooked input stream support + + + Given the wide scope of features above, and the current usage + in Un*x world, Wine comes out with three different ways for + running a console program (aka a CUI executable): + + + bare streams + + + wineconsole with user backend + + + wineconsole with curses backend + + + + The names here are a bit obscure. "bare streams" means + that no extra support of wine is provide to map between the + unix console access and Windows console access. The two other + ways require the use of a specific Wine program (wineconsole) + which provide extended facilities. The following table + describes what you can do (and cannot do) with those three + ways. + + Basic differences in consoles + + + + Function + Bare streams + Wineconsole & user backend + Wineconsole & curses backend + + + + + How to run (assuming executable is called foo.exe) + +$ wine foo.exe + + +$ wineconsole -- --backend=user foo.exe + + +$ wineconsole foo.exe + You can also use --backend=curses as an option + + + Good support for line oriented CUI applications + (which print information line after line) + + Yes + Yes + Yes + + + Good support for full screen CUI + applications (including but not limited to color + support, mouse support...) + No + Yes + Yes + + + Can be run even if X11 is not running + Yes + No + Yes + + + Implementation + Maps the standard Windows streams to the + standard Unix streams (stdin/stdout/stderr) + + + Wineconsole will create a new Window (hence + requiring the USER32 DLL is available) where all + information will be displayed + + + Wineconsole will use existing unix console + (from which the program is run) and with the help of + the (n)curses library take control of all the terminal + surface for interacting with the user + + + + Known limitations + + + + Will produce strange behavior if two (or more) + Windows consoles are used on the same Un*x terminal. + + + + +
+ + + Configuration of CUI executables + + When wineconsole is used, several configuration options are + available. Wine (as Windows do) stores, on a per application + basis, several options in the registry. This let a user, for + example, define the default screen-buffer size he would like + to have for a given application. + + + As of today, only the USER backend allows you to edit those + options (we don't recommend editing by hand the registry + contents). This edition is fired when a user right click in + the console (this popups a menu), where you can either + choose from: + + + + Default: this will edit the settings shared by all + applications which haven't been configured yet. So, + when an application is first run (on your machine, + under your account) in wineconsole, wineconsole will + inherit this default settings for the + application. Afterwards, the application will have its + own settings, that you'll be able to modify at your will. + + + Properties: this will edit the application's + settings. When you're done, with the edition, you'll + be prompted whether you want to: + + + + Keep these modified settings only for this + session (next time you run the application, you + will not see the modification you've just made). + + + + + Use the settings for this session and save them + as well, so that next you run your application, + you'll use these new settings again. + + + + + + + + + Here's the list of the items you can configure, and their + meanings: + + Wineconsole configuration options + + + + Configuration option + Meaning + + + + + Cursor's size + + Defines the size of the cursor. Three options are + available: small (33% of character height), medium + (66%) and large (100%) + + + + Popup menu + + It's been said earlier that wineconsole + configuration popup was triggered using a right + click in the console's window. However, this can + be an issue when the application you run inside + wineconsole expects the right click events to be + sent to it. By ticking control or shift you select + additional modifiers on the right click for + opening the popup. For example, ticking shift will + send events to the application when you right + click the window without shift being hold down, + and open the window when you right-click while + shift being hold down. + + + + Quick edit + + This tick box lets you decide whether left-click + mouse events shall be interpreted as events to be + sent to the underlying application (tick off) or + as a selection of rectangular part of the screen + to be later on copied onto the clipboard (tick on). + + + + History + + This lets you pick up how many commands you want + the console to recall. You can also drive whether + you want, when entering several times the same + command - potentially intertwened with others - + whether you want to store all of them (tick off) + or only the last one (tick on). + + + + Police + + The Police property sheet allows you to pick the + default font for the console (font file, size, + background and foreground color). + + + + Screenbuffer & window size + + The console as you see it is made of two different + parts. On one hand there's the screenbuffer which + contains all the information your application puts + on the screen, and the window which displays a + given area of this screen buffer. Note that the + window is always smaller or of the same size than + the screen buffer. Having a stricly smaller window + size will put on scrollbars on the window so that + you can see the whole screenbuffer's content. + + + + Close on exit + + If it's ticked, then the wineconsole will exit + when the application within terminates. Otherwise, + it'll remain opened until the user manually closes + it: this allows seeing the latest information of a + program after it has terminated. + + + + Edition mode + + + + When the user enter commands, he or she can + choose between several edition modes: + + + + Emacs: the same keybindings as under + emacs are available. For example, Ctrl-A + will bring the cursor to the beginning + of the edition line. See your emacs + manual for the details of the commands. + + + + + Win32: this are the standard Windows + console key-bindings (mainly using + arrows). + + + + + + + + + +
+ + +