This file describes the TProcess object.

Important remark:

As of version 2.5.1 (April 2011) the CommandLine and ApplicationName
properties are deprecated in favour of properties Executable and Parameters.
If CommandLine or ApplicationName is set, it will automatically be converted
to Executable and Parameters. If you wish to use the latter 2 properties, 
simply clear the CommandLine and ApplicationName properties.

The TProcess object provides an easy way to start and manipulate
the running of other programs (processes) by your application.
On top of that, it allows you to redirect the program's input, output
and standard error to streams that are readable/writeable by your
program.

It is a descendent class of TComponent.

Furthermore it is written in such a way that it is easily extensible,
although most of the properties that a Process has, are accessible and
can be controlled with this object.

In what follows, is a description of the object's methods and properties.

The following two types control the creation of the TProcess Object.
See The constructor description for a description on what they do.

TProcessOptions = (poExecuteOnCreate,poRunSuspended,poUsePipes,poNewConsole,
                    poNoConsole,poStderrToOutPut,poWaitOnExit);
TCreateOptions = Set of TPRocessOptions;



Options control the behaviour of the object. It can be a set of the
following constants:

poExecuteOnCreate
  If you include this option, the constructor will immediatly
  call the Execute method, using default settings for all parameters.
  This has the effect that the program is run at once.
  
poRunSuspended
  If you include this option, the Execute method will start the
  program in a suspended state, and the program will start running
  only after you have called the Resume method.

poUsePipes
  If you include this option, the Execute method will redirect the
  standard input,output and error descriptors to 3 pipes, which you
  can read from or write to.
  (see Input,OutPut and Error properties)
  It makes little sense to use ths for GUI applications (i.e. non-
  console applications)
  
poNoConsole
  If you include this option, the application will not display a
  console, untill it explicitly needs one or requests one using the
  AllocConsole method. This is very convenient in combination with the
  poUsePipes option, allowing you to run an application without getting
  the Console window, and being able to read it's output at once.
  
poStderrToOutPut
  If This option is included, then the error desciptor is redirected to
  the standard output director, i.e. all output goes to the standard
  output.
  
poWaitOnExit
  If you specify this option, then the Execute method will wait for the
  executed program to finish, before returning.
  This option will be ignored if you also specified ExecuteOnCreate and
  CreateSuspended.

poNewConsole 
  If you specify this option, then the Execute method will open a console to
  execute the program in. On windows, the standard console is used.
  On Unix, the console program is detected as follows:
  - XTermProgram is used if it is set.
  - the terminals in TryTerminals are tested
  - the 'DESKTOP_SESSION' variable is examined and the corresponding
    terminal is tested for availability.
  - A set of standard terminals is tested:
    ('x-terminal-emulator','xterm','aterm','wterm','rxvt')
  if none of these can be detected, an exception is raised.
     
Destructor Destroy; virtual;

  Destroys the TProcess Object. Be careful NOT to close a TProcess
  object when you use pipes, and the application is still running.
  you may kill it.
  
Procedure Execute; virtual;
  This actually runs the application. It will return immediatly, unless
  you specified the poWaitOnExit option when creating the object.

Function Resume : Integer; virtual;
  Resume lowers the suspend count of the application.
  it returns the new suspend count of the application. As long as the
  suspend count is larger than 0, the application will not run.
  If the suspend count reaches 0, the application will continue
  running.
  
Function Suspend : Integer; virtual;
  Increases the suspend count of the application, and returns the
  new suspend count of the application.
  
Function Terminate (AExitCode : Integer): Boolean; virtual;
  Terminate terminates the main thread of the application, giving it
  exitcode 'AExitCode'
  It returns True on succes, False on failure.

Function WaitOnExit : Boolean;
  This function returns true if the wait for the process exit was succesful,
  false if some error occurded. It returns immediatly if the application is 
  not running, and waits for the application to finish if it was still running.
  
Property ApplicationName : String;
  Sets the name of the application.
  
Property CommandLine : String; (Deprecated)
  contains the commandline of the application. method of TProcess.
  If Set, it overrides the Executable and Parameters properties

Property Executable : String;
  The binary program to be executed. It will be searched in the PATH.

Property Parameters : TStrings
  The command-line parameters to be passed to Executable. One parameter per
  line must be specified. If 2 or more words, separated by a space, are detected 
  in an argument, they will be treated as 1 argument and quoted if the OS
  requires it.
  
Property ConsoleTitle : String;
  For console applications only :
  Sets the title that appears in the title bar of the Console window.
  
Property CreateOptions : TCreateOptions;
  Read-Only
  Contains the options as set by the Create method of TProcess.
  
Property CreationFlags : Cardinal;
  This contains the creation flags that are passed to the CreateProcess
  call. These flags are modified by the Execute call to reflect any
  settings tat you may have made.
  
Property CurrentDirectory : String;
  When set, the process wil start in the directory that you have set
  for it.

Property DeskTop : String;
  NT only:
  Contains the name of the desktop or window station that the process
  will be run on. See STARTUPINFO in the win32 programmers manual.
  
