Kommander Notes

I intend to develop a complete command reference manual for kommander, since it bugs me how something so good could be so cryptic.

Tips

Layout: hiding and showing widgets

Like the parent project "QT Designer" the packer favours vertical layouts. So if you want to switch controls using hiding and showing always stack the controls vertically.

Layout in the editor

Running the app(hides the Konsole and the "Hide" button)

After clicking the "Detail" button

Dynamic Widget Resizing

Goes along the lines of:

@dcop(@dcopid, MainWindowClass, resize(int,int), 100, 100)

!!except this doesn't work!!

Closing the app

@dcop(@dcopid, MainWindowClass, quit())

UPDATE: This is now:

@dcop(@dcopid, MainApplication-Interface, quit)

Running Bash Script from Kommander

Event Handlers

You can fire bash functions like events from a kommander dialog

Create a script called hello.sh with:

# My dialog handler

Button1()
{
    kdialog --msgbox "Hello, World!"
}

Then create a kommander dialog with a button and put:

@execBegin

. @global(_KDDIR)/hello.sh

Button1

@execEnd

...in the "Kommander Text" for the button, thus:

Kommander dialog for "Hello, World!" bash script

When you run the dialog the bash script pops up a message box:

Dialog running a bash script

Now you can put all the functionality into a script and have the dialog do the GUI bit.

Talking to Controls

If you modify the Kommander Text thus:

@execBegin

DIALOGID=@dcopid

cd @global(_KDDIR)

. ./pb.sh

init

@execEnd

You can send messages to the controls from the Bash script too.

Add a text control named StatusBar
Include into you Bash Script:

StatusBar()
{
	dcop $DIALOGID KommanderIf $1 StatusBar "$2"
}

Means you can run

StatusBar setText "Some text"

To see "Some Text" appear in the text control

Developer Reference

This will probabably appear a bit disorganised. I will deal with order when the table is filled

Kommander internal

Command	Prototype	Param1	Param2	Param3	Param4	Description	Example
selectedWidgetText	selectedWidgetText()					Returns selected text or text of current item. This is deprecated for @mywidget.selected.
null	null()					Does nothing. This is useful if you request a CheckBox or RadioButton to return a value where a state, typically the unchecked state, has novalue. The @null prevents an error indicating it is empty.
pid	pid()					Returns the pid (process ID) of the current process.
dcopid	dcopid()					Returns DCOP identifier of current process. This is shorthand for kmdr-executor-@pid.
parentPid	parentPid()					Returns the pid of the parent Kommander window.
execBegin	execBegin(string)	shell				Executes a script block. Bash is used if no shell is given. It is primarily for use in non-button widgets where script actions are not expected. Full path is not required for the shell which may be useful for portability. If this is used inside a button it allows alternate script languages to be used and will return a value to the main script, which may be unexpected.
execEnd	execEnd					Ends the script block.
env	env(string)	variable				Returns value of an environment (shell) variable. Do not use $ in the name. For example, @env(PATH).
exec	exec(string)	command				Executes an external shell command.	@exec (cat /proc/cpuinfo \| grep "model name")
expr	expr(string)	expression				Parses an expression and returns computed value.
forEach	forEach(string,string)	variable	items			Executes loop: values from items list (passed asEOL-separated string) are assigned to the variable. @forEach(i,A\nB\nC\n) @# @i=A @endif
for	for(string,int,int,int)	variable	start	end	step	Executes loop: variable is set to start and is increased by step each time loop is executed. Execution stops when variable becomes larger then end. @for(i,1,10,1) @# @i=1 @endif.
global	global(string)	variable				Returns the value of a global variable.
i18n	i18n(string)	variable				Translates the string into the current language. Texts in GUI would be automatically extracted for translation.
if	if(string)	expression				Executes block if expression is true (non-zero number of non-empty string.) <p>Close with @endif</></p>
dialog	dialog(string,string)	file	args			Executes another Kommander dialog. Current dialog directory is used if no path is given. Arguments may be given as named arguments which will become global variables in the new dialog. For instance: var=val
readSetting	readSetting(string,string)	key	default			Reads setting from configration file for this dialog.
setGlobal	setGlobal(string,string)	variable	value			Sets the value of a global variable. Global variables exist for the life of the Kommander window.
writeSetting	writeSetting(string,string)	key	value			Stores setting in configuration file for this dialog.
switch	switch(string)	expression				Begin of switch block. Following case values are compared to expression. @switch() @case() @end	@switch (program) @case (xterm) @exec (xterm) @case (konqueror) @exec (konqueror) @end
dcop	dcop(string,string,string,string)	id	interface	function	args	Executes an external DCOP call.	@thisCheckbox.setChecked (@dcop(kdesktop,KDesktopIface,"isIconsEnabled()")) @dcop(kdesktop,KDesktopIface,"setIconsEnabled(bool)", @thisCheckbox)
#	#(string,string,string,string)	string	string	string	string	Adds a comment to EOL that Kommander will not parse

