Cat'sEyE, the newusercommand sytanx

'NewUserCommand'

The usercommand as you know it so far is very simple, but not very flexible. The pair-structure where the names of the marked items are simply added behind the value or command the user defines is very limitating.

To be more flexible the newusercommand was created. However, the syntax still is the same as in the old one and therefore, the old usercommand still works.

The difference is in the 'value' (or better 'command') section of the pair-structur ('keyphrase:name;value'). Here, the newusercommand is organized in three blocks, one formating the command called to a shell, one to define a dialog to get input from the user, and the last one to define some options about the way of calling the items to the system.

Each block starts with '<blockname' where blockname is a keyword for each block and ends with '/>'. All blocks have to be in one single line so Cat'sEyE can recognise them as the 'value' in the usercommand.

Every block has properties which have to be inside the block.

Inside of the text property of the command block and the question-predefine property of the dialog block you have access to some variables listed below. They are exchanged when processed.

Prefined variables
variable name	exchanged with
<ThisDirectory> <TDIR>	the directory of the view where the contextmenu is opened, no quotes and no ending slash
<OtherDirectory> <ODIR>	the directory of the view of the other side, no quotes and no ending slash
<Home> <home>	the home directory of the user
<MarkedItems> <MI>	all marked items in a single line each one in quotes
<MarkedItemsUnQuoted> <MI_UQ>	same as before but without quotes
<MarkedItemsWithPath> <MIWP>	all marked items with pathes in a single line each one in quotes
<MarkedItemsWithPathUnQuoted> <MIWP_UQ>	same as before but without quotes

Get more information about the values of this variables in different circumstances in: Odds and ends.

The most important one is the command block:
blockname: '<command'

property	description	usage
text	holds the command and variables to build the string given to the shell	text="xv <MarkedItems>"

The most interresting one is the dialog block:
blockname: '<dialog'

This one allows you to define a dialog and your own variables to get input from the user and use it in the command block

property	description	usage
capion	the caption of the dialog	caption="some questions"
label	some text viewed in the dialog	label="some text"
question	define a question text a variable name and, if you want, a predefine to get input from the user	question="text"<VAR1>predefine=<ThisDirectory> question="text"<VAR1>predefine="answer" question="text"<VAR2>
checkbox	define a text a variable name, the value for true and if you want, the value for false and a predefine (if the checkbox is checked first or not)	checkbox="text"<CHK1>"value for true":"value for false(optional)"predefine=<TRUE> checkbox="text"<CHK1>"value for true"predefine="answer" checkbox="text"<CHK1>"value for true"
text	define a text which is displayed	text="some text"
filechooser	creates a button which opens a file chooser dialog. The file you choose will be displayed in the edit box of the leading question. Therefore, there MUST be a question in front of this property	filechooser="button text" filechooser="button text"predefine="dialog caption"
dirchooser	the same as file chooser but lets you only choose directories.	dirchooser="button text" dirchooser="button text"predefine="dialog caption"

The question, checkbox and text properties can be repeated for as much input you need, just change the variable name (in the example <VAR1>). The name of the variable is not fix, it just has to be between '<' and '>'. This variable can be used in the text property of the command block. The order you define them is the same how it will displayed in the dialog.

It's time for a working example:
To pack the marked files with e.g. tar, it is usefull to get some information from the user such as the name of the archive and the destination path.
So, we start with the dialogblock (actually it doesn't matter wich block comes first):

<dialog caption="pack files with tar" label="Predefines:\t\t\t\t\t \n<OtherDirectory> \n<ThisDirectory> \n<MarkedItems> \n<MarkedItemsUnQuoted> \n<Home>\n" question="Name of archive"<NAME> predefine="newarchive.new" question="Path: (without end'/')"<PATH> predefine=<ThisDirectory> question="More options:"<OPTIONS> />

This will show this dialog:

You can see the label and the three questions as they are defined wihtin the block.
The predefine of the first question is a text, the second is one of the prefined variables listed in the table above and the third question is empty because there is no predefine.

The user may now enter a new name, path or add some options. The user is also able to answer the questions with one of the prefined variables.

When the user proceeds the dialog, the usercommand block is read:

<command text="tar -c -f \"<PATH>/<NAME>\" <OPTIONS> <MarkedItems> "/>

where <PATH>, <NAME> and <OPTIONS> are the variables defined within the dialog block and now filled with the users input. All the variables are exchanged to the text they inherited.

You might have recognised the checkbutton 'Show me the complete command' in the dialog box.
Activate this one will bring up a widget showing you the whole command just before it is sent to the shell, so you can check it, change it or even abort the whole procedure.

The last block is the options block:
blockname: '<options'

With the help of this block you can specify how the items are processed.

property	description	usage
call	how to call the items to the system	possible values are: call="all" call="each" call="list"
caption	only works with call="list" and defines the name of the widget	caption="thecaption"
label	only works with call="list", and views some text in the widget	label="some text"
quitreply	When the process ends the text you define here will be displayed. You have access to all variables you have definened and to the predefined too. Does not work with call="list".	quitreply="sometext" quitreply="text <Home>"
folderupdate (unused since 3.0)	When the process ends the text you define here will be identified as a directory which should be updated, when shown on one side. You have access to all variables you have definened and to the predefined too.	folderupdate="/usr/lib" folderupdate="<Home>" folderupdate="<AnyVariable YouDefined>"
actionnote	Defines a little widget which exists as long as the process runs. The user only can define the caption. Within this widget the command is displayed.	actionnote="caption"

If you dont use this block, the items are called to the system in the call-all-with mode (call="all").
This means, that the predefined variables <MarkedItems> and <MarkedItemsUnQuoted> simply hold all the marked items put together in a single line.

When defining call="each", the predefined variables <MarkedItems> and <MarkedItemsUnQuoted> just hold one item at a time while each item is called to the system with the help of the dialog and command block. You will end up to as many processes as you have marked items.

The list mode ( call="list" ) puts all marked items to a list, the predefined variables <MarkedItems> and <MarkedItemsUnQuoted> are filled with just one item at a time but the next item is not processed as long the previous one is not finished.
There will be a widget holding the list and show you which item is currently processed. This is where the other two properties come in handy as you might want to add some text to the list-widget.

And that's all about the newusercommand.

You may look into the configfile, accessible through the downloadsection. It makes use of the most possibilities shown here.