Functions
Prev
Next

Functions

Most old parser functions are supported by new parser. Also, some new functions were added.

String functions

String functions are the same as in old parser, the only difference is that their names are preceeded by str_ instead of @String.

  • str_length(string) - returns length of string

  • str_contains(string, text) - returns 1 if string contains text

  • str_find(string, text, start) - returns position of the first occurrence of text in string; optional start specifies start of the search

  • str_find(string, text, start) - returns position of the last occurrence of text in string; optional start specifies start of the search

  • str_left(string, count) - returns first count characters of string

  • str_right(string, count) - returns last count characters of string

  • str_right(string, start, count) - returns substring of string starting from start and containing count characters (or everything to the end of the string if last parameter is not specified)

  • str_remove(string, text) - returns string with all substrings equal to text removed

  • str_replace(string, text, text2) - returns string with all substrings equal to text replaced with text2

  • str_lower(string) - returns string converted to lowercase

  • str_upper(string) - returns string converted to uppercase

  • str_section(string, separator, start, end) - returns substring containing appropriate sections of string determined by separator; if no end is given, single start section is returned

  • str_args(string, ...) - returns string with %1, %2, %3 replaced with following parameters.

  • str_isnumber(string) - returns 1 if string is a valid number

  • str_isempty(string) - returns 1 if string is empty

  • str_toint(string, default) - returns string converted to integer; if conversion is not possible, optional default value is returned

  • str_todouble(string, default) - returns string converted to double; if conversion is not possible, optional default value is returned

Kommander functions

Most Kommander functions are supported; some (such as expr) were obsoleted by new parser and are not available.

  • debug(string, ...) - writes all parameters on stderr

  • echo(string, ...) - writes all parameters on stdout

  • dcop(string, ...) - calls DCOP function

  • exec(string, shell) - executes external program (using optional shell); block the execution of the current dialog until the program passed as the parameter exits; returns output of that program

  • i18n(string) - marks string for future translation

  • env(string) - returns a value of environmental variable

  • readSetting(key, default) - returns a value stored in config file with given key; if there is no such value default is returned

  • writeSetting(key, value) - writes pair key and value in config file

New in Kommander 1.3

  • execBackground(string, shell) - executes external program (using optional shell) in the background, without blocking the current dialog; contrary to the above exec function, it will not return the output of the program.

  • return(value) - returns a value to the calling object (script, button...)

  • createWidget(widgetname, widgettype, parent) - creates a new widget. You can then place it in a table or toolbox, for example and use mywidget.show(true) to make it visible. If you are putting an new widget on the form you need to consider layout issues. Kommander will not create layouts on the fly or edit pixel by pixel positioning (in most cases). This is confusing even in C++ development. We recommend you use a groupbox and do a layout in the dialog for best control.

  • connect(sender, signal, receiver, slot) - connect a widget signal to a widget slot. See the connection dialog and select similar widgets for possibilities. If for instance a signal looks like looks like execute(const TQString&) that is exactly what must be in quotes there.

  • disconnect(sender, signal, receiver, slot) - undo the connection as listed above. Again, exact syntax is essential.

  • widgetExists(widgetname) - remember you can use a variable name to reference a widget now. Use this when accessing created widgets to insure they are there. Calling a non-existant widget obviously will throw an error.

Array functions

Most array functions are supported; some (such as value) were obsoleted by new parser and are not available. The only difference is that their names are preceeded by array_ instead of @Array.

Warning

Due to parser limitation, name of array has to be specified as string now; for example array_count("MyArray").

  • array_clear(array) - removes all elements from array

  • array_count(array) - returns number of elements in array

  • array_keys(array) - returns string containing EOL-separated keys of array - note that if you had imported a scalar (keys without values, see below for an example) into an array with Kommander you would not be able to access it with array_values("myarray") as you might think (since it seems to only have values) but would instead need to use array_keys("myarray"). You might find a better choice for this is to use the new indexed arrays described below.

  • array_values(array) - returns string containing EOL-separated values of array

  • array_tostring(array) - returns string containing whole array as EOL-separated pairs containing key and value separated with TAB character

  • array_fromstring(array, string) - reads array from string (usually provided by array_tostring function)

  • array_remove(array, key) - removes item with key key from array

