consoles.sgml 4.96 KB
Newer Older
1
  <chapter id="consoles">
2
      <title>Consoles in Wine</title>
3

4
      <para>
5 6 7
	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.
8
      </para>
9 10 11 12 13
      <para>
	The following table describes the main implementation
	differences between the three approaches.

	<table>
Tom Wickline's avatar
Tom Wickline committed
14
	  <title>Function consoles implementation comparison</title>
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
	  <tgroup cols="4" align="left">
	    <thead>
	      <row>
		<entry>Function</entry>
		<entry>Bare streams</entry>
		<entry>Wineconsole &amp; user backend</entry>
		<entry>Wineconsole &amp; curses backend</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry>
		  Console as a Win32 Object (and associated
		  handles)
		</entry> 
		<entry>
		  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
		  (<function>GetConsoleMode</function> /
		  <function>SetConsoleMode</function>) are not
		  supported.
		</entry>
		<entry>
		  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.
		</entry>
		<entry>
		  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.
		</entry>
	      </row>
	      <row>
		<entry>
		  Inheritance (including handling in
		  <function>CreateProcess</function> of
		  <constant>CREATE_DETACHED</constant>,
		  <constant>CREATE_NEW_CONSOLE</constant> flags).
		</entry>
		<entry>
		  Not supported. Every process child of a process
		  will inherit the Unix streams, so will also
		  inherit the Win32 standard streams.
		</entry>
		<entry>
		  Fully supported (each new console creation will be
		  handled by the creation of a new USER32 window)
		</entry>
		<entry>
		  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
Tom Wickline's avatar
Tom Wickline committed
72
		  unpredictable results.
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137
		</entry>
	      </row>
	      <row>
		<entry><function>ReadFile</function> / <function>WriteFile</function> operations</entry>
		<entry>Fully supported</entry>
		<entry>Fully supported</entry>
		<entry>Fully supported</entry>
	      </row>
	      <row>
		<entry>
		  Screen-buffer manipulation (creation, deletion, resizing...)
		</entry>
		<entry>Not supported</entry>
		<entry>Fully supported</entry>
		<entry>
		  Partly supported (this won't work too well as we
		  don't control (so far) the size of underlying Unix
		  terminal
		</entry>
	      </row>
	      <row>
		<entry>
		  APIs for reading/writing screen-buffer content,
		  cursor position
		</entry>
		<entry>Not supported</entry>
		<entry>Fully supported</entry>
		<entry>Fully supported</entry>
	      </row>
	      <row>
		<entry>
		  APIs for manipulating the rendering window size
		</entry>
		<entry>Not supported</entry>
		<entry>Fully supported</entry>
		<entry>
		  Partly supported (this won't work too well as we
		  don't control (so far) the size of underlying Unix
		  terminal
		</entry>
	      </row>
	      <row>
		<entry>
		  Signaling (in particular, Ctrl-C handling)
		</entry>
		<entry>
		  Nothing is done, which means that Ctrl-C will
		  generate (as usual) a <constant>SIGINT</constant>
		  which will terminate the program.
		</entry>
		<entry>
		  Partly supported (Ctrl-C behaves as expected,
		  however the other Win32 CUI signaling isn't
		  properly implemented).
		</entry>
		<entry>
		  Partly supported (Ctrl-C behaves as expected,
		  however the other Win32 CUI signaling isn't
		  properly implemented).
		</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>
      </para>
138

139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166
      <para>
	The Win32 objects behind a console can be created in several occasions:
	<itemizedlist>
	  <listitem>
	    <para>
	      When the program is started from wineconsole, a new
	      console object is created and will be used (inherited)
	      by the process launched from wineconsole.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      When a program, which isn't attached to a console, calls
	      <function>AllocConsole</function>, 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.
	    </para>
	  </listitem>
	</itemizedlist>
      </para>
      <para>
	Please also note, that starting a child process with the
	<constant>CREATE_NEW_CONSOLE</constant> flag, will end-up
	calling <function>AllocConsole</function> in the child
	process, hence creating a wineconsole with the USER32 backend.
      </para>
167 168 169 170 171
  </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
172
sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
173 174
End:
-->