Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdewebdev@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19dav3.5.13-sru
toma
16 years ago
commit
e9ae806948
@ -0,0 +1,38 @@
|
||||
Quanta Plus (quanta):
|
||||
Current maintainers:
|
||||
Eric Laffoon <sequitur@kde.org>
|
||||
Andras Mantia <amantia@kde.org>
|
||||
Original authors:
|
||||
Dmitry Poplavsky <dima@kde.org>
|
||||
Alexander Yakovlev <yshurik@kde.org>
|
||||
|
||||
CSS/Frame editor: Luciano Gulmini <e.gulmini@tiscali.it>
|
||||
PHP Debugger: Linus McCabe <Linus@mccabe.nu>
|
||||
VPL part:
|
||||
Nicolas Deschildre <ndeschildre@kdewebdev.org>
|
||||
Paulo Moura Guedes <moura@kdewebdev.org>
|
||||
|
||||
Home page: http://kdewebdev.org
|
||||
Bug form: http://bugs.kde.org
|
||||
|
||||
Kommander (kommander):
|
||||
Authors:
|
||||
Mark Britton <consume@optusnet.com.au>
|
||||
Eric Laffoon <sequitur@easystreet.com>
|
||||
Michal Rudolf <mrudolf@kdewebdev.org>
|
||||
|
||||
KXSLDbg (kxsldbg):
|
||||
Author: Keith Isdale <k_isdale@tpg.com.au>
|
||||
|
||||
KFileReplace:
|
||||
Maintainer:
|
||||
Emiliano Gulmini <emi_barbarossa@yahoo.it>
|
||||
Andras Mantia <amantia@kde.org>
|
||||
Original author:
|
||||
François Dupoux <fdupoux@dupoux.com>
|
||||
|
||||
KImageMapEditor:
|
||||
Author: Jan Schäfer <JanSchaefer@gmx.de>
|
||||
|
||||
KLinkStatus:
|
||||
Author: Paulo Moura Guedes <pmg@netcabo.pt>
|
||||
@ -0,0 +1,397 @@
|
||||
GNU Free Documentation License
|
||||
Version 1.2, November 2002
|
||||
|
||||
|
||||
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
|
||||
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
|
||||
Everyone is permitted to copy and distribute verbatim copies
|
||||
of this license document, but changing it is not allowed.
|
||||
|
||||
|
||||
0. PREAMBLE
|
||||
|
||||
The purpose of this License is to make a manual, textbook, or other
|
||||
functional and useful document "free" in the sense of freedom: to
|
||||
assure everyone the effective freedom to copy and redistribute it,
|
||||
with or without modifying it, either commercially or noncommercially.
|
||||
Secondarily, this License preserves for the author and publisher a way
|
||||
to get credit for their work, while not being considered responsible
|
||||
for modifications made by others.
|
||||
|
||||
This License is a kind of "copyleft", which means that derivative
|
||||
works of the document must themselves be free in the same sense. It
|
||||
complements the GNU General Public License, which is a copyleft
|
||||
license designed for free software.
|
||||
|
||||
We have designed this License in order to use it for manuals for free
|
||||
software, because free software needs free documentation: a free
|
||||
program should come with manuals providing the same freedoms that the
|
||||
software does. But this License is not limited to software manuals;
|
||||
it can be used for any textual work, regardless of subject matter or
|
||||
whether it is published as a printed book. We recommend this License
|
||||
principally for works whose purpose is instruction or reference.
|
||||
|
||||
|
||||
1. APPLICABILITY AND DEFINITIONS
|
||||
|
||||
This License applies to any manual or other work, in any medium, that
|
||||
contains a notice placed by the copyright holder saying it can be
|
||||
distributed under the terms of this License. Such a notice grants a
|
||||
world-wide, royalty-free license, unlimited in duration, to use that
|
||||
work under the conditions stated herein. The "Document", below,
|
||||
refers to any such manual or work. Any member of the public is a
|
||||
licensee, and is addressed as "you". You accept the license if you
|
||||
copy, modify or distribute the work in a way requiring permission
|
||||
under copyright law.
|
||||
|
||||
A "Modified Version" of the Document means any work containing the
|
||||
Document or a portion of it, either copied verbatim, or with
|
||||
modifications and/or translated into another language.
|
||||
|
||||
A "Secondary Section" is a named appendix or a front-matter section of
|
||||
the Document that deals exclusively with the relationship of the
|
||||
publishers or authors of the Document to the Document's overall subject
|
||||
(or to related matters) and contains nothing that could fall directly
|
||||
within that overall subject. (Thus, if the Document is in part a
|
||||
textbook of mathematics, a Secondary Section may not explain any
|
||||
mathematics.) The relationship could be a matter of historical
|
||||
connection with the subject or with related matters, or of legal,
|
||||
commercial, philosophical, ethical or political position regarding
|
||||
them.
|
||||
|
||||
The "Invariant Sections" are certain Secondary Sections whose titles
|
||||
are designated, as being those of Invariant Sections, in the notice
|
||||
that says that the Document is released under this License. If a
|
||||
section does not fit the above definition of Secondary then it is not
|
||||
allowed to be designated as Invariant. The Document may contain zero
|
||||
Invariant Sections. If the Document does not identify any Invariant
|
||||
Sections then there are none.
|
||||
|
||||
The "Cover Texts" are certain short passages of text that are listed,
|
||||
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
|
||||
the Document is released under this License. A Front-Cover Text may
|
||||
be at most 5 words, and a Back-Cover Text may be at most 25 words.
|
||||
|
||||
A "Transparent" copy of the Document means a machine-readable copy,
|
||||
represented in a format whose specification is available to the
|
||||
general public, that is suitable for revising the document
|
||||
straightforwardly with generic text editors or (for images composed of
|
||||
pixels) generic paint programs or (for drawings) some widely available
|
||||
drawing editor, and that is suitable for input to text formatters or
|
||||
for automatic translation to a variety of formats suitable for input
|
||||
to text formatters. A copy made in an otherwise Transparent file
|
||||
format whose markup, or absence of markup, has been arranged to thwart
|
||||
or discourage subsequent modification by readers is not Transparent.
|
||||
An image format is not Transparent if used for any substantial amount
|
||||
of text. A copy that is not "Transparent" is called "Opaque".
|
||||
|
||||
Examples of suitable formats for Transparent copies include plain
|
||||
ASCII without markup, Texinfo input format, LaTeX input format, SGML
|
||||
or XML using a publicly available DTD, and standard-conforming simple
|
||||
HTML, PostScript or PDF designed for human modification. Examples of
|
||||
transparent image formats include PNG, XCF and JPG. Opaque formats
|
||||
include proprietary formats that can be read and edited only by
|
||||
proprietary word processors, SGML or XML for which the DTD and/or
|
||||
processing tools are not generally available, and the
|
||||
machine-generated HTML, PostScript or PDF produced by some word
|
||||
processors for output purposes only.
|
||||
|
||||
The "Title Page" means, for a printed book, the title page itself,
|
||||
plus such following pages as are needed to hold, legibly, the material
|
||||
this License requires to appear in the title page. For works in
|
||||
formats which do not have any title page as such, "Title Page" means
|
||||
the text near the most prominent appearance of the work's title,
|
||||
preceding the beginning of the body of the text.
|
||||
|
||||
A section "Entitled XYZ" means a named subunit of the Document whose
|
||||
title either is precisely XYZ or contains XYZ in parentheses following
|
||||
text that translates XYZ in another language. (Here XYZ stands for a
|
||||
specific section name mentioned below, such as "Acknowledgements",
|
||||
"Dedications", "Endorsements", or "History".) To "Preserve the Title"
|
||||
of such a section when you modify the Document means that it remains a
|
||||
section "Entitled XYZ" according to this definition.
|
||||
|
||||
The Document may include Warranty Disclaimers next to the notice which
|
||||
states that this License applies to the Document. These Warranty
|
||||
Disclaimers are considered to be included by reference in this
|
||||
License, but only as regards disclaiming warranties: any other
|
||||
implication that these Warranty Disclaimers may have is void and has
|
||||
no effect on the meaning of this License.
|
||||
|
||||
|
||||
2. VERBATIM COPYING
|
||||
|
||||
You may copy and distribute the Document in any medium, either
|
||||
commercially or noncommercially, provided that this License, the
|
||||
copyright notices, and the license notice saying this License applies
|
||||
to the Document are reproduced in all copies, and that you add no other
|
||||
conditions whatsoever to those of this License. You may not use
|
||||
technical measures to obstruct or control the reading or further
|
||||
copying of the copies you make or distribute. However, you may accept
|
||||
compensation in exchange for copies. If you distribute a large enough
|
||||
number of copies you must also follow the conditions in section 3.
|
||||
|
||||
You may also lend copies, under the same conditions stated above, and
|
||||
you may publicly display copies.
|
||||
|
||||
|
||||
3. COPYING IN QUANTITY
|
||||
|
||||
If you publish printed copies (or copies in media that commonly have
|
||||
printed covers) of the Document, numbering more than 100, and the
|
||||
Document's license notice requires Cover Texts, you must enclose the
|
||||
copies in covers that carry, clearly and legibly, all these Cover
|
||||
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
|
||||
the back cover. Both covers must also clearly and legibly identify
|
||||
you as the publisher of these copies. The front cover must present
|
||||
the full title with all words of the title equally prominent and
|
||||
visible. You may add other material on the covers in addition.
|
||||
Copying with changes limited to the covers, as long as they preserve
|
||||
the title of the Document and satisfy these conditions, can be treated
|
||||
as verbatim copying in other respects.
|
||||
|
||||
If the required texts for either cover are too voluminous to fit
|
||||
legibly, you should put the first ones listed (as many as fit
|
||||
reasonably) on the actual cover, and continue the rest onto adjacent
|
||||
pages.
|
||||
|
||||
If you publish or distribute Opaque copies of the Document numbering
|
||||
more than 100, you must either include a machine-readable Transparent
|
||||
copy along with each Opaque copy, or state in or with each Opaque copy
|
||||
a computer-network location from which the general network-using
|
||||
public has access to download using public-standard network protocols
|
||||
a complete Transparent copy of the Document, free of added material.
|
||||
If you use the latter option, you must take reasonably prudent steps,
|
||||
when you begin distribution of Opaque copies in quantity, to ensure
|
||||
that this Transparent copy will remain thus accessible at the stated
|
||||
location until at least one year after the last time you distribute an
|
||||
Opaque copy (directly or through your agents or retailers) of that
|
||||
edition to the public.
|
||||
|
||||
It is requested, but not required, that you contact the authors of the
|
||||
Document well before redistributing any large number of copies, to give
|
||||
them a chance to provide you with an updated version of the Document.
|
||||
|
||||
|
||||
4. MODIFICATIONS
|
||||
|
||||
You may copy and distribute a Modified Version of the Document under
|
||||
the conditions of sections 2 and 3 above, provided that you release
|
||||
the Modified Version under precisely this License, with the Modified
|
||||
Version filling the role of the Document, thus licensing distribution
|
||||
and modification of the Modified Version to whoever possesses a copy
|
||||
of it. In addition, you must do these things in the Modified Version:
|
||||
|
||||
A. Use in the Title Page (and on the covers, if any) a title distinct
|
||||
from that of the Document, and from those of previous versions
|
||||
(which should, if there were any, be listed in the History section
|
||||
of the Document). You may use the same title as a previous version
|
||||
if the original publisher of that version gives permission.
|
||||
B. List on the Title Page, as authors, one or more persons or entities
|
||||
responsible for authorship of the modifications in the Modified
|
||||
Version, together with at least five of the principal authors of the
|
||||
Document (all of its principal authors, if it has fewer than five),
|
||||
unless they release you from this requirement.
|
||||
C. State on the Title page the name of the publisher of the
|
||||
Modified Version, as the publisher.
|
||||
D. Preserve all the copyright notices of the Document.
|
||||
E. Add an appropriate copyright notice for your modifications
|
||||
adjacent to the other copyright notices.
|
||||
F. Include, immediately after the copyright notices, a license notice
|
||||
giving the public permission to use the Modified Version under the
|
||||
terms of this License, in the form shown in the Addendum below.
|
||||
G. Preserve in that license notice the full lists of Invariant Sections
|
||||
and required Cover Texts given in the Document's license notice.
|
||||
H. Include an unaltered copy of this License.
|
||||
I. Preserve the section Entitled "History", Preserve its Title, and add
|
||||
to it an item stating at least the title, year, new authors, and
|
||||
publisher of the Modified Version as given on the Title Page. If
|
||||
there is no section Entitled "History" in the Document, create one
|
||||
stating the title, year, authors, and publisher of the Document as
|
||||
given on its Title Page, then add an item describing the Modified
|
||||
Version as stated in the previous sentence.
|
||||
J. Preserve the network location, if any, given in the Document for
|
||||
public access to a Transparent copy of the Document, and likewise
|
||||
the network locations given in the Document for previous versions
|
||||
it was based on. These may be placed in the "History" section.
|
||||
You may omit a network location for a work that was published at
|
||||
least four years before the Document itself, or if the original
|
||||
publisher of the version it refers to gives permission.
|
||||
K. For any section Entitled "Acknowledgements" or "Dedications",
|
||||
Preserve the Title of the section, and preserve in the section all
|
||||
the substance and tone of each of the contributor acknowledgements
|
||||
and/or dedications given therein.
|
||||
L. Preserve all the Invariant Sections of the Document,
|
||||
unaltered in their text and in their titles. Section numbers
|
||||
or the equivalent are not considered part of the section titles.
|
||||
M. Delete any section Entitled "Endorsements". Such a section
|
||||
may not be included in the Modified Version.
|
||||
N. Do not retitle any existing section to be Entitled "Endorsements"
|
||||
or to conflict in title with any Invariant Section.
|
||||
O. Preserve any Warranty Disclaimers.
|
||||
|
||||
If the Modified Version includes new front-matter sections or
|
||||
appendices that qualify as Secondary Sections and contain no material
|
||||
copied from the Document, you may at your option designate some or all
|
||||
of these sections as invariant. To do this, add their titles to the
|
||||
list of Invariant Sections in the Modified Version's license notice.
|
||||
These titles must be distinct from any other section titles.
|
||||
|
||||
You may add a section Entitled "Endorsements", provided it contains
|
||||
nothing but endorsements of your Modified Version by various
|
||||
parties--for example, statements of peer review or that the text has
|
||||
been approved by an organization as the authoritative definition of a
|
||||
standard.
|
||||
|
||||
You may add a passage of up to five words as a Front-Cover Text, and a
|
||||
passage of up to 25 words as a Back-Cover Text, to the end of the list
|
||||
of Cover Texts in the Modified Version. Only one passage of
|
||||
Front-Cover Text and one of Back-Cover Text may be added by (or
|
||||
through arrangements made by) any one entity. If the Document already
|
||||
includes a cover text for the same cover, previously added by you or
|
||||
by arrangement made by the same entity you are acting on behalf of,
|
||||
you may not add another; but you may replace the old one, on explicit
|
||||
permission from the previous publisher that added the old one.
|
||||
|
||||
The author(s) and publisher(s) of the Document do not by this License
|
||||
give permission to use their names for publicity for or to assert or
|
||||
imply endorsement of any Modified Version.
|
||||
|
||||
|
||||
5. COMBINING DOCUMENTS
|
||||
|
||||
You may combine the Document with other documents released under this
|
||||
License, under the terms defined in section 4 above for modified
|
||||
versions, provided that you include in the combination all of the
|
||||
Invariant Sections of all of the original documents, unmodified, and
|
||||
list them all as Invariant Sections of your combined work in its
|
||||
license notice, and that you preserve all their Warranty Disclaimers.
|
||||
|
||||
The combined work need only contain one copy of this License, and
|
||||
multiple identical Invariant Sections may be replaced with a single
|
||||
copy. If there are multiple Invariant Sections with the same name but
|
||||
different contents, make the title of each such section unique by
|
||||
adding at the end of it, in parentheses, the name of the original
|
||||
author or publisher of that section if known, or else a unique number.
|
||||
Make the same adjustment to the section titles in the list of
|
||||
Invariant Sections in the license notice of the combined work.
|
||||
|
||||
In the combination, you must combine any sections Entitled "History"
|
||||
in the various original documents, forming one section Entitled
|
||||
"History"; likewise combine any sections Entitled "Acknowledgements",
|
||||
and any sections Entitled "Dedications". You must delete all sections
|
||||
Entitled "Endorsements".
|
||||
|
||||
|
||||
6. COLLECTIONS OF DOCUMENTS
|
||||
|
||||
You may make a collection consisting of the Document and other documents
|
||||
released under this License, and replace the individual copies of this
|
||||
License in the various documents with a single copy that is included in
|
||||
the collection, provided that you follow the rules of this License for
|
||||
verbatim copying of each of the documents in all other respects.
|
||||
|
||||
You may extract a single document from such a collection, and distribute
|
||||
it individually under this License, provided you insert a copy of this
|
||||
License into the extracted document, and follow this License in all
|
||||
other respects regarding verbatim copying of that document.
|
||||
|
||||
|
||||
7. AGGREGATION WITH INDEPENDENT WORKS
|
||||
|
||||
A compilation of the Document or its derivatives with other separate
|
||||
and independent documents or works, in or on a volume of a storage or
|
||||
distribution medium, is called an "aggregate" if the copyright
|
||||
resulting from the compilation is not used to limit the legal rights
|
||||
of the compilation's users beyond what the individual works permit.
|
||||
When the Document is included in an aggregate, this License does not
|
||||
apply to the other works in the aggregate which are not themselves
|
||||
derivative works of the Document.
|
||||
|
||||
If the Cover Text requirement of section 3 is applicable to these
|
||||
copies of the Document, then if the Document is less than one half of
|
||||
the entire aggregate, the Document's Cover Texts may be placed on
|
||||
covers that bracket the Document within the aggregate, or the
|
||||
electronic equivalent of covers if the Document is in electronic form.
|
||||
Otherwise they must appear on printed covers that bracket the whole
|
||||
aggregate.
|
||||
|
||||
|
||||
8. TRANSLATION
|
||||
|
||||
Translation is considered a kind of modification, so you may
|
||||
distribute translations of the Document under the terms of section 4.
|
||||
Replacing Invariant Sections with translations requires special
|
||||
permission from their copyright holders, but you may include
|
||||
translations of some or all Invariant Sections in addition to the
|
||||
original versions of these Invariant Sections. You may include a
|
||||
translation of this License, and all the license notices in the
|
||||
Document, and any Warranty Disclaimers, provided that you also include
|
||||
the original English version of this License and the original versions
|
||||
of those notices and disclaimers. In case of a disagreement between
|
||||
the translation and the original version of this License or a notice
|
||||
or disclaimer, the original version will prevail.
|
||||
|
||||
If a section in the Document is Entitled "Acknowledgements",
|
||||
"Dedications", or "History", the requirement (section 4) to Preserve
|
||||
its Title (section 1) will typically require changing the actual
|
||||
title.
|
||||
|
||||
|
||||
9. TERMINATION
|
||||
|
||||
You may not copy, modify, sublicense, or distribute the Document except
|
||||
as expressly provided for under this License. Any other attempt to
|
||||
copy, modify, sublicense or distribute the Document is void, and will
|
||||
automatically terminate your rights under this License. However,
|
||||
parties who have received copies, or rights, from you under this
|
||||
License will not have their licenses terminated so long as such
|
||||
parties remain in full compliance.
|
||||
|
||||
|
||||
10. FUTURE REVISIONS OF THIS LICENSE
|
||||
|
||||
The Free Software Foundation may publish new, revised versions
|
||||
of the GNU Free Documentation License from time to time. Such new
|
||||
versions will be similar in spirit to the present version, but may
|
||||
differ in detail to address new problems or concerns. See
|
||||
http://www.gnu.org/copyleft/.
|
||||
|
||||
Each version of the License is given a distinguishing version number.
|
||||
If the Document specifies that a particular numbered version of this
|
||||
License "or any later version" applies to it, you have the option of
|
||||
following the terms and conditions either of that specified version or
|
||||
of any later version that has been published (not as a draft) by the
|
||||
Free Software Foundation. If the Document does not specify a version
|
||||
number of this License, you may choose any version ever published (not
|
||||
as a draft) by the Free Software Foundation.
|
||||
|
||||
|
||||
ADDENDUM: How to use this License for your documents
|
||||
|
||||
To use this License in a document you have written, include a copy of
|
||||
the License in the document and put the following copyright and
|
||||
license notices just after the title page:
|
||||
|
||||
Copyright (c) YEAR YOUR NAME.
|
||||
Permission is granted to copy, distribute and/or modify this document
|
||||
under the terms of the GNU Free Documentation License, Version 1.2
|
||||
or any later version published by the Free Software Foundation;
|
||||
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
|
||||
A copy of the license is included in the section entitled "GNU
|
||||
Free Documentation License".
|
||||
|
||||
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
|
||||
replace the "with...Texts." line with this:
|
||||
|
||||
with the Invariant Sections being LIST THEIR TITLES, with the
|
||||
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
|
||||
|
||||
If you have Invariant Sections without Cover Texts, or some other
|
||||
combination of the three, merge those two alternatives to suit the
|
||||
situation.
|
||||
|
||||
If your document contains nontrivial examples of program code, we
|
||||
recommend releasing these examples in parallel under your choice of
|
||||
free software license, such as the GNU General Public License,
|
||||
to permit their use in free software.
|
||||
@ -0,0 +1,19 @@
|
||||
Global kdewebdev changelog. For detailed changes see each included
|
||||
application's own ChangeLog file.
|
||||
|
||||
2008-02-13: kdewebdev 3.5.9
|
||||
2006-10-10: kdewebdev 3.5.5
|
||||
2006-08-02: kdewebdev 3.5.4
|
||||
2006-05-31: kdewebdev 3.5.3
|
||||
2006-03-21: kdewebdev 3.5.2
|
||||
2006-01-31: kdewebdev 3.5.1
|
||||
2005-11-29: kdewebdev 3.5.0
|
||||
2005-02-22: kdewebdev 3.4.0
|
||||
2005-02-09: kdewebdev 3.4 Beta2
|
||||
2005-01-07: kdewebdev 3.4 Beta1
|
||||
2004-12-06: kdewebdev 3.4 Alpha1
|
||||
2004-08-18: kdewebdev 3.3.0
|
||||
2004-08-04: kdewebdev 3.3 RC1
|
||||
2004-07-07: kdewebdev 3.3 Beta1
|
||||
2004-06-01: kdewebdev 3.3 Alpha1
|
||||
2004-05-06: First kdewebdev release - kdewebdev 3.3 Bleeding Edge 2
|
||||
@ -0,0 +1,167 @@
|
||||
Basic Installation
|
||||
==================
|
||||
|
||||
These are generic installation instructions.
|
||||
|
||||
The `configure' shell script attempts to guess correct values for
|
||||
various system-dependent variables used during compilation. It uses
|
||||
those values to create a `Makefile' in each directory of the package.
|
||||
It may also create one or more `.h' files containing system-dependent
|
||||
definitions. Finally, it creates a shell script `config.status' that
|
||||
you can run in the future to recreate the current configuration, a file
|
||||
`config.cache' that saves the results of its tests to speed up
|
||||
reconfiguring, and a file `config.log' containing compiler output
|
||||
(useful mainly for debugging `configure').
|
||||
|
||||
If you need to do unusual things to compile the package, please try
|
||||
to figure out how `configure' could check whether to do them, and mail
|
||||
diffs or instructions to the address given in the `README' so they can
|
||||
be considered for the next release. If at some point `config.cache'
|
||||
contains results you don't want to keep, you may remove or edit it.
|
||||
|
||||
The file `configure.in' is used to create `configure' by a program
|
||||
called `autoconf'. You only need `configure.in' if you want to change
|
||||
it or regenerate `configure' using a newer version of `autoconf'.
|
||||
|
||||
The simplest way to compile this package is:
|
||||
|
||||
1. `cd' to the directory containing the package's source code and type
|
||||
`./configure' to configure the package for your system. If you're
|
||||
using `csh' on an old version of System V, you might need to type
|
||||
`sh ./configure' instead to prevent `csh' from trying to execute
|
||||
`configure' itself.
|
||||
|
||||
Running `configure' takes a while. While running, it prints some
|
||||
messages telling which features it is checking for.
|
||||
|
||||
2. Type `make' to compile the package.
|
||||
|
||||
3. Type `make install' to install the programs and any data files and
|
||||
documentation.
|
||||
|
||||
4. You can remove the program binaries and object files from the
|
||||
source code directory by typing `make clean'.
|
||||
|
||||
Compilers and Options
|
||||
=====================
|
||||
|
||||
Some systems require unusual options for compilation or linking that
|
||||
the `configure' script does not know about. You can give `configure'
|
||||
initial values for variables by setting them in the environment. Using
|
||||
a Bourne-compatible shell, you can do that on the command line like
|
||||
this:
|
||||
CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
|
||||
|
||||
Or on systems that have the `env' program, you can do it like this:
|
||||
env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
|
||||
|
||||
Compiling For Multiple Architectures
|
||||
====================================
|
||||
|
||||
You can compile the package for more than one kind of computer at the
|
||||
same time, by placing the object files for each architecture in their
|
||||
own directory. To do this, you must use a version of `make' that
|
||||
supports the `VPATH' variable, such as GNU `make'. `cd' to the
|
||||
directory where you want the object files and executables to go and run
|
||||
the `configure' script. `configure' automatically checks for the
|
||||
source code in the directory that `configure' is in and in `..'.
|
||||
|
||||
If you have to use a `make' that does not supports the `VPATH'
|
||||
variable, you have to compile the package for one architecture at a time
|
||||
in the source code directory. After you have installed the package for
|
||||
one architecture, use `make distclean' before reconfiguring for another
|
||||
architecture.
|
||||
|
||||
Installation Names
|
||||
==================
|
||||
|
||||
By default, `make install' will install the package's files in
|
||||
`/usr/local/bin', `/usr/local/man', etc. You can specify an
|
||||
installation prefix other than `/usr/local' by giving `configure' the
|
||||
option `--prefix=PATH'.
|
||||
|
||||
You can specify separate installation prefixes for
|
||||
architecture-specific files and architecture-independent files. If you
|
||||
give `configure' the option `--exec-prefix=PATH', the package will use
|
||||
PATH as the prefix for installing programs and libraries.
|
||||
Documentation and other data files will still use the regular prefix.
|
||||
|
||||
If the package supports it, you can cause programs to be installed
|
||||
with an extra prefix or suffix on their names by giving `configure' the
|
||||
option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
|
||||
|
||||
Optional Features
|
||||
=================
|
||||
|
||||
Some packages pay attention to `--enable-FEATURE' options to
|
||||
`configure', where FEATURE indicates an optional part of the package.
|
||||
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
|
||||
is something like `gnu-as' or `x' (for the X Window System). The
|
||||
`README' should mention any `--enable-' and `--with-' options that the
|
||||
package recognizes.
|
||||
|
||||
For packages that use the X Window System, `configure' can usually
|
||||
find the X include and library files automatically, but if it doesn't,
|
||||
you can use the `configure' options `--x-includes=DIR' and
|
||||
`--x-libraries=DIR' to specify their locations.
|
||||
|
||||
Specifying the System Type
|
||||
==========================
|
||||
|
||||
There may be some features `configure' can not figure out
|
||||
automatically, but needs to determine by the type of host the package
|
||||
will run on. Usually `configure' can figure that out, but if it prints
|
||||
a message saying it can not guess the host type, give it the
|
||||
`--host=TYPE' option. TYPE can either be a short name for the system
|
||||
type, such as `sun4', or a canonical name with three fields:
|
||||
CPU-COMPANY-SYSTEM
|
||||
|
||||
See the file `config.sub' for the possible values of each field. If
|
||||
`config.sub' isn't included in this package, then this package doesn't
|
||||
need to know the host type.
|
||||
|
||||
If you are building compiler tools for cross-compiling, you can also
|
||||
use the `--target=TYPE' option to select the type of system they will
|
||||
produce code for and the `--build=TYPE' option to select the type of
|
||||
system on which you are compiling the package.
|
||||
|
||||
Sharing Defaults
|
||||
================
|
||||
|
||||
If you want to set default values for `configure' scripts to share,
|
||||
you can create a site shell script called `config.site' that gives
|
||||
default values for variables like `CC', `cache_file', and `prefix'.
|
||||
`configure' looks for `PREFIX/share/config.site' if it exists, then
|
||||
`PREFIX/etc/config.site' if it exists. Or, you can set the
|
||||
`CONFIG_SITE' environment variable to the location of the site script.
|
||||
A warning: not all `configure' scripts look for a site script.
|
||||
|
||||
Operation Controls
|
||||
==================
|
||||
|
||||
`configure' recognizes the following options to control how it
|
||||
operates.
|
||||
|
||||
`--cache-file=FILE'
|
||||
Use and save the results of the tests in FILE instead of
|
||||
`./config.cache'. Set FILE to `/dev/null' to disable caching, for
|
||||
debugging `configure'.
|
||||
|
||||
`--help'
|
||||
Print a summary of the options to `configure', and exit.
|
||||
|
||||
`--quiet'
|
||||
`--silent'
|
||||
`-q'
|
||||
Do not print messages saying which checks are being made.
|
||||
|
||||
`--srcdir=DIR'
|
||||
Look for the package's source code in directory DIR. Usually
|
||||
`configure' can determine that directory automatically.
|
||||
|
||||
`--version'
|
||||
Print the version of Autoconf used to generate the `configure'
|
||||
script, and exit.
|
||||
|
||||
`configure' also accepts some other, not widely useful, options.
|
||||
|
||||
@ -0,0 +1,8 @@
|
||||
|
||||
There are some docs ( at 11.04.2001 avaible docs for html, css, php, javascript )
|
||||
you need to download packages from http://quanta.sourceforge.net
|
||||
( html.tar.bz2, php.tar.bz2, css.tar.bz2 ) and uncompress them
|
||||
to $KDEDIR/share/apps/quanta/doc/
|
||||
or to ~/.kde/share/apps/quanta/doc/
|
||||
and restart quanta.
|
||||
|
||||
@ -0,0 +1,30 @@
|
||||
COMPILE_FIRST = lib
|
||||
MAINTAINERCLEANFILES = subdirs configure.in acinclude.m4 configure.files
|
||||
|
||||
dist-hook:
|
||||
cd $(top_distdir) && perl admin/am_edit -padmin
|
||||
cd $(top_distdir) && $(MAKE) -f admin/Makefile.common subdirs
|
||||
|
||||
|
||||
install-data-local:
|
||||
@echo ""
|
||||
@echo ""
|
||||
@echo "*************** Important *************************"
|
||||
@echo ""
|
||||
@echo " Add "$(bindir)" to your PATH and"
|
||||
@echo " add "$(prefix)" to your KDEDIRS!"
|
||||
@echo ""
|
||||
@echo " Please report bugs with our web form at"
|
||||
@echo " http://bugs.kde.org"
|
||||
@echo " Current maintainers are"
|
||||
@echo " Eric Laffoon <sequitur@kde.org>"
|
||||
@echo " Andras Mantia <amantia@kde.org>"
|
||||
@echo ""
|
||||
@echo " The KDE Web Dev developers hope you enjoy Quanta+,"
|
||||
@echo " Kommander, KFileReplace, KXSL dbg, KImageMapEditor"
|
||||
@echo " and KLinkStatus!"
|
||||
@echo "****************************************************"
|
||||
@echo ""
|
||||
|
||||
include admin/deps.am
|
||||
|
||||
@ -0,0 +1,15 @@
|
||||
|
||||
all:
|
||||
@echo "This Makefile is only for the CVS repository"
|
||||
@echo "This will be deleted before making the distribution"
|
||||
@echo ""
|
||||
@if test ! -d admin; then \
|
||||
echo "Please recheckout this module!" ;\
|
||||
echo "for cvs: use checkout once and after that update again" ;\
|
||||
echo "for cvsup: checkout kde-common from cvsup and" ;\
|
||||
echo " link kde-common/admin to ./admin" ;\
|
||||
exit 1 ;\
|
||||
fi
|
||||
$(MAKE) -f admin/Makefile.common cvs
|
||||
|
||||
.SILENT:
|
||||
@ -0,0 +1,2 @@
|
||||
For the latest new features and bugfixes in Quanta+ and the other included
|
||||
applications take a look at the ChangeLog file in the subdirectories.
|
||||
@ -0,0 +1,77 @@
|
||||
Here there is some information about requirements for packagers. Please take
|
||||
care of the below compilation and runtime dependencies when packaging Quanta.
|
||||
|
||||
Severity levels mean:
|
||||
- Required: Quanta will not run without it
|
||||
- Highly recommended: Quanta will run, but some important functionality will be missing
|
||||
- Recommended: some functionality will be missing
|
||||
- Optional: completes the functionalities in Quanta, making the development easier
|
||||
|
||||
1. Compilation requirements:
|
||||
------------------------------
|
||||
- KDE 3.4 libraries or above
|
||||
Severity: Required
|
||||
- cvsservice headers:
|
||||
Description: cvsservice headers are used for the incorporated CVS actions. Without them
|
||||
the CVS submenu from the file context menus will be missing.
|
||||
Severity: Highly recommended
|
||||
Location: kdesdk/cervisia
|
||||
|
||||
2. Runtime dependencies:
|
||||
---------------------------
|
||||
- Kommander:
|
||||
Description: Required to run some of the dialogs in Quanta+
|
||||
Severity: Highly recommended
|
||||
Location: kdewebdev module
|
||||
|
||||
- KFileReplace:
|
||||
Description: Used to search and replace in external files
|
||||
Severity: Highly recommended
|
||||
Location: kdewebdev module
|
||||
|
||||
- KLinkStatus:
|
||||
Description: Used to check the validity of the links
|
||||
Severity: Highly recommended
|
||||
Location: kdewebdev module
|
||||
|
||||
- HTML Tidy:
|
||||
Description: Used to check the validity of the HTML documents
|
||||
Severity: Highly recommended
|
||||
Location: http://tidy.sf.net
|
||||
|
||||
- Gubed:
|
||||
Description: the PHP Debugger used by Quanta
|
||||
Severity: Highly recommended
|
||||
Location: http://gubed.sf.net (only the server is required)
|
||||
|
||||
- cvsservice:
|
||||
Description: used by the *integrated* CVS commands.
|
||||
Severity: Highly Recommended
|
||||
Localtion: kdesdk module
|
||||
|
||||
- Cervisia:
|
||||
Description: Used to perform CVS operations
|
||||
Severity: Recommended
|
||||
Location: kdesdk module
|
||||
|
||||
- KXSLDbg:
|
||||
Description: XSLT debugger
|
||||
Severity: Recommended
|
||||
Location: kdewebdev module
|
||||
|
||||
- KImageMapEditor:
|
||||
Description: Helps creation and editing of HTML image-maps
|
||||
Severity: Optional
|
||||
Location: kdewebdev module
|
||||
|
||||
- Kompare:
|
||||
Description: compares two files by content. Used when a file was modified outside of Quanta.
|
||||
Severity: Recommended
|
||||
Localtion: kdesdk module
|
||||
|
||||
- GPG (OpenPGP):
|
||||
Description: digital signature tool. Makes possible the signature verification of downloaded
|
||||
resources.
|
||||
Severity: Highly Recommended
|
||||
Location: http://www.gnupg.de
|
||||
|
||||
@ -0,0 +1,24 @@
|
||||
KDE WebDev - WEB Development package for the K Desktop Environment.
|
||||
Version: 3.5 line
|
||||
|
||||
|
||||
The kdewebdev package contains Quanta Plus and other applications, which are useful
|
||||
for web development. They are runtime dependencies of Quanta Plus, and it is
|
||||
highly recommended that you install them.
|
||||
|
||||
The extra applications are:
|
||||
|
||||
Kommander: a GUI script builder and executor tool. Needed for some Quanta functionality.
|
||||
KFileReplace: powerful search and replace in multiple files
|
||||
KXSLDbg: XSL debugger
|
||||
KImageMapEditor: image map editor
|
||||
KLinkStatus: link checker
|
||||
|
||||
Be sure to read the README files in each application's directory!
|
||||
Packagers, please read the PACKAGING file for detailed information about compilation
|
||||
and runtime dependencies.
|
||||
|
||||
|
||||
Enjoy Quanta+!
|
||||
|
||||
The Quanta team
|
||||
@ -0,0 +1,8 @@
|
||||
if test "$enable_editors" = "yes"; then
|
||||
echo ""
|
||||
echo "WARNING: You have enabled the editor chooser feature!"
|
||||
echo "This feature is highly experimental, and officially only the"
|
||||
echo "Kate part (Advanced Text Editor) is supported!"
|
||||
echo "Some features are not accessible with other editors, and"
|
||||
echo "Quanta may even crash with those!"
|
||||
fi
|
||||
@ -0,0 +1,264 @@
|
||||
#MIN_CONFIG(3.3)
|
||||
dnl If the quanta executable name and the data dirs are changed from the default "quanta",
|
||||
dnl the following changes are needed:
|
||||
dnl - change the quanta_datadir
|
||||
dnl - change the QUANTA_PACKAGE and QUANTA_VERSION in quanta/src/quanta.h
|
||||
dnl - change the KDE_ICON in quanta/data/icons/Makefile.am
|
||||
dnl - create a .desktop file and the corresponding icons
|
||||
dnl - make sure the .desktop file is installed in the quanta/src/Makefile.am
|
||||
dnl (kdelnk_DATA = quanta.desktop line)
|
||||
dnl - change the bin_PROGRAMS and the _SOURCES, _LDADD, _METASOURCES, _LDFLAGS
|
||||
dnl below it in the quanta/src/Makefile.am, so it reflects the new executable name
|
||||
|
||||
AM_INIT_AUTOMAKE(@MODULENAME@, @VERSION@)
|
||||
KDE_ENABLE_HIDDEN_VISIBILITY
|
||||
|
||||
quanta_datadir='${kde_datadir}/quanta'
|
||||
package="quanta"
|
||||
AC_SUBST(package)
|
||||
AC_SUBST(quanta_datadir)
|
||||
AM_CONDITIONAL(QUANTAUIRC_HOOK, test "x$package" != "xquanta")
|
||||
|
||||
dnl These are common macros that you might or might not want to use
|
||||
|
||||
dnl Checks for header files.
|
||||
AC_HEADER_DIRENT
|
||||
AC_HEADER_STDC
|
||||
AC_HEADER_TIME
|
||||
AC_CHECK_HEADERS(fcntl.h sys/time.h unistd.h stdlib.h paths.h sys/statvfs.h sys/statfs.h sys/vfs.h sys/mount.h sys/param.h stdarg.h)
|
||||
AC_CHECK_FUNCS(usleep)
|
||||
AC_CHECK_FUNCS(statvfs)
|
||||
|
||||
AC_DEFINE_UNQUOTED(PREFIX,"$prefix",[Define the PREFIX to be used later])
|
||||
|
||||
dnl
|
||||
dnl The following new parameters were added to offer
|
||||
dnl the ability to specify the location of the libxml
|
||||
dnl library during linking and compilation.
|
||||
dnl Mathieu Lacage 30/03/2000
|
||||
dnl
|
||||
LIBXML_PREFIX=""
|
||||
AC_ARG_WITH(libxml-prefix,
|
||||
[ --with-libxml-prefix=[PFX] Specify location of libxml],
|
||||
LIBXML_PREFIX="$withval"
|
||||
)
|
||||
|
||||
if test "x${LIBXML_PREFIX}" != "x"
|
||||
then
|
||||
AC_MSG_RESULT(Using a libxml prefix of ${LIBXML_PREFIX})
|
||||
fi
|
||||
|
||||
|
||||
AC_SUBST(LIBXML_LIBS)
|
||||
|
||||
dnl Test for libxml2 version
|
||||
XML_CONFIG="xml2-config"
|
||||
AC_MSG_CHECKING(for libxml libraries >= "2.6.0")
|
||||
XML_WARNING=""
|
||||
if test "x$LIBXML_PREFIX" != "x"
|
||||
then
|
||||
if ${LIBXML_PREFIX}/bin/xml2-config --libs print > /dev/null 2>&1
|
||||
then
|
||||
XML_CONFIG=${LIBXML_PREFIX}/bin/xml2-config
|
||||
else
|
||||
XML_WARNING="1"
|
||||
XML_CONFIG=xml2-config
|
||||
fi
|
||||
fi
|
||||
|
||||
AC_DEFUN([VERSION_TO_NUMBER],
|
||||
[`$1 | sed -e 's/libxml //' | $AWK 'BEGIN { FS = "."; } { printf "%d",
|
||||
([$]1* 1000 + [$]2) * 1000 + [$]3;}'`])
|
||||
|
||||
dnl
|
||||
dnl test version and init our variables
|
||||
dnl
|
||||
if test "x$XML_CONFIG" != "x"
|
||||
then
|
||||
vers=VERSION_TO_NUMBER($XML_CONFIG --version)
|
||||
if test "$vers" -lt VERSION_TO_NUMBER(echo "2.6.0")
|
||||
then
|
||||
CXXFLAGS="$CXXFLAGS -DLIBXML_2_5"
|
||||
AC_MSG_RESULT(not found - assuming 2.5.x)
|
||||
else
|
||||
AC_MSG_RESULT(found)
|
||||
fi
|
||||
LIBXML_LIBS="`$XML_CONFIG --libs`"
|
||||
LIBXML_CFLAGS="`$XML_CONFIG --cflags`"
|
||||
LIBXML_PREFIX="$XML_CONFIG --prefix"
|
||||
else
|
||||
AC_MSG_ERROR(Could not find libxml2 anywhere, check ftp://xmlsoft.org/.)
|
||||
fi
|
||||
|
||||
if test "x${XML_WARNING}" != "x"
|
||||
then
|
||||
AC_MSG_RESULT(
|
||||
!!Warning!! using xml2-config in default path
|
||||
)
|
||||
fi
|
||||
|
||||
LIBXML_PREFIX_DIR="`$XML_CONFIG --prefix`"
|
||||
|
||||
AC_SUBST(XML_CONFIG)
|
||||
AC_SUBST(LIBXML_PREFIX)
|
||||
AC_SUBST(LIBXML_LIBS)
|
||||
AC_SUBST(LIBXML_CFLAGS)
|
||||
|
||||
LIBXSLT_PREFIX=""
|
||||
AC_ARG_WITH(libxslt-prefix,
|
||||
[ --with-libxslt-prefix=[PFX] Specify location of libxslt],
|
||||
LIBXSLT_PREFIX="$withval"
|
||||
)
|
||||
|
||||
if test "x${LIBXSLT_PREFIX}" != "x"
|
||||
then
|
||||
AC_MSG_RESULT(Using a libxslt prefix of ${LIBXSLT_PREFIX})
|
||||
fi
|
||||
|
||||
dnl
|
||||
dnl find libxslt
|
||||
dnl
|
||||
XSLT_CONFIG="xslt-config"
|
||||
XSLT_WARNING=""
|
||||
AC_SUBST(LIBXSLT_REQUIRED_VERSION)
|
||||
AC_MSG_CHECKING(for libxslt libraries >= $LIBXSLT_REQUIRED_VERSION)
|
||||
if test "x$LIBXSLT_PREFIX" != "x"
|
||||
then
|
||||
if ${LIBXSLT_PREFIX}/bin/xslt-config --libs print > /dev/null 2>&1
|
||||
then
|
||||
XSLT_CONFIG=${LIBXSLT_PREFIX}/bin/xslt-config
|
||||
else
|
||||
XSLT_WARNING="1"
|
||||
XSLT_CONFIG=xslt-config
|
||||
fi
|
||||
fi
|
||||
|
||||
|
||||
AC_DEFUN([VERSION_TO_NUMBER],
|
||||
[`$1 | sed -e 's/libxslt //' | $AWK 'BEGIN { FS = "."; } { printf "%d",
|
||||
([$]1 * 1000 + [$]2) * 1000 + [$]3;}'`])
|
||||
|
||||
dnl
|
||||
dnl test version and init our variables
|
||||
dnl
|
||||
if test "x$XSLT_CONFIG" != "x"
|
||||
then
|
||||
vers=VERSION_TO_NUMBER($XSLT_CONFIG --version)
|
||||
if test "$vers" -ge VERSION_TO_NUMBER(echo $LIBXSLT_REQUIRED_VERSION)
|
||||
then
|
||||
LIBXSLT_LIBS="-lexslt `$XSLT_CONFIG --libs`"
|
||||
LIBXSLT_CFLAGS="`$XSLT_CONFIG --cflags`"
|
||||
AC_MSG_RESULT(found)
|
||||
if test "x$LIBXSLT_PREFIX" != "x"
|
||||
then
|
||||
AC_MSG_RESULT(
|
||||
Don't forget to make sure that ${LIBXSLT_PREFIX}/lib has been added
|
||||
to your LD_LIBRARY_PATH environment variable)
|
||||
else
|
||||
LIBXSLT_PREFIX="$XSLT_CONFIG --prefix"
|
||||
fi
|
||||
else
|
||||
AC_MSG_ERROR(You need at least libxslt $LIBXSLT_REQUIRED_VERSION for this
|
||||
version of xsldbg)
|
||||
fi
|
||||
else
|
||||
AC_MSG_ERROR(Could not find libxslt anywhere, check
|
||||
ftp://xmlsoft.org/XSLT/.)
|
||||
fi
|
||||
|
||||
if test "x${XSLT_WARNING}" != "x"
|
||||
then
|
||||
AC_MSG_RESULT(
|
||||
!!Warning!! using xslt-config in default path
|
||||
)
|
||||
fi
|
||||
|
||||
AC_SUBST(XSLT_CONFIG)
|
||||
AC_SUBST(LIBXSLT_PREFIX)
|
||||
AC_SUBST(LIBXSLT_LIBS)
|
||||
AC_SUBST(LIBXSLT_CFLAGS)
|
||||
|
||||
|
||||
dnl **********
|
||||
dnl check whether we need the qextmdi lib
|
||||
dnl (Shamlesly stolen from gideon souorces and
|
||||
dnl modified for quanta by fredi)
|
||||
dnl **********
|
||||
|
||||
AC_DEFUN([QUANTA_CHECK_MDI],
|
||||
[
|
||||
AC_MSG_CHECKING(whether to use kmdi lib from kdelibs)
|
||||
AC_CACHE_VAL(ac_cv_mdi_setup,
|
||||
[
|
||||
AC_LANG_SAVE
|
||||
AC_LANG_CPLUSPLUS
|
||||
save_CXXFLAGS="$CXXFLAGS"
|
||||
CXXFLAGS="$KDE_INCLUDES $QT_INCLUDES"
|
||||
|
||||
AC_TRY_LINK([
|
||||
#include <kdeversion.h>
|
||||
],
|
||||
[
|
||||
#if KDE_VERSION < ((3<<16) | (3<<8) | (92))
|
||||
KDE_choke me
|
||||
#endif
|
||||
],
|
||||
ac_cv_mdi_setup=yes,
|
||||
ac_cv_mdi_setup=no
|
||||
)
|
||||
CXXFLAGS="$save_CXXFLAGS"
|
||||
AC_LANG_RESTORE
|
||||
])
|
||||
|
||||
if test "$ac_cv_mdi_setup" = "yes"; then
|
||||
LIB_KMDI="-lkmdi"
|
||||
QEXTMDI_SUBDIR=""
|
||||
KMDI_INCLUDES=""
|
||||
AC_MSG_RESULT(yes)
|
||||
else
|
||||
LIB_KMDI='$(top_builddir)/lib/compatibility/kmdi/libquantakmdi.la'
|
||||
QEXTMDI_SUBDIR="kmdi"
|
||||
KMDI_INCLUDES='-I$(top_srcdir)/lib/compatibility/kmdi/qextmdi'
|
||||
CXXFLAGS="$CXXFLAGS -DCOMPAT_KMDI"
|
||||
AC_MSG_RESULT(no)
|
||||
fi
|
||||
|
||||
AC_SUBST(LIB_KMDI)
|
||||
AC_SUBST(KMDI_INCLUDES)
|
||||
AC_SUBST(QEXTMDI_SUBDIR)
|
||||
AM_CONDITIONAL(include_qextmdi, test -n "$QEXTMDI_SUBDIR")
|
||||
])
|
||||
|
||||
dnl Check if kmdi is present, if not use giden's one
|
||||
QUANTA_CHECK_MDI
|
||||
|
||||
KDE_CHECK_HEADER(cvsservice_stub.h, [cvsservice_stub_h="found"], [cvsservice_stub_h="none"])
|
||||
AM_CONDITIONAL(include_cvsservice, test "$cvsservice_stub_h" = "found")
|
||||
if test "$cvsservice_stub_h" = "found"; then
|
||||
CXXFLAGS="$CXXFLAGS -DENABLE_CVSSERVICE"
|
||||
fi
|
||||
|
||||
#check for KNewStuffSecure headers
|
||||
KNEWSTUFF_INCLUDES=""
|
||||
LIB_KNEWSTUFF="-lknewstuff"
|
||||
KDE_CHECK_HEADER(knewstuff/knewstuffsecure.h, [knewstuffsecure_h="found"], [knewstuffsecure_h="none"])
|
||||
AM_CONDITIONAL(include_knewstuff, test "$knewstuffsecure_h" != "found")
|
||||
if test "$knewstuffsecure_h" != "found"; then
|
||||
KNEWSTUFF_INCLUDES='-I$(top_srcdir)/lib/compatibility'
|
||||
LIB_KNEWSTUFF='$(top_builddir)/lib/compatibility/knewstuff/libknewstuff.la'
|
||||
fi
|
||||
AC_SUBST(KNEWSTUFF_INCLUDES)
|
||||
AC_SUBST(LIB_KNEWSTUFF)
|
||||
|
||||
|
||||
|
||||
AC_ARG_ENABLE(editors, [ --enable-editors Enable selection of other editors aside of Kate],
|
||||
[enable_editors=$enableval], [enable_editors="no"])
|
||||
|
||||
if test "$enable_editors" = "yes"; then
|
||||
CXXFLAGS="$CXXFLAGS -DENABLE_EDITORS"
|
||||
fi
|
||||
AC_SUBST(enable_editors)
|
||||
|
||||
AC_CHECK_PROGS(TAR, gnutar gtar tar, [AM_MISSING_PROG(tar)])
|
||||
AC_CHECK_PROG(GZIP_COMMAND, gzip, gzip)
|
||||
@ -0,0 +1,4 @@
|
||||
KDE_LANG = en
|
||||
KDE_DOCS = AUTO
|
||||
SUBDIRS = $(AUTODIRS)
|
||||
|
||||
@ -0,0 +1,2 @@
|
||||
KDE_DOCS = AUTO
|
||||
KDE_LANG = en
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 979 B |
Binary file not shown.
|
After Width: | Height: | Size: 1.1 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.1 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.1 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 820 B |
Binary file not shown.
|
After Width: | Height: | Size: 713 B |
Binary file not shown.
|
After Width: | Height: | Size: 339 B |
Binary file not shown.
|
After Width: | Height: | Size: 1.1 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.1 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.1 KiB |
@ -0,0 +1,613 @@
|
||||
<?xml version="1.0" ?>
|
||||
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
|
||||
<!ENTITY kfilereplace "<application>KFileReplace</application>">
|
||||
<!ENTITY kappname "&kfilereplace;">
|
||||
<!ENTITY package "kdewebdev">
|
||||
<!ENTITY % addindex "IGNORE">
|
||||
<!ENTITY % English "INCLUDE">
|
||||
<!ENTITY kdewebdev "<application>kdewebdev</application>">
|
||||
<!ENTITY bc "<application>bc</application>">
|
||||
]>
|
||||
|
||||
<book lang="&language;">
|
||||
|
||||
<bookinfo>
|
||||
<title>The &kfilereplace; Handbook</title>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Emiliano</firstname>
|
||||
<surname>Gulmini</surname>
|
||||
<affiliation>
|
||||
<address><email>emi_barbarossa@yahoo.it</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
|
||||
</authorgroup>
|
||||
|
||||
<copyright>
|
||||
<year>2004</year>
|
||||
<holder>Emiliano Gulmini</holder>
|
||||
</copyright>
|
||||
|
||||
<legalnotice>&FDLNotice;</legalnotice>
|
||||
|
||||
<date>2004-08-09</date>
|
||||
<releaseinfo>1.0.0</releaseinfo>
|
||||
|
||||
<!-- Abstract about this handbook -->
|
||||
|
||||
<abstract>
|
||||
<para>
|
||||
&kfilereplace; is an utility to search and replace strings.
|
||||
</para>
|
||||
</abstract>
|
||||
|
||||
<keywordset>
|
||||
<keyword>KDE</keyword>
|
||||
<keyword>KFileReplace</keyword>
|
||||
<keyword>replace</keyword>
|
||||
<keyword>search</keyword>
|
||||
<keyword>string</keyword>
|
||||
</keywordset>
|
||||
|
||||
</bookinfo>
|
||||
|
||||
<chapter id="introduction">
|
||||
<title>Introduction</title>
|
||||
<para>&kfilereplace; is an application used to search and replace a list of strings in a file tree. The strings may be literal or Qt-like regular expressions. There are also other options to tune your search.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="using-kfilereplace">
|
||||
<title>Using &kfilereplace;</title>
|
||||
|
||||
<para>
|
||||
<screenshot>
|
||||
<screeninfo>&kfilereplace; in its standalone incarnation</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="kfr_standalone_main_window_1.png" format="PNG"/>
|
||||
</imageobject>
|
||||
<textobject>
|
||||
<phrase>&kfilereplace; in its standalone incarnation</phrase>
|
||||
</textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
</para>
|
||||
|
||||
|
||||
<sect1 id="kfilereplace-the-toolbar">
|
||||
<title>The Toolbar</title>
|
||||
|
||||
<para>The &kfilereplace; toolbar should looks like this:
|
||||
<screenshot>
|
||||
<screeninfo>&kfilereplace;'s toolbar</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="toolbar.png" format="PNG"/>
|
||||
</imageobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="toolbar.eps" format="EPS"/>
|
||||
</imageobject>
|
||||
<textobject>
|
||||
<phrase>&kfilereplace;'s toolbar</phrase>
|
||||
</textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
</para>
|
||||
|
||||
<para>The toolbar shows you the buttons of the main functionalities.
|
||||
<variablelist>
|
||||
<title>Toolbar Icons</title>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="project.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject><guiicon>New session</guiicon></term>
|
||||
<listitem>
|
||||
<para>This button shows a <link linkend="kfilereplace-the-project-dialog">session dialog</link> in which you can set several basic options; if &kfilereplace; run as standalone application you should click this button as first step.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="filesearch.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject><guiicon>Search only</guiicon></term>
|
||||
<listitem>
|
||||
<para>This button starts a search loop.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="filereplace.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject><guiicon>Replace</guiicon></term>
|
||||
<listitem>
|
||||
<para>This button starts a search&replace loop. When a string has been found, &kfilereplace; replaces it with another string.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="filesimulate.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject><guiicon>Simulated Replace</guiicon></term>
|
||||
<listitem>
|
||||
<para>This button starts a simulated search&replace loop. Nothing really happens when you click this button.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="stop.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject><guiicon>Stop</guiicon></term>
|
||||
<listitem>
|
||||
<para>This button stops an operation.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="edit_add.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject><guiicon>Add Strings</guiicon></term>
|
||||
<listitem>
|
||||
<para>This button opens the <link linkend="kfilereplace-the-add-dialog">Add Strings</link> dialog in which you can edit your string list.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="edit_remove.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject><guiicon>Delete Strings</guiicon></term>
|
||||
<listitem>
|
||||
<para>This button deletes the selected (or the current if there is no selection) string from the list.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="edit.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject><guiicon>Edit Strings</guiicon></term>
|
||||
<listitem>
|
||||
<para>This button edits a selected string.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="eraser.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject><guiicon>Delete List</guiicon></term>
|
||||
<listitem>
|
||||
<para>This button deletes all the strings in the list.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="invert.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject><guiicon>Invert Strings</guiicon></term>
|
||||
<listitem>
|
||||
<para>This button swaps the search string with the replace string, so you can revert a search/replace operation.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="unsortedList.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject><guiicon>Load String List</guiicon></term>
|
||||
<listitem>
|
||||
<para>This button loads a <link linkend="kfilereplace-the-kfr-file">string list</link> saved in a xml file with a <literal role="extension">kfr</literal> extension.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="recursive_option.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject><guiicon>Search in Subfolders</guiicon></term>
|
||||
<listitem>
|
||||
<para>This button allows you to search/replace recursively in the subfolders of your base directory.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="backup_option.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject><guiicon>Make Backup Files</guiicon></term>
|
||||
<listitem>
|
||||
<para>This button enables generation of <link linkend="kfilereplace-backup-file">backup</link> files.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="casesensitive_option.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject><guiicon>Case-sensitive Search</guiicon></term>
|
||||
<listitem>
|
||||
<para>This button enables case-sensitive searching.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="command_option.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject><guiicon>Commands</guiicon></term>
|
||||
<listitem>
|
||||
<para>This button enables commands capability. Commands are special strings. See <xref linkend="kfilereplace-commands"/>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="regularexpression_option.png" format="PNG"/>
|
||||
</imageobject>
|
||||
</inlinemediaobject><guiicon>Regular expressions</guiicon></term>
|
||||
<listitem>
|
||||
<para>This button enables <link linkend="kfilereplace-QT-regexp">Qt-like regular expressions</link>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="kfilereplace-the-results-view">
|
||||
<title>The Results List</title>
|
||||
<screenshot>
|
||||
<screeninfo>&kfilereplace;'s Results view</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="results_view.png" format="PNG"/>
|
||||
</imageobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="results_view.eps" format="EPS"/>
|
||||
</imageobject>
|
||||
<textobject>
|
||||
<phrase>&kfilereplace;'s Results view</phrase>
|
||||
</textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
<para>The <guilabel>Results</guilabel> view shows the name of the files that contain the strings you have to retrieve (and replace), their path, their size, the number of strings found and the user id of the files. This view also provides the exact position of each match. You can also open a file by clicking with the &RMB; on an list entry that contains line and column position.</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="kfilereplace-the-strings-view">
|
||||
<title>The String List</title>
|
||||
|
||||
<para>This is the <guilabel>Strings</guilabel> view:
|
||||
<screenshot>
|
||||
<screeninfo>&kfilereplace;'s Strings view</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="strings_view.png" format="PNG"/>
|
||||
</imageobject>
|
||||
<textobject>
|
||||
<phrase>&kfilereplace;'s Strings view</phrase>
|
||||
</textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
</para>
|
||||
|
||||
<para>The <guilabel>Strings</guilabel> view visualizes the list of strings you want search/replace. Please note that in search mode the <guilabel>Results</guilabel> view and the <guilabel>Strings</guilabel> view have a different layout.</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="kfilereplace-the-project-dialog">
|
||||
<title>The <guilabel>New Session</guilabel> Dialog</title>
|
||||
<para>The <guilabel>New Session</guilabel> dialog is used to setup the basic parameters needed by &kfilereplace; to work. It consists of two tabs, <guilabel>General</guilabel> and <guilabel>Advanced</guilabel>.
|
||||
</para>
|
||||
|
||||
<sect2 id="kfilereplace-the-project-dialog-general-page">
|
||||
<title>The <guilabel>General</guilabel> Tab</title>
|
||||
<screenshot>
|
||||
<screeninfo>&kfilereplace; General tab</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="projectdialog_main_window_1.png" format="PNG"/>
|
||||
</imageobject>
|
||||
<textobject>
|
||||
<phrase>&kfilereplace; General tab</phrase>
|
||||
</textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
<para>When you want to begin a new session the first step is to click on the <link linkend="kfilereplace-the-toolbar"><guiicon>New Session</guiicon> button</link>. Then you must enter the base path and a sequence of shell-like wildcards to use as filter.</para>
|
||||
<para>Then you could set some useful options, like searching in all the subfolders, doing a case-sensitive search, enabling commands and/or regular expressions<footnote id="performancewarning"><para>Please note that regular expressions and commands could slow down the speed performances.</para></footnote>, doing a backup copy of each file before replacing.</para>
|
||||
<para>If you want to start searching, you can put a string in the search box and press <guibutton>Search Now</guibutton>, otherwise leave the search box empty and press <guibutton>Search Later</guibutton>.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="kfilereplace-the-project-dialog-advanced-page">
|
||||
<title>The <guilabel>Advanced</guilabel> Tab</title>
|
||||
<screenshot>
|
||||
<screeninfo>&kfilereplace; Advanced tab</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="projectdialog_main_window_2.png" format="PNG"/>
|
||||
</imageobject>
|
||||
<textobject>
|
||||
<phrase>&kfilereplace; Advanced tab</phrase>
|
||||
</textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
<para>The <guilabel>Advanced</guilabel> tab allows you to set up some useful options to restrict the search to a subset of your target file tree. If you want to run &kfilereplace; only over files that have a size in the range of 10KB - 100KB, then you could use the size options. There is also a date option that restricts the search in a temporal range, and a last option that allows you to only search for files owned (or not owned) by a particular user (this may be more useful to the system administrators).</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="kfilereplace-the-options-dialog">
|
||||
<title>The <guilabel>Options</guilabel> Dialog</title>
|
||||
<para>This dialog contains options that are in the toolbar and extra options that may come in handy in some situations. You can invoke it selecting <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure KFileReplace...</guimenuitem></menuchoice> in the main menu.
|
||||
</para>
|
||||
<sect2 id="kfilereplace-the-options-dialog-general-page">
|
||||
<title>General options</title>
|
||||
<para>These options have been presented in the <link linkend="kfilereplace-the-toolbar">Toolbar</link> section.
|
||||
<screenshot>
|
||||
<screeninfo>The General tab of the Options window</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="optionsdialog_main_window_1.png" format="PNG"/>
|
||||
</imageobject>
|
||||
<textobject>
|
||||
<phrase>The General tab of the Options window</phrase>
|
||||
</textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="kfilereplace-the-options-dialog-advanced-page">
|
||||
<title>Advanced options</title>
|
||||
<para>
|
||||
<screenshot>
|
||||
<screeninfo>The Advanced tab of the Options window</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="optionsdialog_main_window_2.png" format="PNG"/>
|
||||
</imageobject>
|
||||
<textobject>
|
||||
<phrase>The Advanced tab of the Options window</phrase>
|
||||
</textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
<segmentedlist>
|
||||
<segtitle>Do not show files if no strings are found or replaced</segtitle>
|
||||
<segtitle>When searching, stop on first string found</segtitle>
|
||||
<segtitle>Follow symbolic links</segtitle>
|
||||
<segtitle>Ignore hidden files and directories</segtitle>
|
||||
<seglistitem>
|
||||
<seg>shows only the files that match some of your strings. This will speed up the search.</seg>
|
||||
<seg>&kfilereplace; will stop when it finds a matching string, and will continue to search for other strings or, if you search for only one string, it will continue with the next file.</seg>
|
||||
<seg>if a file is a link to another one, then search in the real file.</seg>
|
||||
<seg>if hidden files or folders are encountered, ignore them.</seg>
|
||||
</seglistitem>
|
||||
</segmentedlist>
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1 id="kfilereplace-the-add-dialog">
|
||||
<title>The <guilabel>Add Strings</guilabel> Dialog</title>
|
||||
<screenshot>
|
||||
<screeninfo>&kfilereplace;'s Add Strings dialog</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="addstringsdialog_window.png" format="PNG"/>
|
||||
</imageobject>
|
||||
<textobject>
|
||||
<phrase>&kfilereplace;'s Add Strings dialog</phrase>
|
||||
</textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
<para>This dialog is used to insert and edit a list of strings. You just have to insert either a search-only or a search-and-replace list, and then with the two mini-editors you will introduce your text. The arrow buttons allow you to add pairs of strings or delete them. When you finish, click <guibutton>OK</guibutton>.</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
<chapter id="kfilereplace-features">
|
||||
<title>&kfilereplace; features</title>
|
||||
<para>This chapter provides informations about some useful capabilities of &kfilereplace;.</para>
|
||||
<sect1 id="kfilereplace-the-kfr-file">
|
||||
<title>How to save your string list</title>
|
||||
<para>When you want to reuse a list of strings you can save it in a <literal role="extension">xml</literal> file. To do this select from the menubar <menuchoice><guimenu>Search/Replace</guimenu><guisubmenu>Strings</guisubmenu><guimenuitem>Save Strings List to File</guimenuitem></menuchoice>. When you save a list, a simple <literal role="extension">xml</literal> file with extension <literal role="extension">kfr</literal> is created. To load a <literal role="extension">kfr</literal> file select from menubar <menuchoice><guimenu>Search/Replace</guimenu><guisubmenu>Strings</guisubmenu><guimenuitem>Load Strings List from File</guimenuitem></menuchoice>. The actual file looks like this:</para>
|
||||
<screen>
|
||||
<?xml version="1.0" ?>
|
||||
<kfr>
|
||||
<mode search="false"/>
|
||||
<replacement>
|
||||
<oldstring><![CDATA[SEARCH_STRING_1]] ></oldstring>
|
||||
<newstring><![CDATA[REPLACE_STRING_1]]></newstring>
|
||||
</replacement>
|
||||
<replacement>
|
||||
<oldstring><![CDATA[SEARCH_STRING_2]]></oldstring>
|
||||
<newstring><![CDATA[REPLACE_STRING_2]]></newstring>
|
||||
</replacement>
|
||||
|
||||
|
||||
<replacement>
|
||||
<oldstring><![CDATA[SEARCH_STRING_N]]></oldstring>
|
||||
<newstring><![CDATA[REPLACE_STRING_N]]></newstring>
|
||||
</replacement>
|
||||
|
||||
</kfr></screen>
|
||||
|
||||
<para>If you are using a previous format, you can update by hand your file by simply modifying it according to the above scheme. Alternatively, you can load the file written in the old format and save it again with &kfilereplace; in the way explained before.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="kfilereplace-the-report-file">
|
||||
<title>How to Create a Simple Report</title>
|
||||
<para>You can create a report by choosing <menuchoice><guimenu>Search/Replace</guimenu><guisubmenu>Results</guisubmenu><guimenuitem>Create Report File</guimenuitem></menuchoice> from the main menu. A report is a folder containing an <literal role="extension">xml</literal> and a <literal role="extension">css</literal> file. Reports may be useful to maintain a simple log of your operations.
|
||||
<screenshot>
|
||||
<screeninfo>&kfilereplace;'s Report feature</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="report_example.png" format="PNG"/>
|
||||
</imageobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="report_example.eps" format="EPS"/>
|
||||
</imageobject>
|
||||
<textobject>
|
||||
<phrase>&kfilereplace;'s Report feature</phrase>
|
||||
</textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="kfilereplace-QT-regexp">
|
||||
<title>How to use Regular Expressions</title>
|
||||
<para>
|
||||
If you want search for every string that starts with <quote>x</quote>, <quote>ht</quote> or <quote>u</quote> and ends with <quote>ml</quote>, you can write a regular expression like this: <userinput>(x|ht|u)ml</userinput>. Insert this expression in the search editor, click <guibutton>OK</guibutton>, and enable regular expressions by toggling the <link linkend="kfilereplace-the-toolbar"><guibutton>Regular Expression</guibutton> button</link>. Please note that using regular expressions lets you to make very complicated searches, but the cost could be a performance degradation. Regular expression can be very tricky, and it is often the case that <quote>if you want to solve a problem with a regular expression, you have two problems</quote>.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="kfilereplace-backup-file">
|
||||
<title>How to Protect Original Files</title>
|
||||
<para>If you do not want to lose your original files, you can make a copy of them before replacing the strings. After inserting your strings, and before starting the replacement process, you have just to toggle the <link linkend="kfilereplace-the-toolbar"><guiicon>Backup</guiicon> button</link>. If you want to customize the extension of the backup files open the <link linkend="kfilereplace-the-options-dialog"><guilabel>Options</guilabel> dialog</link>.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="kfilereplace-open-file">
|
||||
<title>How to Open a File</title>
|
||||
<para>If you want to open a file that matches some of your strings, you have to select a line in the result view and click on it with the &RMB;. A context menu will appear from which you can open the file. If you use &kfilereplace; embedded in &quantaplus;, you can open the file directly in it at the specified line and column.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="kfilereplace-commands">
|
||||
<title>Commands</title>
|
||||
<para>Suppose you want replace the phrase <quote>Alice's adventures in Wonderland</quote> with the <ulink url="http://www.textlibrary.com/download/alice-wo.txt">entire file that contains Carroll's novel</ulink>. Probably you don't want to do this by hand, what you need is a command that will do it for you. Click the <link linkend="kfilereplace-the-toolbar"><guiicon>Add</guiicon></link> button, select <guilabel>Search and Replace Mode</guilabel> and insert the following strings: <userinput>Alice's adventure in Wonderland</userinput> in the search mini-editor and the string <userinput>[$loadfile:<replaceable>/the-path-to-my-folder/my-folder/my-file</replaceable>$]</userinput> in the replacement mini-editor. Click <guibutton>OK</guibutton>. When you come back to the &kfilereplace; main window, toggle the <link linkend="kfilereplace-the-toolbar">Command action</link> button that enables the commands, and start the replacement process. There are also other commands, see <xref linkend="available-commands"/> for a list of all of them.</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
<chapter id="credits">
|
||||
<title>Credits and License</title>
|
||||
|
||||
<para>&kfilereplace;. Program copyright 1999 by François Dupoux <email>dupoux@dupoux.com</email>, 2003 Andras Mantia <email>amantia@kde.org</email>, 2004 Emiliano Gulmini <email>emi_barbarossa@yahoo.it</email>
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
<title>The &kfilereplace; authors and maintainers:</title>
|
||||
<varlistentry>
|
||||
<term>François Dupoux <email>dupoux@dupoux.com</email></term>
|
||||
<listitem><para>Original author</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>Andras Mantia <email>amantia@kde.org</email></term>
|
||||
<listitem><para>Shell autor, KPart creator, co-maintainer</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>Emiliano Gulmini <email>emi_barbarossa@yahoo.it</email></term>
|
||||
<listitem><para>Current maintainer, code cleaner & rewriter</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>
|
||||
Documentation Copyright © 2004 Emiliano Gulmini <email>emi_barbarossa@yahoo.it</email>
|
||||
</para>
|
||||
|
||||
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
|
||||
|
||||
&underFDL; <!-- FDL: do not remove -->
|
||||
&underGPL; <!-- GPL License -->
|
||||
|
||||
</chapter>
|
||||
|
||||
<appendix id="installation">
|
||||
<title>Installation</title>
|
||||
|
||||
<sect1 id="getting-kfilereplace">
|
||||
<title>How to install &kfilereplace;</title>
|
||||
<para>
|
||||
&kfilereplace; is currently part of &kdewebdev; package, so, in order to install it, you have to get a copy of &kdewebdev;. Note that if you are using a &kde; installation provided by your OS vendor, probably you already have &kdewebdev; installed; in this case, you can use &kfilereplace; either by opening &quantaplus; Web editor, or by calling it directly (unless you have an old &kde; version). Else you can download the &kdewebdev; package from the Internet: please refer to <ulink url="http://kdewebdev.org">&kdewebdev; home site</ulink> for more information.
|
||||
<!--&install.intro.documentation;-->
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="requirements">
|
||||
<title>Requirements</title>
|
||||
<para>In order to use the command <link linkend="available-commands">[$mathexp:<replaceable>some_math_expression</replaceable>$]</link> you should install the &bc; mathematical utility (version 1.06 or newer) written by Philip A. Nelson (<email>philnelson@acm.org</email>).</para>
|
||||
</sect1>
|
||||
|
||||
</appendix>
|
||||
|
||||
<appendix id="available-commands">
|
||||
<title>&kfilereplace; commands</title>
|
||||
<para>
|
||||
<segmentedlist>
|
||||
<segtitle>[$datetime:iso$]</segtitle>
|
||||
<segtitle>[$datetime:local$]</segtitle>
|
||||
<segtitle>[$user:uid$]</segtitle>
|
||||
<segtitle>[$user:gid$]</segtitle>
|
||||
<segtitle>[$user:loginname$]</segtitle>
|
||||
<segtitle>[$user:fullname$]</segtitle>
|
||||
<segtitle>[$user:homedir$]</segtitle>
|
||||
<segtitle>[$user:shell$]</segtitle>
|
||||
<segtitle>[$loadfile:<replaceable>/my-path/my-directory/my-file</replaceable>$]</segtitle>
|
||||
<segtitle>[$empty:$]</segtitle>
|
||||
<segtitle>[$random:<replaceable>AN_INTEGER_NUMBER</replaceable>$]</segtitle>
|
||||
<segtitle>[$random:$]</segtitle>
|
||||
<segtitle>[$mathexp:<replaceable>bc-expression</replaceable>$]</segtitle>
|
||||
<seglistitem>
|
||||
<seg>this command return the current date and time in Qt ISO format.</seg>
|
||||
<seg>like above but in local format.</seg>
|
||||
<seg>return the UID of the current user.</seg>
|
||||
<seg>return the GID of the current user.</seg>
|
||||
<seg>return the login name of the current user.</seg>
|
||||
<seg>return the full name of the current user.</seg>
|
||||
<seg>return the home directory of the current user.</seg>
|
||||
<seg>return the shell of the current user.</seg>
|
||||
<seg>return the content of the <emphasis>my-file</emphasis> file.</seg>
|
||||
<seg>return the empty string.</seg>
|
||||
<seg>return a random number string using <emphasis>AN_INTEGER_NUMBER</emphasis> as the initial seed.</seg>
|
||||
<seg>like above, but without initial seed.</seg>
|
||||
<seg>return the result of a &bc; v1.06 mathematical expression.</seg>
|
||||
</seglistitem>
|
||||
</segmentedlist>
|
||||
</para>
|
||||
</appendix>
|
||||
|
||||
&documentation.index;
|
||||
</book>
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 1.2 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 83 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 808 B |
Binary file not shown.
|
After Width: | Height: | Size: 53 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 615 B |
Binary file not shown.
|
After Width: | Height: | Size: 959 B |
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 54 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.3 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 9.3 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 8.0 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 279 B |
@ -0,0 +1,2 @@
|
||||
KDE_DOCS = AUTO
|
||||
KDE_LANG = en
|
||||
@ -0,0 +1,498 @@
|
||||
<?xml version="1.0" ?>
|
||||
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
|
||||
<!ENTITY klinkstatus "<application>KLinkStatus</application>">
|
||||
<!ENTITY kappname "&klinkstatus;">
|
||||
<!ENTITY package "kdewebdev">
|
||||
<!ENTITY % addindex "IGNORE">
|
||||
<!ENTITY % English "INCLUDE"><!-- change language only here -->
|
||||
]>
|
||||
<!-- kdoctemplate v0.8 October 1 1999
|
||||
Minor update to "Credits and Licenses" section on August 24, 2000
|
||||
Removed "Revision history" section on 22 January 2001
|
||||
Changed to Installation/Help menu entities 18 October 2001
|
||||
Other minor cleanup and changes 18 October 2001 -->
|
||||
|
||||
|
||||
<!--
|
||||
This template was designed by: David Rugge davidrugge@mindspring.com
|
||||
with lots of help from: Eric Bischoff ebisch@cybercable.tm.fr
|
||||
and Frederik Fouvry fouvry@sfs.nphil.uni-tuebingen.de
|
||||
of the KDE DocBook team.
|
||||
|
||||
You may freely use this template for writing any sort of KDE documentation.
|
||||
If you have any changes or improvements, please let us know.
|
||||
|
||||
Remember:
|
||||
- in XML, the case of the <tags> and attributes is relevant ;
|
||||
- also, quote all attributes.
|
||||
|
||||
Please don't forget to remove all these comments in your final documentation,
|
||||
thanks ;-).
|
||||
-->
|
||||
|
||||
<!-- ................................................................ -->
|
||||
|
||||
<!-- The language must NOT be changed here. -->
|
||||
|
||||
<book lang="&language;">
|
||||
|
||||
<!-- This header contains all of the meta-information for the document such
|
||||
as Authors, publish date, the abstract, and Keywords -->
|
||||
|
||||
<bookinfo>
|
||||
<title>The &klinkstatus; Handbook</title>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Paulo</firstname>
|
||||
<surname>Moura Guedes</surname>
|
||||
<affiliation>
|
||||
<address><email>moura@kdewebdev.org</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
|
||||
</authorgroup>
|
||||
|
||||
<copyright>
|
||||
<year>2004</year>
|
||||
<holder>Paulo Moura Guedes</holder>
|
||||
</copyright>
|
||||
<!-- Translators: put here the copyright notice of the translation -->
|
||||
<!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook
|
||||
and in the FDL itself on how to use it. -->
|
||||
<legalnotice>&FDLNotice;</legalnotice>
|
||||
|
||||
<!-- Date and version information of the documentation
|
||||
Don't forget to include this last date and this last revision number, we
|
||||
need them for translation coordination !
|
||||
Please respect the format of the date (YYYY-MM-DD) and of the version
|
||||
(V.MM.LL), it could be used by automation scripts.
|
||||
Do NOT change these in the translation. -->
|
||||
|
||||
<date>2004-04-29</date>
|
||||
<releaseinfo>0.1.3</releaseinfo>
|
||||
|
||||
<!-- Abstract about this handbook -->
|
||||
|
||||
<abstract>
|
||||
<para>
|
||||
&klinkstatus; is a link checker for &kde;.
|
||||
</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>KLinkStatus</keyword>
|
||||
<keyword>link checker</keyword>
|
||||
<keyword>validation</keyword>
|
||||
</keywordset>
|
||||
|
||||
</bookinfo>
|
||||
|
||||
|
||||
<chapter id="introduction">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>&klinkstatus; is a link checker for &kde;.
|
||||
It allows you to search internal and external links in your entire web site,
|
||||
just a single page and choose the depth to search.
|
||||
You can also check local files, ftp, fish, &etc;, as &klinkstatus; uses KIO.
|
||||
For performance, links can be checked simultaneously.
|
||||
|
||||
Please report any problems or feature requests to http://linkstatus.paradigma.co.pt/bugs/.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="using-klinkstatus">
|
||||
<title>Using &klinkstatus;</title>
|
||||
|
||||
<para>
|
||||
|
||||
<!-- Note that all graphics should be in .png format. Use no gifs because of
|
||||
patent issues. -->
|
||||
|
||||
<screenshot>
|
||||
<screeninfo>Here's a screenshot of &klinkstatus;</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="klinkstatus-mainwindow">
|
||||
<title>The main &klinkstatus; window</title>
|
||||
|
||||
<sect2>
|
||||
<title>The File Menu</title>
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>File</guimenu>
|
||||
<guimenuitem>New Link Check</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Creates a new session, if none is empty</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>File</guimenu>
|
||||
<guimenuitem>Open URL</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Opens a &URL;</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>File</guimenu>
|
||||
<guimenuitem>Close Tab</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Close the current tab.</action></para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>The <guimenu>Help</guimenu> Menu</title>
|
||||
|
||||
<!-- Assuming you have a standard help menu (help, what's this, about -->
|
||||
<!-- &klinkstatus;, about &kde;) then the documentation is already written. -->
|
||||
<!-- The following entity is valid anywhere that a variablelist is -->
|
||||
<!-- valid. -->
|
||||
|
||||
&help.menu.documentation;
|
||||
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
<!--
|
||||
<chapter id="developers">
|
||||
<title>Developer's Guide to &klinkstatus;</title>
|
||||
-->
|
||||
<!-- (OPTIONAL) A Programming/Scripting reference chapter should be
|
||||
used for apps that use plugins or that provide their own scripting hooks
|
||||
and/or development libraries. -->
|
||||
<!--
|
||||
<para>FILL_ME</para>
|
||||
-->
|
||||
<!-- Use refentries to describe APIs. Refentries are fairly complicated and you
|
||||
should consult the docbook reference for further details. The example below was
|
||||
taken from that reference and shortened a bit for readability.
|
||||
|
||||
<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 “Algorithm” 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>FILL_ME
|
||||
</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>
|
||||
-->
|
||||
<!-- (OPTIONAL but recommended) This chapter should include all of the silly
|
||||
(and not-so-silly) newbie questions that fill up your mailbox. This chapter
|
||||
should be reserved for BRIEF questions and answers! If one question uses more
|
||||
than a page or so then it should probably be part of the
|
||||
"Using this Application" chapter instead. You should use links to
|
||||
cross-reference questions to the parts of your documentation that answer them.
|
||||
This is also a great place to provide pointers to other FAQ's if your users
|
||||
must do some complicated configuration on other programs in order for your
|
||||
application work. -->
|
||||
<!--
|
||||
&reporting.bugs;
|
||||
&updating.documentation;
|
||||
|
||||
|
||||
<qandaset id="faqlist">
|
||||
<qandaentry>
|
||||
-
|
||||
<question>
|
||||
<para>My Mouse doesn't work. How do I quit &klinkstatus;?</para>
|
||||
</question>
|
||||
<answer>
|
||||
<para>You silly goose! Check out the <link linkend="commands">Commands
|
||||
Section</link> for the answer.</para>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
<qandaentry>
|
||||
<question>
|
||||
<para>Why am I unable to twiddle my documents?</para>
|
||||
</question>
|
||||
<answer>
|
||||
<para>You can only twiddle your documents if you have the foobar.lib
|
||||
installed.</para>
|
||||
</answer>
|
||||
|
||||
</qandaentry>
|
||||
</qandaset>
|
||||
|
||||
</chapter>
|
||||
-->
|
||||
|
||||
<chapter id="credits">
|
||||
|
||||
<!-- Include credits for the programmers, documentation writers, and
|
||||
contributors here. The license for your software should then be included below
|
||||
the credits with a reference to the appropriate license file included in the KDE
|
||||
distribution. -->
|
||||
|
||||
<title>Credits and License</title>
|
||||
|
||||
<para>
|
||||
&klinkstatus;
|
||||
</para>
|
||||
<para>
|
||||
Program Copyright © 2004 Paulo Moura Guedes <email>pmg@netcabo.pt</email>
|
||||
</para>
|
||||
<para>
|
||||
Documentation Copyright © 2004 Paulo Moura Guedes <email>pmg@netcabo.pt</email>
|
||||
</para>
|
||||
|
||||
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
|
||||
|
||||
&underFDL; <!-- FDL: do not remove -->
|
||||
&underGPL; <!-- GPL License -->
|
||||
|
||||
</chapter>
|
||||
|
||||
<appendix id="installation">
|
||||
<title>Installation</title>
|
||||
|
||||
<sect1 id="getting-klinkstatus">
|
||||
<title>How to obtain &klinkstatus;</title>
|
||||
|
||||
<!-- This first entity contains boiler plate for applications that are
|
||||
part of KDE CVS. You should remove it if you are releasing your
|
||||
application -->
|
||||
|
||||
<!--&install.intro.documentation;-->
|
||||
<para>http://kde-apps.org
|
||||
</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 &klinkstatus;, you need &kde; 1.1. Foobar.lib is
|
||||
required in order to support the advanced &klinkstatus; features. &klinkstatus; uses
|
||||
about 5 megs of memory to run, but this may vary depending on your
|
||||
platform and configuration.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All required libraries as well as &klinkstatus; itself can be found
|
||||
on <ulink url="ftp://ftp.klinkstatus.org">The &klinkstatus; home page</ulink>.
|
||||
</para>
|
||||
-->
|
||||
<!-- For a list of updates, you may refer to the application web site
|
||||
or the ChangeLog file, or ... -->
|
||||
<!--
|
||||
<para>
|
||||
You can find a list of changes at <ulink
|
||||
url="http://apps.kde.org/klinkstatus">http://apps.kde.org/klinkstatus</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 &klinkstatus; won't work !</para>
|
||||
|
||||
</sect1>
|
||||
-->
|
||||
</appendix>
|
||||
|
||||
&documentation.index;
|
||||
</book>
|
||||
|
||||
<!--
|
||||
Local Variables:
|
||||
mode: sgml
|
||||
sgml-minimize-attributes:nil
|
||||
sgml-general-insert-case:lower
|
||||
sgml-indent-step:0
|
||||
sgml-indent-data:nil
|
||||
End:
|
||||
|
||||
vim:tabstop=2:shiftwidth=2:expandtab
|
||||
-->
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 79 KiB |
@ -0,0 +1,3 @@
|
||||
KDE_LANG = en
|
||||
KDE_DOCS = AUTO
|
||||
|
||||
@ -0,0 +1,135 @@
|
||||
<?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>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 648 B |
Binary file not shown.
|
After Width: | Height: | Size: 817 B |
Binary file not shown.
|
After Width: | Height: | Size: 585 B |
Binary file not shown.
|
After Width: | Height: | Size: 549 B |
@ -0,0 +1,14 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
|
||||
<chapter id="commands">
|
||||
<chapterinfo>
|
||||
<title>Command Reference</title>
|
||||
</chapterinfo>
|
||||
|
||||
<title>Reference</title>
|
||||
|
||||
&widgets;
|
||||
&specials;
|
||||
&dcop-functions;
|
||||
|
||||
</chapter>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 1.3 KiB |
@ -0,0 +1,59 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
|
||||
<chapter id="credits">
|
||||
<chapterinfo>
|
||||
<title>Credits and License</title>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Tamara</firstname>
|
||||
<surname>King</surname>
|
||||
<affiliation><address>
|
||||
<email>tik@acm.org</email>
|
||||
</address></affiliation>
|
||||
</author>
|
||||
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
|
||||
</authorgroup>
|
||||
</chapterinfo>
|
||||
|
||||
<title>Credits and License</title>
|
||||
|
||||
<variablelist>
|
||||
<title>The &kommander; Development Team</title>
|
||||
<varlistentry>
|
||||
<term>Britton, Marc <email>consume@optusnet.com.au</email></term>
|
||||
<listitem><para>Developer and documentation</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>King, Tamara <email>tik@acm.org</email></term>
|
||||
<listitem><para>Documentation</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>Laffoon, Eric <email>sequitur@kde.org</email></term>
|
||||
<listitem><para>Project manager and documentation</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>Mantia, András <email>amantia@kde.org</email></term>
|
||||
<listitem><para>Developer</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>Rudolf, Michal <email>mrudolf@kdewebdev.org</email></term>
|
||||
<listitem><para>Developer</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>
|
||||
&kommander; <trademark class="copyright" /> 2004 - 2008 &kommander; Development Team.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
&kommander; User Manual <trademark class="copyright" /> 2004 - 2008 &kommander; Development Team.
|
||||
</para>
|
||||
|
||||
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
|
||||
|
||||
&underFDL;
|
||||
&underGPL;
|
||||
|
||||
</chapter>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 965 B |
@ -0,0 +1,203 @@
|
||||
<?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>
|
||||
@ -0,0 +1,642 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
|
||||
<sect1 id="editor">
|
||||
<sect1info>
|
||||
<title>The Editor</title>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Tamara</firstname>
|
||||
<surname>King</surname>
|
||||
<affiliation><address>
|
||||
<email>tik@acm.org</email>
|
||||
</address></affiliation>
|
||||
</author>
|
||||
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
|
||||
</authorgroup>
|
||||
</sect1info>
|
||||
|
||||
<title>The Editor</title>
|
||||
|
||||
<para>
|
||||
The editor is based on &designer;, a tool for designing and implementing user interfaces created by <ulink url="http://www.trolltech.com">Trolltech</ulink>. We have modified &designer; in the following ways:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>Its interface is much simpler</para></listitem>
|
||||
<listitem><para>Built in our own widgets</para></listitem>
|
||||
<listitem><para>Added the ability to setup &kommander; Text</para></listitem>
|
||||
<listitem><para>Various other superficial changes</para></listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
For those of you already familiar with using &designer;, using the &kmdr-editor; will be trivial.
|
||||
</para>
|
||||
|
||||
<sect2 id="editor-gui">
|
||||
<title>Main Window</title>
|
||||
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata format="PNG" fileref="editor.png" />
|
||||
</imageobject>
|
||||
</mediaobject>
|
||||
|
||||
<orderedlist>
|
||||
<listitem><para>Toolbars contain a number of buttons to provide quick access to number of functions.</para></listitem>
|
||||
<listitem><para>The File Overview displays all of the files. Use the search field to rapidly switch between files.</para></listitem>
|
||||
<listitem><para>The Object Explorer provides an overview of the relationships between the widgets in a form. It is useful for selecting widgets in a form with a complex layout.</para></listitem>
|
||||
<listitem><para>The Property Editor is where the behavior and appearance of a widget is changed.</para></listitem>
|
||||
<listitem><para>The Dialog Editor is where dialogs are created and edited.</para></listitem>
|
||||
</orderedlist>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>The File Menu</title>
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>File</guimenu>
|
||||
<guimenuitem>New</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Creates a new dialog</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>File</guimenu>
|
||||
<guimenuitem>Open</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Search the file system to open an existing dialog</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>File</guimenu>
|
||||
<guimenuitem>Open Recent</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Quick list of the last several files you've opened. This list will change each time you open a file that is not on it with the oldest being bumped off first.</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>File</guimenu>
|
||||
<guimenuitem>Close</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Closes the active dialog</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>File</guimenu>
|
||||
<guimenuitem>Save</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Saves the active dialog</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>File</guimenu>
|
||||
<guimenuitem>Save As</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Saves the active dialog with another name</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>File</guimenu>
|
||||
<guimenuitem>Save All</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Saves all open dialogs</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>File</guimenu>
|
||||
<guimenuitem>Exit</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Quits</action> &kommander;</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>The Edit Menu</title>
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Edit</guimenu>
|
||||
<guimenuitem>Undo</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Undo the last action performed.</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>Y</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Edit</guimenu>
|
||||
<guimenuitem>Redo</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Redo the last action undone.</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Edit</guimenu>
|
||||
<guimenuitem>Cut</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Cut the current item and place it content on the clipboard.</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Edit</guimenu>
|
||||
<guimenuitem>Copy</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Copy the current item to the clipbard.</action></para></listitem>
|
||||
</varlistentry>
|
||||
<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 contents of the clipboard at the current cursor position.</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Edit</guimenu>
|
||||
<guimenuitem>Delete</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Delete the current item.</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycap>Del</keycap>
|
||||
</shortcut>
|
||||
<guimenu>Edit</guimenu>
|
||||
<guimenuitem>Select All</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Select all of the items in the current dialog.</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Alt;<keycap>R</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Edit</guimenu>
|
||||
<guimenuitem>Check Accelerators</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Verifies that all the accelerators are used only once.</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Edit</guimenu>
|
||||
<guimenuitem>Connectors</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Displays the view and edit connections dialog.</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Edit</guimenu>
|
||||
<guimenuitem>Form Setting</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Displays the form setting dialog.</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Edit</guimenu>
|
||||
<guimenuitem>Preferences</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Displays the preferences dialog.</action></para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>The Tools Menu</title>
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycap>F2</keycap>
|
||||
</shortcut>
|
||||
<guimenu>Tools</guimenu>
|
||||
<guimenuitem>Pointer</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action></action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycap>F3</keycap>
|
||||
</shortcut>
|
||||
<guimenu>Tools</guimenu>
|
||||
<guimenuitem>Connect Signal/Slots</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action></action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycap>F3</keycap>
|
||||
</shortcut>
|
||||
<guimenu>Tools</guimenu>
|
||||
<guimenuitem>Tab Order</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action></action></para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Tools</guimenu>
|
||||
<guisubmenu>&kommander;</guisubmenu>
|
||||
</menuchoice></term>
|
||||
<listitem>
|
||||
<para>Here there are listed all the &kommander; widgets. This widgets are guaranteed to be available on every system running the same (or higher) version of &kommander;.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Tools</guimenu>
|
||||
<guisubmenu>Custom</guisubmenu>
|
||||
</menuchoice></term>
|
||||
<listitem>
|
||||
<para>The widgets provided by the plugins will be listed under this menu entry. The dialogs using these widgets will run only if the plugin that provides them is installed and configured.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>The Layout Menu</title>
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>J</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Layout</guimenu>
|
||||
<guimenuitem>Adjust Size</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action></action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>H</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Layout</guimenu>
|
||||
<guimenuitem>Lay Out Horizontally</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action></action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>L</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Layout</guimenu>
|
||||
<guimenuitem>Lay Out Vertically</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action></action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Layout</guimenu>
|
||||
<guimenuitem>Lay Out in a Grid</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action></action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Layout</guimenu>
|
||||
<guimenuitem>Lay Out Horizontally (in Splitter)</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action></action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Layout</guimenu>
|
||||
<guimenuitem>Lay Out Vertically (in Splitter)</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action></action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Layout</guimenu>
|
||||
<guimenuitem>Break Layout</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action></action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Layout</guimenu>
|
||||
<guimenuitem>Add Spacer</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action></action></para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>The Run Menu</title>
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Run</guimenu>
|
||||
<guimenuitem>Run Dialog</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Runs the current dialog.</action></para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>The Window Menu</title>
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>F4</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Window</guimenu>
|
||||
<guimenuitem>Close</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Closes current dialog.</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guimenuitem>Close All</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Closes all dialogs.</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>F6</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Window</guimenu>
|
||||
<guimenuitem>Next</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action></action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;&Shift;<keycap>F6</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Window</guimenu>
|
||||
<guimenuitem>Previous</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action></action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guimenuitem>Tile</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action></action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guimenuitem>Cascade</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action></action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guisubmenu>Views</guisubmenu>
|
||||
</menuchoice></term>
|
||||
<listitem>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guisubmenu>Views</guisubmenu>
|
||||
<guimenuitem>File Overview</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem><para></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guisubmenu>Views</guisubmenu>
|
||||
<guimenuitem>Object Explorer</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem><para></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guisubmenu>Views</guisubmenu>
|
||||
<guimenuitem>Property Editor/Signal Handlers</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem><para></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guisubmenu>Views</guisubmenu>
|
||||
<guimenuitem>Line Up</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem><para></para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guisubmenu>Toolbars</guisubmenu>
|
||||
</menuchoice></term>
|
||||
<listitem>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guisubmenu>Toolbars</guisubmenu>
|
||||
<guimenuitem>File</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem><para></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guisubmenu>Toolbars</guisubmenu>
|
||||
<guimenuitem>Edit</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem><para></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guisubmenu>Layout</guisubmenu>
|
||||
<guimenuitem>File</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem><para></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guisubmenu>Toolbars</guisubmenu>
|
||||
<guimenuitem>Tools</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem><para></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guisubmenu>Toolbars</guisubmenu>
|
||||
<guimenuitem>&kommander;</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem><para></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guisubmenu>Toolbars</guisubmenu>
|
||||
<guimenuitem>Custom</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem><para></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guisubmenu>Toolbars</guisubmenu>
|
||||
<guimenuitem>Help</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem><para></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<guimenu>Window</guimenu>
|
||||
<guisubmenu>Toolbars</guisubmenu>
|
||||
<guimenuitem>Line Up</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem><para></para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>The Settings Menu</title>
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Settings</guimenu>
|
||||
<guimenuitem>Configure Shortcuts</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>See and modify the editor keyboard shortcuts.</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Settings</guimenu>
|
||||
<guimenuitem>Configure Plugins</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Add or remove &kommander; plugins. The editor needs to be restarted after a new plugin is added.</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Settings</guimenu>
|
||||
<guimenuitem>Configure Editor</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Configure the text editor used for modifying the Kommander text associated with widgets.</action></para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><menuchoice>
|
||||
<guimenu>Settings</guimenu>
|
||||
<guimenuitem>Configure &kommander;</guimenuitem>
|
||||
</menuchoice></term>
|
||||
<listitem><para><action>Configure how the editor looks and works.</action></para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>The <guimenu>Help</guimenu> Menu</title>
|
||||
|
||||
<!-- Assuming you have a standard help menu (help, what's this, about -->
|
||||
<!-- &kommander;, about KDE) then the documentation is already written. -->
|
||||
<!-- The following entity is valid anywhere that a variablelist is -->
|
||||
<!-- valid. -->
|
||||
|
||||
&help.menu.documentation;
|
||||
|
||||
</sect2>
|
||||
|
||||
|
||||
</sect1>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
@ -0,0 +1,440 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
|
||||
<chapter id="extending">
|
||||
<chapterinfo>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Andras</firstname>
|
||||
<surname>Mantia</surname>
|
||||
<affiliation><address><email>amantia@kde.org</email></address></affiliation>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Michal</firstname>
|
||||
<surname>Rudolf</surname>
|
||||
<affiliation><address><email>mrudolf@kdewebdev.org</email></address></affiliation>
|
||||
</author>
|
||||
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
|
||||
</authorgroup>
|
||||
</chapterinfo>
|
||||
<title>Extending &kommander;</title>
|
||||
|
||||
<sect1 id="create-widgets">
|
||||
<title>Creating &kommander; Widgets</title>
|
||||
<para>
|
||||
With &kommander; you can create new widgets based on non-&kommander; widgets
|
||||
fairly easily.
|
||||
</para>
|
||||
<para>There are two ways of adding new widgets to &kommander;: by creating
|
||||
plugins or by adding it directly to the &kommander; source.
|
||||
</para>
|
||||
<sect2 id="create-class">
|
||||
<title>Create the widget class</title>
|
||||
<para>
|
||||
The first step is to create the widget class. The approach is to derive your new &kommander; widget class from the
|
||||
&Qt;/&kde; widget which you wish to integrate with &kommander;, and then also from the
|
||||
KommanderWidget class. Overriding methods from this class gives the &kommander;
|
||||
widget its functionality.
|
||||
</para>
|
||||
<para>
|
||||
Most of the code of a &kommander; widget is just template code.
|
||||
Therefore, you can use the KDevelop &kommander; plugin template to generate
|
||||
most the &kommander; widget code for you. To do so run KDevelop (3.5 is recommended),
|
||||
select <guimenu>Project->New Project</guimenu>, tick the <guilabel>Show all project templates</guilabel> checkbox,
|
||||
select the <guilabel>C++/&kommander;/KommanderPlugin</guilabel> template. Give a name for your plugin and
|
||||
follow the instructions in the wizard.
|
||||
</para>
|
||||
<para>
|
||||
All you have to do is fill in the
|
||||
important parts relating to your widget like any state information, widget text
|
||||
etc.
|
||||
</para>
|
||||
<para>
|
||||
Let's say we want to create a new line edit widget for &kommander;,
|
||||
based on the KDE widget KLineEdit. Using the &kommander; widget generator
|
||||
dialog, we get something like this in the generated header file:
|
||||
</para>
|
||||
<screen>
|
||||
#include <kommanderwidget.h>
|
||||
|
||||
class QShowEvent;
|
||||
class KomLineEdit : public KLineEdit, public KommanderWidget
|
||||
{
|
||||
Q_OBJECT
|
||||
|
||||
Q_PROPERTY(QString populationText READ populationText WRITE setPopulationText DESIGNABLE false)
|
||||
Q_PROPERTY(QStringList associations READ associatedText WRITE setAssociatedText DESIGNABLE false)
|
||||
Q_PROPERTY(bool KommanderWidget READ isKommanderWidget)
|
||||
|
||||
public:
|
||||
KomLineEdit(QWidget *a_parent, const char *a_name);
|
||||
~KomLineEdit();
|
||||
|
||||
virtual QString widgetText() const;
|
||||
|
||||
virtual bool isKommanderWidget() const;
|
||||
virtual void setAssociatedText(const QStringList&);
|
||||
virtual QStringList associatedText() const;
|
||||
virtual QString currentState() const;
|
||||
|
||||
virtual QString populationText() const;
|
||||
virtual void setPopulationText(const QString&);
|
||||
public slots:
|
||||
virtual void setWidgetText(const QString &);
|
||||
virtual void populate();
|
||||
protected:
|
||||
void showEvent( QShowEvent *e );
|
||||
signals:
|
||||
void widgetOpened();
|
||||
void widgetTextChanged(const QString &);
|
||||
};
|
||||
</screen>
|
||||
<para>Most of this is just template code that you don't need to worry about.
|
||||
The only two things you need to take notice of are that the kommanderwidget.h
|
||||
file is included at the top, and that the class is derived first from the
|
||||
widget we wish to integrate with &kommander;, and secondly from KommanderWidget.
|
||||
</para>
|
||||
<para>
|
||||
There are a few parts in the cpp file that are important to each particular widget.
|
||||
</para>
|
||||
<screen>
|
||||
KomLineEdit::KomLineEdit(QWidget *a_parent, const char *a_name)
|
||||
: KLineEdit(a_parent, a_name), KommanderWidget(this)
|
||||
{
|
||||
QStringList states;
|
||||
states << "default";
|
||||
setStates(states);
|
||||
setDisplayStates(states);
|
||||
}
|
||||
</screen>
|
||||
<para>In the constructor, we set the states this widget may have.
|
||||
Our line edit doesn't have any kind of state, so we just
|
||||
give it one state <emphasis>default</emphasis>. If you were creating a widget
|
||||
that had different kinds of states, such as a check box, you might
|
||||
set three states <emphasis>unchecked</emphasis>, <emphasis>semichecked</emphasis> and <emphasis>checked</emphasis> here.
|
||||
</para>
|
||||
<screen>
|
||||
QString KomLineEdit::currentState() const
|
||||
{
|
||||
return QString("default");
|
||||
}</screen>
|
||||
<para>We set the states in the constructor above, and this just
|
||||
returns the current state of the widget. For our widget
|
||||
it will always be <emphasis>default</emphasis>, but you should put code here
|
||||
that checks what state your widget is currently in and
|
||||
return the appropriate string here.
|
||||
</para>
|
||||
<screen>
|
||||
QString KomLineEdit::widgetText() const
|
||||
{
|
||||
return KLineEdit::text();
|
||||
}
|
||||
|
||||
void KomLineEdit::setWidgetText(const QString &a_text)
|
||||
{
|
||||
KLineEdit::setText(a_text);
|
||||
emit widgetTextChanged(a_text);
|
||||
}
|
||||
</screen>
|
||||
<para>These are the two most important methods, where the bulk of the
|
||||
functional code goes.
|
||||
<emphasis>QString KomLineEdit::widgetText() const</emphasis> method returns the widget text of the
|
||||
widget (the text that the <emphasis>@widgetText</emphasis> special is expanded to in text
|
||||
associations). For our widget, the widget text is simply the text inside
|
||||
the line edit, so we just return that. Similarly when setting the widget text,
|
||||
we just set the text inside the line edit. We emit the <emphasis>widgetTextChanged()</emphasis>
|
||||
signal after setting the widget text so other widgets can recognize the fact
|
||||
that this widget was updated.
|
||||
</para>
|
||||
<para>
|
||||
In order to add functionality to the widget, you need to register some function and add code to handle them. Here is the code to be used to register, put it in the beginning of the cpp file, above the constructor:
|
||||
</para>
|
||||
<screen>
|
||||
#include <klocale.h> //for i18n
|
||||
|
||||
#include "kommanderplugin.h"
|
||||
#include "specials.h"
|
||||
|
||||
enum Functions {
|
||||
FirstFunction = 1159,
|
||||
Function1,
|
||||
Function2,
|
||||
LastFunction
|
||||
};
|
||||
KomLineEdit::KomLineEdit(QWidget *a_parent, const char *a_name)
|
||||
: KLineEdit(a_parent, a_name), KommanderWidget(this)
|
||||
{
|
||||
... //code like described above
|
||||
KommanderPlugin::setDefaultGroup(Group::DCOP);
|
||||
KommanderPlugin::registerFunction(Function1, "function1(QString widget, QString arg1, int arg2)", i18n("Call function1 with two arguments, second is optional."), 2, 3);
|
||||
KommanderPlugin::registerFunction(function2, "function2(QString widget)", i18n("Get a QString as a result of function2."), 1);
|
||||
}
|
||||
</screen>
|
||||
<para>This registers two functions: <emphasis>function1 and function2</emphasis>. The number assigned to the functions (here <emphasis>1160</emphasis> and <emphasis>1161</emphasis>) must be unique, not used in any other plugin or
|
||||
inside &kommander;. <emphasis>function1</emphasis> takes two arguments, one is optional, <emphasis>function2</emphasis> takes no argument and returns a string. The <emphasis>QString widget</emphasis> argument in the signatures notes that this functions work on a widget, like: <emphasis>KomLineEdit.function1("foo", 1)</emphasis>.
|
||||
</para>
|
||||
<para>To teach &kommander; that the widget supports these functions, add a method like this:
|
||||
</para>
|
||||
<screen>
|
||||
bool KomLineEdit::isFunctionSupported(int f)
|
||||
{
|
||||
return (f > FirstFunction && f < LastFunction) || f == DCOP::text;
|
||||
}
|
||||
</screen>
|
||||
<para>This means that KomLineEdit supports the above functions and the standard <emphasis>text</emphasis>
|
||||
function.
|
||||
The function code should be handled inside the handleDCOP method:
|
||||
</para>
|
||||
<screen>
|
||||
QString KomLineEdit::handleDCOP(int function, const QStringList& args)
|
||||
{
|
||||
switch (function)
|
||||
{
|
||||
case function1:
|
||||
handleFunction1(arg[0], arg[1].toInt()); //call your function1 handler
|
||||
break;
|
||||
case function2:
|
||||
return handleFunction2(); //call function2
|
||||
break;
|
||||
case DCOP::text:
|
||||
return text(); //call the standard KLineEdit::text() method
|
||||
break;
|
||||
default:
|
||||
return KommanderWidget::handleDCOP(function, args);
|
||||
}
|
||||
return QString::null;
|
||||
}
|
||||
</screen>
|
||||
<para>There are cases when the widget should appear differently in the editor than in
|
||||
the executor, like the case of ScriptObjects, about dialog, etc. The usual solution is to show a QLabel instead of the widget. For this, your widget must
|
||||
derive from QLabel, and use this in the constructor:
|
||||
</para>
|
||||
<screen>
|
||||
if (KommanderWidget::inEditor)
|
||||
{
|
||||
setPixmap(KGlobal::iconLoader()->loadIcon("iconname", KIcon::NoGroup, KIcon::SizeMedium));
|
||||
setFrameStyle(QFrame::Box | QFrame::Plain);
|
||||
setLineWidth(1);
|
||||
setFixedSize(pixmap()->size());
|
||||
}
|
||||
else
|
||||
setHidden(true);
|
||||
</screen>
|
||||
<para>You can create the widget itself (if you need a widget at all, maybe your
|
||||
"widget" provides only functionality to access e.g databases) in one of your
|
||||
functions, like in the <emphasis>execute</emphasis> function. Here is an example from the AboutDialog widget:
|
||||
</para>
|
||||
<screen>
|
||||
QString AboutDialog::handleDCOP(int function, const QStringList& args)
|
||||
{
|
||||
switch (function) {
|
||||
...
|
||||
case DCOP::execute:
|
||||
{
|
||||
if (m_aboutData)
|
||||
{
|
||||
KAboutApplication dialog(m_aboutData, this);
|
||||
dialog.exec();
|
||||
}
|
||||
break;
|
||||
}
|
||||
...
|
||||
}
|
||||
</screen>
|
||||
<para>You now have a complete &kommander; widget. All that's left
|
||||
to do is make it available to the &kommander; system via plugins.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2 id="create-plugin">
|
||||
<title>Create the &kommander; plugin</title>
|
||||
<para>
|
||||
All of the widgets in &kommander; are provided by plugins.
|
||||
The standard widgets are loaded as widget plugins, but the &kommander; editor
|
||||
is also linked against this library because certain mechanisms in the editor
|
||||
are tied specifically to the standard widgets.
|
||||
</para>
|
||||
<para>
|
||||
A plugin in &kommander; is simply a shared library that has the symbol
|
||||
'kommander_plugin'. This symbol is a function returning a pointer
|
||||
to an instance of a KommanderPlugin class.
|
||||
</para>
|
||||
<para>
|
||||
&kommander; makes it easy to create a plugin for you widgets, so you don't
|
||||
need to worry about this low level stuff. The basic idea is to derive
|
||||
a new plugin class for your widgets from the KommanderPlugin base class
|
||||
and implement a few specific details. A template code is generated by the above described KDevelop project template.
|
||||
</para>
|
||||
<para>The following code continues on our example of creating a Kommander line edit
|
||||
widget.
|
||||
</para>
|
||||
<screen>
|
||||
#include <kommanderplugin.h>
|
||||
|
||||
/* WIDGET INCLUDES */
|
||||
#include "komlineedit.h"
|
||||
|
||||
</screen>
|
||||
<para>
|
||||
First thing we do is include kommanderplugin.h. This contains the definition
|
||||
of the KommanderPlugin class. We also include all header files of the widgets
|
||||
this plugin provides - only komlineedit.h in this case.
|
||||
</para>
|
||||
<screen>
|
||||
class MyKomPlugin : public KommanderPlugin
|
||||
{
|
||||
public:
|
||||
MyKomPlugin();
|
||||
virtual QWidget *create( const QString &className, QWidget *parent = 0, const char *name = 0 );
|
||||
};
|
||||
</screen>
|
||||
<para>
|
||||
We then create a KommanderPlugin sub-class called <emphasis>MyKomPlugin</emphasis>.
|
||||
This class simply has a constructor and an overridden create method.
|
||||
</para>
|
||||
<screen>
|
||||
MyKomPlugin::MyKomPlugin()
|
||||
{
|
||||
addWidget( "KomLineEdit", "My Widget Group", i18n("A Kommander line edit widget") new QIconSet(KGlobal::iconLoader()->loadIcon("iconname", KIcon::NoGroup, KIcon::SizeMedium)));
|
||||
//add my other widgets here
|
||||
}
|
||||
</screen>
|
||||
<para>In the constructor of the plugin, we call <emphasis>addWidget()</emphasis> for each widget we wish
|
||||
to provide in this plugin. <emphasis>addWidget()</emphasis> takes 6 arguments but only the first 4
|
||||
are required. In order, the arguments are the widget's class name, group,
|
||||
tool tip, an iconset for the icon used in the editor toolbar, what's this information, and a bool indicating whether the widget
|
||||
is a container for other widgets or not. This information is used
|
||||
by the editor when grouping your widget in menus, providing help information
|
||||
etc.
|
||||
</para>
|
||||
<para>
|
||||
Regarding the icon, the above example loads a medium sized icon called <emphasis>iconname</emphasis> from the standard &kde; icon location.
|
||||
</para>
|
||||
<screen>
|
||||
QWidget *MyKomPlugin::create( const QString &className, QWidget *parent, const char *name )
|
||||
{
|
||||
if( className == "KomLineEdit" )
|
||||
return new KomLineEdit( parent, name );
|
||||
//create my other widgets here
|
||||
return 0;
|
||||
}
|
||||
</screen>
|
||||
<para>
|
||||
<emphasis>create()</emphasis> is where instances of our widgets actually get created.
|
||||
Whenever &kommander; wants an instance of one of the classes provided
|
||||
by our plugin, it will call <emphasis>create()</emphasis> with the name of the class it wants,
|
||||
and the parent and name that should be used.
|
||||
If the <emphasis>className</emphasis> matches any widget we know about, we return a new instance
|
||||
of that class but otherwise we return 0.
|
||||
</para>
|
||||
<para>
|
||||
Finally, we export our plugin. This just provides an entry point to our
|
||||
plugin so the &kommander; system can get access to it. Without this,
|
||||
&kommander; will not recognize your library as a &kommander; plugin.
|
||||
</para>
|
||||
<screen>
|
||||
KOMMANDER_EXPORT_PLUGIN(MyKomPlugin)
|
||||
</screen>
|
||||
<para>
|
||||
To compile your new &kommander; extension, you should compile all files
|
||||
as a shared library, linking against the kommanderplugin, kommanderwidget
|
||||
and any appropriate KDE libraries.
|
||||
With the line edit example, if we had komlineedit.h, komlineedit.cpp and
|
||||
mykomplugin.cpp, compiling and installing your plugin would involve
|
||||
something similar to the following commands:
|
||||
</para>
|
||||
<screen>
|
||||
libtool --mode=compile g++ -$KDEDIR/include -IQTDIR/include \
|
||||
-I. -fPIC -c komlineedit.cpp
|
||||
libtool --mode=compile g++ -$KDEDIR/include -IQTDIR/include \
|
||||
-I. -fPIC -c mykomplugin.cpp
|
||||
|
||||
libtool --mode=link g++ -shared -L$KDEDIR/lib -lkdeui -lkommanderwidget \
|
||||
-lkommanderplugin komlineedit.cppkomlineedit.o mykomplugin.o
|
||||
-o libmykomplugin.so
|
||||
</screen>
|
||||
<para>
|
||||
If you want to install new plugin system-wide, root, use:
|
||||
</para>
|
||||
<screen>
|
||||
su -c "cp libmykomplugin.so $KDEDIR/lib"
|
||||
</screen>
|
||||
<note><para>If you use the KDevelop project generator, you will not need to do the above, but instead adapt the Makefile.am to link against extra libraries. By default, it will link to &Qt; and &kde; libraries and generate all the needed object files. Just run <command>make</command> to build, and <command>su -c make install</command> to install.</para></note>
|
||||
</sect2>
|
||||
<sect2 id="config-plugin">
|
||||
<title>Configure the installed plugins</title>
|
||||
<para>
|
||||
Now that the plugin is installed, run the <command>kmdr-plugins</command> program or choose <guimenu>Settings->Configure Plugins</guimenu> from the Editor. The list in this program displays the
|
||||
plugins that are currently loaded by &kommander;. Add the new plugin to the
|
||||
list by clicking the <guilabel>Add</guilabel> button in the toolbar and choosing your plugin.
|
||||
Closing the program saves changes.
|
||||
</para>
|
||||
<para>
|
||||
If you now restart the &kommander; editor, the widgets your new plugin
|
||||
provides should be available in the menus and toolbars. You can
|
||||
now use your new widgets in &kommander; dialogs.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="add-widget">
|
||||
<title>Add the widget directly to &kommander;</title>
|
||||
<para>This section is for &kommander; developers and describes how to add a new widget directly to &kommander;.</para>
|
||||
<para>
|
||||
Ironically, this one is more complicated, especially if the widget needs
|
||||
extra editing methods.
|
||||
First you create the widget like above. After that you need to register the
|
||||
widget to the editor and the executor.
|
||||
To register it inside the editor, add it to <emphasis>editor/widgetdatabase.cpp</emphasis>:
|
||||
</para>
|
||||
<screen>
|
||||
...
|
||||
#include "mywidget.h"
|
||||
...
|
||||
void WidgetDatabase::setupDataBase( int id )
|
||||
{
|
||||
...
|
||||
r = new WidgetDatabaseRecord;
|
||||
r->name = "MyWidgetName";
|
||||
r->iconName = "icon.png";
|
||||
r->group = widgetGroup( "Kommander" );
|
||||
r->toolTip = i18n("My new widget");
|
||||
append(r);
|
||||
...
|
||||
}
|
||||
</screen>
|
||||
<para>
|
||||
You need to add to the <emphasis>editor/widgetfactory.cpp</emphasis> as well:
|
||||
</para>
|
||||
<screen>
|
||||
...
|
||||
#include "mywidget.h"
|
||||
...
|
||||
QWidget *WidgetFactory::createWidget( const QString &className, QWidget *parent, const char *name, bool init,
|
||||
const QRect *r, Qt::Orientation orient )
|
||||
{
|
||||
...
|
||||
else if (className == "MyWidgetName")
|
||||
return new MyWidget(parent, name);
|
||||
...
|
||||
}
|
||||
</screen>
|
||||
<para>
|
||||
To register to the executor (actually to the plugin system), add this to
|
||||
<emphasis>widgets/plugin.cpp</emphasis>:
|
||||
</para>
|
||||
<screen>
|
||||
KomStdPlugin::KomStdPlugin()
|
||||
{
|
||||
...
|
||||
addWidget("MyWidgetName", group, "", new QIconSet(KGlobal::iconLoader()->loadIcon("iconname", KIcon::NoGroup, KIcon::SizeMedium)));
|
||||
...
|
||||
}
|
||||
</screen>
|
||||
<para>This is similar to how the widget is registered via the plugin system in the
|
||||
first case.
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
</chapter>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 521 B |
@ -0,0 +1,39 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
|
||||
<glossary id="glossary">
|
||||
|
||||
<glossaryinfo>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Tamara</firstname>
|
||||
<surname>King</surname>
|
||||
<affiliation><address>
|
||||
<email>tik@acm.org</email>
|
||||
</address></affiliation>
|
||||
</author>
|
||||
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
|
||||
</authorgroup>
|
||||
</glossaryinfo>
|
||||
|
||||
<glossdiv>
|
||||
<title>Keywords</title>
|
||||
<glossentry id="text-association-glosref">
|
||||
<glossterm>Text Association</glossterm>
|
||||
<glossdef>
|
||||
<para>
|
||||
A piece of text that is associated or bound to a widget's particular state.
|
||||
</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
<glossentry id="widget-text-glosref">
|
||||
<glossterm>Widget Text</glossterm>
|
||||
<glossdef>
|
||||
<para>
|
||||
Text associated to a widget. This is represented in &kommander; with the special @widgetText. The widget text varies depending on the widget.
|
||||
</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
</glossdiv>
|
||||
</glossary>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 439 B |
@ -0,0 +1,121 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
|
||||
<!ENTITY kommander "<application>Kommander</application>">
|
||||
<!ENTITY kappname "&kommander;">
|
||||
<!ENTITY package "kdewebdev">
|
||||
<!ENTITY basics SYSTEM "basics.docbook">
|
||||
<!ENTITY commands SYSTEM "commands.docbook">
|
||||
<!ENTITY parser SYSTEM "parser.docbook">
|
||||
<!ENTITY credits SYSTEM "credits.docbook">
|
||||
<!ENTITY dcop-functions SYSTEM "dcop.docbook">
|
||||
<!ENTITY editor SYSTEM "editor.docbook">
|
||||
<!ENTITY extending SYSTEM "extending.docbook">
|
||||
<!ENTITY translating SYSTEM "translating.docbook">
|
||||
<!ENTITY glossary SYSTEM "glossary.docbook">
|
||||
<!ENTITY installation SYSTEM "installation.docbook">
|
||||
<!ENTITY introduction SYSTEM "introduction.docbook">
|
||||
<!ENTITY q-and-a SYSTEM "q-and-a.docbook">
|
||||
<!ENTITY specials SYSTEM "specials.docbook">
|
||||
<!ENTITY tutorials SYSTEM "tutorials.docbook">
|
||||
<!ENTITY widgets SYSTEM "widgets.docbook">
|
||||
<!ENTITY designer "<application>&Qt; Designer</application>">
|
||||
<!ENTITY kmdr-editor "&kommander; Editor">
|
||||
<!ENTITY kmdr-executor "&kommander; Executor">
|
||||
<!ENTITY GIMP "<application>The GIMP</application>">
|
||||
<!ENTITY IDE "<acronym>IDE</acronym>">
|
||||
<!ENTITY PHP "<acronym>PHP</acronym>">
|
||||
<!ENTITY PID "<acronym>PID</acronym>">
|
||||
<!ENTITY % addindex "IGNORE">
|
||||
<!ENTITY % English "INCLUDE">
|
||||
]>
|
||||
|
||||
<book lang="&language;">
|
||||
|
||||
<bookinfo>
|
||||
<title>The &kommander; Handbook</title>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Marc</firstname>
|
||||
<surname>Britton</surname>
|
||||
<affiliation>
|
||||
<address><email>consume@optushome.com.au</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<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>eric@kdewebdev.org</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>András</firstname>
|
||||
<surname>Manţia</surname>
|
||||
<affiliation>
|
||||
<address><email>amantia@kde.org</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
|
||||
</authorgroup>
|
||||
|
||||
<copyright>
|
||||
<year>2008</year>
|
||||
<holder>&kommander; Development Team</holder>
|
||||
</copyright>
|
||||
|
||||
<legalnotice>&FDLNotice;</legalnotice>
|
||||
|
||||
<!-- Date and version information of the documentation
|
||||
Don't forget to include this last date and this last revision number, we
|
||||
need them for translation coordination !
|
||||
Please respect the format of the date (YYYY-MM-DD) and of the version
|
||||
(V.MM.LL), it could be used by automation scripts.
|
||||
Do NOT change these in the translation. -->
|
||||
|
||||
<date>2008-02-12</date>
|
||||
<releaseinfo>3.2.95</releaseinfo>
|
||||
|
||||
<!-- Abstract about this handbook -->
|
||||
|
||||
<abstract>
|
||||
<para>These docs have been partially complete for years, but not always available or easy to find. Since around 2002 little spurts of effort on &kommander; have produced dramtic results. &kommander; is a new approach to development and there have been modifications in approach and features. Consequently much of this documentation is out of date, however still useful due to legacy support. Please refer to our web site at <ulink url="http://kommander.kdewebdev.org">http://kommander.kdewebdev.org</ulink> for up to date information, news on KDE4 development, new tools, plugins, tips and tutorials.</para>
|
||||
<para>
|
||||
&kommander; is a set of tools that allow you to create dynamic &GUI; windows that has been used as a front end for command line programs, database front ends, simple program extentions and much more. The best part of it all? You aren't required to write a single line of code! Okay, that was old text... You can actually use the function browser and even with the new parser write almost none of the code. The inherent difference between &kommander; and other &GUI; scripting tools is that &kommander; doesn't care about how the window gets drawn. &kommander; was designed from the GUI down to the language elements and can embrace multiple languages. &kommander; does not use scripting to draw a window on the screen like other &GUI; scripting tools. As Kommander matures it will expose all it's internals to any scripting language people want to enable. We welcome anyone wishing to enhance support for any scripting language.
|
||||
</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>Kommander</keyword>
|
||||
<keyword>Quanta</keyword>
|
||||
</keywordset>
|
||||
|
||||
</bookinfo>
|
||||
|
||||
&introduction;
|
||||
&basics;
|
||||
&commands;
|
||||
&parser;
|
||||
&extending;
|
||||
&translating;
|
||||
&tutorials;
|
||||
&q-and-a;
|
||||
&credits;
|
||||
&installation;
|
||||
&glossary;
|
||||
|
||||
</book>
|
||||
@ -0,0 +1,50 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
|
||||
<appendix id="installation">
|
||||
<title>Installation</title>
|
||||
|
||||
<sect1 id="getting-kapp">
|
||||
<title>How to obtain &kommander;</title>
|
||||
|
||||
<!-- This first entity contains boiler plate for applications that are
|
||||
part of KDE CVS. You should remove it if you are releasing your
|
||||
application -->
|
||||
|
||||
&install.intro.documentation;
|
||||
|
||||
<para>There is a dedicated homepage for &kommander; at <ulink url="http://kommander.kdewebdev.org">http://kommander.kdewebdev.org</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>
|
||||
&kommander; requires the latest version of &kde; 3.x series, currently 3.5.9. It might work with previous 3.5.x versions, but this was not tested throughfully.
|
||||
<!-- For a list of updates, you may refer to the application web site
|
||||
or the ChangeLog file, or ... -->
|
||||
</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>
|
||||
|
||||
</appendix>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 171 KiB |
@ -0,0 +1,134 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
|
||||
<chapter id="introduction">
|
||||
<chapterinfo>
|
||||
<title>Introduction</title>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Eric</firstname>
|
||||
<surname>Laffoon</surname>
|
||||
<affiliation>
|
||||
<address><email>sequitur@kde.org</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
|
||||
</authorgroup>
|
||||
</chapterinfo>
|
||||
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>
|
||||
&kommander; is a visual dialog building tool which can be used to create
|
||||
full mainwindow applications, provided the window is initially created in Qt Designer
|
||||
or from a template in &kommander;. The primary objective is to create as much
|
||||
functionality as possible with the absolute minimum use of scripting. This is
|
||||
provided by the following features:
|
||||
</para>
|
||||
<note><para>Please note this document includes legacy documentation for compatibility reasons. In a nutshell &kommander; offers extremely rapid development and extensive abilities and capabilities. Following is a new list, followed by the legacy content.</para></note>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><emphasis>Capable internal scripting</emphasis> - &kommander; now offers nested logic structures, simple arrays and useful functions </para>
|
||||
</listitem>
|
||||
<listitem><para>
|
||||
<emphasis>Function Browsers</emphasis> - One never need know exact syntax for any function or command, just click the button and point and click your way to a functional program. Even the project lead finds it easier than typos much of the time.</para>
|
||||
</listitem>
|
||||
<listitem><para>
|
||||
<emphasis>Extensive widgets</emphasis> - &kommander; now has a tree/detail widget, spreadsheet like table widget, font dialog, color dialog, about dialog, timer, tab widgets, toolbox, popup menus, date picker and a lot more. </para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><emphasis>Plugins</emphasis> - &kommander; can run easy to create plugins. Plugins as of this writing are a database plugin offering a set of non visual tools, an HTTP plugin offering HTTPS and access to password protected areas and a KPart loader.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><emphasis>Scripting language support</emphasis> - The ability to run multiple scripting language in &kommander; scripts, inside your dialog
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><emphasis>KPart creation</emphasis> - the ability to make your own plugins... and stranger yet you can even make a &kommander; window load a dialog as a KPart and directly access it with &kommander; functions!
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
<para>Look for documentation on tips and tricks like how to make &kommander; fake programming techniques like including a file, creating and using custom widgets, making collapsable panels in windows and other unexpected tricks. Below is our legacy list.</para>
|
||||
<itemizedlist>
|
||||
|
||||
|
||||
<listitem><para>Specials are prefaced with an <quote>@</quote> like @widgetText. The offer
|
||||
special features like the value of a widget, functions, aliases, global
|
||||
variables and such.</para></listitem>
|
||||
|
||||
|
||||
<listitem><para>&DCOP; integration allows &kommander; dialogs to control and be
|
||||
controlled in interactions with other &kde; applications. It is a very powerful
|
||||
feature!</para></listitem>
|
||||
|
||||
<listitem><para>Signals and Slots is a little less intuitive to a new user. It is
|
||||
under review for how we process things in the first major release. These
|
||||
offer a limited event model for when a button is pushed or a widget is
|
||||
changed. Combined with <quote>Population Text</quote> it is rather powerful.</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>
|
||||
The central key feature of &kommander; dialogs is that you can bind text
|
||||
(&kommander; Text) to a widget. So if you have @widget1 and @widget2 and
|
||||
they are line edits you can set &kommander; to show their contents by
|
||||
entering @widgetText in their &kommander; Text area. Then enter hello in
|
||||
@widget1 and world in @widget2. A button can have the string
|
||||
My first @widget1 @widget2 program in &kommander;
|
||||
If you run this dialog from a console it will output
|
||||
My first hello world program in &kommander;
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Hopefully you begin to see a small glimmering of the potential. &kommander;
|
||||
enables a much faster design model for simple applications because if allows
|
||||
you to stop thinking so much about language and revert to the more basic and
|
||||
natural conceptual model. In computers language is a means to define concepts
|
||||
and as such it is a layer between concept and implementation that can impede
|
||||
progress with minutia. &kommander; seeks to minimize that layer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
&kommander; also seeks to build on standards. It is built on the &Qt; Designer
|
||||
framework and creates *.ui files which it renames to *.kmdr. It can easily
|
||||
import any &kde; widget and this can be done without having to rebuild
|
||||
&kommander;, by using plugins.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
&kommander;'s other significant factor is how it addresses the requirements of
|
||||
language. Computer languages can be wonderful things but they tend to have
|
||||
their own dogmas and zealots often seeking to provide an advance to &GUI;
|
||||
design in an integrated development environment. Ironically the acceptance
|
||||
of such &IDE;s is limited by the number of people willing to adopt a new new
|
||||
language to gain access to a desired feature. It is really not reasonable to
|
||||
expect people to need to change over to a dozen languages to access various
|
||||
feature sets. By being language neutral and allowing a &kommander; dialog to be
|
||||
extended by using any scripting language &kommander; positions itself in a
|
||||
unique position for wide spread adoption. Multiple script languages can be
|
||||
used in a single dialog and applications can be taken over by people using
|
||||
a different language than the original developer and gradually converting
|
||||
and extending it. New widgets and features can be instantly leveraged by all
|
||||
available languages.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
We hope that &kommander; begins to get the developer support and recognition
|
||||
required to achieve the potential it offers. Our end goal is to make &kommander;
|
||||
useful for novice users to extend and merge their applications. At the same
|
||||
time it should become a good prototyping tool. Also it opens the door to the
|
||||
promise of open source in a new way. We know that people can extend our GPL'd
|
||||
programs, but the fact remains very few have the skills. With &kommander; those
|
||||
numbers see a huge multiplier! Some applications may be most logical as a
|
||||
&kommander; application. We already use it in areas we want to allow
|
||||
extensibility in &quantaplus;.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
We hope you enjoy &kommander;. Please help us with bug reports and example
|
||||
dialogs, as well as any requests you may have. You can join our <ulink url="http://mail.kdewebdev.org/mailman/listinfo/kommander">user list</ulink>
|
||||
for help developing &kommander; applications.
|
||||
</para>
|
||||
|
||||
<para>Best Regards from the &kommander; development team!</para>
|
||||
|
||||
</chapter>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 1.2 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.4 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.1 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 953 B |
Binary file not shown.
|
After Width: | Height: | Size: 461 B |
Binary file not shown.
|
After Width: | Height: | Size: 386 B |
Binary file not shown.
|
After Width: | Height: | Size: 759 B |
Binary file not shown.
|
After Width: | Height: | Size: 1.0 KiB |
@ -0,0 +1,751 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
|
||||
<chapter id="new_parserdocs">
|
||||
<chapterinfo>
|
||||
<title>&kommander; New Parser</title>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Michal</firstname>
|
||||
<othername></othername>
|
||||
<surname>Rudolf</surname>
|
||||
<affiliation>
|
||||
<address><email>mrudolf@kdewebdev.org</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Eric</firstname>
|
||||
<othername></othername>
|
||||
<surname>Laffoon</surname>
|
||||
<affiliation>
|
||||
<address><email>eric@kdewebdev.org</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
</authorgroup>
|
||||
<copyright>
|
||||
<year>2005-2008</year>
|
||||
<holder>Michal Rudolf</holder>
|
||||
<holder>Eric Laffoon</holder>
|
||||
</copyright>
|
||||
<legalnotice>&FDLNotice;</legalnotice>
|
||||
</chapterinfo>
|
||||
|
||||
<title>New Parser Documentation</title>
|
||||
<para>
|
||||
The new parser was introduced in &kommander; with version 1.2, released with
|
||||
KDE 3.4. This document was originally released to show all the features of new parser.
|
||||
As of &kommander; 1.3, released with KDE 3.5.9, the new parser is now the default, except for MainWindow applications created in &Qt; Designer. Because
|
||||
the new parser is so much richer in ability, overcomes the limitations of nesting in the
|
||||
old parser and adds so many new features we strongly recommend using it.
|
||||
</para>
|
||||
<para>
|
||||
&kommander; itself will not be described here. Please refer to other documents to
|
||||
see what is &kommander; for, how to create dialogs and how to manipulate widgets
|
||||
on runtime.
|
||||
</para>
|
||||
<!--
|
||||
</chapter>
|
||||
|
||||
|
||||
|
||||
<chapter id="two_parsers">
|
||||
<title>New parser vs. old parser</title>
|
||||
-->
|
||||
<sect1 id="two_parsers">
|
||||
<title>Old parser</title>
|
||||
<para>
|
||||
Here we compare the two parsers. While we advocate the new one for most purposes the old one is still
|
||||
supported and useful, particularly when working with other scripting languages.
|
||||
</para>
|
||||
|
||||
<sect2 id="old_parser">
|
||||
<title>Old parser</title>
|
||||
<para>
|
||||
The old parser was in fact macro parser. Only strings beginning with @ were
|
||||
recognized, locally parsed and expanded.
|
||||
<screen>
|
||||
@LineEdit1.setText(@ListBox.selection)
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All the underlying functionality (local variables, expressions, file manipulation)
|
||||
had to be done in another scripting language, such as Bash. While the intent with &kommander; is to support
|
||||
all other scripting languages, and this is presently possible to some degree, there
|
||||
was a need for a fast, native scripting language that was assured to be portable.
|
||||
The biggest problem with the old parser is that the &kommander; specials are evaluated <emphasis>before</emphasis> the code is passed to the scripting language, making them impossible to use in loops and conditions.</para>
|
||||
<para>
|
||||
The developers considered bash slow and not friendly to new users, and the old parser
|
||||
had been initially bash calling DCOP. The paradox for &kommander; being language neutral
|
||||
resulted in a need to do more than just functions natively.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="new_parser">
|
||||
<title>New parser</title>
|
||||
<para>
|
||||
The new parser is a full parser. It parses the whole script, not just functions. As we were interested
|
||||
in GUI interaction, not the proliferation of scripting languages, we made compromises.
|
||||
As a result you should find &kommander;'s scripting to be capable for most basic tasks
|
||||
and natural and easy to use. There is also the <emphasis>Function Browser</emphasis>, which will help you
|
||||
assemble statements. The Function Browser is intended to make &kommander; accessible to complete novice
|
||||
programmers. It is similar to what you would find in KSpread to help you choose a function
|
||||
and fill in the parameters.
|
||||
<tip><para>If you want enhanced functionality found in other languages you can include
|
||||
them in &kommander; script objects headed with a shebang. While in these scripts the Function
|
||||
Browser will help you insert references to widgets. Just remember when using this functionality
|
||||
that the parser makes one pass for the old parser functions and one pass for your script. So if you
|
||||
try to change something in a widget and read it in the middle of a script you may not get what you expect.</para></tip>
|
||||
<screen>
|
||||
#!/usr/bin/php
|
||||
</screen>
|
||||
</para>
|
||||
<para>The following feature list is from version 1.2</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>local and global variables and associative arrays</para></listitem>
|
||||
<listitem><para>numerical expressions</para></listitem>
|
||||
<listitem><para>string manipulation</para></listitem>
|
||||
<listitem><para>various structure commands: if, while, for, foreach</para></listitem>
|
||||
<listitem><para>most functions from old parser</para></listitem>
|
||||
<listitem><para>direct widget manipulation</para></listitem>
|
||||
<listitem><para>many additional functions</para></listitem>
|
||||
<listitem><para>decent execution speed</para></listitem>
|
||||
<listitem><para>receive parameters from signals in script slots</para></listitem>
|
||||
</itemizedlist>
|
||||
<para>This list is from version 1.3</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>pass parameters and receive them with script execute calls</para></listitem>
|
||||
<listitem><para>return a value from a script</para></listitem>
|
||||
<listitem><para>create widgets on the fly</para></listitem>
|
||||
<listitem><para>connect signals and slots on the fly</para></listitem>
|
||||
<listitem><para>use a variable alias for a widget name</para></listitem>
|
||||
<listitem><para>simple indexed array functions</para></listitem>
|
||||
<listitem><para>directly access a widgets slots</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="invoking">
|
||||
<title>Invoking new parser</title>
|
||||
<para>
|
||||
To enable new parser, set <command>useInternalParser</command> property of the dialog to
|
||||
<command>true</command>. You can also enable new parser in a single script by putting
|
||||
<screen>
|
||||
#!kommander
|
||||
</screen>
|
||||
on the first line of the script. Also note if you are using another scripting language in
|
||||
a script with a shebang that &kommander; automatically enables the old parser for interacting
|
||||
with the dialog.
|
||||
<screen>
|
||||
#!/bin/bash
|
||||
echo @Self.item(0)
|
||||
# returns first parameter passed to script
|
||||
# echo $returnvalue passes back to calling script
|
||||
</screen>
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<!--
|
||||
</chapter>
|
||||
<chapter id="features">
|
||||
-->
|
||||
<sect1 id="features">
|
||||
<title>New Parser Features</title>
|
||||
|
||||
<sect2 id="types">
|
||||
<title>Types</title>
|
||||
<para>
|
||||
Each value is of one of three types: string, integer or double. Type conversion is
|
||||
automatic and chooses most appropriate type (for example, if you add double to integer,
|
||||
result will be double). If one of the values is string, result will be string too.
|
||||
</para>
|
||||
<para>Places you can get into trouble here are getting a numerical value from a widget
|
||||
and trying to perform a mathematical function on it. Since &kommander; uses <command>+</command>
|
||||
to concatonate two strings of text it can treat <command>LineEdit1.text + 2</command> as
|
||||
<command>22</command> instead of <command>2</command>. See the conversion functions in
|
||||
<link linkend="string_functions">String functions</link> to avoid problems.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="expressions">
|
||||
<title>Expressions</title>
|
||||
<para>
|
||||
The following mathematical operators are supported: <command>+, -, *, mod, </command>. Standard brackets
|
||||
are of course supported as well.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All kinds of comparisons are supported: <command><</command>, <command>></command>, <command><=</command>,
|
||||
<command>>=</command>, <command>==</command>, <command>!=</command>. Instead of
|
||||
<command>!=</command> you can also use <command><></command>.
|
||||
Also, logical operators <command>and</command>, <command>or</command>, <command>not</command>
|
||||
are supported, as well as their C equivalents (<command>&&</command>, <command>||</command>, <command>!</command>).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For strings you can use <command>+</command> operator for string concatenation.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Some examples of valid expressions:
|
||||
<screen>
|
||||
2+3
|
||||
-5 * (2 - 13 mod 3)
|
||||
"This list has " + 12 + "items."
|
||||
</screen>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="variables">
|
||||
<title>Variables</title>
|
||||
<para>
|
||||
Variables don't need to be declared. Once you use variable, it is considered declared.
|
||||
<link linkend="types">Type</link> of a variable is recognized automatically and can be changed later.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Associative arrays are supported as well. They map string keys onto values of any type. To declare
|
||||
such array, you can just add some element to it, for example: <command>A["Quanta"] = "Web editor"</command>.
|
||||
Arrays are also handled by <link linkend="foreach">foreach </link> command and
|
||||
<link linkend="array_functions">array functions</link>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Local and global variables are supported. Global variables are marked by leading underscore.
|
||||
So, <command>myVar</command> is a local variable, but <command>_myVar</command> is global. The same applies
|
||||
to arrays.
|
||||
</para>
|
||||
|
||||
<screen>
|
||||
a = 5
|
||||
b = 2 * 5 - (a + 1)
|
||||
c = "[Item " + b + "]"
|
||||
d["MyKey"] = "MyValue"
|
||||
d["MyKey2"] = 5
|
||||
</screen>
|
||||
|
||||
<para>
|
||||
Using variables for widgets works much as you would expect. This is useful when looping widgets into a table.
|
||||
</para>
|
||||
|
||||
<screen>
|
||||
for i=0 to 10 do
|
||||
mycombo = "ComboTable"+i
|
||||
createWidget(mycombo, "ComboBox", "Form1")
|
||||
end
|
||||
</screen>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="comments">
|
||||
<title>Comments</title>
|
||||
<para>
|
||||
You can use comments in &kommander; using the two traditional program language comment forms for line comments. For those users who are new to programming wondering <quote>what traditional form?</quote> see below. You can copy and paste the text below into a button or dialog initialization and see how comments behave in action.
|
||||
</para>
|
||||
<screen>
|
||||
// this is a comment for one line
|
||||
message_info("Hello World") //traditional first program
|
||||
// the above comment also ignored - the messagebox is not
|
||||
# this is also a comment
|
||||
message_info("This message will show")
|
||||
</screen>
|
||||
<para>
|
||||
Using the following multi-line comment will <emphasis>not</emphasis> work and will cause the rest of the widget execution to fail.
|
||||
</para>
|
||||
<screen>
|
||||
/*
|
||||
Hi, I was supposed to be a comment
|
||||
None of the script after this will execute
|
||||
DON'T USE THIS TYPE OF COMMENT IN KOMMANDER!
|
||||
*/
|
||||
</screen>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="globals">
|
||||
<title>Built in Globals</title>
|
||||
<para>
|
||||
&kommander; has some built in globals you may find handy.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><command>_ARGS</command> - the argument string passed to the dialog on opening
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>_ARGCOUNT</command> - the count of arguments passed. These can be retrieved as <command>ARG1</command> to <command>ARGn</command> where n is the total number of args passed
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>_KDDIR</command> - the directory from which the dialog was run. &kommander; will default to your home directory, or a directory change if asked for it's current directory. This is useful for saving and reading files with the &kommander; file.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>_NAME</command> - there is no reason to use this so don't
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>_PID</command> - the process id the current dialog is being run from - also available as just <emphasis>pid</emphasis> Avoid using this name for your variables!
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>_VERSION</command> - this is handy if you want to display the version of &kommander; that is running
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect2>
|
||||
<sect2 id="passargs">
|
||||
<title>Passing arguments in &kommander;</title>
|
||||
<para>You can pass arguments via script parameters, signals and slots, command line parameters and DCOP. Let's look at scripts. Call your script like:
|
||||
<screen>result = ScriptObject1.execute("Hello World")
|
||||
debug(result)</screen>
|
||||
Inside your script you might have the following
|
||||
<screen>var = str_upper(Self.Item(0))
|
||||
return(var)</screen>
|
||||
Now you will get a return in your <emphasis>Stderr</emphasis> message log of <emphasis>HELLO WORLD</emphasis>
|
||||
</para>
|
||||
<para>Receiving a signal connected to a script slot works the same way. <emphasis>Self.Item(0)</emphasis> is parameter one and so on. You can retrieve the count of arguments passed with <emphasis>ScriptObject.count</emphasis>.
|
||||
</para>
|
||||
<para>Command line parameters allow for named or unnamed arguments. Unnamed look like
|
||||
<screen>kmdr-executor myprog.kmdr 100 red</screen>
|
||||
Where you will find _ARG1 = 100 and _ARG2 = red. One quirk is passing strings with spaces as an argument means they need to be quoted. Using the dialog command complicates matters as the entire argument string must pass as one string, meaning in quotes.
|
||||
<screen>dialog("mydialog.kmdr", 100+" \"Hello World\"")</screen>
|
||||
This returns <emphasis>_ARG1 = 100</emphasis> and <emphasis>_ARG2 = Hello World</emphasis>. Without the escaped quotes you would have <emphasis>_ARG2 = Hello</emphasis> and <emphasis>_ARG3 = World</emphasis>. Using Named Parameters is rather nice and potentially less confusing.
|
||||
<screen>dialog("mydialog.kmdr", "xcount=100 xquote=Hello world")</screen>
|
||||
And now you access those with <emphasis>_xcount</emphasis> and <emphasis>_xquote</emphasis> global variables.
|
||||
</para>
|
||||
<para>
|
||||
DCOP can be complex, which is why we recommend using the tools we develop to enable creating DCOP for remote &kommander; dialogs with something like a function browser. Here is an example DCOP call issued from a dialog opened from a parent &kommander; window. Since it knows who its parent is it can send information back while it is open and freely access all its parent's functionality with the exception of slots. Of course that can be done internally with a script which can be called externally, so in practice there is no limit to what can be done.
|
||||
<screen>dcop("kmdr-executor-"+parentPid, "KommanderIf", "setText(QString,QString)", "StatusBar8", "Hello")</screen>
|
||||
Let's look at this piece by piece. First of all we add <emphasis>parentPid</emphasis> to "kmdr-executor-" as we make no assumption a &kommander; window was the caller. You could use this with Quanta or KSpread or whatever. Next we are addressing <emphasis>KommanderIf</emphasis>, which is a <emphasis>nice</emphasis> interface for end users which has been cleaned up. We hope eventually as KDE moves from DCOP to DBUS on KDE4 that more applications adopt a nice interface for integration. The next parameter, <emphasis>"setText(QString,QString)"</emphasis> is important because it <emphasis>prototypes</emphasis> the parameters allowed. Otherwise &kommander; could not validate the call. So without a definition of the DCOP call being used you will get an error. The remaining parameters are of course what is being passed. We recommend you look at applications with <command>kdcop</command> to see how this works and practice dcop calls from the shell to get your syntax right.
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<!--
|
||||
</chapter>
|
||||
-->
|
||||
<sect1 id="parser_commands">
|
||||
|
||||
<title>Commands</title>
|
||||
<para>
|
||||
Various structure commands are supported. They can be freely nested.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
There are also three special commands: <command>exit</command>, <command>break</command> and <command>continue</command>.
|
||||
The first one ends script execution and returns. The second exits current block (<link linkend="while">while</link>,
|
||||
<link linkend="for">for</link> or <link linkend="foreach">foreach</link> and the third exits just a current step, restarting
|
||||
from the beginning of the loop.
|
||||
</para>
|
||||
|
||||
|
||||
<sect2 id="if">
|
||||
<title>if</title>
|
||||
<para>
|
||||
Command <command>if</command> has following syntax:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<command>if</command> <emphasis>condition</emphasis> <command>then</command>
|
||||
<emphasis>code</emphasis> <command>elseif</command> <emphasis>condition</emphasis>
|
||||
<command>then</command> <emphasis>code</emphasis> <command>else</command>
|
||||
<emphasis>code</emphasis> <command>endif</command>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Both <command>elseif</command> and <command>else</command> parts are optional. <emphasis>Condition</emphasis>
|
||||
is any expression. <emphasis>Code</emphasis> is executed if condition is true. That means:
|
||||
<itemizedlist>
|
||||
<listitem><para>non-zero for integers and double</para></listitem>
|
||||
<listitem><para>non-empty for strings</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<screen>
|
||||
if a * 2 > 7 then
|
||||
b = 1
|
||||
elseif a < 0 then
|
||||
b = 2
|
||||
elseif
|
||||
b = 0
|
||||
endif
|
||||
</screen>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="while">
|
||||
<title>while</title>
|
||||
<para>
|
||||
<command>while</command> <emphasis>condition</emphasis> <command>do</command>
|
||||
<emphasis>code</emphasis> <command>end</command>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<emphasis>Condition</emphasis> is recalculated each time loop is executed.
|
||||
<screen>
|
||||
while i < 15 do
|
||||
i = i + a
|
||||
end
|
||||
</screen>
|
||||
</para>
|
||||
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2 id="for">
|
||||
<title>for</title>
|
||||
<para>
|
||||
Command <command>for</command> has following syntax:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<command>for</command> <emphasis>variable</emphasis> <command>=</command>
|
||||
<emphasis>start value</emphasis> <command>to</command> <emphasis>end value</emphasis>
|
||||
<command>step</command> <emphasis>expression</emphasis> <command>do</command>
|
||||
<emphasis>code</emphasis> <command>end</command>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Loop is executed starting from <emphasis>start value</emphasis> and it is ended when variable's value is
|
||||
bigger then <emphasis>end value</emphasis>. If <command>step</command> part is specified, on each step
|
||||
variable's value is increased by given value instead of <command>1</command>.
|
||||
<screen>
|
||||
foreach i = 1 to 20 step 5 do
|
||||
a = a + 2 * i
|
||||
end
|
||||
</screen>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="foreach">
|
||||
<title>foreach</title>
|
||||
<para>
|
||||
Command <command>foreach</command> has following syntax:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<command>for</command> <emphasis>variable</emphasis> <command>in</command>
|
||||
<emphasis>array</emphasis> <command>do</command>
|
||||
<emphasis>code</emphasis> <command>end</command>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Loop is executed for each key in given array. In each step variable is assigned the next key from the array.
|
||||
|
||||
<screen>
|
||||
sum = 0
|
||||
foreach i in myArray do
|
||||
sum = sum + myArray[i]
|
||||
end
|
||||
</screen>
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<!--
|
||||
</chapter>
|
||||
-->
|
||||
<sect1 id="functions">
|
||||
|
||||
<title>Functions</title>
|
||||
<para>
|
||||
Most old parser functions are supported by new parser. Also, some new functions were added.
|
||||
</para>
|
||||
|
||||
|
||||
<sect2 id="string_functions">
|
||||
<title>String functions</title>
|
||||
<para>String functions are the same as in old parser, the only difference is that their names
|
||||
are preceeded by <command>str_</command> instead of <command>@String.</command>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><command>str_length(<parameter>string</parameter>)</command> - returns length of <emphasis>string</emphasis>
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>str_contains(<parameter>string</parameter>, <parameter>text</parameter>)</command> - returns 1 if <emphasis>string</emphasis> contains <emphasis>text</emphasis>
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>str_find(<parameter>string</parameter>, <parameter>text</parameter>, <parameter>start</parameter>)</command> - returns position of the first occurrence of <emphasis>text</emphasis> in <emphasis>string</emphasis>; optional <emphasis>start</emphasis>
|
||||
specifies start of the search
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>str_find(<parameter>string</parameter>, <parameter>text</parameter>, <parameter>start</parameter>)</command> - returns position of the last occurrence of <emphasis>text</emphasis> in <emphasis>string</emphasis>; optional <emphasis>start</emphasis>
|
||||
specifies start of the search
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>str_left(<parameter>string</parameter>, <parameter>count</parameter>)</command> - returns first <emphasis>count</emphasis> characters of <emphasis>string</emphasis>
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>str_right(<parameter>string</parameter>, <parameter>count</parameter>)</command> - returns last <emphasis>count</emphasis> characters of <emphasis>string</emphasis>
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>str_right(<parameter>string</parameter>, <parameter>start</parameter>, <parameter>count</parameter>)</command> - returns substring of <emphasis>string</emphasis> starting from <emphasis>start</emphasis> and containing <emphasis>count</emphasis>
|
||||
characters (or everything to the end of the string if last parameter is not specified)
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>str_remove(<parameter>string</parameter>, <parameter>text</parameter>)</command> - returns <emphasis>string</emphasis> with all substrings equal to <emphasis>text</emphasis> removed
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>str_replace(<parameter>string</parameter>, <parameter>text</parameter>, <parameter>text2</parameter>)</command> - returns <emphasis>string</emphasis> with all substrings equal to <emphasis>text</emphasis> replaced with <emphasis>text2</emphasis>
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>str_lower(<parameter>string</parameter>)</command> - returns <emphasis>string</emphasis> converted to lowercase
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>str_upper(<parameter>string</parameter>)</command> - returns <emphasis>string</emphasis> converted to uppercase
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>str_section(<parameter>string</parameter>, <parameter>separator</parameter>, <parameter>start</parameter>,
|
||||
<parameter>end</parameter>)</command> - returns substring containing appropriate sections of <emphasis>string</emphasis> determined
|
||||
by <emphasis>separator</emphasis>; if no <emphasis>end</emphasis> is given, single <emphasis>start</emphasis> section is returned
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>str_args(<parameter>string</parameter>, <parameter>...</parameter>)</command> - returns <emphasis>string</emphasis> with <command>%1</command>, <command>%2</command>, <command>%3</command> replaced with following parameters.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>str_isnumber(<parameter>string</parameter>)</command> - returns 1 if <emphasis>string</emphasis> is a valid number
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>str_isempty(<parameter>string</parameter>)</command> - returns 1 if <emphasis>string</emphasis> is empty
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>str_toint(<parameter>string</parameter>, <parameter>default</parameter>)</command> - returns <emphasis>string</emphasis> converted to integer; if conversion is not possible, optional <emphasis>default</emphasis> value is returned
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>str_todouble(<parameter>string</parameter>, <parameter>default</parameter>)</command> - returns <emphasis>string</emphasis> converted to double; if conversion is not possible, optional <emphasis>default</emphasis> value is returned
|
||||
</para></listitem>
|
||||
</itemizedlist></para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="kommander_functions">
|
||||
<title>&kommander; functions</title>
|
||||
<para>
|
||||
Most &kommander; functions are supported; some (such as <command>expr</command>)
|
||||
were obsoleted by new parser and are not available.
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><command>debug(<parameter>string</parameter>, <parameter>...</parameter>)</command> - writes all parameters on stderr
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>echo(<parameter>string</parameter>, <parameter>...</parameter>)</command> - writes all parameters on stdout
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>dcop(<parameter>string</parameter>, <parameter>...</parameter>)</command> - calls DCOP function</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><command>exec(<parameter>string</parameter>, <parameter>shell</parameter>)</command> - executes external program
|
||||
(using optional <emphasis>shell</emphasis>); block the execution of the current dialog until the program passed as the parameter exits; returns output of that program
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>i18n(<parameter>string</parameter>)</command> - marks <emphasis>string</emphasis> for future translation
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>env(<parameter>string</parameter>)</command> - returns a value of environmental variable
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>readSetting(<parameter>key</parameter>, <parameter>default</parameter>)</command> - returns a value stored in config
|
||||
file with given <emphasis>key</emphasis>; if there is no such value <emphasis>default</emphasis> is returned
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<command>writeSetting(<parameter>key</parameter>, <parameter>value</parameter>)</command> - writes pair
|
||||
<emphasis>key</emphasis> and <emphasis>value</emphasis> in config file
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
<para>New in &kommander; 1.3</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><command>execBackground(<parameter>string</parameter>, <parameter>shell</parameter>)</command> - executes external program
|
||||
(using optional <emphasis>shell</emphasis>) in the background, without blocking the current dialog; contrary to the above <command>exec</command> function, it will not return the output of the program.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>return(<parameter>value</parameter>)</command> - returns a value to the calling object (script, button...)
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>createWidget(<parameter>widgetname</parameter>, <parameter>widgettype</parameter>, <parameter>parent</parameter>)</command> - creates a new widget. You can then place it in a table or toolbox, for example and use <command>mywidget.show(true)</command> 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.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>connect(<parameter>sender</parameter>, <parameter>signal</parameter>, <parameter>receiver</parameter>, <parameter>slot</parameter>)</command> - 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 <command>execute(const QString&)</command> that is exactly what must be in quotes there.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>disconnect(<parameter>sender</parameter>, <parameter>signal</parameter>, <parameter>receiver</parameter>, <parameter>slot</parameter>)</command> - undo the connection as listed above. Again, exact syntax is essential.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>widgetExists(<parameter>widgetname</parameter>)</command> - 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.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="array_functions">
|
||||
<title>Array functions</title>
|
||||
<para>
|
||||
Most array functions are supported; some (such as <command>value</command>)
|
||||
were obsoleted by new parser and are not available. The only difference is that their names
|
||||
are preceeded by <command>array_</command> instead of <command>@Array.</command>
|
||||
</para>
|
||||
|
||||
<warning><para>Due to parser limitation, name of array has to be specified as string now; for example
|
||||
<command>array_count("MyArray")</command>.</para></warning>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><command>array_clear(<parameter>array</parameter>)</command> - removes all elements from <emphasis>array</emphasis>
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>array_count(<parameter>array</parameter>)</command> - returns number of elements in <emphasis>array</emphasis>
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>array_keys(<parameter>array</parameter>)</command> - returns string containing EOL-separated keys of <emphasis>array</emphasis> - 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 <command>array_values("myarray")</command> as you might think (since it seems to only have values) but would instead need to use <command>array_keys("myarray")</command>. You might find a better choice for this is to use the new <emphasis>indexed arrays</emphasis> described below.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>array_values(<parameter>array</parameter>)</command> - returns string containing EOL-separated values of <emphasis>array</emphasis>
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>array_tostring(<parameter>array</parameter>)</command> - returns string containing whole <emphasis>array</emphasis>
|
||||
as EOL-separated pairs containing key and value separated with TAB character
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>array_fromstring(<parameter>array</parameter>, <parameter>string</parameter>)</command> - reads array from <emphasis>string</emphasis> (usually provided by <command>array_tostring</command> function)
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>array_remove(<parameter>array</parameter>, <parameter>key</parameter>)</command> - removes item with key
|
||||
<emphasis>key</emphasis> from <emphasis>array</emphasis>
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
<para>Here is an example for array manipulation:</para>
|
||||
<screen>
|
||||
array_fromstring("myArray", "1\tA\nsecond\tB\n3\tC")
|
||||
foreach key in myArray do
|
||||
debug("myArray[" + key + "]= " + myArray[key])
|
||||
end
|
||||
</screen>
|
||||
<para>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.</para>
|
||||
<screen>
|
||||
myArray[1]= A
|
||||
myArray[3]= C
|
||||
myArray[second]= B
|
||||
</screen>
|
||||
<para>Another example for keyless arrays:</para>
|
||||
<screen>
|
||||
array_fromstring("myArray", "A\nB\nC")
|
||||
foreach key in myArray do
|
||||
debug(key)
|
||||
end
|
||||
debug("Array elements:\n" + array_keys("myArray"))
|
||||
</screen>
|
||||
<para>This results in:</para>
|
||||
<screen>
|
||||
A
|
||||
B
|
||||
C
|
||||
Array elements:
|
||||
A
|
||||
B
|
||||
C
|
||||
</screen>
|
||||
|
||||
<para>New in &kommander; 1.3</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><command>array_indexedFromString(<parameter>array</parameter>, <parameter>string</parameter>, <parameter>separator</parameter>)</command> - 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. <emphasis>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.</emphasis>
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>array_indexedInsertElements(<parameter>array</parameter>, <parameter>key</parameter>, <parameter>string</parameter>, <parameter>separator</parameter>)</command> - 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.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>array_indexedRemoveElements(<parameter>array</parameter>, <parameter>key start</parameter>, <parameter>number</parameter>)</command> - 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.
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>array_indexedToString(<parameter>array</parameter>, <parameter>separator</parameter>)</command> - 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 <command>TreeWidget1.selection</command> to get the selected row. it will be separated by tabs and you could look at a the fifth element by using <command>str_section(TreeWidget1.selection, "\t", 4)</command> (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 <command>val1+"\t"+val2...</command> Using indexed arrays you could edit that fifth element like so...
|
||||
<screen>
|
||||
idx = TreeWidget1.currentItem
|
||||
array_indexedFromString("z", TreeWidget1.selection)
|
||||
z[4] = "new value"
|
||||
TreeWidget1.removeItem(idx)
|
||||
TreeWidget1.insertItem(array_indexedToString("z"), idx)
|
||||
</screen>
|
||||
Note that only two short lines were added to accomplish this! This was very welcome for database use.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2 id="file_functions">
|
||||
<title>File functions</title>
|
||||
<para>
|
||||
All file functions are supported, the only difference is that their names
|
||||
are preceeded by <command>file_</command> instead of <command>@File.</command>
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><command>file_read(<parameter>name</parameter>)</command> - returns content of file <emphasis>name</emphasis>
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>file_write(<parameter>name</parameter>, <parameter>...</parameter>)</command> - writes all arguments
|
||||
to file <emphasis>name</emphasis>
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>file_append(<parameter>name</parameter>, <parameter>...</parameter>)</command> - appends all arguments
|
||||
to file <emphasis>name</emphasis>
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2 id="input_functions">
|
||||
<title>Input functions</title>
|
||||
<para>
|
||||
These functions show some dialog allowing user to enter some value. They are accessible in the old parser using <command>@Input.</command>. For most functions all parameters are optional, exception is
|
||||
<command>input_text</command> which requires 2 parameters and <command>input_value</command> which requires 5 parameters.
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><command>input_color(<parameter>caption</parameter>, <parameter>default</parameter>)</command> - returns color in #RRGGBB format
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>input_text(<parameter>caption</parameter>, <parameter>label</parameter>, <parameter>default</parameter>)</command> - returns text entered by user
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>input_value(<parameter>caption</parameter>, <parameter>label</parameter>, <parameter>default</parameter>,
|
||||
<parameter>min</parameter>, <parameter>max</parameter>, <parameter>step</parameter>)</command> - returns value entered by user
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>input_directory(<parameter>startdir</parameter>, <parameter>filter</parameter>, <parameter>caption</parameter>)</command> - returns directory selected by user
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>input_openfile(<parameter>caption</parameter>, <parameter>label</parameter>, <parameter>default</parameter>)</command> - returns existing file entered by user
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>input_savefile(<parameter>caption</parameter>, <parameter>label</parameter>, <parameter>default</parameter>)</command> - returns file entered by user (if file exists, confirmation will be required)
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>input_openfiles(<parameter>caption</parameter>, <parameter>label</parameter>, <parameter>default</parameter>)</command> - returns string of EOL-separated existing files entered by user
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2 id="message_functions">
|
||||
<title>Message functions</title>
|
||||
<para>
|
||||
These functions show some message for user or ask user to confirm some action. In the old parser use <command>@Message.</command> instead.
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><command>message_info(<parameter>text</parameter>, <parameter>caption</parameter>)</command> - shows information text
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>message_error(<parameter>text</parameter>, <parameter>caption</parameter>)</command> - shows error text
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>message_warning(<parameter>text</parameter>, <parameter>caption</parameter>, <parameter>button1</parameter>,
|
||||
<parameter>button2</parameter>, <parameter>button3</parameter>)</command> - shows question with warning and up to three buttons; number
|
||||
of chosen button is returned; if no button names are specified, <command>Yes</command> and <command>No</command> will be displayed
|
||||
</para></listitem>
|
||||
<listitem>
|
||||
<para><command>message_question(<parameter>text</parameter>, <parameter>caption</parameter>, <parameter>button1</parameter>,
|
||||
<parameter>button2</parameter>, <parameter>button3</parameter>)</command> - shows question and up to three buttons; number
|
||||
of chosen button is returned; if no button names are specified, <command>Yes</command> and <command>No</command> will be displayed
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect2>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 1.2 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 609 B |
Binary file not shown.
|
After Width: | Height: | Size: 408 B |
@ -0,0 +1,11 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
|
||||
<chapter id="faq">
|
||||
<chapterinfo>
|
||||
<title>Questions and Answers</title>
|
||||
</chapterinfo>
|
||||
|
||||
<title>Questions and Answers</title>
|
||||
<para>The list of Frequently Asked Questions can be found on <ulink url="http://kommander.kdewebdev.org/faq.php">our home page</ulink>.
|
||||
</para>
|
||||
</chapter>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 586 B |
Binary file not shown.
|
After Width: | Height: | Size: 834 B |
Binary file not shown.
|
After Width: | Height: | Size: 213 B |
Binary file not shown.
|
After Width: | Height: | Size: 1.0 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 729 B |
@ -0,0 +1,371 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
|
||||
<sect1 id="specials">
|
||||
<sect1info>
|
||||
<title>Specials and Built-in Global Variables</title>
|
||||
</sect1info>
|
||||
|
||||
<title>Specials and Built-in Global Variables</title>
|
||||
|
||||
<para>
|
||||
Specials are functions that are processed by &kommander;. You should be aware that whe using the old style parser all &kommander; specials will be executed first and then the script will be executed. In most cases this is not a problem, but in a few (mostly in loops, conditions) it is.
|
||||
</para>
|
||||
<note><para>The below list might be slightly outdated. It is recommended to use the <guilabel>Function Browser</guilabel> to get help about the available functions.
|
||||
The <guilabel>Function Browser</guilabel> can be reached from inside the <guilabel>Kommander Text</guilabel> editor, by clicking the <guilabel>Function...</guilabel> button.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><function>@dcop(<parameter>appId</parameter>, <parameter>object</parameter>, <parameter>function</parameter>, <parameter>arguments</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Make a &DCOP; call. @dcop(<quote>kmail</quote>, <quote>KMailIface</quote>, <quote>checkMail()</quote>, <quote></quote>)
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@dcopid</function></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The &DCOP; id of the process. (kmdr-executor-@pid)
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@dialog(<parameter>dialog</parameter>[,<parameter>parameters</parameter>])</function></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Launches the specified Kommander dialog. Dialog is sought in dialog directory and in current directory - in that order. This prepends the call to the executor and sets the default directory to the one the Kommander application is in. Parameters can be passed in the usual Unix way or you can pass named parameters like <quote>variable=value</quote>. You can then find passed parameters in the global pool. @global(variable) would return <quote>value</quote>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@env(<parameter>environmentVariable</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Expands to the specified environment variable. @env(PWD) expands to $PWD. Remember that <quote>$</quote> is part of the shell and shouldn't be used.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@exec(<parameter>command</parameter >)</function></term>
|
||||
<listitem>
|
||||
<para>
|
||||
returns the output of executing the specified command. @exec(ls -l).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@execBegin ... @execEnd</function ></term>
|
||||
<listitem>
|
||||
<para>
|
||||
same as <function>@exec</function>, but supports shebang and multiline scripts. This serves for various scripting languages either by decalring them or using a shebang.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem><para><function>@execBegin(php)</function></para></listitem>
|
||||
<listitem><para><function>@execBegin</function>(#!/usr/bin/php)</para></listitem>
|
||||
</itemizedlist>
|
||||
<para>The first one uses the name of the <acronym>PHP</acronym> executable. &kommander; searches PATH for <application>php</application> and if it is not found looks to see if it is registered with &kommander; in a location outside of your path. If not it tells the user it cannot be found. The second examples uses the classic <quote>shebang</quote> which can have some benefits and also problems. If you have a beta copy of <acronym>PHP5</acronym>, for instance, in <filename>/usr/local/bin</filename> which would not be found because it would find on in <filename>/usr/bin</filename> this is useful. If, however, you distribute the dialog to someone who has <acronym>PHP</acronym> in <filename>/usr/local/bin</filename> only it will not be found with the shebang used. So using shebangs is cautioned and using the executable is recommenede if you are sharing files.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@global(<parameter>variable</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>expands to the value of the specified global variable.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@null</function></term>
|
||||
<listitem>
|
||||
<para>Returns null. Now that Kommander checks for empty widgetText on execution this will prevent erroneous errors in the case of an unset state on a widget.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@parentPid</function></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The &PID; of the parent process.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@pid</function></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The &PID; of the process.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@readSetting(<parameter>key</parameter >, <parameter>defaultValue</parameter >)</function></term>
|
||||
<listitem>
|
||||
<para>
|
||||
reads a value from <filename>kommanderrc</filename>. See also @writeSetting.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@selectedWidgetText</function ></term>
|
||||
<listitem>
|
||||
<para>
|
||||
the selected content in a widget that can show more than one value, like list widgets
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@setGlobal(<parameter>variable</parameter>, <parameter>value</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Sets the global variable to the specified value.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@widgetText</function></term>
|
||||
<listitem>
|
||||
<para>
|
||||
the content of a widget
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@writeSetting(<parameter>key</parameter>, <parameter>value</parameter >)</function ></term>
|
||||
<listitem>
|
||||
<para>
|
||||
write value to <filename>kommanderrc</filename>. All &kommander; dialogs share the same kommanderc file, each one will have its own section inside it.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<sect2 id="arrays">
|
||||
<title>Array Function Group</title>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><function>@Array.values(<parameter>array</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Returns an EOL-separated list of all values in the array. Can be used to walk through an array.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@Array.keys(<parameter>array</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Returns an EOL-separated list of all keys in the array.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@Array.setValue(<parameter>array</parameter>, <parameter>key</parameter>, <parameter>value</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Sets a key and value for an element of an array. If no array exists it is created.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@Array.clear(<parameter>array</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Remove all elements from the array.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@Array.count(<parameter>array</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Return number of elements in the array.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@Array.value(<parameter>array</parameter>,<parameter>key</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Return the value associated with the given key.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@Array.remove(<parameter>array</parameter>,<parameter>key</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Remove element with the given key from the array.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@Array.fromString(<parameter>array</parameter>,<parameter>string</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Add all elements in the string to the array. String should have <emphasis>key\tvalue\n</emphasis> format."</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@Array.toString(<parameter>array</parameter>,<parameter>string</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>"Return all elements in the array in <emphasis>key\tvalue\n</emphasis> format."</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="files">
|
||||
<title>File Function Group</title>
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@File.read(<parameter>file</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Return content of the given file.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@File.write(<parameter>file</parameter><parameter>string</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Write given string to a file.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@File.append(<parameter>file</parameter><parameter>string</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Append given string to the end of a file.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="strings">
|
||||
<title>String Function Group</title>
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@String.length(<parameter>string</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Return number of chars in the string.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@String.contains(<parameter>string</parameter>,<parameter>substring</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Check if the string contains given substring.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@String.find(<parameter>string</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Return position of a substring in the string, or -1 if it isn't found."</para>
|
||||
<note><para>This will have an optional integer start postion for find next uses in Alpha 6.</para></note>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@String.left(<parameter>string</parameter>, <parameter>int</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Return first n chars of the string.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@String.right(<parameter>string</parameter>, <parameter>int</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Return last n chars of the string.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@String.mid(<parameter>string</parameter>, <parameter>int start</parameter>, <parameter>int end</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Return substring of the string, starting from given position.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@String.remove(<parameter>string</parameter>, <parameter>substring</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Remove all occurences of a given substring.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@String.replace(<parameter>string</parameter>, <parameter>substring find</parameter>, <parameter>substring replace</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Replace all occurences of a given substring with a given replacement.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@String.upper(<parameter>string</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Convert the string to uppercase.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@String.lower(<parameter>string</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Convert the string to lowercase.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@String.compare(<parameter>string</parameter>, <parameter>string</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Compare two strings. Return 0 if they are equal, -1 if the first one is lower, 1 if the first one is higher</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@String.isEmpty(<parameter>string</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Check if string is empty.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><function>@String.isNumber(<parameter>string</parameter>)</function></term>
|
||||
<listitem>
|
||||
<para>Check if string is a valid number.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="builtins">
|
||||
<title>Built-in Globals</title>
|
||||
<para>Built-in globals are accessed just like regular global variables with <function>@global</function>.</para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><function>@global(_KDDIR)</function></term>
|
||||
<listitem>
|
||||
<para>The directory the current dialog is in.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><function>@global(_NAME)</function></term>
|
||||
<listitem><para>The name of the dialog</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 455 B |
Binary file not shown.
|
After Width: | Height: | Size: 294 B |
Binary file not shown.
|
After Width: | Height: | Size: 483 B |
Binary file not shown.
|
After Width: | Height: | Size: 572 B |
Binary file not shown.
|
After Width: | Height: | Size: 514 B |
Binary file not shown.
|
After Width: | Height: | Size: 497 B |
Binary file not shown.
|
After Width: | Height: | Size: 1.4 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 783 B |
@ -0,0 +1,72 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
|
||||
<chapter id="translating">
|
||||
<chapterinfo>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>András</firstname>
|
||||
<surname>Mantia</surname>
|
||||
<affiliation><address><email>amantia@kde.org</email></address></affiliation>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Michal</firstname>
|
||||
<surname>Rudolf</surname>
|
||||
<affiliation><address><email>mrudolf@kdewebdev.org</email></address></affiliation>
|
||||
</author>
|
||||
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
|
||||
</authorgroup>
|
||||
</chapterinfo>
|
||||
<title>Translating &kommander; dialogs</title>
|
||||
|
||||
<sect1 id="translation-howto">
|
||||
<title>Translating &kommander; dialogs</title>
|
||||
<para>
|
||||
&kommander; dialogs can be translated to different languages. The mechanism is similar to the translation of other &kde; applications. The dialog is written in English, the texts that are needed to be translated are specially marked. A tool extracts these strings, another tool can be used to translate them. The translation then can be compiled and installed and the dialog will automatically recognize and use it.
|
||||
</para>
|
||||
<para>
|
||||
Here is a short description about the needed steps to make a dialog translatable and translated it:
|
||||
<orderedlist>
|
||||
<listitem><para>How to prepare dialog to be translated?</para>
|
||||
<para>Always use <emphasis>@i18n("This is my text")</emphasis> when you use some English text. This marks "This is my text" as a text to be translated.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem><para>How to extract the messages and create the .po file?</para>
|
||||
<para>
|
||||
Use the <command>kmdr2po</command> script to extract the strings. The script is inside the <emphasis>working</emphasis> directory of the source release tarball and should be installed to <command>$KDEDIR/share/apps/kommander/translating</command> as well.
|
||||
</para>
|
||||
<para>
|
||||
Just run:
|
||||
<screen>
|
||||
kmdr2po <your-kommander-dialog.kmdr>
|
||||
</screen>
|
||||
An appropriate <your-kommander-dialog.po> file will be created.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>How to translate it?</para>
|
||||
<para>Use <command>KBabel</command> to translate it. <command>Use msgfmt</command> to compile the translation. Look at <ulink url="http://i18n.kde.org">http://i18n.kde.org</ulink> for help on this subject.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem><para>How to install the translation?</para>
|
||||
<para>Put the compiled *.mo file either to</para>
|
||||
<para><command>$KDEDIR/share/locale/<your language>/LC_MESSAGES/</command> (will be available globally for all users)</para>
|
||||
<para>or to </para>
|
||||
<para><command>$HOME/.kde/share/locale/<your language>/LC_MESSAGES/</command> (will be available only for the current user)</para>
|
||||
<para>directory.</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To open a different catalog (translation *.mo file) for a dialog, use the -c argument for kmdr-executor. The below example will take the translations from the Quanta translation file:
|
||||
<screen>
|
||||
kmdr-executor mydialog.kmdr -c quanta
|
||||
</screen>
|
||||
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
</chapter>
|
||||
@ -0,0 +1,380 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
|
||||
<chapter id="tutorials">
|
||||
<chapterinfo>
|
||||
<title>Tips and Tutorials</title>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Eric</firstname>
|
||||
<surname>Laffoon</surname>
|
||||
<affiliation><address>
|
||||
<email>eric@kdewebdev.org</email>
|
||||
</address></affiliation>
|
||||
</author>
|
||||
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
|
||||
</authorgroup>
|
||||
</chapterinfo>
|
||||
|
||||
<title>Tips on use &kommander;</title>
|
||||
<para>In this section we go beyond listing widgets to actually using &kommander;. If you want to have a good experience you will find this section very helpful.</para>
|
||||
|
||||
<sect1 id="tutorial-editor">
|
||||
<title>Using the Editor</title>
|
||||
<para>
|
||||
At first glance the editor looks pretty obvious, and in many ways it is. Click on the icon to create a new form, then click a widget and click or click and drag on the form. There are the widget handles that will be familiar to anyone who ever put a picture in a word processing document. What is less obvious are the little things. One thing to mention up front is widget naming. Names must be unique and &kommander; employs a naming scheme of the formal widget name and a number unique to that widget type. You can rename a widget and &kommander; will not allow a duplicate name. However if you build a complex dialog and decide to start renaming you're going to have problems. Signals and slots will manage naming for you and any widget you change will be reflected in the signals and slots connections. Unfortunately we never got this feature in the widget functions. So ever call to that widget will be wrong. You could close the dialog and open it in a text editor like KWrite and do find and replace. A better solution is to start out with some idea what kind of descriptive names you want to give to key widgets. It may be a waste of time naming Labels, but scripts and container widgets for data quickly prove a real mistake not to name. You can also set icons for scripts making them even quicker to visually identify.
|
||||
</para>
|
||||
|
||||
|
||||
<sect2 id="tutorial-editor-tools">
|
||||
<title>Editor Tools</title>
|
||||
<para>
|
||||
The first thing you will notice is a properties window, generally docked on the left. Explore this! Here you will find many useful settings for forms and widgets. Some of them would be layout settings, icons, if something is active, text and more. For instance if you put a TreeWidget in a form you can change the default path separator, which is useful if you have data in there. It's easy for a slash to create a sub-item accidentally. Here you will also find selection modes, whether to highlight the whole row in multi column widgets and more. Before you assune something is just how &kommander; is check this.
|
||||
</para>
|
||||
<para>
|
||||
If you play with layouts and lose a widget behind another or off the form the object explorer will come in handy. It's also nice for seeing structure. The next very useful view is the log view which shows stdout and stderr. The error view is indispensable. This is where your debug() commands prints and where you get detailed information. For instance when using the database plugin this gives you additional information with data errors. It also shows you all shell calls and more. The Stdout view lets you see what would go to the shell or an application using this like Quanta. The dialog view is of little use unless you have a lot of dialogs open. The Action view is only active with MainWindow use and in that case it is the only way to add Actions, menu and toolbar items.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tututorial-add-tools">
|
||||
<title>Adding Custom Tools</title>
|
||||
<para>
|
||||
&kommander; makes it easy to add custom tools, which you can develop in &kommander;, to the editor. We will be shipping some with &kommander; as well as making some available for download. You can add your own easily. First have a look and see where they are. If they are installed they are on the tools menu below the splitter. The &kommander; menu offers access to widgets. The Custom menu offers access to installed plugins. The Editor menu is where your custom tools go. To manually add a tool first decide if you are going to make it available system wide or just to your desktop. System wide start from the directory KDE is installed in. For your desktop user start in the hidden KDE directory in your home directory, usually ~/kde. From either the path is/share/apps/kmdr-editor/editor/ If the dialog you add needs access to tools or files you can put them in a subdirectory. Whatever &kommander; dialogs you put there will be recognized and added to your menu on startup. Clicking the menu will load the dialog. You will note there is a templates directory there too and you can add templates for new dialogs.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="included-tools">
|
||||
<title>Included custom tools</title>
|
||||
<para>
|
||||
Several tools are included with this release, already installed on the tools meu under editor. More tools are under development for project management, database front end development, code snippets and more. The most imporant and useful tool to look for is the examples dialog. As the editor is no longer under development for KDE3 it cannot insert a dialog in the current editor, but it will open any selected dialog in a new instance of the editor. There are old dialogs from the early days of &kommander;, tutorials from more recent development and the current section showing new features of this release. Looking at these should help. Keep an eye on our web site for more.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tutorial-layout">
|
||||
<title>Using Layout</title>
|
||||
<para>
|
||||
People love to share &kommander; dialogs. Almost without fail they don't know about laying them out. Make a dialog and then try resizing it and see what happens. Wouldn't it be nice if it behaved like it should instead of leaving your widgets the same? It gets worse when you share it and differences in fonts, monitor size and X pixel resolution conspire to make your masterpiece look like it was put together by a three year old using bubblegum and thumbtacks. Always, always always... Lay out your dialogs!
|
||||
</para>
|
||||
<para>
|
||||
Okay, you're sold you don't want a frustrated email from me asking you to please layout your dialog. How do you do it. There are layout buttons on the toolbar and the context menu. Since &kommander; is based on an older version of Qt Designer you can look at Qt Designer docs and tutorials here. I'm just going to mention a few basics and a few tips.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>Use the Grid. This will place everything in a <quote>best guess</quote> location</para></listitem>
|
||||
<listitem><para>Remember containers are separate. A TabWidget, GroupBox or layout group has it's own layout. So don't forget the window.</para></listitem>
|
||||
<listitem><para>Widgets that are not visible during execution can make layout seem more challenging. What to do with them? I recommend grouping them in their own layour next to or below your main layout. Your visible widgets will simply push these aside and give you a predictable result.</para></listitem>
|
||||
<listitem><para>Look at your properties were you can set a widget to expand or do other things as well as minimum and maximum size. A little experimentation will teach you a lot. You can also set a tighter spacing here,</para></listitem>
|
||||
</itemizedlist>
|
||||
<para>And now for a few tricks and tips.</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>Along with basic layout you can use splitters. When your dialog is running you can drag the splitter up and down or right and left to get a better look at things. It may look like there is a limitation here or it doesn't work. It works and has no limitations. Just make sure to put multiple widgets into two layouts and make sure when you click or right click to get the layout and not just a child widget. You are free to create a maze of splitters as long as you adhere to the rules.</para></listitem>
|
||||
<listitem><para>Fake docs are possible! Create a GroupBox and drop widgets on it. Position it in your layout so that when it's invisible other widgets/layouts will expand to take it's place. Now toggle it's visibility with a button or menu. </para></listitem>
|
||||
<listitem><para>ToolBox tricks - The Toolbox has an editor bug where you can't add widget panels in the editor without it going nuts. As a result you need to add them at run time. However it looks for one widget and if you want something complex you should use a groupbox and lay it out. then layout your dialog with the groupbox at the outside, even if it goes off the edge of the window. Now load it on initialization into the ToolBox. Your window layout will snap into place.</para></listitem>
|
||||
<listitem><para>Layout glitches can occur where widgets set to something like Minimum/Expanding can end up obscured before you complete layout on the window. The layout system will honor your oddness and can be shrunk to obscure scrollbars and more. Make sure all is visible before finishing layout and consider not using minimum in that case.</para></listitem>
|
||||
</itemizedlist>
|
||||
<para>For more on this look up the Qt Designer docs for Qt 3.x.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="signals-slots">
|
||||
<title>Signals and Slots</title>
|
||||
<para>
|
||||
One of the very useful features inherited from Qt Designer was signals and slots. Of course the interface has been redesigned in an attempt to make it friendly to &kommander;. Signals and slots are internal event control for Qt/KDE applications. We try to make it so you don't have to know the difference between C++ data types, but if you use the new function to create connections on the fly it is handy to be able to copy that information from the connection tool. Let's look at what all this means. Something happens in one of you widgets. It could be click on, double clicked, have it's value changed, something selected or a menu could be requested. That is just some of the possible events that would enable a signal to be sent. You may want to change the list in a ListBox if a new selection is made in a ComboBox. That's a useful feature in a sophisticated application and the only way to do it without having to press a button next is to have a signal connected to a slot. That slot could be in a script or button. When the slot receives the signal it goes about doing what it was told. There is a tool to edit these connections. Pay attention when do this as there are a good number of inherited signals and slots. Telling a script which is invisible when the dialog is run to adjust it's size by accident when you meant to execute will have you wondering what happened.
|
||||
</para>
|
||||
<para>
|
||||
To access the connection tool you can open it by right clicking anywhere on the dialog and selecting it. Click the menu and you will see a list of connections made at the bottom. Above that are two lists of signals and slots and above them the respective sender and receiver are selected. An easy way to make connections is visually. Look at the toolbar or the Tools menu. There are three items grouped there. A pointer, signals and slot connections and the tab order or widgets. Selecting this sets connection mode for the curios. Click on your widget to send the signal and drag it to your widget to receive it in a slot. As you do this you will see a line and drop indications on the widget under the mouse. The StatusBar on the Editor will tell you what is being connected.
|
||||
</para>
|
||||
<note><para>In version 1.3 there is a &kommander; function connect() which allows you to connect signals and slots on the fly. This is useful if you just used createWidget. Obviously you can't use the dialog for something &kommander; doesn't yet know exists. Unfortunately there are too many combinations to list so you have to type out signals and slots. <emphasis>These must be typed verbatim or they will fail.</emphasis> This is where the connection tool is handy again. Open it and select two widgets like the two you want to connect and read the connection information. if it says <command>execute(const QString&)</command> that is exactly what you must type.</para></note>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="slot-functions">
|
||||
<title>Slot Functions</title>
|
||||
<para>
|
||||
As of version 1.3 &kommander; adds Slot functions. You can see this in the Function Browser, which is uncharacteristicly less than friendly with descriptions here. What &kommander; is doing is reading every slot registered for a given widget and making it available directly. This is very useful. For instance the Table widget doesn't have a default method to auto adjust column width. You may find this annoying, but if you look under slots there it is. The TextEdit is also lacking in built in functions for any real editing, but look under slots and there is anything you could wish for. You may have to reference some docs or just experiment. It is simply too difficult to document every slot available in builtin widgets and plugins. Most slots however are self explanatory.
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="tutorial-basics">
|
||||
<title>Basic Tutorials</title>
|
||||
<para>
|
||||
Most of the information in this section is based on example dialogs some time ago, which unfortunately were not widely available as they were shipped with the source, but not installed. You should find them in your tools menu under examples in the <quote>tutorial</quote> section. Keep in mind most of these particular examples use the old parser. That is neither good nor bad. Most of the functionality in &kommander; is shared in both parsers. It's just each is particularly suited to do a better job with a given task. As &kommander; now defaults to the new parser you can set either one. Please see the <link linkend="new_parserdocs">New Parser docs</link> for more information on the two parsers.
|
||||
</para>
|
||||
<para>
|
||||
When examining example dialogs remember to look in the following places to see how things are done.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>Dialog Initialization - middle click on the dialog face or right click and select &kommander; Text. Here you see what is run when the dialog starts.</para></listitem>
|
||||
<listitem><para>Buttons - middle click the button, or right click. Scripts are typically here.</para></listitem>
|
||||
<listitem><para>Widgets - some widgets like Timers and Konsoles will hold instructions inside them.</para></listitem>
|
||||
<listitem><para><link linkend="signals-slots">Signals and Slots</link> - this is how Qt/KDE programs internally communicate. </para></listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
The following list of dialogs may be brief so as to focus on where more information is required to explain more complex tasks possible with &kommander;. They were copied from Michal's notes.
|
||||
</para>
|
||||
|
||||
<sect2 id="tutorial-globals">
|
||||
<title>Globals</title>
|
||||
<para>Shows using global and setGlobal &DCOP; calls to provide global variables for script</para>
|
||||
<blockquote><para>
|
||||
Functions/concepts:
|
||||
- global
|
||||
- setGlobal
|
||||
- changeWidgetText
|
||||
</para></blockquote>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tutorial-dcop">
|
||||
<title>&DCOP;</title>
|
||||
<para>Shows how to use both local and external &DCOP; calls to communicate with external application (here: KMail).</para>
|
||||
<blockquote><para>
|
||||
Functions/concepts:
|
||||
- external DCOP
|
||||
- addListItem
|
||||
- enableWidget
|
||||
- @selectedWidgetText
|
||||
- @widgetText
|
||||
</para></blockquote>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tutorlal-slots">
|
||||
<title>Slots</title>
|
||||
<para>Shows how to us connections/slot to handle events. Both population and standard slots are used.</para>
|
||||
<note><para>Population text was originally developed before &kommander; DCOP, specials and scripting. Given that everything it does can be done in other ways and that it is easy to forget to look here for problems, along with the inherent difference of introducing an additional behavior to explain, this is a deprecated function. It is left in for illustration, however while &kommander; dialogs will be easy to port to KDE4 this feature is not assured to work in the future. <emphasis>Don't use it!</emphasis> </para></note>
|
||||
<blockquote><para>
|
||||
standard slots are used.
|
||||
- slots/connections
|
||||
- populate()
|
||||
</para></blockquote>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tutorial-settings">
|
||||
<title>Settings</title>
|
||||
<para>Shows how to use @readSetting and @writeSetting functions to write/restore widget content. Also, show how to use populate() slot to initialize widget content.</para>
|
||||
<blockquote><para>
|
||||
Functions/concepts:
|
||||
- @readSetting
|
||||
- @writeSetting
|
||||
- populate()
|
||||
- slots/connections
|
||||
- destroy
|
||||
</para></blockquote>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tutorial-append">
|
||||
<title>Append</title>
|
||||
<para>Shows how you can append text to TextEdit and how you can use it to display formatted text. See newer examples for how to use slots to edit rich text and new font and color dialogs too.</para>
|
||||
<blockquote><para>
|
||||
Functions/concepts:
|
||||
- changeWidetText
|
||||
- RichTextEdit
|
||||
</para></blockquote>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tutorial-cmdline">
|
||||
<title>Command Line</title>
|
||||
<para>Shows how you can pass parameters to &kommander; dialog via command line. Also, shows how to change list content and button text. See the section on <link linkend="passargs">passing arguments</link> in the new parser for more on this.</para>
|
||||
<blockquote><para>
|
||||
Functions/concepts:
|
||||
- command-line arguments
|
||||
- global
|
||||
- changeWidgetText
|
||||
- addListItem
|
||||
- clearList
|
||||
</para></blockquote>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tutorial-initialize">
|
||||
<title>Initialize</title>
|
||||
<para>
|
||||
Shows how you use 'initialization' to 'destroy' scripts of main dialog to initialize and store some settings.
|
||||
</para>
|
||||
<blockquote><para>
|
||||
Functions/concepts:
|
||||
- initialization
|
||||
- destroy
|
||||
- readSetting
|
||||
- writeSetting
|
||||
</para></blockquote>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tutorial-array">
|
||||
<title>Array</title>
|
||||
<para>
|
||||
Shows how to use associative arrays to store and restore information
|
||||
associated with container items.</para>
|
||||
<blockquote><para>
|
||||
Functions/concepts:
|
||||
- @Array functions
|
||||
</para></blockquote>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tutorial-strings">
|
||||
<title>Strings</title>
|
||||
<para>
|
||||
Shows how to use string-handling functions
|
||||
Functions/concepts:
|
||||
</para>
|
||||
<blockquote><para>
|
||||
- @String functions
|
||||
- rich text editor
|
||||
</para></blockquote>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tutorial-tree">
|
||||
<title>Tree</title>
|
||||
<para>
|
||||
Shows how to use tree widget
|
||||
</para>
|
||||
<blockquote><para>
|
||||
- tree widget
|
||||
- FileSelector
|
||||
- initialization
|
||||
- env
|
||||
</para></blockquote>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tutorial-widgets">
|
||||
<title>Widgets</title>
|
||||
<para>
|
||||
Shows how to get widget information
|
||||
</para>
|
||||
<blockquote><para>
|
||||
- type method
|
||||
- children method
|
||||
</para></blockquote>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tutorial-statusbar">
|
||||
<title>StatusBar</title>
|
||||
<para>
|
||||
Shows how to use statusbar widget
|
||||
</para>
|
||||
<blockquote><para>
|
||||
- statusbar widget
|
||||
- populate
|
||||
</para></blockquote>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tutorial-loop">
|
||||
<title>Loop</title>
|
||||
<para>
|
||||
Shows how to use internal loops
|
||||
</para>
|
||||
<blockquote><para>
|
||||
- for
|
||||
- forEach
|
||||
</para></blockquote>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tutorial-calc">
|
||||
<title>Calc</title>
|
||||
<para>
|
||||
Shows how to use @expr function to do some calculations
|
||||
</para>
|
||||
<blockquote><para>
|
||||
- expr
|
||||
- String.replace
|
||||
</para></blockquote>
|
||||
<note><para>The @expr() function is no longer required in the new parser as expressions can be directly interpreted anywhere you would logically want to use them.</para></note>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tutorial-picview">
|
||||
<title>Picview</title>
|
||||
<para>
|
||||
Shows how to use PixmapLabel widget using populate() function
|
||||
</para>
|
||||
<blockquote><para>
|
||||
- PixmapLabel
|
||||
- populate
|
||||
- FileSelector
|
||||
- slots/connections
|
||||
</para></blockquote>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tutorial-table">
|
||||
<title>Table</title>
|
||||
<para>
|
||||
Shows how to use Table widget
|
||||
</para>
|
||||
<blockquote><para>
|
||||
- insertRow
|
||||
- insertColumn
|
||||
- currentRow
|
||||
- currentColumn
|
||||
- setColumnCaption
|
||||
- setRowCaption
|
||||
- removeRow
|
||||
- removeColumn
|
||||
</para></blockquote>
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="examples">
|
||||
<title>Current Examples</title>
|
||||
<para>
|
||||
These examples reflect the most recent development state of &kommander;. In its current state &kommander; has few limitations for developing small to medium applications. It certainly is not suitable for building a KWord clone, but for a simple editor, database frontend, GUI for commandline programs or any application in the spirit of Unix/Linux small applications it is a good choice. The examples presented here are intended to show the potential as well as how to work around limitations. There are some useful tricks included in these if you want to do a more capable small application with &kommander;. Remember &kommander; is not intended to do everything, but to do most things. For this concession you should be able to build something in &kommander; faster than other alternatives ad add GUI to scripting languages not otherwise supported in KDE.
|
||||
</para>
|
||||
<note><para>
|
||||
The examples are installed to <command>$KDEDIR/share/apps/kmdr-editor/editor</command>. In case you do not have them there, get from <ulink url="http://kommander.kdewebdev.org">our home page</ulink>, by downloading the latest release.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<sect2 id="editor-poc">
|
||||
<title>editor-poc.kmdr</title>
|
||||
<para>
|
||||
The little dialog that grew into a Mainwindow. As &kommander; does not have a native MainWindow widget it has been assumed it only does dialogs. In fact only dialogs are officially supported... but you can run MainWindows in &kommander;. This is an example editor. If you want to create a MainWindow application in &kommander; just open Qt Designer and make one, save it and rename the *.ui file to a *.kmdr file. Now open it in &kommander; and do what you would do normally.
|
||||
</para>
|
||||
<note><para>As of this writing what is known not to work on the &kommander; side is the settings read and write. There is no Initialize or Destroy section as there is no &kommander; Text, however there are signals for this on the window, so the functionality is intact. On the MainWindow side it is not possible to talk to any actions via DCOP as these are QActions from Designer and KActions are not derived from QActions in KDE 3.x. This means a DCOP call to list actions or set states will not work. It is also not possible to talk to the Statusbar. Also submenus on the menubar and dropdown actions on the Toolbar will not work. Even though this is not a &kommander; widget, or officicially supported, it seems suitable for many small application uses.</para></note>
|
||||
<para>
|
||||
There is a quick help dialog this editor launches that discusses in depth what is happening inside.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="example-key-value">
|
||||
<title>kevaluecombo.kmdr</title>
|
||||
<para>
|
||||
&kommander; can be used with databases and has an optional <ulink url="http://kommander.kdewebdev.org/releases.php#plugins">database plugin</ulink>. One shortcoming is not being able to store key/value pairs in the ComboBox. An ingenious trick was realized for this. It requires only that the content of the ComboBox not be changed unless it is done using the arrays that go with it. As this is commonly used with SQL in small data sets it's quite fast even to reload the whole Combobox. The inherent problem is that &kommander; does not have internally indexed arrays by default. This is compounded by the fact that to accommodate shell commands that return lines separated by newlines &kommander;'s array functions will load what is effectively an array of keys. Such an array can only be accessed with a foreach loop. This is the reason new indexed array functions were added. It is important to remember that these arrays are not self maintaining, but their insert and delete functions will help you.
|
||||
</para>
|
||||
<para>
|
||||
Getting back to the ComboBox, it will return selected text, but it also will return the current index. It does rigidly maintain a contiguous zero based array. That's the key. We loop through a data set with a zero based index counter and create two arrays, as &kommander; also cannot create arrays of arrays. It can however use an array value to represent a key just like any value could. .If you look at the included dialog the code actually managing this is in <quote>ScriptObject36</quote>. We will extract the key code here.
|
||||
</para>
|
||||
<screen>
|
||||
c = ListBox1.count-1
|
||||
for i = 0 to c do
|
||||
array_indexedFromString("x", ListBox1.item(i))
|
||||
_a[x[0]] = x[1]
|
||||
_b[i] = x[0]
|
||||
ComboBox10.insertItem(_a[_b[i]], i)
|
||||
end
|
||||
</screen>
|
||||
<para>
|
||||
There is more going on, like checking for duplicate keys, but this is the core. You can right click on the ListBox and try menu items. The net result is that it is using keyed index by proxy and returning both the key and the value. Use this code if you want to be 100% certain your key/value relationship is accurate.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="kpart-demo">
|
||||
<title>Kpart demo</title>
|
||||
<para>
|
||||
As of Kommander 1.3 Kommander automatically makes KParts using the libkommander_part.la. In addition to this there is a KPart plugin which allows Kommander to load plugins. Being curious developers we tried loading a Kommander part into Kommander. Why do that? Why not? The results were interesting and are demonstrated here. One interesting thing is the parent part can directly access all of the child part. While this is handy it has a down side. Any child widget being called with the same name as a parent widget will cause a lock up! In addition to that the DCOP interface is generated all over again for the part which wipes out the parent interface and disables most of the old parser functionality as well as Kommander specific DCOP to the parent. This is too difficult to fix for the remaining life of the KDE3 version. Even with these limitations and cautions this can be useful, if used carefully. The example files to look at this are in the current examples as kpartmwframe.kmdr and kpartpart.kmdr. Remember you will need the KPart plugin to fully run this example.
|
||||
</para>
|
||||
<para>
|
||||
You can also load KMail, KOrganizer and many other KDE applications right into Kommander, of course without the problems. KHTML and KDE's file manager widgets seem not to have some functionality but there is a special KHTML plugin if you really want to incorporate a browser.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="example-passed-params">
|
||||
<title>passvariables.kmdr</title>
|
||||
<para>
|
||||
As of &kommander; 1.3 you can pass and return variables with scripts. This dialog demonstrates that. Look carefully at the content of the buttons. You will see that neither button directly writes to any of the LineEdit boxes receiving text from the script. While one is written directly from the script another is written with the content passed from the button. The third is not written at all but passed back in a return() function where it is received by the button and written. This is also shown on the right side using PHP so you can see how this might work with Python, Ruby, Perl or even a less commonly used language like Rexx. Languages that Speak DCOP can do a lot more in &kommander; too. The point of this demo is the freedom provided. &kommander; does not have functions, yet it does. Create a script, declare some globals if you like, pass some parameters to another script and return a value. For an intentionally simplified GUI scripting tool that is capable behavior. This behavior is only in the new parser and is documented <link linkend="passargs">here</link>.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="tableselect">
|
||||
<title>tableselect.kmdr</title>
|
||||
<para>
|
||||
This example demonstrates how to use the new select function in the table widget. It is now possible to get four coordinates to enable a block selection. This also shows how it would have had to be done prior to this function. and how to use the parameters passed to a script. In addition this demonstrates a simple block copy and paste function for a table as well as summation of a block.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
</chapter>
|
||||
@ -0,0 +1,599 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
|
||||
<sect1 id="widgets">
|
||||
<sect1info>
|
||||
<title>Widgets</title>
|
||||
</sect1info>
|
||||
|
||||
<title>Widgets</title>
|
||||
|
||||
<para>
|
||||
The building blocks of a &kommander; dialog are the widgets. They are like any other widget in the &Qt; and &kde; libraries except they have some extra functionality that allows them to have a <quote>text association</quote>. Text is associated with a state of the widget or its populate slot. The number of states depends on the widget. If a widget only has one state, that state is called default.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>The main dialog has two special states for &kommander; text. They are Initialization and Destroy. These are run when the dialog is initialized and when it is destroyed. These protect against what is know as <quote>race</quote> problems on open and mean that you do not require any special procedures on close to manage housekeeping.</para>
|
||||
<para>In case of using a MainWindow based application (created with &Qt; Designer), there are no Initialization and Destroy states, instead the <emphasis>initialize</emphasis> and <emphasis>destroy</emphasis> signals can be used to get information when is the application constructed or closed</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
Below are the standard &kommander; widgets. Each of them has numerous functions, you can learn about them by looking at the widget functions in the <guilabel>Function Browser</guilabel>. Many of them have signals and slots as well, documentation about these methods can be found in the &Qt; and &kde; API documentation. Each &kommander; widget has a note about its base widget.
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="label.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
Label
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A simple widget that contains a piece of text. This widget lets you set a pixmap too.
|
||||
</para>
|
||||
<para>
|
||||
See the QLabel documentation to learn more about text labels in &Qt;.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="pixlabel.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
PixmapLabel
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A simple widget that contains an image or text label. The pixmap to display is set in the pixmap property. The text is set in the text property. Only one of these properties can be set at the same time (I think, I can't get the editor to set both at the same time). If scaledContents is set to true the image will be scaled to fit the size of the widget. The format of the text can be set with the textFormat property.
|
||||
</para>
|
||||
<para>
|
||||
See the QLabel documentation to learn more about text labels in &Qt;.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="lineedit.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
LineEdit
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A LineEdit widget is a one line text editor. It allows the user to enter and modify a single line of text. Initial text for the editor can be set in the text property. The widget can be set to read-only with the readOnly property. There are 3 modes for the widget, Normal, NoEcho, and Password. The mode is set with the echoMode property.
|
||||
</para>
|
||||
<para>
|
||||
LineEdit has one state, default.
|
||||
</para>
|
||||
<para>
|
||||
The widget text for LineEdit is the text contained in the editor.
|
||||
</para>
|
||||
<para>
|
||||
See the KLineEdit documentation to learn more about text labels in &kde;.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="multilineedit.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
TextEdit
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A simple multi-line text editor.
|
||||
</para>
|
||||
<para>
|
||||
See the KTextEdit documentation to learn more about multiline text edit in &kde;.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="textbrowser.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
TextBrowser
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A simple reach text browser with hyperlink navigation.
|
||||
</para>
|
||||
<para>
|
||||
See the KTextBrowser documentation to learn more about it.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="listbox.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
ListBox
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A ListBox widget provides a list of selectable items. Normally one or no items are selected. This behavior can be changed with the selectionMode property. Items are added to the ListBox using the edit window.
|
||||
</para>
|
||||
<para>
|
||||
A ListBox has only one state, default.
|
||||
</para>
|
||||
<para>
|
||||
The widget text for a ListBox is the items contained in the ListBox. @selectedWidgetText will return only the items that are currently selected.
|
||||
</para>
|
||||
<para>
|
||||
See the KListBox documentation to learn more about it.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="combobox.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
ComboBox
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
ComboBox is a selection widget that combines a button and a pop-up menu. It shows the user's current choice from a list of options in minimal space. Items are added to the list using the edit window. If the editable property is set to true the user can enter arbitrary strings.
|
||||
</para>
|
||||
<para>
|
||||
ComboBox has one state, default.
|
||||
</para>
|
||||
<para>
|
||||
The widget text for a ComboBox is the text of the selected item.
|
||||
</para>
|
||||
<para>
|
||||
See the KComboBox documentation to learn more about it.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="listview.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
TreeWidget
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A widget that provides a list in the form of a tree structure. You can add child items and multi-column data. The current limitation is that you cannot modify columns. To add a child node use <quote>/</quote> as a separator. To add column data use the escaped tab <quote>\t</quote> character between columns.
|
||||
</para>
|
||||
<para>
|
||||
See the KListView documentation to learn more about it.
|
||||
</para>
|
||||
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="table.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
Table
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A table widget that support different widgets in its cells.
|
||||
</para>
|
||||
<para>
|
||||
See the QTable documentation to learn more about it.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="pushbutton.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
ExecButton
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A button that when clicked executes its text association. The label on the button is set with the text property. Output from the text association (how to say that) will be echoed to stdout if the writeStdout property is set to true. The button can be the default action for the dialog if the default property is set to true.
|
||||
</para>
|
||||
<para>
|
||||
ExecButton has one state, default.
|
||||
</para>
|
||||
<para>
|
||||
There isn't widget text associated with ExecButton.
|
||||
</para>
|
||||
<para>
|
||||
See the KPushButton documentation to learn more about it.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="closebutton.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
CloseButton
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A button that when clicked, executes its text association and then closes the dialog. The label on the button is set with the text property. Output from the text association (how to say that) will be echoed to stdout if the writeStdout property is set to true. The button can be the default action for the dialog if the default property is set to true.
|
||||
</para>
|
||||
<para>
|
||||
CloseButton has one state, default.
|
||||
</para>
|
||||
<para>
|
||||
There isn't any widget text associated with a CloseButton.
|
||||
</para>
|
||||
<para>
|
||||
See the KPushButton documentation to learn more about it.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="konsole.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
Konsole
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A widget that captures the output of scripts in a text browser. The default state is executed and the output of those commands (internal or external) are shown in the widget.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="lineedit.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
FileSelector
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The FileSelector widget combines a LineEdit with a button when clicked will present the user with dialog for the selection of files/folders. The file/folder selected is stored in the LineEdit. The type of the FileSelector is set with the selectionType property. Available types are Open, Save, and Directory. Multiple files/folders can be selected if the selectionOpenMutliple property is set to true. A caption for the FileChooser can be set with the selectionCaption property. This is display as the window title of the dialog. If a caption isn't specified, the type of selection will be display in the title. The files displayed in the dialog can be limited using the selectionFilter property.
|
||||
</para>
|
||||
<para>
|
||||
FileSelector has one state, default.
|
||||
</para>
|
||||
<para>
|
||||
The widget text for a FileSelector is the text contained in the LineEdit (the file chosen by the user).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="checkbox.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
CheckBox
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A button that can be checked on and off. It can also be semi-checked if the tristate property is set to true. The label associated with the CheckBox is set in the text property. Setting the checked property will have the CheckBox initially checked.
|
||||
</para>
|
||||
<para>
|
||||
A CheckBox has 3 states, checked, semichecked, and unchecked.
|
||||
</para>
|
||||
<para>
|
||||
The widget text for a CheckBox is the value from the text property.
|
||||
</para>
|
||||
<para>
|
||||
See the KCheckBox documentation to learn more about it.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="radiobutton.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
RadioButton
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A button that can be checked or unchecked, usually used in the ButtonGroup to make an exclusive choice. A label associated with the button can be set in the text property. A button can be initialized to checked by setting the checked property to true. If all RadioButtons in a ButtonGroup have the checked property set to true, then the last button will be the one that is checked.
|
||||
</para>
|
||||
<para>
|
||||
RadioButton has 2 states checked and unchecked.
|
||||
</para>
|
||||
<para>
|
||||
There is no widget text associated with a RadioButton.
|
||||
</para>
|
||||
<para>
|
||||
See the KRadioButton documentation to learn more about it.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="buttongroup.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
ButtonGroup
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A container to organize buttons into a group. An optional title can be set using the title property. The frame can be adjusted with the lineWidth property. The button group can be set to exclusive by setting the exclusive property to true. This means when one toggle button is clicked all other toggle buttons will be set to off with the exception of radio buttons that are always mutual exclusive even if the group is non-exclusive. Radio buttons can be set to non-exclusive using the radioButtonExclusive property. (I am not so sure that this property actually works.)
|
||||
</para>
|
||||
<para>ButtonGroup has one state, default.</para>
|
||||
<para>
|
||||
The widget text for a ButtonGroup is the text associations for each of the buttons in the order they appear in the ButtonGroup.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="groupbox.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
GroupBox
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A container widget that holds other widgets. The frame is adjusted with the lineWidth property. A title can be added by setting the title property.
|
||||
</para>
|
||||
<para>
|
||||
GroupBox has one state, default.
|
||||
</para>
|
||||
<para>
|
||||
The widget text for GroupBox is the text associations of each of the widgets it contains combined. They will be in the order they appear inside of the GroupBox.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="tabwidget.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
TabWidget
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A widget that provides multiple tabs each may contain other widgets.
|
||||
</para>
|
||||
<para>
|
||||
See the KTabWidget documentation to learn more about it.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="spinbox.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
SpinBoxInt
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A widget that allows the user to change a integer value by either press up and down arrows or entering a value into the box. Minimum and maximum values for the widget can be set with the minValue and maxValue properties. The specialValueText property is used to set a text value that will be displayed instead of the minimum value.
|
||||
</para>
|
||||
<para>
|
||||
This widget has only one state, default.
|
||||
</para>
|
||||
<para>
|
||||
The widget text for a SpinBoxInt is the currently displayed integer.
|
||||
</para>
|
||||
<para>
|
||||
See the QSpinBox documentation to learn more about it.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="slider.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
Slider
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A widget that provides horizontal or vertical slider.
|
||||
</para>
|
||||
<para>
|
||||
See the QSlider documentation to learn more about it.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="richtextedit.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
RichTextEditor
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This widgets provides a text editor that allows for simple text formatting.
|
||||
</para>
|
||||
<para>
|
||||
RichTextEditor has one state, default.
|
||||
</para>
|
||||
<para>
|
||||
The widget text for RichTextEditor is the text contained in the editor in rich text format. Selected text can be returned with @selectedWidgetText.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="statusbar.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
StatusBar
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A widget to display status information, usually used at the bottom of the dialogs.
|
||||
</para>
|
||||
<para>
|
||||
See the KStatusBar documentation to learn more about it.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="progress.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
ProgressBar
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A widget to display progress information.
|
||||
</para>
|
||||
<para>
|
||||
See the KProgress documentation to learn more about it.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="shellscript.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
ScriptObject
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This is a pseudo-widget, it does not appear when the dialog is run. It can be though about as a function. A ScriptObject holds code that can be executed anytime from the dialog by calling its <emphasis>execute</emphasis> function. Arguments can be passed to the ScripObject with the above method and accessed inside the ScriptObject as <emphasis>@Self.item(0), @Self.item(1), etc.</emphasis> if using the old style parsing or <emphasis>Self.item(0, Self.item(1), etc.</emphasis> with the new parser.
|
||||
</para>
|
||||
<para>
|
||||
Signals can be connected to the <emphasis>execute</emphasis> function as well, as it acts also as a slot.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="timer.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
Timer
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This is a pseudo-widget, it does not appear when the dialog is run. It can be used to perform an action after a specified time once, or regularly. Set the timeout <guilabel>interval</guilabel> in milliseconds, choose if it should run once (<guilabel>singleShot</guilabel>) or not. Connect its <emphasis>timeout</emphasis> signal to a slot, which will be executed once the specified time passes.
|
||||
</para>
|
||||
<para>
|
||||
The timer is not started by default, run the <emphasis>execute</emphasis> function to start it.
|
||||
</para>
|
||||
<para>
|
||||
See the QTimer documentation to learn more.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="datepicker.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
DatePicker
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A widget used to select a date. The default date can be set in the <guilabel>date</guilabel> property or with the <emphasis>setText</emphasis> function in ISO format: <emphasis>YYYY-MM-DD</emphasis>.
|
||||
</para>
|
||||
<para>
|
||||
The widget text is the currently displayed date.
|
||||
</para>
|
||||
<para>
|
||||
See the KDatePicker documentation to learn more.
|
||||
</para>
|
||||
<note><para>New in Kommander 1.3.</para></note>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="kommander.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
AboutDialog
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This is a pseudo-widget, it does not appear when the dialog is run. It stores information about the application, the authors, the license. Shows the about dialog
|
||||
when the <emphasis>execute</emphasis> function is called.
|
||||
<warning><para>The <emphasis>initialize</emphasis> function must be called before anything else, including the <emphasis>execute</emphasis> function.</para></warning>
|
||||
</para>
|
||||
<note><para>New in Kommander 1.3.</para></note>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="kfontcombo.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
FontDialog
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A pseudo-widget, that can be used to get a font selection dialog. The default font can be set with the <emphasis>setFont</emphasis> function, and the selected font's properties retrieved with the <emphasis>family, pointSize, bold, italic</emphasis> functions. The dialog is shown when the <emphasis>execute</emphasis> function is called.
|
||||
</para>
|
||||
<note><para>New in Kommander 1.3.</para></note>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="contents.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
PopupMenu
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A pseudo-widget, that can be used to display a menu. Use the <emphasis>insert...</emphasis> functions to add menu entries. Whenever the user clicks on a menu entry, the specified <emphasis>executeWidget</emphasis>'s <emphasis>execute</emphasis> function will be run. It is possible to connect the menu entries to the popupmenu's own <emphasis>execute</emphasis> function, in which case the text assigned to the <emphasis>default</emphasis> state is run. When adding menu items you can assign an index to them and handle the all the items on a menu in the menu widget as the request passes this index back. To see how this works look at the current example <link linkend="example-key-value">keyvaluecombo.kmdr</link> included with this release. To find it look on the tools menu of the editor for the examples dialog.
|
||||
</para>
|
||||
<para>To show the menu, use <emphasis>popup</emphasis> slot. Usually this is connected to another widget's <emphasis>contextMenuRequested</emphasis> signal.</para>
|
||||
<para>A menu can contain other PopupMenu submenus.</para>
|
||||
<note><para>New in Kommander 1.3.</para></note>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<inlinemediaobject><imageobject>
|
||||
<imagedata fileref="toolbox.png" format="PNG" />
|
||||
</imageobject></inlinemediaobject>
|
||||
ToolBox
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A container widget, like TabWidget. It has several pages, each page can hold other widgets.
|
||||
</para>
|
||||
<warning><para>This widget has an editor bug that does not affect it's use in execution, but does affect it's use in the editor. If you try to add pages in the editor it will become unreadable. Don't do this. If you want to use the ToolBox please use fill the widget on the fly using the <command>addWidget</command> command. If there is time an example will be added to the 1.3 release, or check the web site.</para></warning>
|
||||
<para>See the QToolBox documentation to learn more about it.</para>
|
||||
<note><para>New in Kommander 1.3.</para></note>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
</variablelist>
|
||||
</sect1>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 637 B |
@ -0,0 +1,3 @@
|
||||
KDE_LANG = en
|
||||
KDE_DOCS = AUTO
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
@ -0,0 +1,37 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<sect1 id="callstack">
|
||||
<sect1info>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Keith</firstname>
|
||||
<surname>Isdale</surname>
|
||||
<affiliation>
|
||||
<address><email>k_isdale@tpg.com.au</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
</authorgroup>
|
||||
</sect1info>
|
||||
|
||||
<title>Working With the Callstack</title>
|
||||
|
||||
<para>
|
||||
All call stack items found are listed here. The older the callstack entry
|
||||
the lower the frame number it will have. See below for an example.</para>
|
||||
|
||||
<screenshot>
|
||||
<screeninfo>The Callstack Window</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="callstack_window.png" format="PNG" />
|
||||
</imageobject>
|
||||
<textobject><phrase>The Callstack Window</phrase></textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
|
||||
<para>
|
||||
Clicking on a callstack entry in the list shown will cause the cursor in
|
||||
the main window to move to the file and line number indicated.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 615 B |
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
@ -0,0 +1,44 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<chapter id="credits-and-licenses">
|
||||
<chapterinfo>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Keith</firstname>
|
||||
<surname>Isdale</surname>
|
||||
<affiliation>
|
||||
<address><email>k_isdale@tpg.com.au</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
</authorgroup>
|
||||
</chapterinfo>
|
||||
<title>Credits and Licenses</title>
|
||||
|
||||
<para>&kxsldbg; © 2004 Keith Isdale</para>
|
||||
<para>Documentation © 2004 Keith Isdale</para>
|
||||
|
||||
|
||||
<itemizedlist>
|
||||
<title>Thanks to:</title>
|
||||
<listitem>
|
||||
<para>
|
||||
The writers the <application>libxml</application> and
|
||||
<application>libxslt</application>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Robert Jacolin for feedback on earlier version of &kxsldbg;.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Igor Zlatkovic for creating WIN32 binaries of
|
||||
<application>libxml/xslt</application> and &xsldbg;.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
&underFDL;
|
||||
&underGPL;
|
||||
|
||||
</chapter>
|
||||
@ -0,0 +1,42 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<sect1 id="entities">
|
||||
<sect1info>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Keith</firstname>
|
||||
<surname>Isdale</surname>
|
||||
<affiliation>
|
||||
<address><email>k_isdale@tpg.com.au</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
</authorgroup>
|
||||
</sect1info>
|
||||
<title>Working With &XML; Data Files (Entities)</title>
|
||||
|
||||
<para> If the inspector dialog is not showing use the <menuchoice>
|
||||
<guimenu>Tools</guimenu> <guimenuitem>Show inspectors</guimenuitem>
|
||||
</menuchoice> menu item. To work with entities click on the
|
||||
<guilabel>Entities</guilabel> tab of dialog shown. </para>
|
||||
|
||||
<para> All external &XML; entities included via the DATA file or one
|
||||
of its siblings are listed here. For this example I have run &kxsldbg;
|
||||
on <filename>testdoc.xsl</filename> with
|
||||
<filename>testdoc.xml</filename> (found in the
|
||||
<filename role="directory"><KDE PREFIX>/share/apps/kxsldbg</filename> folder so that you can see some entities.</para>
|
||||
|
||||
<screenshot>
|
||||
<screeninfo>The Entities Window</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="entities_window.png" format="PNG" />
|
||||
</imageobject>
|
||||
<textobject><phrase>The Entities Window</phrase></textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
|
||||
<para>
|
||||
Clicking on a entity entry in the list shown will cause the cursor in the
|
||||
main window to move to the start of the file indicated.
|
||||
</para>
|
||||
</sect1>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 855 B |
@ -0,0 +1,47 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<glossary id="glossary">
|
||||
<glossaryinfo>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Keith</firstname>
|
||||
<surname>Isdale</surname>
|
||||
<affiliation>
|
||||
<address><email>k_isdale@tpg.com.au</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
</authorgroup>
|
||||
</glossaryinfo>
|
||||
|
||||
<glossdiv>
|
||||
<title>Keywords</title>
|
||||
<glossentry id="xsldbg-glosref">
|
||||
<glossterm>&xsldbg;</glossterm>
|
||||
<glossdef>
|
||||
<para>
|
||||
See <ulink url="http://xsldbg.sourceforge.net"></ulink>.
|
||||
</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>XPath</glossterm>
|
||||
<glossdef>
|
||||
<para>
|
||||
A valid expression that defines what data is required. See
|
||||
<ulink url="http://www.w3.org">W3C web site</ulink>.
|
||||
</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
|
||||
<glossentry>
|
||||
<glossterm>QName</glossterm>
|
||||
<glossdef>
|
||||
<para>
|
||||
A fully qualified name. For example, <emphasis>xsl:myvariable</emphasis>.
|
||||
See <ulink url="http://www.w3.org">W3C web site</ulink>
|
||||
</para>
|
||||
</glossdef>
|
||||
</glossentry>
|
||||
</glossdiv>
|
||||
</glossary>
|
||||
@ -0,0 +1,150 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
|
||||
<!ENTITY kxsldbg "<application>KXSLDbg</application>">
|
||||
<!ENTITY kappname "&kxsldbg;">
|
||||
<!ENTITY package "quanta">
|
||||
<!ENTITY % addindex "IGNORE">
|
||||
<!ENTITY % English "INCLUDE">
|
||||
<!ENTITY configure-section SYSTEM "kxsldbg_configure.docbook">
|
||||
<!ENTITY mainwindow-section SYSTEM "kxsldbg_mainwindow.docbook">
|
||||
<!ENTITY inspector-section SYSTEM "kxsldbg_inspector.docbook">
|
||||
<!ENTITY tools-section SYSTEM "kxsldbg_tools.docbook">
|
||||
<!ENTITY credits-chapter SYSTEM "credits.docbook">
|
||||
<!ENTITY callstack SYSTEM "callstack.docbook">
|
||||
<!ENTITY entities SYSTEM "entities.docbook">
|
||||
<!ENTITY sources SYSTEM "sources.docbook">
|
||||
<!ENTITY templates SYSTEM "templates.docbook">
|
||||
<!ENTITY variables SYSTEM "variables.docbook">
|
||||
<!ENTITY xsldbg "<application>xsldbg</application>">
|
||||
<!ENTITY DTD "<acronym>DTD</acronym>">
|
||||
<!ENTITY XSD "<acronym>XSD</acronym>">
|
||||
<!ENTITY XSLT "<acronym>XSLT</acronym>">
|
||||
]>
|
||||
|
||||
<book lang="&language;">
|
||||
|
||||
<bookinfo>
|
||||
<title>The &kxsldbg; Handbook</title>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Keith</firstname>
|
||||
<surname>Isdale</surname>
|
||||
<affiliation>
|
||||
<address><email>k_isdale@tpg.com.au</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
|
||||
</authorgroup>
|
||||
|
||||
<copyright>
|
||||
<year>2002</year>
|
||||
<year>2003</year>
|
||||
<year>2004</year>
|
||||
<holder>Keith Isdale</holder>
|
||||
</copyright>
|
||||
|
||||
<legalnotice>&FDLNotice;</legalnotice>
|
||||
<date>2004-11-18</date>
|
||||
<releaseinfo>0.5</releaseinfo>
|
||||
|
||||
<abstract>
|
||||
<para>
|
||||
&kxsldbg; is a provides a graphic user interface front-end to
|
||||
&xsldbg;, which supports
|
||||
debugging of &XSLT; scripts.
|
||||
</para>
|
||||
</abstract>
|
||||
|
||||
<keywordset>
|
||||
<keyword>KDE</keyword>
|
||||
<keyword>xsldbg</keyword>
|
||||
<keyword>libxslt</keyword>
|
||||
<keyword>debugger</keyword>
|
||||
</keywordset>
|
||||
</bookinfo>
|
||||
|
||||
<chapter id="introduction">
|
||||
<title>Introduction</title>
|
||||
|
||||
<sect1 id="features">
|
||||
<title>Features</title>
|
||||
|
||||
<para>
|
||||
&kxsldbg; provides access to most of &xsldbg;'s commands to
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Set and modify breakpoints
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Display value of XPaths
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Display information about the templates, variables,
|
||||
callstack entries, stylesheets and entities present
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Set and modify breakpoints and variables
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Move around &XSL; source and &XML; document via XPaths
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Lookup PUBLIC and SYSTEM ID's in the current &XML; catalog
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="new-features">
|
||||
<title>Recently added features</title>
|
||||
<para>&kxsldbg; can now
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Set and modify variables
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Renders the text in the main window using the &kate; libraries
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
|
||||
|
||||
</chapter>
|
||||
|
||||
<chapter id="using-kxsldbg">
|
||||
<title>Using &kxsldbg;</title>
|
||||
&configure-section;
|
||||
&mainwindow-section;
|
||||
&inspector-section;
|
||||
&variables;
|
||||
&callstack;
|
||||
&templates;
|
||||
&sources;
|
||||
&entities;
|
||||
&tools-section;
|
||||
</chapter>
|
||||
|
||||
&credits-chapter;
|
||||
|
||||
</book>
|
||||
@ -0,0 +1,102 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<sect1 id="configure">
|
||||
<sect1info>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Keith</firstname>
|
||||
<surname>Isdale</surname>
|
||||
<affiliation>
|
||||
<address><email>k_isdale@tpg.com.au</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
</authorgroup>
|
||||
</sect1info>
|
||||
|
||||
<title>Configuring a &kxsldbg; Session</title>
|
||||
|
||||
<para>
|
||||
You start configuration by clicking
|
||||
<menuchoice>
|
||||
<guimenu>Debug</guimenu>
|
||||
<guimenuitem>Configure</guimenuitem>
|
||||
</menuchoice> in the Menubar.
|
||||
</para>
|
||||
|
||||
<screenshot>
|
||||
<screeninfo>The Configuration Dialog</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="configure_window.png" format="PNG" />
|
||||
</imageobject>
|
||||
<textobject><phrase>The Configuration Dialog</phrase></textobject>
|
||||
<caption><para>The Configuration Dialog.</para></caption>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
|
||||
<sect2>
|
||||
<title>Getting Started</title>
|
||||
|
||||
<para>
|
||||
To be able to run a stylesheet you need to specify the:
|
||||
<itemizedlist mark="bullet">
|
||||
<listitem><para>&XSL; source</para></listitem>
|
||||
<listitem><para>&XML; data</para></listitem>
|
||||
<listitem><para>Output file</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para> By using the <guibutton>...</guibutton> button to choose file
|
||||
desired. The <guilabel>&XSL; source</guilabel> and <guilabel>>&XML; data</guilabel> may refer
|
||||
to URI that contains a http://, ftp:// or file://. The <guilabel>Output file</guilabel>
|
||||
must refer to a writable local file.</para>
|
||||
<para>
|
||||
To follow along with the examples, select the following files in the
|
||||
example <filename role="directory"><KDE PREFIX>/share/apps/kxsldbg</filename> folder
|
||||
<itemizedlist mark="bullet">
|
||||
<listitem><para>&XSL; source: testdoc.xsl</para></listitem>
|
||||
<listitem><para>&XML; data: testdoc.xml</para></listitem>
|
||||
<listitem><para>Output file: /tmp/xsldbg_output.txt</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Working With Options</title>
|
||||
|
||||
<para>
|
||||
You can select zero or more options from the <guilabel>Options</guilabel> dialog. Each option has a tooltip with a hint on what effect it has.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Working With Parameters</title>
|
||||
|
||||
<para>
|
||||
You can add zero or more parameters via the <guilabel>LibXSLT Parameters</guilabel>
|
||||
section of dialog. This allows you to provide parameter values to the
|
||||
stylesheet.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For example you could add a enter a <guilabel>Parameter name</guilabel> of <parameter>myparam</parameter>
|
||||
with a <guilabel>Parameter value</guilabel> of <parameter>'Hello World!'</parameter> and click the <guibutton>Add</guibutton> button.
|
||||
. To update the value of an existing
|
||||
parameter just use the navigate to the value you wish to change with the <guibutton>Prev</guibutton> or <guibutton>Next</guibutton> button, provide a new <guilabel>Parameter value</guilabel> then click the <guibutton>Apply</guibutton>.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Apply Changes</title>
|
||||
|
||||
<para>
|
||||
For the changes you have made to take effect press the <guibutton>Apply</guibutton>
|
||||
button. To ignore any changes press the <guibutton>Cancel</guibutton> button.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can close the dialog using the <guibutton>X</guibutton> provided at the top right of the window. If you need to change the configuration just re-open the
|
||||
configuration dialog as shown before.
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
@ -0,0 +1,103 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<sect1 id="breakpoints">
|
||||
<sect1info>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Keith</firstname>
|
||||
<surname>Isdale</surname>
|
||||
<affiliation>
|
||||
<address><email>k_isdale@tpg.com.au</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
</authorgroup>
|
||||
</sect1info>
|
||||
<title>Setting and Modifying Breakpoints</title>
|
||||
|
||||
<para>
|
||||
The primary way to work with breakpoints is via the main window. See
|
||||
<xref linkend="mainwindow-section"/>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Once you have started the style sheet, you can use the
|
||||
<menuchoice>
|
||||
<guimenu>Tools</guimenu>
|
||||
<guimenuitem>Show inspectors</guimenuitem>
|
||||
</menuchoice>
|
||||
menu item. Then click on the Breakpoints tab. See below for an example.
|
||||
</para>
|
||||
|
||||
<screenshot>
|
||||
<screeninfo>Setting Breakpoints</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="breakpoints_window.png" format="PNG" />
|
||||
</imageobject>
|
||||
<textobject><phrase>Setting Breakpoints</phrase></textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
|
||||
<sect2>
|
||||
<title>Adding a Breakpoint</title>
|
||||
|
||||
<para>
|
||||
You can add a breakpoint by supplying any of:</para>
|
||||
<orderedlist>
|
||||
<listitem><para>a file and line number</para>
|
||||
</listitem>
|
||||
<listitem><para>a template name</para>
|
||||
</listitem>
|
||||
<listitem><para>a template name and a mode name</para>
|
||||
</listitem>
|
||||
<listitem><para>a mode name</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
|
||||
<para>
|
||||
And then pressing the <guibutton>Add</guibutton> button.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Argument Details</title>
|
||||
|
||||
<para>
|
||||
A file name may be absolute path to a local file. Or partial file (⪚
|
||||
<filename>xsldoc.xsl</filename>).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A template or mode name may is fully Qualified Name where the non-local
|
||||
part is optional ⪚ <emphasis>xsl:mytemplate</emphasis> is matched by
|
||||
<emphasis>mytemplate</emphasis>
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Deleting a Breakpoint</title>
|
||||
|
||||
<para>
|
||||
Firstly left mouse click the breakpoint you want to delete in the list of
|
||||
current breakpoints. Then click the <guibutton>Delete</guibutton> button.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Deleting All Breakpoints</title>
|
||||
|
||||
<para>
|
||||
Click the <guibutton>Delete All</guibutton> button.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Enabling or Disabling a Breakpoint</title>
|
||||
|
||||
<para>
|
||||
Firstly &LMB; click the breakpoint you want to delete in the list of
|
||||
current breakpoints. Then click the <guibutton>Enable</guibutton> button.
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
@ -0,0 +1,455 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<sect1 id="mainwindow-section">
|
||||
<sect1info>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Keith</firstname>
|
||||
<surname>Isdale</surname>
|
||||
<affiliation>
|
||||
<address><email>k_isdale@tpg.com.au</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
</authorgroup>
|
||||
</sect1info>
|
||||
<title>Using the Main Window</title>
|
||||
|
||||
<screenshot>
|
||||
<screeninfo>The Main Window</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="main_window.png" format="PNG"/>
|
||||
</imageobject>
|
||||
<textobject><phrase>A text view of the current file being debugged</phrase></textobject>
|
||||
<caption><para>A text view of the current file being debugged.</para></caption>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
|
||||
<sect2>
|
||||
<title>Working With the Main Window</title>
|
||||
|
||||
<para>
|
||||
The state of a given breakpoint is indicated via the relevant text with a different background color.
|
||||
You can choose the color desired: see the
|
||||
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
|
||||
Editor</guimenuitem></menuchoice> dialog, on the
|
||||
<guilabel>Colors</guilabel> page.</para>
|
||||
|
||||
|
||||
<para>You can set, disable or delete a breakpoint using keys, the <guimenu>Debug</guimenu> menu or the buttons on the tool bar.</para>
|
||||
|
||||
<para>You can move the cursor around the text using the following keys:</para>
|
||||
|
||||
<simplelist>
|
||||
<member>Arrow keys: <keysym>Left Arrow</keysym>, <keysym>Right Arrow</keysym>, <keysym>Up Arrow</keysym> or <keysym>Down Arrow</keysym>.</member>
|
||||
<member>Page keys: <keycap>Page Up</keycap> or <keycap>Page Down</keycap></member>
|
||||
|
||||
</simplelist>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Working With &kxsldbg; Output</title>
|
||||
|
||||
<para>
|
||||
Most of the output from &kxsldbg; is captured and presented either in the
|
||||
inspectors dialog or the &kxsldbg; output window. The exceptions to this rule
|
||||
are:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>An error message that comes from &kxsldbg; is displayed inside a message dialog.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The result of evaluating an expression is displayed in a message dialog.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>The output of search is sent to the file indicated in the &kxsldbg; output window.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</sect2>
|
||||
|
||||
<!-- FIXME: There's way too many things wrong with this, for people to
|
||||
bother translating it just yet. We can fix post 3.2
|
||||
|
||||
Specifically: Wrong icon images, all keybindings are incorrect, all
|
||||
keybindings in the app are unmodified and therefore will probably be
|
||||
changed, and this isn't the ideal place to put a toolbar ref anyway.
|
||||
|
||||
Plan: Add a menu ref chapter, include an updated toolbar ref in it
|
||||
|
||||
<sect2>
|
||||
<title>&kxsldbg; Toolbar</title>
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guiicon>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="configure.png" format="PNG" />
|
||||
</imageobject>
|
||||
</inlinemediaobject>
|
||||
</guiicon>
|
||||
<guimenu>Debug</guimenu>
|
||||
<guimenuitem>Configure</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Configuration for a session, <xref linkend="configure"/>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guiicon>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="configure.png" />
|
||||
</imageobject>
|
||||
</inlinemediaobject>
|
||||
</guiicon>
|
||||
<guimenu>Debug</guimenu>
|
||||
<guimenuitem>Inspect</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
To be written.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guiicon>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="run.png" />
|
||||
</imageobject>
|
||||
</inlinemediaobject>
|
||||
</guiicon>
|
||||
<guimenu>Debug</guimenu>
|
||||
<guimenuitem>Run</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Restart execution applying current configuration.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guiicon>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="1downarrow.png" />
|
||||
</imageobject>
|
||||
</inlinemediaobject>
|
||||
</guiicon>
|
||||
<guimenu>Debug</guimenu>
|
||||
<guimenuitem>Continue</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Continue execution stoping at next breakpoint. This will cause the
|
||||
debugger to stop at the start of the stylesheet if no further breakpoints
|
||||
are found.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guiicon>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="step.png" />
|
||||
</imageobject>
|
||||
</inlinemediaobject>
|
||||
</guiicon>
|
||||
<guimenu>Debug</guimenu>
|
||||
<guimenuitem>Step</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Step to the next XSLT instruction found.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guiicon>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="next.png" />
|
||||
</imageobject>
|
||||
</inlinemediaobject>
|
||||
</guiicon>
|
||||
<guimenu>Debug</guimenu>
|
||||
<guimenuitem>Next</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Proceed to the next instruction at the same call stack depth. This is
|
||||
useful for stepping over a <emphasis>xsl:apply-templates</emphasis> or
|
||||
<emphasis>xsl:call-template</emphasis>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guiicon>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="xsldbg_stepup.png" />
|
||||
</imageobject>
|
||||
</inlinemediaobject>
|
||||
</guiicon>
|
||||
<guimenu>Debug</guimenu>
|
||||
<guimenuitem>StepUp</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Proceed to the next instruction in a cooler stack frame. This is best
|
||||
used within a template at a greater depth than the root match template.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guiicon>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="xsldbg_stepdown.png" />
|
||||
</imageobject>
|
||||
</inlinemediaobject>
|
||||
</guiicon>
|
||||
<guimenu>Debug</guimenu>
|
||||
<guimenuitem>StepDown</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Proceed to the next instruction in a warmer stack frame.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guiicon>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="xsldbg_break.png" />
|
||||
</imageobject>
|
||||
</inlinemediaobject>
|
||||
</guiicon>
|
||||
<guimenu>Debug</guimenu>
|
||||
<guimenuitem>Break</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Add a breakpoint at the current cursor location
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guiicon>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="xsldbg_delete.png" />
|
||||
</imageobject>
|
||||
</inlinemediaobject>
|
||||
</guiicon>
|
||||
<guimenu>Debug</guimenu>
|
||||
<guimenuitem>Delete</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Delete a breakpoint at the current cursor location
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guiicon>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="xsldbg_enable.png" />
|
||||
</imageobject>
|
||||
</inlinemediaobject>
|
||||
</guiicon>
|
||||
<guimenu>Debug</guimenu>
|
||||
<guimenuitem>Enable/Disable</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Enable or disable a breakpoint at the current cursor location
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guiicon>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="xsldbg_source.png" />
|
||||
</imageobject>
|
||||
</inlinemediaobject>
|
||||
</guiicon>
|
||||
<guimenu>Debug</guimenu>
|
||||
<guimenuitem>Source</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Cause the current XSLT source file to be shown
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guiicon>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="xsldbg_data.png" />
|
||||
</imageobject>
|
||||
</inlinemediaobject>
|
||||
</guiicon>
|
||||
<guimenu>Debug</guimenu>
|
||||
<guimenuitem>Data</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Cause the current &XML; data file to be shown
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guiicon>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="xsldbg_output.png" />
|
||||
</imageobject>
|
||||
</inlinemediaobject>
|
||||
</guiicon>
|
||||
<guimenu>Debug</guimenu>
|
||||
<guimenuitem>Output</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Cause the current Output file to be shown
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guiicon>
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="xsldbg_refresh.png" />
|
||||
</imageobject>
|
||||
</inlinemediaobject>
|
||||
</guiicon>
|
||||
<guimenu>Debug</guimenu>
|
||||
<guimenuitem>Reload</guimenuitem>
|
||||
</menuchoice>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Cause the displayed file to be reloaded from disk
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</sect2>
|
||||
-->
|
||||
|
||||
</sect1>
|
||||
@ -0,0 +1,93 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<sect1 id="tools-section">
|
||||
<sect1info>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Keith</firstname>
|
||||
<surname>Isdale</surname>
|
||||
<affiliation>
|
||||
<address><email>k_isdale@tpg.com.au</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
</authorgroup>
|
||||
</sect1info>
|
||||
|
||||
<title>Miscellenous Tools</title>
|
||||
|
||||
<para>
|
||||
Several tools are available via the tools menu the main tool is the
|
||||
inspector tool.
|
||||
</para>
|
||||
|
||||
<sect2>
|
||||
<title>Inspector Tool</title>
|
||||
|
||||
<para>
|
||||
The inspector tool is the contains all the individual dialogs for working
|
||||
with:</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>Breakpoints</para></listitem>
|
||||
<listitem><para>Templates</para></listitem>
|
||||
<listitem><para>Variables</para></listitem>
|
||||
<listitem><para>Callstack entries</para></listitem>
|
||||
<listitem><para>&XSL; source files</para></listitem>
|
||||
<listitem><para>&XML; Enties</para></listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Execute by Walking</title>
|
||||
|
||||
<para>By clicking on <guimenuitem>Start execution with
|
||||
walking</guimenuitem> menu a dialog is shown to allow the walk speed
|
||||
to be chosen.</para>
|
||||
|
||||
<screenshot>
|
||||
<screeninfo>The Walk Window</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="walk_window.png" format="PNG"/>
|
||||
</imageobject>
|
||||
<textobject><phrase>The Walk Window</phrase></textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
|
||||
<para>To stop walking either use the <keycap>W</keycap> key or select the
|
||||
<guimenuitem>Start execution with walking</guimenuitem> menu item.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Lookup &XML; Entities</title>
|
||||
|
||||
<para>To lookup a System ID in the current &XML; catalog
|
||||
use the <guimenuitem>Lookup System ID</guimenuitem> menu then enter the
|
||||
value to find the the dialog that displays.</para>
|
||||
|
||||
<screenshot>
|
||||
<screeninfo>The System ID Window</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="systemid_window.png" format="PNG"/>
|
||||
</imageobject>
|
||||
<textobject><phrase>The System ID Window</phrase></textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
|
||||
<para>To lookup a PUBLIC ID use the <guimenuitem>Lookup Public
|
||||
ID</guimenuitem> menu entry then enter the value to find the the dialog that
|
||||
displays.</para>
|
||||
|
||||
<screenshot>
|
||||
<screeninfo>The Public ID Window</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="publicid_window.png" format="PNG"/>
|
||||
</imageobject>
|
||||
<textobject><phrase>The Public ID Window</phrase></textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
|
||||
</sect2>
|
||||
</sect1>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 42 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 235 B |
Binary file not shown.
|
After Width: | Height: | Size: 10 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 740 B |
@ -0,0 +1,44 @@
|
||||
<sect1 id="sources-section">
|
||||
<sect1info>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Keith</firstname>
|
||||
<surname>Isdale</surname>
|
||||
<affiliation>
|
||||
<address><email>k_isdale@tpg.com.au</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
</authorgroup>
|
||||
</sect1info>
|
||||
<title>Working With &XSLT; Source Files (Sources)</title>
|
||||
|
||||
<para>
|
||||
If the inspector dialog is not showing use the
|
||||
<menuchoice>
|
||||
<guimenu>Tools</guimenu>
|
||||
|
||||
<guimenuitem>Show inspectors</guimenuitem>
|
||||
</menuchoice>
|
||||
menu item. To work with sources click on the sources tab of dialog shown.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All &XSLT; source files that are included by the &XSLT; file or one of its
|
||||
siblings are listed here.</para>
|
||||
|
||||
<screenshot>
|
||||
<screeninfo>The Sources Window</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="sources_window.png" format="PNG" />
|
||||
</imageobject>
|
||||
<textobject><phrase>The Sources Window</phrase></textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
|
||||
<para>
|
||||
Clicking on a source entry in the list shown will cause the cursor in the
|
||||
main window to move to the start of file indicated.
|
||||
</para>
|
||||
</sect1>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 473 B |
Binary file not shown.
|
After Width: | Height: | Size: 10 KiB |
@ -0,0 +1,34 @@
|
||||
<sect1 id="templates">
|
||||
<title>Working With Templates</title>
|
||||
|
||||
<para>
|
||||
If the inspector dialog is not showing use the
|
||||
<menuchoice>
|
||||
<guimenu>Tools</guimenu>
|
||||
<guimenuitem>Show inspectors</guimenuitem>
|
||||
</menuchoice>
|
||||
menu item. To work with templates click on the templates tab of dialog
|
||||
shown.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All templates found are listed here. Please note that the export rules of
|
||||
&XSLT; apply. So only there may be more than one template with the same
|
||||
match and mode details.</para>
|
||||
|
||||
<screenshot>
|
||||
<screeninfo>The Templates Window</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="templates_window.png" format="PNG"/>
|
||||
</imageobject>
|
||||
<textobject><phrase>The Templates Window</phrase></textobject>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
|
||||
<para>
|
||||
Clicking on a template entry in the list shown will cause the cursor in
|
||||
the main window to move to the file and line number indicated.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
@ -0,0 +1,69 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<sect1 id="variables">
|
||||
<sect1info>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Keith</firstname>
|
||||
<surname>Isdale</surname>
|
||||
<affiliation>
|
||||
<address><email>k_isdale@tpg.com.au</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
</authorgroup>
|
||||
</sect1info>
|
||||
|
||||
<title>Working With Variables</title>
|
||||
|
||||
<para>
|
||||
If the inspector dialog is not showing use the
|
||||
<menuchoice>
|
||||
<guimenu>Tools</guimenu>
|
||||
<guimenuitem>Show inspectors</guimenuitem>
|
||||
</menuchoice>
|
||||
menu item.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Local and global variables are show in a tab on the inspector dialog.
|
||||
The following example shows a XSLT code segment that declares a global and a local variable
|
||||
</para>
|
||||
<informalexample>
|
||||
<programlisting>
|
||||
<xsl:variable name="globalvariable" select="'foo'"/>
|
||||
|
||||
<xsl:template match="/"/>
|
||||
<xsl:param name="localvariable" select="'bar'"/>
|
||||
</xsl:template match="/"/>
|
||||
</programlisting>
|
||||
</informalexample>
|
||||
<para>
|
||||
Clicking with with mouse on a variable in the list will cause summary
|
||||
information to be displayed in the bottom of the dialog. If a variable has
|
||||
a select expression, for example
|
||||
</para>
|
||||
<informalexample>
|
||||
<programlisting>
|
||||
<xsl:variable name="changeable" select="'oldValue'" />
|
||||
</programlisting>
|
||||
</informalexample>
|
||||
<para>
|
||||
then a new XPath an be choosen by entering a new value
|
||||
for <guilabel>Variable expression</guilabel> then clicking the <guibutton>Set expression</guibutton> button.</para>
|
||||
|
||||
<screenshot>
|
||||
<screeninfo>The Variables tab</screeninfo>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="variables_window.png" format="PNG" />
|
||||
</imageobject>
|
||||
<textobject><phrase>The Variables Tab</phrase></textobject>
|
||||
<caption><para>The Variables Tab</para></caption>
|
||||
</mediaobject>
|
||||
</screenshot>
|
||||
|
||||
<para>
|
||||
Clicking on a variable entry in the list shown will cause the cursor in
|
||||
the main window to move to the file and line number indicated.
|
||||
</para>
|
||||
</sect1>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 221 B |
Binary file not shown.
|
After Width: | Height: | Size: 243 B |
Binary file not shown.
|
After Width: | Height: | Size: 228 B |
Binary file not shown.
|
After Width: | Height: | Size: 336 B |
Binary file not shown.
|
After Width: | Height: | Size: 120 B |
Binary file not shown.
|
After Width: | Height: | Size: 232 B |
Binary file not shown.
|
After Width: | Height: | Size: 231 B |
Binary file not shown.
|
After Width: | Height: | Size: 137 B |
Binary file not shown.
|
After Width: | Height: | Size: 195 B |
@ -0,0 +1,3 @@
|
||||
KDE_LANG = en
|
||||
KDE_DOCS = $(package)
|
||||
KDE_MANS = AUTO
|
||||
@ -0,0 +1,623 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
|
||||
<chapter id="advanced-quanta-3-2">
|
||||
<chapterinfo>
|
||||
<title>Advanced Features</title>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Christopher</firstname>
|
||||
<surname>Hornbaker</surname>
|
||||
<affiliation>
|
||||
<address><email>chrishornbaker@earthlink.net</email></address>
|
||||
</affiliation>
|
||||
|
||||
</author>
|
||||
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
|
||||
</authorgroup>
|
||||
</chapterinfo>
|
||||
|
||||
<title>Advanced Features</title>
|
||||
|
||||
<para>
|
||||
This chapter outlines the advanced features of &quantaplus; and how to use
|
||||
them.
|
||||
</para>
|
||||
|
||||
<sect1 id="xml-tools-3-2">
|
||||
<title>&XML; Tools</title>
|
||||
|
||||
<para>
|
||||
The 3.2 release of &quantaplus; brings with it many new &XML; tools and
|
||||
features. The tools are unique in their integration within &quantaplus;.
|
||||
All of these tools use <application>Kommander</application> as a front-end and
|
||||
<application>libxml2</application> and <application>libxslt</application>
|
||||
as a back-end. The combination of these makes for fast, efficient,
|
||||
productive, and complete tools.
|
||||
</para>
|
||||
|
||||
<sect2 id="kde-db-3-2">
|
||||
<title>&kde; Documentation Tools</title>
|
||||
|
||||
<para>
|
||||
&quantaplus; supports &kde;'s two main documentation tools:
|
||||
<command>meinproc</command> and <command>checkXML</command>.
|
||||
</para>
|
||||
|
||||
<sect3 id="meinproc-3-2">
|
||||
<title><command>meinproc</command></title>
|
||||
|
||||
<para>
|
||||
Anyone who has worked with &kde; documentation knows
|
||||
<command>meinproc</command> and how superb it is. Well, take it up a notch
|
||||
with a great graphical interface! No longer resort to a shell; just click
|
||||
the icon that resembles a processor and you are done!
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><guilabel>Current Working Folder</guilabel></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This application expects an <filename>index.docbook</filename>
|
||||
file to be present in a folder. If <filename>index.docbook</filename>
|
||||
is in the current working folder, then simply leave <guilabel>Current Working
|
||||
Folder</guilabel> checked. If it is not, then uncheck <guilabel>Current Working Folder</guilabel>
|
||||
and enter the folder you wish to process in the <guilabel>Other Folder</guilabel> field.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
Outputted files are placed in the same folder as the sources files.
|
||||
All &HTML; files are removed each time
|
||||
<command>meinproc</command> is ran.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
</sect3>
|
||||
|
||||
<sect3 id="checkxml-3-2">
|
||||
<title><command>checkXML</command></title>
|
||||
|
||||
<para>
|
||||
Again, anyone who has worked with &kde; documentation knows this
|
||||
helpful application. Again, &quantaplus; provides a great little graphical
|
||||
front-end to this one.
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><guilabel>Current Working Folder</guilabel></term>
|
||||
<listitem>
|
||||
<para>
|
||||
If the currently opened file is the <filename>index.docbook</filename>
|
||||
file, then simply leave <guilabel>Current Working Folder</guilabel> checked.
|
||||
If it is not, then uncheck <guilabel>Current Working Folder</guilabel> and
|
||||
enter the folder of where <filename>index.docbook</filename> can be found.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<note>
|
||||
<title>Output</title>
|
||||
<para>
|
||||
If there is output, then your file is invalid. Please correct the reported
|
||||
errors and try again.
|
||||
</para>
|
||||
</note>
|
||||
</sect3>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="xmlval-3-2">
|
||||
<title>&XML; Validation</title>
|
||||
|
||||
<para>
|
||||
&quantaplus; has a great &XML; validation tool, which uses a
|
||||
<command>xmllint</command> back-end.
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><guilabel>Current File</guilabel></term>
|
||||
<listitem>
|
||||
<para>
|
||||
If the file to be validated is currently focused on in &quantaplus;, then
|
||||
simply leave <guilabel>Current File</guilabel> checked. If it is not, then
|
||||
uncheck <guilabel>Current File</guilabel> and select the file to be
|
||||
validated from the Other File file selector.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><guilabel>Well-formed Checking</guilabel></term>
|
||||
<listitem>
|
||||
<para>
|
||||
If you only wish to know only if the file is well-formed, click the
|
||||
<guilabel>Well-formed Checking Only</guilabel> check box.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><guilabel>Definition &URI;</guilabel></term>
|
||||
<listitem>
|
||||
<para>
|
||||
If you are using a &DTD; and it is specified within the &XML; file, then
|
||||
select &DTD; (Internal) (default), else select &DTD; (External) and locate
|
||||
the &DTD; with the Definition &URI; file selector. Both &W3C; &XML;
|
||||
Schema and RelaxNG validation are required to be
|
||||
externally defined via the <guilabel>Definition &URI;</guilabel> file selector.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="xsltproc-3-2">
|
||||
<title>&XSL; Processing</title>
|
||||
|
||||
<para>
|
||||
Yep, &quantaplus; has a &XSL; processing tool, too! This uses the
|
||||
<command>xsltproc</command> tool provided with
|
||||
<application>libxml2</application>.
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><guilabel>Current File</guilabel></term>
|
||||
<listitem>
|
||||
<para>
|
||||
If the file to be processed is currently focused on in &quantaplus;, then
|
||||
simply leave <guilabel>Current File</guilabel> checked. If it is not,
|
||||
then uncheck <guilabel>Current File</guilabel> and select the file to be
|
||||
processed from the <guilabel>Other File</guilabel> selector.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>Stylesheet</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Select the &XSL; file that you wish to be used.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><guilabel>Output file name</guilabel></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Enter the name of the file that you want the resulting file to be called.
|
||||
File is outputed to your home folder by default.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
This application lacks flexibility. Sorry, we will do better next time.
|
||||
</para>
|
||||
</note>
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
<!-- <sect1 id="kfilereplace-3-2">
|
||||
<title>KFileReplace</title>
|
||||
|
||||
<para>
|
||||
KFileReplace is a terrific new addition to &quantaplus;. It allows one to
|
||||
quickly replace strings over multiple files in only a few clicks of the
|
||||
mouse. Imagine you have converted all your GIF images to PNG images
|
||||
(hasn't everyone done this already?), only the extension has changed, and
|
||||
you have the <img /> tag scattered throughout 50 XHTML files. Are you
|
||||
going to do a Find & Replace on every file? Surely not when you can do
|
||||
them all at the same time! This is only one of the many situations where
|
||||
you will find KFileReplace a seriously helpful tool. This section will show
|
||||
you how to use this wonderful feature.
|
||||
</para>
|
||||
|
||||
<sect2 id="using-kfr-3-2">
|
||||
<title>Using KFileReplace</title>
|
||||
|
||||
<para>
|
||||
With all these wonderful features KFileReplace has, surely you are
|
||||
incredibly interested in how to use it! Well, make sure your swim suit
|
||||
is on tight, because we are about to dive in!
|
||||
</para>
|
||||
|
||||
<sect3 id="start-kfr-3-2">
|
||||
<title>Starting KFileReplace</title>
|
||||
|
||||
<para>
|
||||
You will find KFileReplace in two places: &quantaplus;' main toolbar and the
|
||||
menubar (Plugins -> KFileReplace). It is represented by this icon:
|
||||
<inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="kfr-icon.png" format="PNG" />
|
||||
</imageobject>
|
||||
</inlinemediaobject>.
|
||||
By executing it from either location, you will be presented with the New
|
||||
Search & Replace Project dialog.
|
||||
</para>
|
||||
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="kfr-new-dialog.png" format="PNG" />
|
||||
</imageobject>
|
||||
<caption><para>KFileReplace's New Search & Replace Project dialog.</para></caption>
|
||||
</mediaobject>
|
||||
|
||||
</sect3>
|
||||
|
||||
<sect3 id="replace-string-kfr-3-2">
|
||||
<title>Replacing Strings in Files Over Multiple Folders</title>
|
||||
|
||||
|
||||
<para>
|
||||
Your boss just gave word that:
|
||||
|
||||
<orderedlist numeration="arabic">
|
||||
<listitem>
|
||||
<para>all image formats will be PNG from now on;</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>all current images must be converted to PNG;</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>and it all needs to be done in one hour.</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
<quote>One hour!?!?</quote> you think to yourself. <quote>It'll take at
|
||||
least 45 minutes to convert the images!</quote> Calm down. Convert
|
||||
the images, load up your project, and fire up KFileReplace. Filter for
|
||||
only the file types you want to change. Press the <inlinemediaobject>
|
||||
<imageobject><imagedata format="PNG" fileref="" /></imageobject>
|
||||
</inlinemediaobject> and for, say GIF images, .gif for the string to
|
||||
replace and .png for the replacement string.
|
||||
</para>
|
||||
|
||||
</sect3>
|
||||
</sect2>
|
||||
</sect1> -->
|
||||
|
||||
<sect1 id="kparts-3-2">
|
||||
<sect1info>
|
||||
<title>Using Plugins</title>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Mathieu</firstname>
|
||||
<surname>Kooiman</surname>
|
||||
<affiliation>
|
||||
<address><email>quanta@map-is.nl</email></address>
|
||||
</affiliation>
|
||||
</author>
|
||||
|
||||
<!-- TRANS:ROLES_OF_TRANSLATORS -->
|
||||
|
||||
</authorgroup>
|
||||
</sect1info>
|
||||
|
||||
<title>Using Plugins</title>
|
||||
|
||||
<sect2 id="what-is-a-plugin-3-2">
|
||||
<title>What is a Plugin?</title>
|
||||
|
||||
<para>
|
||||
&quantaplus; is able to load plugins, which are KParts. The
|
||||
KPart framework is another very powerfull framework of &kde;. A KPart is a
|
||||
relatively small, reusable container of functionality. It allows &kde;
|
||||
developers to easily build on the work of other programmers. One
|
||||
example of this is &quantaplus; itself. The editor &quantaplus; uses is
|
||||
the &kate; KPart. The &kate; KPart already had a bunch of functionality that
|
||||
&quantaplus; needed, like syntax highlighting. Integrating it into
|
||||
&quantaplus; allowed the &quantaplus; developers to focus on what
|
||||
&quantaplus; should be able to do, rather than facing the many problems
|
||||
that developing a new editor KPart/component from scratch would bring.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The plugins &quantaplus; loads might have nothing to do with &quantaplus;
|
||||
itself. This makes it a very powerful plugin system. You can benefit from
|
||||
extra functionality and need not to wait until someone integrates it into
|
||||
&quantaplus;! The plugins can be loaded into a number of &GUI; elements.
|
||||
More on this below.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2 id="plugin-dialog-3-2">
|
||||
<title>Understanding the Edit Plugin Dialog</title>
|
||||
|
||||
<para>To install a Plugin or KPart we will work from the
|
||||
<menuchoice>
|
||||
<guimenu>Plugins</guimenu>
|
||||
<guimenuitem>Edit</guimenuitem>
|
||||
</menuchoice> menu. This will bring up the following dialog:
|
||||
</para>
|
||||
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata format="PNG" fileref="plugin-edit.png" />
|
||||
</imageobject>
|
||||
<caption><para>The Edit Plugin dialog.</para></caption>
|
||||
</mediaobject>
|
||||
|
||||
<para>
|
||||
This dialog lets you manage all defined plugins and lets you add new ones.
|
||||
We will describe each &GUI; element in here:
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><guilabel>Search paths</guilabel></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Here you can fill in a search path. When adding a plugin without a
|
||||
<guilabel>Location</guilabel>, &quantaplus; will search these paths to
|
||||
find the plugin.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><guilabel>Add</guilabel></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This will bring up a dialog which allows you to add a new plugin.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><guilabel>Configure</guilabel></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This will allow you to change the settings of a particular plugin.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><guilabel>Remove</guilabel></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Removes the currently selected plugin.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><guilabel>Refresh</guilabel></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Refreshes the dialog's contents.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
<para>Read <xref linkend="configure-plugins" /> to learn more about plugins.</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1 id="team-members">
|
||||
<title>Team Development</title>
|
||||
<para>Often a project has more than one people working on it and there is some kind of hierarchical relationsship between them. &quantaplus; supports the notion of team members and they are configurable in the
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Shift;<keycap>F7</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Project</guimenu>
|
||||
<guimenuitem>Project Properties</guimenuitem>
|
||||
</menuchoice> dialog.
|
||||
</para>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata format="PNG" fileref="team-editing.png" />
|
||||
</imageobject>
|
||||
<caption><para>The team member editor dialog</para></caption>
|
||||
</mediaobject>
|
||||
<para>
|
||||
The <guilabel>Name</guilabel>, <guilabel>Email</guilabel> entries are self explaining. <guilabel>Nickname</guilabel> is the nick of the user and acts as an unique identifier.
|
||||
</para>
|
||||
<para><guilabel>Role</guilabel> specifies the role of the member in the project and can be one of the following:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
<guilabel>Team leader</guilabel>
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<guilabel>Subproject Leader</guilabel>
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<guilabel>Task Leader</guilabel>
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
<guilabel>Simple Member</guilabel>
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
<para><guilabel>Task</guilabel> is a description of the task assigned to this member.</para>
|
||||
<para><guilabel>Subproject</guilabel>: you can select a list of subproject. Subprojects can be configured and created by pressing the <guilabel>Edit subprojects</guilabel> button. Each subproject has a user visible name and a location entry, the later specifying a relative path to a directory under the project tree. This means that a subproject is a directory under the main project. For example the main project can be the website of your company, while a subproject can be the website for the intranet, located under the <filename path="intranet">intranet</filename> folder in the project.</para>
|
||||
<para>One member can have more than one role in the project, like both team leader and subproject leader.</para>
|
||||
<para>The user should select who is himself from the list of the team members. This is possible by selecting a team member from the list and pressing the <guilabel>Set to Yourself</guilabel> button. The currently selected member (your identity) appears in bold after the <guilabel>You are:</guilabel> text.</para>
|
||||
<para>Nicknames and setting yourself is important regarding messaging and annotations. See <xref linkend="annotations"/> to learn more about annotations.</para>
|
||||
<para>Aside of keeping track of your team, there is one more benefit of setting up the team members: you can configure an event to inform the team leaders when some action happens. See <xref linkend="event-actions"/> about how to do it.</para>
|
||||
</sect1>
|
||||
<sect1 id="event-actions">
|
||||
<title>Event Actions</title>
|
||||
<para>Event actions are actions executed when some event happens in the project. An example would be logging when the project was opened and closed, so it can be later reviewed how much one worked on it, or sending a mail when a file is saved, or adding the file to the CVS with the help of a script when the file is added to the project and the list could continue.</para>
|
||||
<para>On the <guilabel>Event Configuration</guilabel> page of the
|
||||
<menuchoice>
|
||||
<shortcut>
|
||||
<keycombo action="simul">&Shift;<keycap>F7</keycap></keycombo>
|
||||
</shortcut>
|
||||
<guimenu>Project</guimenu>
|
||||
<guimenuitem>Project Properties</guimenuitem>
|
||||
</menuchoice> dialog you can create, edit and delete the event actions.
|
||||
</para>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata format="PNG" fileref="event-editing.png" />
|
||||
</imageobject>
|
||||
<caption><para>The event editor dialog</para></caption>
|
||||
</mediaobject>
|
||||
<para>The entries in the dialog are:</para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><guilabel>Event</guilabel></term>
|
||||
<listitem><para>the action is executed when the event selected from the list happens. The event names are self explanatory.</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><guilabel>Action</guilabel></term>
|
||||
<listitem><para>
|
||||
the type of the executed action. The possible choices are
|
||||
</para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><guilabel>Non-script action</guilabel></term>
|
||||
<listitem><para>an action that is not a user defined script action. See <xref linkend="user-actions" /> for user action.
|
||||
</para>
|
||||
<para><guilabel>Action name</guilabel> specifies the action to be executed when the event happens.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><guilabel>Send email</guilabel></term>
|
||||
<listitem><para>an email is sent when the action happens to the recipient selected in the <guilabel>Receiver</guilabel> list. The recipient can be a team or subproject leader. See <xref linkend="team-members" /> for defining such leaders.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><guilabel>Log event</guilabel></term>
|
||||
<listitem><para>the event is logged in a file. The arguments for this action are:
|
||||
</para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><guilabel>Log file</guilabel></term>
|
||||
<listitem><para>the filename with full path</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>Detail</term>
|
||||
<listitem><para>How much information will the log contain</para></listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><guilabel>Behavior</guilabel></term>
|
||||
<listitem><para>Whether to create/overwrite the existing log file or append the new logged event to it.</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</listitem>
|
||||
</varlistentry
|
||||
>
|
||||
<varlistentry>
|
||||
<term><guilabel>Script action</guilabel></term>
|
||||
<listitem><para>an user defined script action. See <xref linkend="user-actions" /> for user action.
|
||||
</para>
|
||||
<para><guilabel>Action name</guilabel> specifies the action to be executed when the event happens.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<para>The other entries depend on the <guilabel>Action</guilabel> type as they were described.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="annotations">
|
||||
<title>Annotations</title>
|
||||
<para>Annotations are special comments in the documents. They differ from regular comments by the following things:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
the information is collected by Quanta and shown in the <guilabel>Annotations</guilabel> toolview.
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
the information can be addressed to a team member
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
<para>Entering annotations is simple. You can either use the <guilabel>Annotate</guilabel> entry from the editor context menu or enter the <emphasis>@annotation</emphasis> keyword in a comment area followed by the annotation text.
|
||||
<example><title>Annotation example in XML</title><screen>
|
||||
<!-- @annotation It is possible that this code is wrong. --></screen>
|
||||
<screen>
|
||||
<!-- @annotation
|
||||
Multiline
|
||||
annotation.
|
||||
--></screen></example>
|
||||
<example><title>Annotation example in PHP</title><screen>
|
||||
/* @annotation
|
||||
Use PHP comments when annotating a PHP area
|
||||
*/</screen>
|
||||
|
||||
</example>
|
||||
</para>
|
||||
<para>Annotations can be addressed for a specific member of your team. The syntax in this case is <emphasis>@annotation(nickname)</emphasis> or <emphasis>@annotation(role)</emphasis>, where <emphasis>nickname</emphasis> is the nickname of a team member, while <emphasis>role</emphasis> is a project role from the following items:
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
team leader
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
task leader
|
||||
</para></listitem>
|
||||
<listitem><para>
|
||||
subproject leader
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
The task and subproject leaders should be followed by the corresponding task and subproject name, like it is shown in the below examples.
|
||||
</para>
|
||||
<para>
|
||||
<example><title>Make a note to a team member with the nickname <emphasis>eric</emphasis></title>
|
||||
<screen><-- @annotation(eric) Eric, please look at this. Andras --></screen>
|
||||
</example>
|
||||
<example><title>Inform the team leader</title>
|
||||
<screen><-- @annotation(team leader) This is very important for the team --></screen>
|
||||
</example>
|
||||
<example><title>Inform the <emphasis>PHP</emphasis> subproject leader</title>
|
||||
<screen>// @annotation(subproject leader:PHP) What do you think about it?</screen>
|
||||
</example>
|
||||
</para>
|
||||
<para>Nicknames and role names are case insensitive, but spaces around brackets and the <emphasis>:</emphasis> make the annotation invalid.</para>
|
||||
<para>More about team members, roles and nicknames can be found in <xref linkend="team-members"/>.</para>
|
||||
<para>
|
||||
The annotations found in the project can be inspected in the <guilabel>Annotations</guilabel> view. It consists of tree tabs:
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><guilabel>Current File</guilabel></term>
|
||||
<listitem><para>
|
||||
The annotation found in the current file.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><guilabel>For You</guilabel></term>
|
||||
<listitem><para>
|
||||
Annotations in the project addressed for you. The entries are groupped per file.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><guilabel>All Files</guilabel></term>
|
||||
<listitem><para>
|
||||
The annotations found in all the project files, groupe dy files
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
The annotations are scanned on project and file load for external modifications. This way even is somebody adds an annotation outside of &quantaplus;, it will be recognized. As scanning can take some time, the information dialog about new annotations addressed for you might appear after some seconds of the project loading.
|
||||
</para>
|
||||
</sect1>
|
||||
<!--<sect1 id="cvs-3-2">
|
||||
<title>Using CVS</title>
|
||||
|
||||
<para>
|
||||
&quantaplus; uses Cervisia for CVS. Explain its usage within &quantaplus;.
|
||||
</para>
|
||||