tdewebdev/doc/kommander/basics.docbook

<?xml version="1.0"  encoding="UTF-8" ?>

<chapter id="kmdr-basics">
<chapterinfo>
<title>&kommander; Basics</title>
<authorgroup>
<author>
<firstname>Tamara</firstname>
<surname>King</surname>
<affiliation><address>
<email>tik@acm.org</email>
</address></affiliation>
</author>
<author>
<firstname>Eric</firstname>
<surname>Laffoon</surname>
<affiliation><address>
<email>sequitur@kde.org</email>
</address></affiliation>
</author>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>
</chapterinfo>

<title>&kommander; Basics</title>

<!-- This chapter should tell the user how to use your app. You should use as
many sections (Chapter, Sect1, Sect3, etc...) as is necessary to fully document
your application. -->

<sect1 id="concepts">
<title>Concepts</title>


<para>
&kommander; was originally designed around a simple concept that has proven somewhat revolutionairy among visual design tools. Typically these tools allow you to create dialogs and possibly mainwindow interfaces.  Of course a mainwindow interface is the main program window which typically has menus, toolbars, statusbar and the application area. Dialogs are child windows which typically don't have menus and are so named because their purpose is to <quote>have a dialog</quote> or exchange information between you and the main application. The elements on a dialog are called <quote>widgets</quote> and you hook your program into these widgets. &kommander; is different because it is inherently nonprogrammatic here. It uses the concept of associating text with the widgets on the dialog. Initially this was called <quote>Associated Text</quote> but now it is called <quote>&kommander; Text</quote>. Widgets on &kommander; dialogs can include the content of other widgets by reference and a widget can reference its own content by use of a <quote>Special</quote> that looks like this, @widgetText. Specials are commands with special meaning in &kommander;. So if you created a dialog with two LineEdit widgets and named the first <quote>FirstName</quote> and the second <quote>LastName</quote> you could create a button and set its &kommander; Text to <quote>My name is @FirstName @LastName</quote>. You would need to set @widgetText in the first and last name widgets. Remember?  We need to tell &kommander; to reference the text in them.  You could run this from a <application>Konsole</application> and it would output the string for you. So it would reference the first name like so:  @FirstName -> get the widget named FirstName(@FirstName) -> @widgetText -> get the contents of the LineEdit widget.  So in this case @FirstName returns <quote>Eric</quote>:  @FirstName -> @widgetText -> <quote>Eric</quote>.
</para>

<para>
That is the simple core of &kommander;. What you can do with this is where it gets interesting. First of all it is worth noting that compared to the normal approach of a language based tool &kommander; does not need programming statements to define these operations. This makes &kommander; quick for developers. For end users it's much simpler than learning language constructs. For everyone it means you can focus on your task instead of having your reference material eternally at hand. Initially when people are exposed to a tool like &kommander; the first question is <quote>Where could I find a use for this cool tool?</quote> As it turns out, manipulating strings is used just about anywhere you look.
</para>

<para>
So what can &kommander; do? Here is the list distilled to the base operations.
&kommander; can:
</para>

<orderedlist>
<listitem><para>Pass strings to the calling program via stdout.</para></listitem>
<listitem><para>Call executable programs.</para></listitem>
<listitem><para>Use &DCOP; to interact with &kde; programs</para></listitem>
</orderedlist>

<para>
If you're not a programmer you may want that in laymans terms. In number one, if you launch &kommander; from a console then the console is the calling program. There is a parent child relationship there. Sending a message to console is done with the standard output (stdout) of the child program, so named because there is also error output. This is interesting because some programs, like &quantaplus;, use stdout to receive information from programs they launch. So &kommander; dialogs can output their text strings directly into &quantaplus;'s editor if they are called from &quantaplus;. This means &kommander; dialogs can be useful extentions to programs.
</para>

<para>
The second case is calling an executable. Any program that runs on your system is an executable. Even a script program is run by the script's interpreter so technically it's executed too. &kommander; can run commands just like the console even if you run it from the menu. So for instance if you wanted it to open &GIMP; you would have a button derive the string <quote>gimp</quote> and put it in a special like so: @exec(gimp).  Just like that you will see &GIMP; open when using this. You could also exec <quote>ls -l</quote> too but you would only see the output if you were running from a console.
</para>

<para>
The third case is very interesting indeed. &DCOP; is short for &kde;'s <emphasis>D</emphasis>esktop <emphasis>CO</emphasis>mmunication <emphasis>P</emphasis>rotocol and it is very powerful. Go ahead and run the <application>kdcop</application> program and have a look around. You'll quickly see that any &kde; application that is built to standards has things happening in &DCOP; and the well designed ones have a lot going on. With &DCOP; you can query information of all sorts as well as set widget values and more. There is a section on using &DCOP; in this manual. &kommander; can send &DCOP; to any &kde; program as well as be controlled by &DCOP;. In fact you can send &DCOP; from the command line to any &kde; program.  So what's the big deal?  The deal is, if you want to do any volume of commands you begin to realized that command line &DCOP; is adequate for short commands, but it can cause delays for instance being called from a loop several hundred times. This is why &kommander; has a @dcop special, because this is roughly 1000 times faster. Because &kommander; can send and receive &DCOP;, &DCOP; can be used to script &kommander;. That is why we also have a local &DCOP; special, @ldcop, that allows you to type a lot less to issue a command.
</para>

