xnee-3.19/doc/xnee_prot.texi

@chapter File types and format

The files used by Xnee are
@itemize @bullet
@item  Xnee Project File
@item  Xnee Session File
@end itemize
These files must follow the Xnee File Format.

@section Project file
@cindex  Project file
Xnee can be set either using command line options (when using xnee) or by
clicking the correct buttons etc in the GUI (using gnee). Instead of setting
the same settings over and over again, you can use the Xnee Project File.


@subsection  Create a project file
@cindex      Create a project file
You can create a project by yourself. This can be done using
the @code{write-settings} option in cnee or the ``save settings to file''
when using gnee or you can use the Xnee GUI (gnee) to write one.
You can also write one by yourself in your favorite editor.  Just make sure you
follow the Xnee format. For information and specification on this format read
the Xnee format chapter.
@

The authors of Xnee suggests you start off with a generated project file. To get one
such file, type the following
@code{cnee --mouse --keyboard --write-settings new_proj.xnp}. You will now
have a file @code{new_proj.xnp} with some useful values, which you can edit as you wish.
@

To use this file to record, simply type
@code{cnee --record --project new_proj.xnp}


@section Xnee Session file
@cindex  Session file
The Xnee session files are the printouts from a recorded session
following the Xnee File Format. For information and specification on
this format read the Xnee File Format chapter.


@section Xnee file format
The Xnee Format is divided into different directives.
The format is line based, meaning that

@itemize @bullet
@item  there is one directive per line
@item  one line contains one (and only one) directive
@end itemize
These directives are definied as follows.

@section Xnee directives
The following directives are used in Xnee:
@multitable  @columnfractions .0 .30 .70
@item
@tab @b{Directives}
@tab @b{Description}

@item
@tab Comment
@tab This is used to comment the various files

@item
@tab Project
@tab These contains information about the session- or project file

@item
@tab Settings
@tab Data used when recording and replaying

@item
@tab Replay data
@tab Recorded replayable data (used when replaying)

@item
@tab Script replay data
@tab Scriptable primitives

@item
@tab Mark
@tab Lines inserted in the seesion file when a modifier+key was pressed

@item
@tab Execution
@tab Lines that trigger the execution of an external program

@item
@tab  Project information
@tab  Project

@end multitable


@subsection Comment
@cindex  Comment directives


@multitable  @columnfractions .0 .20 .50 .30
@item
@tab @b{First token}
@tab @b{Interpretation}