Arrays

Command	Prototype	Param1	Param2	Param3	Description	Example
values	values(string)	array			Returns an EOL-separated list of all values in the array.
keys	keys(string)	array			Returns an EOL-separated list of all keys in the array.
clear	clear(string)	array			Removes all elements from the array.
count	count(string)	array			Returns the number of elements in the array.
value	value(string,string)	array	key		Returns the value associated with the given key.	@thisLabel.setText (@Array.value (programs,0))
remove	remove(string,string)	array	key		Removes element with the given key from the array.
setValue	setValue(string,string,string)	array	key	value	Adds element with the given key and value to the array	@Array.setValue (programs,0,kuickshow)
fromString	fromString(string,string)	array	string		Adds all elements in the string to the array.
toString	toString(string)	array			Returns all elements in the array in key\tvalue\n format.

DCOP

Command	Prototype	Param1	Param2	Description
addUniqueItem	addUniqueItem(string)	item		Inserts the item if it will not create a duplicate.
associatedText	associatedText()			Returns scripts associated with widget. This is an advanced feature that would not be commonly used.
checked	checked()			Returns 1 for checked boxes, 0 for unchecked.
children	children(bool)	recursive		Returns the list of child widgets contained in the parent widget. Set the recursive parameter to true to include widgets contained by child widgets.
clear	clear()			Removes all content from the widget.
count	count()			Returns number of items in a widget such as combobox or listbox.
currentItem	currentItem()			Returns index of current item.
insertItem	insertItem(string,int)	item	index	Inserts item at index position.
insertItems	insertItems(string list,int)	items	index	Inserts multiple items (EOL-separated) at index position.
item	item(int)	index		Returns the text of the item at the given index.
itemDepth	itemDepth(int)	index		Returns the depth of the current item in the tree. Root items have depth 0.
itemPath	itemPath(int)	index		Returns the slash-separated path to the given item in the tree.
removeItem	removeItem(int)	index		Removes the item with the given index.
setAssociatedText	setAssociatedText(string)	text		Sets scripts associated with widget. This is an advanced feature that would not be commonly used.
setEnabled	setEnabled(bool)	enabled		Enables or disables widget.
selection	selection()			Returns selected text or text of current item.
setChecked	setChecked(bool)	checked		Sets/unsets checkbox.
setCurrentItem	setCurrentItem(int)	index		Selects the item at the specified index. Indexes are zero based.
setMaximum	setMaximum(int)	value		Sets maximum numeric value
setPixmap	setPixmap(string,int)	iconName	index	Sets pixmap at the given index to the specified icon. Use index = -1 to set the pixmap for all items.
setSelection	setSelection(string)	text		Selects given text or select item containing given text.
setVisible	setVisible(bool)	visible		Shows/hides widget.
findItem	findItem(string)	item		Returns the index of an item with the given text.
type	type()			Returns type(class) of widget.

File

Command	Prototype	Param1	Param2	Description
read	read()			Returns content of given file.
write	write(string,string)	file	string	Writes given string to a file.
append	append(string,string)	file	string	Appends given string to the end of a file.

String