Property Environment : Pointer;
  A pointer to a null-terminated list of environment variable pointers.
  Each pair is of the form 'Name=Value'.
  If this is nil, the environment of your application is used.
  
Property ExitStatus : Integer;  
  Read-Only
  This returns the exit status of the application, or STILL_ACTIVE
  (defined in Windows.pas) if the application is still running.
  This is the low-level exit status as reported by the OS.

Property ExitCode : Integer;  
  Read-Only
  This returns the exit code as returned by the application, if it exited correcly.
  It returns 0 if the process didn't exit correctly (e.g. a signal).
  
Property FillAttribute : Integer;
  For console processes only.
  Sets the fill color for the console window.

Property Handle : THandle;
  Read-Only;
  Returns the handle of the process, which can be used to pass on to
  calls that require a handle of a process.
  Onl valid if the process is running.
  
  
Property Input : TOutPutPipeStream;
  Read-Only
  Returns the Input handle of the process.
  Anything you write to this stream, will appear on the applications
  input file descriptor.
  Only valid if you used poUsePipes when you created the TProcess
  object.
  
Property InheritHandles : LongBool;
  If you set this to true, each inheritable handle of your application
  is inherited by the new application.
  
Property OutPut : TInputPipeStream;
  Read-Only
  Returns the Output handle of the process. Anything the process writes
  to its standard output can be read from this stream.
  Only valid if you used poUsePipes when you created the TProcess
  object.
  
Property ProcessAttributes : TSecurityAttributes;
  
Property ProcessInformation : TProcessInformation;
  Read-Only
  Gives access to the ProcessInformation returned by Windows
  upon executing the program. This contains
    hProcess : Process Handle (See Handle property)
    hThread  : Process' main thread handle (See ThreadHandle property)
    dwProcessId : Process ID. (as seen in the task manager) 
    dwThreadId : Process' main thread ID

Property Running : Boolean;
  Read-Only
  Retruns True if the application is still running, False otherwise.
  If the application is suspended or not doesn't affect the result.
  
Property ShowWindow : Word;
  You can set the applications ShowWindow attribute here.

Property StartupInfo : TStartupInfo;
  Read-Only
  Gives access to the TStartupInfo that will be passed to the
  application in the CreateProcess Call. You can manipulate its various
  members through the properties of the TProcess object.
  
Property StdErr : TinputPipeStream;
  Read-Only
  Returns the Output handle of the process. Anything the process writes
  to its error output can be read from this stream.
  Only valid if you used poUsePipes when you created the TProcess
  object.
  If you specified poStderrToOutput then this is the same as the
  'Output' stream.

Property ThreadAttributes : TSecurityAttributes;
  Contains the security attributes that will be passed to the process'
  main thread. By default, no security attributes are passed.
  
Property ThreadHandle : THandle;
  Read-Only
  Returns the Handle of the process' main thread.
  
Property WindowColumns : Integer;
  For console applications:
  This will set the number of screen columns that the console window
  will have.
  If you don't set this property nor the WindowRows property, Windows will
  choose default values.
  You can only set this PRIOR to calling the execute method, after
  the application was executed, or while it is running, the setting
  will be ignored until you run it again.
  
Property WindowHeight : Integer;
  Set the height of the application's main window.
  If you don't specify this, nor WindowWidth, Windows will choose
  the height and Width of the applications window.
  You can only set this PRIOR to calling the execute method, after
  the application was executed, or while it is running, the setting
  will be ignored until you run it again.

Property WindowLeft : Integer;
  Set the applications main window position, in pixels from the left
  side of the screen.
  If you don't specify this, nor WindowTop, Windows will choose
  the Left and Top of the applications window.
  You can only set this PRIOR to calling the execute method, after
  the application was executed, or while it is running, the setting
  will be ignored until you run it again.
  
Property WindowRows : Integer;
  For console applications:
  This will set the number of screen rows (lines) that the console window
  will have.
  If you don't set this property nor the WindowColumns property, Windows will
  choose default values.
  You can only set this PRIOR to calling the execute method, after
  the application was executed, or while it is running, the setting
  will be ignored until you run it again.

Property WindowTop : Integer;
  Set the applications main window position, in pixels from the Top
  side of the screen.
  If you don't specify this, nor WindowLeft, Windows will choose
  the Left and Top of the applications window.
  You can only set this PRIOR to calling the execute method, after
  the application was executed, or while it is running, the setting
  will be ignored until you run it again.

Property WindowWidth : Integer;
  Set the Width of the application's main window.
  If you don't specify this, nor WindowWidth, Windows will choose
  the height and Width of the applications window.
  You can only set this PRIOR to calling the execute method, after
  the application was executed, or while it is running, the setting
  will be ignored until you run it again.

Property WindowRect : Trect;
  This sets the bounding rectangle of the application's main window.
  It allows to set the WindowTop, WindowLeft, WindowHeight, WindowWidth
  properties in 1 call.

 

