libisoburn/frontend/README-tcltk

------------------------------------------------------------------------------
                                xorriso-tcltk
------------------------------------------------------------------------------
Copyright (C) 2012, Thomas Schmitt <scdbackup@gmx.net>, libburnia-project.org
Provided under GNU GPL version 2 or later.
------------------------------------------------------------------------------

xorriso-tcltk is mainly a proof of concept for a frontend that operates
xorriso in dialog mode.

It exercises several fundamental gestures of communication:
- connecting via two pipes
- sending commands
- receiving replies
- inquiring the xorriso message sieve
- using the xorriso parsing service

Note that any other language than Tcl/Tk could be used, if it only can
do i/o via standard input and standard output or via named pipes.
Further it has to perform integer arithmetics and string manipulations.
And, well, a graphical widget set would be nice.

See man xorriso for a documentation of xorriso concepts and commands.
See man xorrecord for details of the burn image file feature.


Quick start:

  xorriso -launch_frontend $(which xorriso-tcltk) --stdio --


The Tcl shell "wish" is allergic to options which start by "-h".
So here is the output of  xorriso-tcltk --help :
------------------------------------------------------------------------
Usage:
  xorriso-tcltk [options]
Options:
 All options must be given with two dashes ("--option") in
 order to distinguish them from any options of the Tcl shell.
 --help
     Print this text and exit.
 --stdio
     Establishes connection to xorriso via stdin and stdout.
     E.g. when letting xorriso start this frontend program:
       xorriso -launch_frontend $(which xorriso-tcltk) --stdio --
 --named_pipes cmd_fifo reply_fifo
     Establishes connection to a xorriso process started by:
       xorriso -dialog on <cmd_fifo >reply_fifo
     which is then ready for a run of:
       xorriso-tcltk --named_pipes cmd_fifo reply_fifo
     It is important that the parent of xorriso and of this
     tcl/tk frontend opens the named pipe for commands before
     it opens the named pipe for replies. This avoids deadlock.
 --geometry {+|-}X{+|-}Y
     Sets the position of the main window.
 --click_to_focus
     Chooses that input fields and list boxes get the keyboard
     focus only when being clicked by the mouse.
 --auto_focus
     Chooses that the keyboard focus is where the mouse
     pointer is. (Default)
 --log_file path
     Set a file address for logging of xorriso commands and
     reply messages. The log lines will be appended.

Either --stdio or --named_pipes must be given for a program run.

------------------------------------------------------------------------


                         Overview of GUI elements

The window is separated into three main areas:
- Connection to xorriso.
- Management of drives and image files.
- Inspection, manipulation, and exploitation of xorriso ISO image model.

------------------------------------------------------------------------

                         Connection to xorriso

The "End" button leads to the end of frontend and xorriso process.

The ready/busy field indicates whether a xorriso command is being executed
and the frontend is still waiting for its reply messages.

The "Command:" field can be used to send commands to xorriso.

The "Refresh state display" button causes the other two main areas to update
their display after manually transmitted commands may have changed the state
of drives or ISO model.

The "Log pipes" switch controls whether all xorriso commands and replies
shall be logged to standard error resp. to the file that has been iven
with program argumen --log_file. Caution: This log is verbous.

The message box displays commands sent to xorriso and messages recieved
from xorriso.
Many commands which are emitted by the GUI will hide themselves and their
replies from this display.
All event messages with severity WARNING or higher will show up, nevertheless.

The "Recent problem:" field shows the most severe event message that occured
during the execution of the most recent command. It also displays the most
recent problem message from the frontend program itself.
Several commands emitted by the GUI will not clear this display. But any
manually transmitted command and the major GUI gestures will do.

The "Worst problem:" field shows the most severe event message that occured
since last time the "Clear" button was hit. It will not clear automatically.


------------------------------------------------------------------------

                    Management of drives and image files

The "Scan for drives" button executes command -devices and puts the list
of found optical drives into the box underneath the button.

The "Pick input drive" button executes command -indev and obtains some
information about the medium status. This info is displayed in the 
"Input drive or image" line.
Further it causes the display of the ISO image model to be updated.

The "Pick output drive" button executes command -outdev and displays the
related info in the "Output drive or image" line.

The "Pick drive for both roles" button executes command -dev and displays
info in both "... drive or image" lines.

The "Give up drives" executes commands -indev "" -outdev "" and clears
both "... drive or image" lines, as well as the ISO model.

The "Calm drives" button executes command -calm_drives which tells the
aquired optical drives to stop spinning until the next drive activity
gets triggered.

The "Rollback" button excutes command -rollbackwhich drops all pending
changes of the ISO model and reloads it from the input drive, if one is
aquired.

The box underneath these buttons shows the optical drives found by the
"Can for drives" button.
A double-click on a drive item has the same effect as button "Pick drive
for both roles".

The line "Input drive or image" displays address and medium status of
the input drive.
Its "Eject" button excutes command -eject "in".
Editing the drive address and pressing the Return key causes the execution
of command -indev with the field content as drive address. Use this to
load the model from ISO image data files on hard disk.

The line "Output drive or image" does about the same for the output drive.
The text input field can be used to address an existing ISO image data
file or to address a data file that does not yet exist. In the latter
case, the ,edium status will be blank.