Here is an example for array manipulation:

array_fromstring("myArray", "1\tA\nsecond\tB\n3\tC")
foreach key in myArray do
  debug("myArray[" + key + "]= " + myArray[key])
end

This will print out the following to the stderr. It is visible that there is no guarantee about the order of array elements, as well that the keys are strings, not numbers.

myArray[1]= A
myArray[3]= C
myArray[second]= B

Another example for keyless arrays:

array_fromstring("myArray", "A\nB\nC")
foreach key in myArray do
  debug(key)
end
debug("Array elements:\n" + array_keys("myArray"))

This results in:

A
B
C
Array elements:
A
B
C

New in Kommander 1.3

  • array_indexedFromString(array, string, separator) - this compensates for Kommander not having indexed arrays. it creates an array with a zero based sequential index. Remember to use quotes on the array name and any strings not represented by a variable. The separator argument is optional and defaults to "\t" [TAB] which is used to separate fields reading and writing tables, arrays or detail widgets. Remember this array index does not enforce any rules on its self. It is just like you created it with a for loop, just more convenient.

  • array_indexedInsertElements(array, key, string, separator) - this function is part of the indexed array suite and enables you to insert elements in your array while maintaining an index that is sequential, contiguous and unique. Set the index key to start at and the text string and how it is separated. The elements will be added shifting all the index numbers after by the number added.

  • array_indexedRemoveElements(array, key start, number) - this enables you to remove elements from an indexed array and avoid gaps in your index. Specify the key to start at and optionally how many to remove. The default is one. You will end up with a re-indexed array less the removed elements.

  • array_indexedToString(array, separator) - this enables you to convert your indexed array back into a string, particularly useful for detail widgets. For instance if you are displaying a database query result in TreeWidget1 and it has six columns you can use TreeWidget1.selection to get the selected row. it will be separated by tabs and you could look at a the fifth element by using str_section(TreeWidget1.selection, "\t", 4) (remember it is zero based). That's nice for reading a value, but if you want to change it you can see you have a lot more work to do. After you split that string you have to reassemble with val1+"\t"+val2... Using indexed arrays you could edit that fifth element like so...

    idx = TreeWidget1.currentItem
    array_indexedFromString("z", TreeWidget1.selection)
    z[4] = "new value"
    TreeWidget1.removeItem(idx)
    TreeWidget1.insertItem(array_indexedToString("z"), idx)
    
    Note that only two short lines were added to accomplish this! This was very welcome for database use.

File functions

All file functions are supported, the only difference is that their names are preceeded by file_ instead of @File.

  • file_read(name) - returns content of file name

  • file_write(name, ...) - writes all arguments to file name

  • file_append(name, ...) - appends all arguments to file name

Input functions

These functions show some dialog allowing user to enter some value. They are accessible in the old parser using @Input.. For most functions all parameters are optional, exception is input_text which requires 2 parameters and input_value which requires 5 parameters.

  • input_color(caption, default) - returns color in #RRGGBB format

  • input_text(caption, label, default) - returns text entered by user

  • input_value(caption, label, default, min, max, step) - returns value entered by user

  • input_directory(startdir, filter, caption) - returns directory selected by user

  • input_openfile(caption, label, default) - returns existing file entered by user

  • input_savefile(caption, label, default) - returns file entered by user (if file exists, confirmation will be required)

  • input_openfiles(caption, label, default) - returns string of EOL-separated existing files entered by user

Message functions

These functions show some message for user or ask user to confirm some action. In the old parser use @Message. instead.

  • message_info(text, caption) - shows information text

  • message_error(text, caption) - shows error text

  • message_warning(text, caption, button1, button2, button3) - shows question with warning and up to three buttons; number of chosen button is returned; if no button names are specified, Yes and No will be displayed

  • message_question(text, caption, button1, button2, button3) - shows question and up to three buttons; number of chosen button is returned; if no button names are specified, Yes and No will be displayed

Prev
Next
Home


Would you like to comment or contribute an update to this page?
Send feedback to the TDE Development Team