<para>
Is that all the core concepts in &kommander;? No, but it should help you to make sense of how it works so that what is covered does not look like a foreign language to you. There are a few more. Signals and slots are how &kommander; handles events. An event in a program basically means <quote>something happened</quote> like a widget was created or had its text changed. These changes <quote>emit signals</quote> and you can connect those signals to a receiving slot which will then do something when the event happens. One use of this in &kommander; is the sibling of &kommander; Text, <quote>Population Text</quote>. Population Text will populate a widget when called. Just like &kommander; Text, Population Text can contain text strings or scripts.
</para>

<para>
That should give you the base concepts to begin using &kommander;. We try to keep the number of Specials low and we use &DCOP; a lot. The idea is that we want to keep the power of &kommander; as consistent and streamlined as possible. You will find that you can incorporate any scripting language into &kommander; where ever you need to and even multiple scripting languages in a dialog. The rest of the information in this document assumes you are familiar with the concepts and terms presented here. The examples and tutorials are also very useful to understanding what can be done with &kommander;.
</para>
</sect1>

&editor;

<sect1 id="executor">
<title>The Executor</title>

<para>
The executor, called <application>kmdr-executor</application>, runs &kommander; scripts.  It loads <literal role="extension">.kmdr</literal> files and dynamically produces a fully functional dialog. 
<warning><para>Starting with version 1.3, the executor warns if the script file is not executable. This is an extra security feature that tries to make the user think about the possible bad consequences of running a script from untrusted source. The user can confirm to run the dialog or if he trusts the source, can make the script executable and get rid of the warning completely.</para></warning>
<note><para>Version 1.3 supports the <emphasis>#!/path/kmdr-executor</emphasis> shebang in the beginning of the .kmdr script files (replace path with path to the 
Such files if they are made executable can be run from command line just like any executable application, without the need to pass the script to kmdr-executor as argument.</para>
<para>
Remember, that once you add the shebang at the beginning of the file, the dialog cannot be run or edited with older versions of &kommander;.</para>
<para>The recommended usage is
<screen>
#!/usr/bin/kommander
</screen>
and create a symlink from kmdr-executor to /usr/bin/kommander.</para>
<para>The shebang can be added to a dialog directly from the editor, by modifying the <guilabel>useShebang</guilabel> and <guilabel>shebang</guilabel> properties for the main dialog.</para>

</note>
</para>

<sect2 id="executor-for-programmers">
<title>Executor for Programmers</title>

<para>
C++ developers can easily use the Instance class in their C++ programs so that the execution functionality is embedded in the their application obsoleting the need for running the external executor program.  For standard dialog the dialog creation overhead is minimal but the creation of the &kde; application may delay the dialog for around a second.
</para>
<para>Another approach is to use the <emphasis>kommander_part</emphasis> KReadOnlyPart. This KPart can load and execute any &kommander; dialog inside another KDE application.</para>
</sect2>

</sect1>

<sect1 id="create-dialog">
<title>Creating a Dialog</title>
<para>
To learn about how to create a dialog, add widgets, use layouts, modify widgets properties, please consult the &Qt; Designer (version 3.x) manual. You can access it by running <command>designer</command> from the command line or from your desktop menu.
</para>
<para>
The extra functionality that &kommander; offers is the <guilabel>Kommander Text</guilabel> associated with each widget. These texts are the executable (script) part of the dialog, written either in a script language (with the old &kommander; syntax) or using the internal &kommander; language, the so called new parser.
</para>
<para>To learn more about the language syntax, commands and how to use the text editor, consult the upcoming chapters and check the examples shipped with the &kommander; source.</para>
</sect1>

<sect1 id="exec-bit">
<title>Executable bit - new in 1.3</title>
<para>
For security reasons we introduced the executable bit requirement in version 1.3. Some will applaud this as long overdue. Others will consider it a terrible annoyance or even too scarey to use. Unfortunately there is no perfect solution. The problem is that you can download a Kommander dialog from anywhere or get one in your email and click on it and run it by accident. Because Kommander can run shell scripts it is sort of in an odd place. While other applications don't nag you this way you actually had to install them so clearly you felt safe and intended to run them. A single line of shell scripting could permanently wipe out your home directory. Our intent is to eliminate an accidental click on an untrusted dialog. We aplogize for any inconvenience, but there is no way to do this to even the developer's satisfaction that it will not annoy you while keeping you safe. 
</para>
<para>
You are not prevented from running a dialog, just nagged. You can make it go away by using a file manager or the shell to set the executable bit. Right click on the dialog in Konqueror, select properties from the menu, choose the permissions tab and check the <quote>is executable</quote> checkbox. Now the nag will be gone from this dialog forever. Check our web site for a tool that searchesfor &kommander; dialogs and allows you to review them and choose whether any or all of them should have the bit set. To use the shell and make all the &kommander; dialogs in a directory executable use this command. 
</para>
<screen>
chmod u+x *.kmdr
</screen>
<warning><para>Do not set dialogs as executable if you are not confident of their origin.</para></warning>
</sect1>

</chapter>