The "Blank" button executes command -blank "as_needed" on the output drive.
This also applies to ISO image data files, which will get invalidated by
a small write operation.

The "Format" button executes -format "as_needed".
This only applies to real optical drives and s of interest only with DVD-RW
or BD-R media, which both can be used formatted and unformatted. Other media
types which mandatorily need formatting will be formatted by the write
commands.

The "Write ISO session" executes command -commit, which writes a session
with all pending changes to the output drive. The output drive must be
either blank or it must be the same as the input drive.

The "Close" switch controls whether command -close "on" is emitted with
"Write ISO session" or whether -as cdrecord option -multi is omitted with
"Burn image file:".

The "TAO" switch controls whether an incremental write type shall be
enforced with write commands. Normally xorriso will decide by medium status
and job parameters which write type to choose.

The "Defect Mgt" switch controls whether slow and error-prone drive internal
check reading shall be enabled with formatted BD-R or with BD-RE.

The "Burn image file:" button executes command -as "cdrecord" with the
content of its text field  as disk file address of a data file that is
to be written to the output drive.
The medium in the drive may be blank or appendable.


------------------------------------------------------------------------

 Inspection, manipulation, and exploitation of xorriso ISO image model

The "Extract to disk:" button executes command -extract with the whole
tree of the current ISO directory or with the selected items of the box
underneath "ISO directory:".
This copies the selected files or directory trees from the input drive
to the address on hard disk which is given by the text filed right of
the button.

The "Underneath" switch controls the effective hard disk address of an item
if the address in the text field points to a directory. If "Underneath"
is enabled, then the file object from the ISO filesystem will be copied to its
name underneath the hard disk directory.
If "Underneath" is disabled then an ISO directory tree item will be merged
with the disk directory tree at the given address.
Example:
Selected are "/iso_dir" and "/iso_file".
Address for hard disk is "/tmp/from_iso". Switch "Selected" is enabled.
"Underneath" enabled causes commands:
  -extract /iso_dir /tmp/from_iso/iso_dir 
  -extract /iso_file /tmp/from_iso/iso_file 
"Underneath" disabled:
  -extract /iso_dir /tmp/from_iso
  -extract /iso_file /tmp/from_iso
The last command will fail because /tmp/from_iso already exists as directory.

The "Selected" switch controls whether the whole current ISO directory,
or only the selected items shall be copied to to hard disk.

The "Overwrite files" switch controls whether existing files may be
overwritten in the ISO image or by extraction on hard disk.
The frontend program will only detect the most obvious name collisions,
but xorriso will reliably refuse to overwrite files if this is banned.

The "Overwrite ISO dirs" switch controls whether it is allowed to replace
an ISO directory by a non-directory file.
If a directory is copied to a directory, then both directory trees will
be merged. So this switch applies only to situations where non-directories
hit directories.

The "Enforce disk dir write access" switch enables the options "auto_chmod_on"
and "sort_lba_on". "auto_chmod_on" allows xorriso to give itself temporariy
w-permission to all disk directories which are owned by the xorriso user.
This is not without dangers, of course, but comes in handy with restoring of
backups.
Option "sort_lba_on" reduces head-moves of optical drives and thus can
speed up extraction substantially. It is bound to "auto_chmod_on" because
else it might get in trouble when restoring ISO directories which offer
no w-permission.

The "Refresh avail:" button triggers a time consuming exact prediction
of the free space on the medium in the output drive. For this purpose,
the size of an ISO session with the pending changes is computed.
With image files rather than real optical drives, the free space of
the hosting filesystem is displayed.

The "Insert from disk:" button executes command -map with the disk file
address that is given by the text field right to the button.

The switch "Underneath" has the same effect as with file extraction:
If enabled, a directory from disk will not be unpacked to its single files
but put underneath the target address by its own leaf name.
If the switch "Selected" is enabled, then the given disk file or tree will
be inserted at or underneath the only selected item in the box inderneath
"ISO directory:".

The text field in the "ISO directory:" line displays the current ISO
directory and can be used to toggle its path directly. Hitting the
Return key causes the current directory to change and the display in
the box underneath to be refreshed.

The "Up" buttons move the current ISO directory one directory level up.

The "Verify" button executes -md5_check_r "SORRY" with the current ISO
directory. ISO images bear MD5s for each data file if they were produced
by xorriso with -md5 "on" resp. -for_backup. This frontend enables this
feature on startup.

The list box underneath the "ISO directory:" line displays the files in
the current ISO directory. One or more item can be selected and play a
role with extraction or insertion of files.
Most of the buttons underneath the box operate on the selected items
unconditionally.

The "Verify" button in the "ISO selection:" line executes command
-md5_check_r "SORRY" with each of the selected items.

The "Delete" button executes command -rm_r with each of the selected items.

The "Rename to:" button iuses command -mv to move each of the selected
items to the address that is given by the text field right to the button.
If this address points to an existing ISO directory, then the items will
be moved underneath that directory and keep their leaf names.
Else there may be only one selected item which will be renamed to the
given address.

The "Make dir" button executes command -mkdir with the address in the
text field to its left (the same as used by "Rename to:"). Useful to
create a target directory before moving the selection.