Command	Prototype	Param1	Param2	Param3	Param4	Description
length	length(string)	string				Returns number of chars in the string.
contains	contains(string,string)	string	substring			Checks if the the string contains the given substring.
find	find(string,string,int)	string	sought	index		Returns the position of a substring in the string, or -1 if it is not found.
findRev	findRev(string,string,int)	string	sought	index		Returns the position of a substring in the string, or -1 if it is not found. String is searched backwards
left	left(string,int)	string	n			Returns the first n chars of the string.
right	right(string,int)	string	n			Returns the last n chars of the string.
mid	mid(string,int,int)	string	start	n		Returns n chars of the string, starting from start.
remove	remove(string,string)	string	substring			Removes all occurrences of given substring.
replace	replace(string,string,string)	string	substring	replacement		Replaces all occurrences of the given substring with the given replacement.
upper	upper(string)	string				Converts the string to uppercase.
lower	lower(string)	string				Converts the string to lowercase.
compare	compare(string,string)	string1	string2			Compares two strings. Returns 0 if they are equal,
isEmpty	isEmpty(string)	string				Checks if the string is empty.
isNumber	isNumber(string)	string				Checks if the string is a valid number.
section	section(string,string,int)	string	separator	index		Returns given section of a string.
args	args(string,string,string,string)	string	arg1	arg2	arg3	Returns the given string with %1, %2, %3 replaced with arg1, arg2, arg3 accordingly.

Combobox

Command	Prototype	Param1	Param2	Description	Example
selection	selection()			Returns selected text or text of current item.
setSelection	setSelection(string)	text		Selects given text or select item containing given text.
currentItem	currentItem()			Returns index of current item.
setCurrentItem	setCurrentItem(int)	index		Selects the item at the specified index. Indexes are zero based.	@thisCheckbox.setChecked (@dcop(kdesktop,KDesktopIface,"isIconsEnabled()")) @dcop(kdesktop,KDesktopIface,"setIconsEnabled(bool)", @thisCheckbox)
item	item(int)	index		Returns the text of the item at the given index.
removeItem	removeItem(int)	index		Removes the item with the given index.
insertItem	insertItem(string,int)	item	index	Inserts item at index position.
insertItems	insertItems(string list,int)	items	index	Inserts multiple items (EOL-separated) at index position.
clear	clear()			Removes all content from the widget.
count	count()			Returns number of items in a widget such as combobox or listbox.

Label

Command	Prototype	Param1	Description	Example
setText	setText(string)	text	Sets widget's content.	@thisLabel.setText (my label text)
text	text		Gets the text of a label.	@thisLabel.setText (@anotherLabel.text)
clear	clear()		Removes all content from the widget.

Listbox

Command	Prototype	Param1	Param2	Description
setText	setText(string)	text		Sets widget's content.
selection	selection()			Returns selected text or text of current item.
setSelection	setSelection(string)	text		Selects given text or select item containing given text.
insertItems	insertItems(string list,int)	items	index	Inserts multiple items (EOL-separated) at index position.
insertItem	insertItem(string,int)	item	index	Inserts item at index position.
removeItem	removeItem(int)	index		Removes the item with the given index.
clear	clear()			Removes all content from the widget.
currentItem	currentItem()			Returns index of current item.
setCurrentItem	setCurrentItem(int)	index		Selects the item at the specified index. Indexes are zero based.
item	item(int)	index		Returns the text of the item at the given index.
addUniqueItem	addUniqueItem(string)	item		Inserts the item if it will not create a duplicate.
findItem	findItem(string)	item		Returns the index of an item with the given text.
setPixmap	setPixmap(string,int)	iconName	index	Sets pixmap at the given index to the specified icon. Use index = -1 to set the pixmap for all items.
count	count()			Returns number of items in a widget such as combobox or listbox.

TextEdit

Command	Prototype	Param1	Description
setText	setText(string)	text	Sets widget's content.
selection	selection()		Returns selected text or text of current item.
clear	clear()		Removes all content from the widget.

CheckBox

