documentation/consoles.sgml

   1   <chapter id="consoles">
   2       <title>Consoles in Wine</title>
   3
   4       <para>
   5         As described in the Wine User Guide's CUI section, Wine
   6         manipulates three kinds of "consoles" in order to support
   7         properly the Win32 CUI API.
   8       </para>
   9       <para>
  10         The following table describes the main implementation
  11         differences between the three approaches.
  12
  13         <table>
  14           <title>Function consoles implementation comparison</title>
  15           <tgroup cols="4" align="left">
  16             <thead>
  17               <row>
  18                 <entry>Function</entry>
  19                 <entry>Bare streams</entry>
  20                 <entry>Wineconsole &amp; user backend</entry>
  21                 <entry>Wineconsole &amp; curses backend</entry>
  22               </row>
  23             </thead>
  24             <tbody>
  25               <row>
  26                 <entry>
  27                   Console as a Win32 Object (and associated
  28                   handles)
  29                 </entry>
  30                 <entry>
  31                   No specific Win32 object is used in this case. The
  32                   handles manipulated for the standard Win32 streams
  33                   are in fact "bare handles" to their corresponding
  34                   Unix streams. The mode manipulation functions
  35                   (<function>GetConsoleMode</function> /
  36                   <function>SetConsoleMode</function>) are not
  37                   supported.
  38                 </entry>
  39                 <entry>
  40                   Implemented in server, and a specific Winelib
  41                   program (wineconsole) is in charge of the
  42                   rendering and user input. The mode manipulation
  43                   functions behave as expected.
  44                 </entry>
  45                 <entry>
  46                   Implemented in server, and a specific Winelib
  47                   program (wineconsole) is in charge of the
  48                   rendering and user input. The mode manipulation
  49                   functions behave as expected.
  50                 </entry>
  51               </row>
  52               <row>
  53                 <entry>
  54                   Inheritance (including handling in
  55                   <function>CreateProcess</function> of
  56                   <constant>CREATE_DETACHED</constant>,
  57                   <constant>CREATE_NEW_CONSOLE</constant> flags).
  58                 </entry>
  59                 <entry>
  60                   Not supported. Every process child of a process
  61                   will inherit the Unix streams, so will also
  62                   inherit the Win32 standard streams.
  63                 </entry>
  64                 <entry>
  65                   Fully supported (each new console creation will be
  66                   handled by the creation of a new USER32 window)
  67                 </entry>
  68                 <entry>
  69                   Fully supported, except for the creation of a new
  70                   console, which will be rendered on the same Unix
  71                   terminal as the previous one, leading to
  72                   unpredictable results.
  73                 </entry>
  74               </row>
  75               <row>
  76                 <entry><function>ReadFile</function> / <function>WriteFile</function> operations</entry>
  77                 <entry>Fully supported</entry>
  78                 <entry>Fully supported</entry>
  79                 <entry>Fully supported</entry>
  80               </row>
  81               <row>
  82                 <entry>
  83                   Screen-buffer manipulation (creation, deletion, resizing...)
  84                 </entry>
  85                 <entry>Not supported</entry>
  86                 <entry>Fully supported</entry>
  87                 <entry>
  88                   Partly supported (this won't work too well as we
  89                   don't control (so far) the size of underlying Unix
  90                   terminal
  91                 </entry>
  92               </row>
  93               <row>
  94                 <entry>
  95                   APIs for reading/writing screen-buffer content,
  96                   cursor position
  97                 </entry>
  98                 <entry>Not supported</entry>
  99                 <entry>Fully supported</entry>
 100                 <entry>Fully supported</entry>
 101               </row>
 102               <row>
 103                 <entry>
 104                   APIs for manipulating the rendering window size
 105                 </entry>
 106                 <entry>Not supported</entry>
 107                 <entry>Fully supported</entry>
 108                 <entry>
 109                   Partly supported (this won't work too well as we
 110                   don't control (so far) the size of underlying Unix
 111                   terminal
 112                 </entry>
 113               </row>
 114               <row>
 115                 <entry>
 116                   Signaling (in particular, Ctrl-C handling)
 117                 </entry>
 118                 <entry>
 119                   Nothing is done, which means that Ctrl-C will
 120                   generate (as usual) a <constant>SIGINT</constant>
 121                   which will terminate the program.
 122                 </entry>
 123                 <entry>
 124                   Partly supported (Ctrl-C behaves as expected,
 125                   however the other Win32 CUI signaling isn't
 126                   properly implemented).
 127                 </entry>
 128                 <entry>
 129                   Partly supported (Ctrl-C behaves as expected,
 130                   however the other Win32 CUI signaling isn't
 131                   properly implemented).
 132                 </entry>
 133               </row>
 134             </tbody>
 135           </tgroup>
 136         </table>
 137       </para>
 138
 139       <para>
 140         The Win32 objects behind a console can be created in several occasions:
 141         <itemizedlist>
 142           <listitem>
 143             <para>
 144               When the program is started from wineconsole, a new
 145               console object is created and will be used (inherited)
 146               by the process launched from wineconsole.
 147             </para>
 148           </listitem>
 149           <listitem>
 150             <para>
 151               When a program, which isn't attached to a console, calls
 152               <function>AllocConsole</function>, Wine then launches
 153               wineconsole, and attaches the current program to this
 154               console. In this mode, the USER32 mode is always
 155               selected as Wine cannot tell the current state of the
 156               Unix console.
 157             </para>
 158           </listitem>
 159         </itemizedlist>
 160       </para>
 161       <para>
 162         Please also note, that starting a child process with the
 163         <constant>CREATE_NEW_CONSOLE</constant> flag, will end-up
 164         calling <function>AllocConsole</function> in the child
 165         process, hence creating a wineconsole with the USER32 backend.
 166       </para>
 167   </chapter>
 168
 169 <!-- Keep this comment at the end of the file
 170 Local variables:
 171 mode: sgml
 172 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
 173 End:
 174 -->