path: root/doc/kommander/dcop.docbook

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

<sect1 id="dcop-interface">
<sect1info>
<title>&DCOP; Functions</title>
</sect1info>

<title>&DCOP; Functions</title>

<para>
&kommander; began accessing it's widgets internally with &DCOP;, which evolved to widget functions. &DCOP; is still available and can be used to share information between dialogs. It can also be used to extend and integrate nearly every existing KDE application.
&DCOP; can be called in several ways in &kommander;.  First is the console method. Open a &kommander; dialog and open a console and try this.
</para>
<note><para>This is largely focused on the old parser. If you are looking for internal widget functions please see the <link linkend="new_parserdocs">new parser</link>. This information is particularly relevent to communicating between dialogs and applications, or running other scripting languages inside Kommander as scripts.</para></note>
<screen>
dcop | grep kmdr
dcop `dcop | grep kmdr`
dcop `dcop | grep kmdr` KommanderIf
</screen>
<para>
This will show you what dialogs are running and what interfaces are available, as well as what is available to call in the &kommander; special interface to internals. In the explanation of &DCOP; here remember that &DCOP; is used internally by KDE applications (replaced with DBUS in KDE4) and it is very useful. Have a look at <command>kdcop</command> by pressing Alt-F2 and typing it in a run dialog. Here you can explore everything running. Now back to &DCOP; in &kommander;.
</para>
<screen>
dcop kmdr-executor-@pid KommanderIf setText myWidget <quote>new text</quote>
</screen>
<para>
This assumes you are inside a &kommander; file and have access to the special @pid which contains the process ID.  In fact it is simpler to replace <quote>kmdr-executor-@pid</quote> with @dcopid.  However, you can use this syntax (obviously without the specials) from the command line or any external script to alter the &kommander; window.
</para>
<para>
&kommander; evolved the much faster internal &DCOP; function. Using it from another application window (console &DCOP; is very slow) is more complicated because you must give lots of information, including a prototype of the call.  The above call would become: (Note that @dcopid is actually internal to the dialog, but you could replace it with a valid process ID)
</para>
<screen>
@dcop(@dcopid, KommanderIf, <quote>enableWidget(QString, bool)</quote>, Widget, true)
</screen>
<para>
In the early &kommander; nesting &DCOP; calls inside script language structures (like <application>bash</application>) used console method calls.  <emphasis>If you use internal &DCOP; all &kommander; specials will be executed first and then the script will be executed.</emphasis> Please read that again as it will cause you no end of grief with a <application>bash</application> loop using &kommander; specials.
</para>
<para>
There is a new simplified way to use &DCOP; inside &kommander; using an object syntax. Let's say you want to change the text in a widget name @LineEdit1. It would look like this.
</para>
<screen>
@LineEdit1.setText(New text)
</screen>
<para>
As you can see the new syntax is very easy, as well as consistent visually with function groups. All the &DCOP; reference here will use the new object syntax listed above. <emphasis>Please note that if you are referencing a widget using &DCOP; from another window or another application the first parameter will always be the widget name. All functions are listed here starting with the second parameter.</emphasis>
</para>

<sect2 id="dcop-globals">
<title>&DCOP; for Global Variables</title>
<variablelist>
<varlistentry>
<term>global(QString variableName)</term>
<listitem>
<para>
Returns the value of the specified global variable.  When a script is run from within a &kommander; window any (non-global) variables set in that script will cease to exist after the script completes and therfore will not be available to other script processes or in a new instance of the calling process.  The global <quote>scope</quote> means the variable will exist for any process of the window until that window is closed.  You may change these variables at any time with a new call to <function>@setGlobal</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>setGlobal(QString variableName, QString value)</term>
<listitem>
<para>
Creates a variable that is global to the window process and assigns the value to it.  This value can be retrieved with global(QString variableName) or set again.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="dcop-all">
<title>&DCOP; for all Widgets</title>

<para>
The following list is old and left here for reference purposes only. For a complete and current reference to all widget functions please look at the <emphasis>Function Browser</emphasis> which is available from any &kommander; text editor window by pressing the lower left button. These are now widget functions, not &DCOP; functions but the &DCOP; functions are published in the <emphasis>KommanderIf</emphasis> &DCOP; interface as described above. Dialogs for listing and constructing calls for this functionality are available at our web site.
</para>
<variablelist>
<varlistentry>
<term>setText(QString text)</term>
<listitem>
<para>
This removes the text displayed in the widget and replaces it with the text supplied.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>enableWidget(bool enable)</term>
<listitem>
<para>
Enables or disables a widget.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>associatedText</term>
<listitem>
<para>
Returns the text associated with the specified widget.  This is not the same as the displayed text.  It would be <quote>@widgetText</quote> or the text and/or scripting used to arrive at the displayed value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>setAssociatedText(QString text)</term>
<listitem>
<para>
This sets the &kommander; Text default string.  This is typically set to <quote>@widgetText</quote> to display what is entered into the widget.  It is unlikely you will have much need for this, but if you do it is there.  Applies to all widgets that can contain data.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="dcop-box">
<title>&DCOP; for ListBox and ComboBox Widgets</title>
<variablelist>
<varlistentry>
<term>addListItem(QString item, int index)</term>
<listitem>
<para>
Adds an item to a ListBox widget at the specified index.  List index starts at zero.  To add to the end of the list use -1.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>addListItems(QStringList items, int index)</term>
<listitem>
<para>
This adds a list of strings all at once.  The list should be delimited by <acronym>EOL</acronym> (\n - newlines).  This is handy as you can use bash to derive the list rather easily.  For instance, using @exec(ls -l ~/projects | grep kmdr) for items will give you a directory listing of &kommander; files in your projects folder.  List index starts at zero.  Use -1 to add to the end of the list.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>addUniqueItem(QString item)</term>
<listitem>
<para>
addUniqueItem will add an item to the end of the list only if it is unique.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>clearList</term>
<listitem>
<para>
Removes all items.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>removeListItem(int index)</term>
<listitem>
<para>
Removes the item at the specified index.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>item(int index)</term>
<listitem>
<para>
Returns the text of the item at the specified index.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>setCurrentListItem(int index)</term>
<listitem>
<para>
Set the current (or selected) item to the index specified.  Applies to ListBox and ComboBox widgets.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="dcop-button">
<title>&DCOP; for CheckBox and RadioButton Widgets</title>
<variablelist>
<varlistentry>
<term>setChecked(QString widgetName, bool checked)</term>
<listitem>
<para>
Checks/unchecks CheckBox or RadioButton widgets.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="dcop-tab">
<title>&DCOP; for TabWidget Widgets</title>
<variablelist>
<varlistentry>
<term>setCurrentTab(QString widgetName, int index)</term>
<listitem>
<para>
Selected the tab by index for TabWidgets.  Index starts at 0.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>


</sect1>