Command	Prototype	Param1	Description	Example
setText	setText(string)	text	Sets widget's content.
checked	checked()		Returns 1 for checked boxes, 0 for unchecked.	@thisCheckbox.setChecked (@anotherCheckbox)
setChecked	setChecked(bool)	checked	Sets/unsets checkbox.	@thisCheckbox.setChecked (false)

ExecButton

Command	Prototype	Param1	Param2	Param3	Param4	Description
setText	setText(string)	text				Sets widget's content.

LineEdit

Command	Prototype	Param1	Description
setText	setText(string)	text	Sets widget's content.
selection	selection()		Returns selected text or text of current item.
setSelection	setSelection(string)	text	Selects given text or select item containing given text.
clear	clear()		Removes all content from the widget.

GroupBox

Command	Prototype	Param1	Param2	Param3	Param4	Description
setText	setText(string)	text				Sets widget's content.

ScriptObject

Command	Prototype	Param1	Param2	Param3	Param4	Description
setText	setText(string)	text				Sets widget's content.
clear	clear()					Removes all content from the widget.

Konsole

Command	Prototype	Param1	Description
setText	setText(string)	text	Sets widget's content.
setAssociatedText	setAssociatedText(string)	text	Sets script content. NOTE: This is Kommander language not shell use exec() to run shell
execute	execute		Runs the script
clear	clear()		Removes all content from the widget.

Enter "ls -c1 /usr/local" for Konsole1 default text and connect the ExecButton1 clicked() signal with Konsole1 execute() slot, then it works.

PixmapLabel

Command	Prototype	Param1	Param2	Param3	Param4	Description
setText	setText(string)	text				Sets widget's content.
clear	clear()					Removes all content from the widget.

TextBrowser

Command	Prototype	Param1	Description
setText	setText(string)	text	Sets widget's content.
selection	selection()		Returns selected text or text of current item.
clear	clear()		Removes all content from the widget.
children	children(bool)	true=recursive	Returns the list of child widgets contained in the parent widget. Set the recursive parameter to true to include widgets contained by child widgets.
setEnabled	setEnabled(bool)	true=enabled	Enables or disables widget.
setVisible	setVisible(bool)	true=visible	Shows/hides widget.
text	text		Returns content of widget.
type	type		Returns type(class) of widget.

TreeWidget

Command	Prototype	Param1	Param2	Description
setText	setText(string)	text		Sets widget's content.
insertItem	insertItem(string,int)	item	index	Inserts item at index position.
insertItems	insertItems(string list,int)	items	index	Inserts multiple items (EOL-separated) at index position.
selection	selection()			Returns selected text or text of current item.
setSelection	setSelection(string)	text		Selects given text or select item containing given text.
clear	clear()			Removes all content from the widget.
removeItem	removeItem(int)	index		Removes the item with the given index.
currentItem	currentItem()			Returns index of current item.
setCurrentItem	setCurrentItem(int)	index		Selects the item at the specified index. Indexes are zero based.
findItem	findItem(string)	item		Returns the index of an item with the given text.
item	item(int)	index		Returns the text of the item at the given index.
itemPath	itemPath(int)	index		Returns the slash-separated path to the given item in the tree.
itemDepth	itemDepth(int)	index		Returns the depth of the current item in the tree. Root items have depth 0.
setPixmap	setPixmap(string,int)	iconName	index	Sets pixmap at the given index to the specified icon. Use index = -1 to set the pixmap for all items.

To insert/set multi column entries use a TAB "\t"
e.g.:

@TreeWidget1.insertItem ("one\ttwo", 0)

inserts "one" to the first column and "two" to the second column of the first row.
NOTE: The columns need to be added first.

To insert a leaf item use a slash "/"
e.g.:

@TreeWidget1.insertItem ("three\four", 0)
@TreeWidget1.insertItem ("three\five", 0)

inserts "three" to the first column with leaf nodes "four" and "five"

Table

