<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kmyapplication "<application>QuadKonsole4</application>">
  <!ENTITY kappname "&kmyapplication;">
  <!ENTITY package "kde-module"><!-- kdebase, kdeadmin, etc.  Leave
                                     this unchanged if your
                                     application is not maintained in KDE CVS -->
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">

  <!-- Do not define any other entities; instead, use the entities
       from entities/general.entities and $LANG/user.entities. -->
]>
<book lang="&language;">

<bookinfo>
<title>The &kmyapplication; Handbook</title>

<authorgroup>
<author>
<!-- This is just put in as an example.  For real documentation, please
     define a general entity in entities/contributor.entities, e.g.
<!ENTITY George.N.Ugnacious "<personname><firstname>George</firstname><othername>N.</othername><surname>Ugnacious</surname></personname>">
<!ENTITY George.N.Ugnacious.mail "<email>gnu@kde.org</email>">
and use `&George.N.Ugnacious; &George.N.Ugnacious.mail;' in the author element.
 -->
<personname>
<firstname>Karsten</firstname>
<othername></othername>
<surname>Borgwaldt</surname>
</personname>
<email>kb@kb.ccchl.de</email>
</author>
</authorgroup>

<copyright>
<year>2011</year>
<holder>Karsten Borgwaldt</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>

<date>2011-04-19</date>
<releaseinfo>0.02.00</releaseinfo>

<abstract>
<para>
&kmyapplication; tries to provide a keyboard focused interface to multiple KParts in one window. The default setting opens four Konsole KParts and defines some shortcuts for navigation. Because there is only one window decoration, it "wastes" a bit less screen space and all KParts are aligned automatically. You can open and close KParts at runtime using keyboard shortcuts or detach any KPart from the main window. Detaching a KPart will open a new &kmyapplication; that can be used exactly like the original.

To use other KParts within &kmyapplication; you can either open a new URL using the URL bar (default: Ctrl+Shift+G) or have &kmyapplication; find another KPart for the current URL use KDE's global settings. Example: Create some tarball or other file using your favoutie commands, switch to dolphin and attach the new file to an email using drag'n'drop.
</para>
</abstract>

<!-- This is a set of Keywords for indexing by search engines.
Please at least include KDE, the KDE package it is in, the name
 of your application, and a few relevant keywords. -->

<keywordset>
<keyword>KDE</keyword>
<keyword>kdeutils</keyword>
<keyword>Kapp</keyword>
<keyword>Konsole</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>
&kmyapplication; embeds multiple Konsole KParts in one window. Please report
any problems or feature requests to quadkonsole4@kb.ccchl.de.
</para>
</chapter>

<chapter id="using-kapp">
<title>Using &kmyapplication;</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. -->
<para>
&kmyapplication; is written to provide all Features of Konsole while still displaying multiple instances of it. All configuration and shortcuts of Konsole should work. There are several command line options to change the startup behaviour for a single instance of &kmyapplication;. To permanently change the settings for any startup, see configuration options.
</para>

<!--para>

<screenshot>
<screeninfo>Here's a screenshot of &kmyapplication;</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="screenshot.png" format="PNG"/>
	  </imageobject>
	  <imageobject>
	    <imagedata fileref="screenshot.eps" format="EPS"/>
	  </imageobject>
	  <textobject>
	    <phrase>Screenshot</phrase>
	  </textobject>
	</mediaobject>
</screenshot>
</para-->

</chapter>
<chapter id="commands">
<title>Command Reference</title>

<sect1 id="kapp-mainwindow">
<title>The main &kmyapplication; window</title>

<sect2>
<title>The File Menu</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Reset layouts</guimenuitem>
</menuchoice></term>
<listitem><para><action>Distributes the available space among all KParts equally</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Quit</guimenuitem>
</menuchoice></term>
<listitem><para><action>Quits</action> &kmyapplication;</para></listitem>
</varlistentry>
</variablelist>
</para>

</sect2>

<sect2>
<title>The <guimenu>Edit</guimenu> Menu</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>V</keycap></keycombo>
</shortcut>
<guimenu>Edit</guimenu>
<guimenuitem>Paste</guimenuitem>
</menuchoice></term>
<listitem><para><action>Paste the current copy buffer. The paste actions still have problems. You should use Konsole's own paste selection/copy actions instead.</action></para></listitem>
</varlistentry>

</variablelist></para>
</sect2>

<sect2>
<title>The <guimenu>Move</guimenu> Menu</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; &Shift;<keycap>Left</keycap></keycombo>
</shortcut>
<guimenu>Move</guimenu>
<guimenuitem>Move left</guimenuitem>
</menuchoice></term>
<listitem><para><action>Move the focus to the left</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; &Shift;<keycap>Right</keycap></keycombo>
</shortcut>
<guimenu>Move</guimenu>
<guimenuitem>Move right</guimenuitem>
</menuchoice></term>
<listitem><para><action>Move the focus to the right</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; &Shift;<keycap>Up</keycap></keycombo>
</shortcut>
<guimenu>Move</guimenu>
<guimenuitem>Move up</guimenuitem>
</menuchoice></term>
<listitem><para><action>Move the focus up</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; &Shift;<keycap>Down</keycap></keycombo>
</shortcut>
<guimenu>Move</guimenu>
<guimenuitem>Move up</guimenuitem>
</menuchoice></term>
<listitem><para><action>Move the focus down</action></para></listitem>
</varlistentry>

</variablelist></para>
</sect2>

<sect2>
<title>The <guimenu>Settings</guimenu> Menu</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; &Shift;<keycap>M</keycap></keycombo>
</shortcut>
<guimenu>Settings</guimenu>
<guimenuitem>Show Menubar</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggle visibility of the menubar</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Show Toolbar</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggle visibility of the toolbar</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Show Statusbar</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggle visibility of the statusbar (currently unused)</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Shortcuts</guimenuitem>
</menuchoice></term>
<listitem><para><action>Configure the shortcuts. Remember that some actions are provided by the KPart.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Toolbars</guimenuitem>
</menuchoice></term>
<listitem><para><action>Configure the elements shown on the toolbars</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure quadkonsole4</guimenuitem>
</menuchoice></term>
<listitem><para><action>Configure the behaviour of &kmyapplication;</action></para></listitem>
</varlistentry>

</variablelist></para>
</sect2>

<sect2>
<title>The <guimenu>Help</guimenu> Menu</title>

&help.menu.documentation;

</sect2>

</sect1>
</chapter>

<!--chapter id="developers">
<title>Developer's Guide to &kmyapplication;</title>

<para>
Programming &kmyapplication; plugins is a joy to behold. Just read through the next
66 pages of API's to learn how!
</para>

<refentry id="re-1007-unmanagechildren-1">
<refmeta>
<refentrytitle>XtUnmanageChildren</refentrytitle>
<refmiscinfo>Xt - Geometry Management</refmiscinfo>
</refmeta>
<refnamediv>
<refname>XtUnmanageChildren
</refname>
<refpurpose>remove a list of children from a parent widget's managed
list.
<indexterm id="ix-1007-unmanagechildren-1"><primary>widgets</primary><secondary>removing</secondary></indexterm>
<indexterm id="ix-1007-unmanagechildren-2"><primary>XtUnmanageChildren</primary></indexterm>
</refpurpose>

</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>4 March 1996</date>
</refsynopsisdivinfo>
<synopsis>
void XtUnmanageChildren(<replaceable class="parameter">children</replaceable>, <replaceable class="parameter">num_children</replaceable>)
    WidgetList <replaceable class="parameter">children</replaceable>;
    Cardinal <replaceable class="parameter">num_children</replaceable>;
</synopsis>

<refsect2 id="r2-1007-unmanagechildren-1">
<title>Inputs</title>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">children</replaceable>
</term>
<listitem>
<para>Specifies an array of child widgets. Each child must be of
class RectObj or any subclass thereof.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">num_children</replaceable>
</term>
<listitem>
<para>Specifies the number of elements in <replaceable class="parameter">children</replaceable>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2></refsynopsisdiv>

<refsect1 id="r1-1007-unmanagechildren-1">
<title>Description
</title>
<para><function>XtUnmanageChildren()</function> unmaps the specified widgets
and removes them from their parent's geometry management.
The widgets will disappear from the screen, and (depending
on its parent) may no longer have screen space allocated for
them.
</para>
<para>Each of the widgets in the <replaceable class="parameter">children</replaceable> array must have
the same parent.
</para>
<para>See the &ldquo;Algorithm&rdquo; section below for full details of the
widget unmanagement procedure.
</para>
</refsect1>

<refsect1 id="r1-1007-unmanagechildren-2">
<title>Usage</title>
<para>Unmanaging widgets is the usual method for temporarily
making them invisible.  They can be re-managed with
<function>XtManageChildren()</function>.
</para>
<para>You can unmap a widget, but leave it under geometry
management by calling <function>XtUnmapWidget()</function>.  You can
destroy a widget's window without destroying the widget by
calling <function>XtUnrealizeWidget()</function>.  You can destroy a
widget completely with <function>XtDestroyWidget()</function>.
</para>
<para>If you are only going to unmanage a single widget, it is
more convenient to call <function>XtUnmanageChild()</function>.  It is
often more convenient to call <function>XtUnmanageChild()</function>
several times than it is to declare and initialize an array
of widgets to pass to <function>XtUnmanageChildren()</function>.  Calling
<function>XtUnmanageChildren()</function> is more efficient, however,
because it only calls the parent's <function>change_managed()</function>
method once.
</para>
</refsect1>

<refsect1 id="r1-1007-unmanagechildren-3">
<title>Algorithm
</title>
<para><function>XtUnmanageChildren()</function> performs the following:
</para>
<variablelist>
<varlistentry>
<term>-
</term>
<listitem>
<para>Ignores the child if it already is unmanaged or is being
destroyed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-
</term>
<listitem>
<para>Otherwise, if the child is realized, it makes it nonvisible
by unmapping it.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
</para>
</refsect1>

<refsect1 id="r1-1007-unmanagechildren-4">
<title>Structures</title>
<para>The <type>WidgetList</type> type is simply an array of widgets:
</para>
<screen id="sc-1007-unmanagechildren-1">typedef Widget *WidgetList;
</screen>
</refsect1>
</refentry>

</chapter-->

<chapter id="faq">
<title>Questions and Answers</title>

&reporting.bugs;
&updating.documentation;

<qandaset id="faqlist">

<qandaentry>
<question>
<para>Can I use a differen terminal emulator/KPart withing &kmyapplication;?</para>
</question>
<answer>
<para>&kmyapplication; was designed only with Konsole's KPart in mind. But it is possible to embed any KPart in it by changing either the name of the loaded KPart (in konsole.cpp) or by editing your "konsolepart.desktop". The embedded KPart should provide a "TerminalInterfaceV2".
</para>
</answer>
</qandaentry>

</qandaset>
</chapter>

<chapter id="credits">

<title>Credits and License</title>

<para>
&kmyapplication;
</para>
<para>
	Program Copyright
	&copy; 2005 Simon Perrault <email>nomis80@nomis80.org</email>
	&copy; 2009 - 2011 Karsten Borgwaldt <email>kb@kb.ccchl.de</email>
</para>

<!--
<para>
Contributors:
<itemizedlist>
<listitem><para>Konqui the KDE Dragon <email>konqui@kde.org</email></para>
</listitem>
<listitem><para>Tux the Linux Penguin <email>tux@linux.org</email></para>
</listitem>
</itemizedlist>
</para>
-->

<para>
Documentation Copyright &copy; 2011 Karsten Borgwaldt <email>kb@kb.ccchl.de</email>
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;
&underGPL;

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-kapp">
<title>How to obtain &kmyapplication;</title>
<para>&kmyapplication; can be found at <ulink url="http://kb.ccchl.de/quadkonsole4">http://kb.ccchl.de/quadkonsole4</ulink>.</para>

</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<!--
List any special requirements for your application here. This should include:
.Libraries or other software that is not included in kdesupport,
kdelibs, or kdebase.
.Hardware requirements like amount of RAM, disk space, graphics card
capabilities, screen resolution, special expansion cards, etc.
.Operating systems the app will run on. If your app is designed only for a
specific OS, (you wrote a graphical LILO configurator for example) put this
information here.
-->

<para>
In order to successfully use &kmyapplication;, you need &kde; 4.x. and Konsole.
</para>

<para>
All required libraries can be found
in <ulink url="ftp://ftp.kapp.org">The &kde; repositories</ulink>.
</para>

<para>
You can find a list of changes at <ulink
url="http://kb.ccchl.de/quadkonsole4/ChangeLog">http://kb.ccchl.de/quadkonsole4/ChangeLog</ulink>.
</para>
</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>

<!-- This entity contains the boilerplate text for standard -->
<!-- compilation instructions.  If your application requires any -->
<!-- special handling, remove it, and replace with your own text. -->

&install.compile.documentation;

</sect1>

<!--sect1 id="configuration">
<title>Configuration</title>

<para>Don't forget to tell your system to start the <filename>dtd</filename>
dicer-toaster daemon first, or &kmyapplication; won't work !</para>

</sect1-->

</appendix>

&documentation.index;
</book>