@item
@tab  #
@tab  The whole line is ignored.
@end multitable
As long as the first token is @code{#} the whole line is intrepreted as a comment, just
as in bash.


@subsection Settings
@cindex Settings

@multitable @columnfractions .45 .15 .6
@item

@b{Settings directive}
@tab @b{Argument}
@tab @b{Interpretation}

@item
data-to-record
@tab  integer
@tab  Limits the number of data to record to to the integer value

@item
events-to-record
@tab  integer
@tab  Limits the number of events to record to to the integer value

@item
time-to-record
@tab  integer
@tab  Limits the number of seconds to record to to the integer value

@item
display
@tab  string
@tab  Sets the display to record or replay to the string

@item
distribute
@tab  string
@tab  Distribute all recorded or replayed replayable events to the display given by the string

@item
file
@tab  string
@tab  Read replay data from the file given by the string

@item
out-file
@tab  string
@tab  Print recorded data to the file given by the string

@item
plugin
@tab  string
@tab  Use the plugin given by the string

@item
first-last
@tab  boolean
@tab  Print only first and last of successive MotionNotify events

@item
verbose
@tab  boolean
@tab  Use verbose debugging printout

@item
buffer-verbose
@tab  boolean
@tab  Use verbose buffer verbose printouts (not built by default)

@item
time
@tab  integer
@tab  Delay the start of the Xnee action

@item
all-clients
@tab  boolean
@tab  Record all curret and future clients (default)

@item
future-clients
@tab  boolean
@tab  Record only future clients

@item
human-printout
@tab  boolean
@tab  Prints the recorded data in a (quite) more ser friendly format

@item
sync-mode
@tab  boolean
@tab  Sets recording mode

@item
speed-percent
@tab  integer
@tab  Sets the replaying speed percentage to the integer value

@item
stop-key
@tab  @acronym{string}
@tab  Sets the stop key combination to the string

@item
pause-key
@tab  @acronym{string}
@tab  Sets the pause key combination to the string

@item
resume-key
@tab  @acronym{string}
@tab  Sets the resume key combination to the string

@item
mark-key
@tab  @acronym{string}
@tab  Sets the mark key combination to the string

@item
exec-key
@tab  @acronym{string}
@tab  Sets the execute key combination to string

@item
replay-resolution
@tab  string
@tab  Sets the replay resolution to the string

@item
replay-resolution
@tab  string
@tab  Sets the replay resolution to the string

@item
recall-window-position
@tab
@tab  Use window position recall during replay

@item
resolution-adjustment
@tab  boolean
@tab  Use resolution adjustment, even if the recored resolution differs from the one to replay to

@item
event-range
@tab  range
@tab  Sets the events to record

@item
error-range
@tab  range
@tab  Sets the errors to record to range*

@item
request-range
@tab  range
@tab  Sets the request to record to range*

@item
reply-range
@tab  range
@tab  Sets the replies to record to range*

@item
extension-request-major-range
@tab  range
@tab  Sets the extension requests (major) to record to range*

@item
extension-request-minor-range
@tab  range
@tab  Sets the extension requests (minor) to record to range*

@item
extension-reply-major-range
@tab  range
@tab  Sets the extension replies (major) to record to range*

@item
extension-reply-minor-range
@tab  range
@tab  Sets the extension replies (minor) to record to range*

@item
force-replay
@tab  boolean
@tab  Continue to replay even if Xnee is out of sync

@item
max-threshold
@tab  integer
@tab  Sets the maximum synchronisation threshold

@item
min-threshold
@tab  integer
@tab  Sets the minimum synchronisation threshold

@item
total-threshold
@tab  integer
@tab  Sets the total maximum synchronisation threshold

@item
events-to-record
@tab  integer
@tab  Sets the number of events to record

@item
data-to-record
@tab  integer
@tab  Sets the number of data to record

@item
time-to-record
@tab  integer
@tab  Sets the number of seconds to record

@item
store-mouse-position
@tab
@tab  If set, Xnee records the initial mouse position and makes sure that replaying starts from there

@item
retype-press-delay
@tab  integer
@tab  Xnee delays processing after a faked key press (during retype)
with integer milli seconds

@item
retype-release-delay
@tab  integer
@tab  Xnee delays processing after a faked key press (during retype)
with integer milli seconds

@end multitable

@cindex Xnee Settings Arguments

@multitable @columnfractions .30 .40 .30
@item @b{Settings argument}
@tab @b{Description}
@tab @b{Example}

@item
@code{integer}
@tab  is an integer value.
@tab  1

@item
@code{string}
@tab  is a string.
@tab  localhost

@item
@code{boolean}
@tab  is a boolean value given by true/1 or false/0
@tab  true, false, 0, 1

@item
@code{subrange}
@tab  Subrange is gives a range of data by specifying a start and stop
      data. In the case of one data the stop data can be omitted.
@tab  2-5 or MapNotify

@item
@code{range}
@tab Ranges are a comma separated list of subranges.
@tab 2-3,MotionNotify-MapNotify,GravityNotify,PropertyNotify,30


@end multitable


@subsection Replay
@cindex Replay directive
@multitable  @columnfractions .40 .60
@item
@b{Replay directive}
@tab @b{Interpretation}

@item
0,0
@tab not valid

@item
0,1
@tab not valid

@item
0,2,void,void,void,keycode,screen,time
@tab KeyPress on key with keycode, used to replay

@item
0,3,void,void,void,keycode,screen,time
@tab KeyRelease on key with keycode, used to replay

@item
0,4,void,void,button nr,void,screen,time
@tab ButtonPress on button nr, used to replay

@item
0,5,void,void,button nr,void,screen,time
@tab ButtonRelease on button nr, used to replay

@item
0,6,x,y,void,void,screen,time
@tab MotionNotify on poistion (x,y), used to replay

@item
1,request number, request type, length, request id, time
@tab Recorded request, used during synchronisation

@item
2,reply number,time
@tab Recorded reply, used during synchronisation

@item
3,error number,time
@tab Recorded error, used during synchronisation

@item
6,EB+2,void,void,void,keycode,screen,time
@tab X Input (master) KeyPress on key with keycode, used to replay

@item
6,EB+3,void,void,void,keycode,screen,time
@tab X Input (master) KeyRelease on key with keycode, used to replay

@item
6,EB+4,void,void,button nr,void,screen,time
@tab X Input (master) ButtonPress on button nr, used to replay

@item
6,EB+5,void,void,button nr,void,screen,time
@tab X Input (master) ButtonRelease on button nr, used to replay

@item
6,EB+6,x,y,void,void,screen,time
@tab X Input (master) MotionNotify on poistion (x,y), used to replay

@item
6,EB+2,void,void,void,keycode,screen,time
@tab X Input (slave) KeyPress on key with keycode, used to replay

@item
6,EB+3,void,void,void,keycode,screen,time
@tab X Input (slave) KeyRelease on key with keycode, used to replay

@item
6,EB+4,void,void,button nr,void,screen,time
@tab X Input (slave) ButtonPress on button nr, used to replay

@item
6,EB+5,void,void,button nr,void,screen,time
@tab X Input (slave) ButtonRelease on button nr, used to replay

@item
6,EB+6,x,y,void,void,screen,time
@tab X Input (slave) MotionNotify on poistion (x,y), used to replay

@end multitable
time is the time on the server the data was to the recording Xnee
client. This time is used to keep the speed intact during replay.

@subsection Script replay data
@cindex   Script replay data

@multitable  @columnfractions .40 .60
@item
@b{Primitive}
@tab @b{Interpretation}

@item
fake-motion
@tab Fakes a mouse motion

@item
fake-button-press
@tab Fakes a button press

@item
fake-button-release
@tab Fakes a button release

@item
fake-button
@tab Fakes a button press and release

@item
fake-key-press
@tab Fakes a key press

@item
fake-key-release
@tab Fakes a key release

@item
fake-key
@tab Fakes a key press and release

@end multitable

@multitable  @columnfractions .20  .20 .60
@item
@b{Primitive variable}
@tab @b{Primitive values}
@tab @b{Interpretation}

@item
x=value
@tab  integer
@tab  Sets the x position used in fake-motion to value

@item
x=value
@tab  +integer
@tab  Set the relative motion (x direction) used in fake-motion to value

@item
x=value
@tab  -integer
@tab  Set the relative motion (x direction) used in fake-motion to value

@item
y=value
@tab  integer
@tab  Sets the y position used in fake-motion to value

@item
y=value
@tab  +integer
@tab  Set the relative motion (y direction) used in fake-motion to value

@item
y=value
@tab  -integer
@tab  Set the relative motion (y direction) used in fake-motion to value

@item
button=value
@tab  integer
@tab  set the button to fake with fake-button-press, fake-button-release and fake-button to value

@item
key=value
@tab  integer
@tab  set the key to fake with fake-key-press, fake-key-release and fake-key to value

@end multitable


@subsection Mark
@cindex  Mark directive
@multitable  @columnfractions .20 .20 .60
@item
@b{First tokens}
@tab @b{Arguments}
@tab @b{Interpretation}

@item
Mark
@tab  time string
@tab  Ignored. This feature is intended to let the user do whatever he/she
      wants to. This will obviously lead to modifying the source code etc.
@end multitable


@subsection Exec
@cindex  Exec directive
@multitable  @columnfractions .20 .20 .60
@item @b{First tokens}
@tab @b{Arguments}
@tab @b{Interpretation}

@item
Exec
@tab  command string
@tab  This is used during to replay to execute a given command. If no
      command string is found Xnee will try to
      read the command from the environment variable @code{XNEE_EXEC_COMMAND}
@end multitable


@subsection Project information
@cindex  Project information directive
@multitable  @columnfractions .45 .55
@item @b{Project information directives}
@tab @b{Arguments}

@item
ProjectName
@tab  string s is the project name

@item
ProjectDescription
@tab  string s is the project description

@item
ProjectCreationDate
@tab  string s is the project creation date

@item
ProjectCreationProgram
@tab  string s is the name of the program that create the project file

@item
ProjectCreationProgVersion
@tab  string s is the version of the program that create the project file

@item
ProjectLastChangeDate
@tab  string s is the date of the last change of the project file

@item
ProjectLastChangeProgram
@tab  string s is the name of the program that last changed of the project file

@item
ProjectLastChangeVersion
@tab  string s is the version of the program that last changed of the project file

@item
ProjectCurrentChangeDate
@tab  string s is the date of the current change of the project file

@item
ProjectCurrentChangeProgram
@tab  string s is the name of the program that current changed of the project file

@item
ProjectCurrentChangeVersion
@tab  string s is the version of the program that current changed of the project file


@end multitable