Command	Prototype	Param1	Param2	Param3	Description
cellText	cellText(int,int)	row	column		Returns text of a cell in a table
children	children(bool)	recursive			Returns the list of child widgets contained in the parent widget. Set the recursive parameter to true to include widgets contained by child widgets.
currentColumn	currentColumn()				Returns index of current column.
currentRow	currentRow()				Returns index of current row.
insertColumn	insertColumn(int,int)	column	count		Inserts new column (or count columns) at column position.
insertRow	insertRow(int,int)	row	count		Inserts new row (or count rows) at row position.
removeColumn	removeColumn(int,int)	row	count		Removes the column (or count consecutive columns) with the given index.
removeRow	removeRow(int,int)	row	count		Removes the row (or count consecutive rows) with the given index.
setCellText	setCellText(int,int,string )	row	col	text	Sets text of a cell in a table.
setColumnCaption	setColumnCaption(int,string)	column	text		Sets caption of the column column.
setEnabled	setEnabled(bool)	enabled			Enables or disables widget.
setRowCaption	setRowCaption(int,string)	row	text		Sets caption of the row row.
setText	setText(string)	text			Sets widget's content.
setVisible	setVisible(bool)	visible			Shows/hides widget.
text	text()				Returns content of widget.
type	type()				Returns type(class) of widget.

CloseButton

Command	Prototype	Param1	Param2	Param3	Param4	Description
setText	setText(string)	text				Sets widget's content.

FileSelector

Command	Prototype	Param1	Description	Example
setText	setText(string)	text	Sets the text field in the file selector	@thisFileSelector.setText (myfile.txt)
selection	selection()		Returns selected text or text of current item.
setSelection	setSelection(string)	text	Selects given text or select item containing given text.
clear	clear()		Removes all content from the widget.

RadioButton

Command	Prototype	Param1	Param2	Param3	Param4	Description
setText	setText(string)	text				Sets widget's content.
setChecked	setChecked(bool)	checked				Sets/unsets checkbox.

ButtonGroup

Command	Prototype	Param1	Param2	Param3	Param4	Description
checked	checked()					Returns 1 for checked boxes, 0 for unchecked.
setChecked	setChecked(bool)	checked				Sets/unsets checkbox.

TabWidget

Command	Prototype	Param1	Param2	Param3	Param4	Description
currentItem	currentItem()					Returns index of current item.
setCurrentItem	setCurrentItem(int)	index				Selects the item at the specified index. Indexes are zero based.

Slider

Command	Prototype	Param1	Description
setText	setText(string)	text	Sets widget's content.
clear	clear()		Removes all content from the widget.
setMaximum	setMaximum(int)	value	Sets maximum numeric value

RichTextEditor

Command	Prototype	Param1	Description
setText	setText(string)	text	Sets widget's content.
clear	clear()		Removes all content from the widget.
selection	selection()		Returns selected text or text of current item.

StatusBar

Command	Prototype	Param1	Param2	Description
setText	setText(string)	text		Sets widget's content.
insertItem	insertItem(string,int)	item	index	Inserts item at index position.
removeItem	removeItem(int)	index		Removes the item with the given index.
clear	clear()			Removes all content from the widget.

ProgressBar

Command	Prototype	Param1	Description
setText	setText(integer)	integer	Sets the numeric progress
clear	clear()		Resets the progress to zero
setMaximum	setMaximum(int)	value	Sets maximum numeric value

Timer

Command	Prototype	Param1	Param2	Param3	Param4	Description
setText	setText(string)	text				Sets widget's content.

Message

Command	Prototype	Param1	Param2	Param3	Param4	Param5	Description
info	Message.info(string,string)	text	caption				Shows an information dialog. Only first argument is obligatory.
error	Message.error(string,string)	text	caption				Shows an error dialog. Only first argument is obligatory.
question	Message.question(string,string,string,string,string)	text	caption	button1	button2	button3	Shows a question dialog with up to three buttons. Returns number of selected button. Only first argument is obligatory.
warning	Message.warning(string,string,string,string,string)	text	caption	button1	button2	button3	Shows a warning dialog with up to three buttons. Returns number of selected button. Only first argument is obligatory.

The button3 doesn't seem to map the text and just shows as "Cancel". This is most likely because the interpreter is designed to interpret only 4 parameters.