<commit_before>\documentclass[a4paper]{howto}

% BIG FAT NOTICE: I hacked verbatim.perl to avoid it wrapping my
% verbatiminputs in <BR>s (no idea why it does that). The diff is as
% follows:
%
% --- verbatim.perl.orig  Sat Oct 12 14:14:15 2002
% +++ verbatim.perl       Sat Oct 12 14:14:17 2002
% @@ -110,7 +110,7 @@
%         $env_id .= ' CLASS="verbatim"' unless ($env_id =
% /(^|\s)CLASS\s*\=/i);
%         $verb_pre =~ s/>/ $env_id>/;
%      }
% -    join('', $closures, "<BR>\n", $verb_pre
% +    join('', $closures, "\n", $verb_pre
%         , $verbatim_mark, 'verbatim', $global{'verbatim_counter'}
%         , '#', $verb_post, $reopens, $outer);
%  }
%
% Generating docs without this mod will cause verbatim stuff to look
% like crap, you have been warned.
%
% Oh, and the image scales are correct. Don't mess with them, it takes a
% lot of time to discover the right ones. And yes, I copy over the
% original pngs over the generated ones; look at the Makefile.

\usepackage{verbatim}
\usepackage{graphicx}

\title{Developing applications with Kiwi}

\release{1.9.9}

\author{<NAME>\\<NAME>\\Async Open Source, Brazil}
\authoraddress{<EMAIL>\\<EMAIL>\\http://www.async.com.br/projects/kiwi/}
\date{August, 2006}

\begin{document}
\maketitle

\begin{abstract}
\noindent
{\bf Kiwi is a library designed to make developing graphical
applications as easy as possible}. It targets developers that work with
{\bf Python} and that are looking for a way to produce applications with
good design without a lot of bureaucracy.  It offers both a framework
and a set of enhanced widgets, and is based on Python and PyGTK. Kiwi
borrows concepts from MVC, Swing and Microsoft MFC, but implements a set
of unique classes that take advantage of the flexibility and simplicity
of Python and GTK+ to make real-world application creation much easier.
In practice, code using Kiwi will be shorter, simpler and easier to
maintain than raw PyGTK, and just browsing through the examples in this
guide and in the package should give you a good idea of how.

{\bf Kiwi includes a framework and a set of enhanced widgets}. There is
\citetitle[http://www.async.com.br/projects/kiwi/api/]{complete API
documentation} to accompany the library, and this paper covers the
Framework in detail, providing examples, screenshots and advice on
designing your application.

All you need to use Kiwi is Python and PyGTK. Gazpacho is a useful add-on,
and is strongly recommended. Kiwi's free software licensed under the LGPL
and can be used and embedded in any application.
\end{abstract}

\section{Kiwi: An Overview}

\textbf{Kiwi} is a Python module for developing graphical applications.
While most free software projects that support programming of graphical
interfaces concentrate on low-level infrastructure and components, Kiwi
provides a high-level framework that helps developers organize their
code and develop applications quickly, removing the need to do a lot of
low-level work to get basic functionality implemented. The framework
allows you to easily write applications that look like this:

\begin{center}
\includegraphics[scale=0.626]{images/diary.eps}

\small{(This example application, \file{examples/framework/diary/diary2.py}, has
65 lines, not counting the XML specification)}
\end{center}

\subsection{Introduction}
For many platforms, graphical applications are developed based on an
application framework that is provided by the platform. For Java we have
Swing (and AWT); for Windows we have MFC (and a number of others). In
general, these frameworks include a set of widgets that are used
natively.

<NAME>'s
\citetitle[http://www.pygtk.org/]{PyGTK}, an excellent
set of \citetitle[http://www.gtk.org/]{GTK+} bindings for
\citetitle[http://www.python.org/]{Python}, supports graphical programs
written in Python, but it offers only a set of widgets, not a framework;
you have to do all the work of organizing your application yourself.
{\bf Kiwi wraps PyGTK to offer both a framework to organize your
application, and a set of enhanced widgets} that can be used either from
the framework or directly in your application. You can use as much or as
little of it as you like.

A framework (in the object-oriented programming sense) is a set of
general purpose classes that work together to provide a base upon which
an application is built. Kiwi is a white-box framework; to use this type
of framework, you inherit and customize one or more classes, instantiate
them, and run it. In Kiwi, a high-level class that controls a window,
for instance, is called \class{BaseView}, and it provides a method
called \function{show\_and\_loop()} that renders it and starts the event
processing upon which all GTK+ (and therefore Kiwi) applications are
based.  The Kiwi framework includes a number of classes that can be
adapted to your specific needs, and they are described further in the
next section.

Kiwi is based on the real-world experience of using Python and GTK+
(through PyGTK) to develop a fairly large application,
\citetitle[http://www.stoq.com.br/]{Stoq}, which uses many concepts
common to most graphical applications: multiple windows and dialogs,
forms, data persistence, lists and high-level classes that support
domain objects directly.

\subsection{Why Use Kiwi?}

You should use Kiwi if you develop a graphical software application
where Python is an option. Python is in my opinion the nicest of
the popular high-level languages available today, and I honestly
recommend all new applications be developed in a high-level language
for many reasons; ease of maintenance, speed of implementation and
security being the most important in my experience.

Kiwi implements a number of interesting tweaks to the standard MVC (or
MV+C) architecture, which is the base of most application frameworks
that exist out there, and a lot of research has gone into the framework
and the widgets to make development as convenient as possible. It goes
way beyond providing a basic `document plus view' schema, doing widget
conversion, automatic signal connection, and adjusting behavior
automatically to reduce drastically the amount of code needed to define
the windows and dialogs for your application. Kiwi also includes native
gazpacho support, which allows you to graphically specify (using
Gazpacho, the UI designer) your user interfaces and use them seamlessly
as part of the framework.

The code used in Kiwi has been developed with quite a lot of care, and
though it is complex in parts (even crufty in a few spots), we consider
it to be generally easy to understand and change, and you can hijack and
customize the code to your need if you feel you don't want YAD (yet
another dependency) for your application.

Kiwi is also being actively developed and supported as a building block
in Stoq, and over the past years has grown to become very useful.
We welcome feedback and have been very fast to respond to requests and
bug reports, so you can be sure your application will be relying a
library that is actively supported and that its authors have a
continued interest in maintaining.

\subsection{Getting and Installing Kiwi}

Kiwi is distributed through its official website, at
\url{http://www.async.com.br/projects/kiwi/}. It is released as a
tarball frequently, and the tarball is distributed from that page.
Announcements of the release should go out to \code{pygtk-list},
\citetitle[http://freshmeat.net/]{Freshmeat} and \code{python-announce}.

You will need to install the following packages if they are not
already on your system:

\begin{itemize}
  \item  \citetitle[http://www.python.org/]{Python} 2.3 or newer
  \item  \citetitle[http://www.gtk.org/]{GTK+} 2.6
  \item  \citetitle[http://www.pygtk.org]{PyGTK} 2.6
  \item  \citetitle[http://gazpacho.sicem.biz]{PyGTK} 0.6.5
\end{itemize}

Most of these packages are available on the main distributions,
including Fedora, Ubuntu, Debian, Conectiva and Mandrake, and might even be
preinstalled in your system. If not, you can pull the source code,
compile and install them.

% XXX: Add subversion checkout instructions
You can also use SVN to check out Kiwi, by following the instructions on
the \citetitle[http://www.async.com.br/projects/cvs.php]{Async CVS
page}. The module name is \code{kiwi}.
\citetitle[http://svn.async.com.br/cgi-bin/viewcvs.cgi/kiwi/?view=query&dir=&file=&file_match=exact&who=&who_match=exact&querysort=date&hours=2&date=month&mindate=&maxdate=]{Async's
ViewCVS service} can be used to check development of the kiwi module in
real time, and there is also an
\citetitle[http://svn.async.com.br/cgi-bin/viewcvs.cgi/]{browse source} of the code.
Finally, bugs in kiwi should be reported to
\citetitle[http://bugs.async.com.br/]{Async's installation of Bugzilla}.

Kiwi includes a fair amount of tests in the \file{tests/} directory in
the tarball, and they can be run in-place (no need to install it first),
so you can easily see what sort of application it supports.

Since Kiwi uses Distutils, installing Kiwi should be very simple.  Once
you have installed the dependent packages, run (as root, normally):

    \begin{verbatim}
    python setup.py install
    \end{verbatim}

in the main directory. That's it. To test the installation, do:
<commit_msg>add one more XXX<commit_after>\documentclass[a4paper]{howto}

% BIG FAT NOTICE: I hacked verbatim.perl to avoid it wrapping my
% verbatiminputs in <BR>s (no idea why it does that). The diff is as
% follows:
%
% --- verbatim.perl.orig  Sat Oct 12 14:14:15 2002
% +++ verbatim.perl       Sat Oct 12 14:14:17 2002
% @@ -110,7 +110,7 @@
%         $env_id .= ' CLASS="verbatim"' unless ($env_id =
% /(^|\s)CLASS\s*\=/i);
%         $verb_pre =~ s/>/ $env_id>/;
%      }
% -    join('', $closures, "<BR>\n", $verb_pre
% +    join('', $closures, "\n", $verb_pre
%         , $verbatim_mark, 'verbatim', $global{'verbatim_counter'}
%         , '#', $verb_post, $reopens, $outer);
%  }
%
% Generating docs without this mod will cause verbatim stuff to look
% like crap, you have been warned.
%
% Oh, and the image scales are correct. Don't mess with them, it takes a
% lot of time to discover the right ones. And yes, I copy over the
% original pngs over the generated ones; look at the Makefile.

\usepackage{verbatim}
\usepackage{graphicx}

\title{Developing applications with Kiwi}

\release{1.9.9}

\author{<NAME>\\<NAME>\\Async Open Source, Brazil}
\authoraddress{<EMAIL>\\<EMAIL>\\http://www.async.com.br/projects/kiwi/}
\date{August, 2006}

\begin{document}
\maketitle

\begin{abstract}
\noindent
{\bf Kiwi is a library designed to make developing graphical
applications as easy as possible}. It targets developers that work with
{\bf Python} and that are looking for a way to produce applications with
good design without a lot of bureaucracy.  It offers both a framework
and a set of enhanced widgets, and is based on Python and PyGTK. Kiwi
borrows concepts from MVC, Swing and Microsoft MFC, but implements a set
of unique classes that take advantage of the flexibility and simplicity
of Python and GTK+ to make real-world application creation much easier.
In practice, code using Kiwi will be shorter, simpler and easier to
maintain than raw PyGTK, and just browsing through the examples in this
guide and in the package should give you a good idea of how.

{\bf Kiwi includes a framework and a set of enhanced widgets}. There is
\citetitle[http://www.async.com.br/projects/kiwi/api/]{complete API
documentation} to accompany the library, and this paper covers the
Framework in detail, providing examples, screenshots and advice on
designing your application.

All you need to use Kiwi is Python and PyGTK. Gazpacho is a useful add-on,
and is strongly recommended. Kiwi's free software licensed under the LGPL
and can be used and embedded in any application.
\end{abstract}

\section{Kiwi: An Overview}

\textbf{Kiwi} is a Python module for developing graphical applications.
While most free software projects that support programming of graphical
interfaces concentrate on low-level infrastructure and components, Kiwi
provides a high-level framework that helps developers organize their
code and develop applications quickly, removing the need to do a lot of
low-level work to get basic functionality implemented. The framework
allows you to easily write applications that look like this:

\begin{center}
\includegraphics[scale=0.626]{images/diary.eps}

\small{(This example application, \file{examples/framework/diary/diary2.py}, has
65 lines, not counting the XML specification)}
\end{center}

\subsection{Introduction}
For many platforms, graphical applications are developed based on an
application framework that is provided by the platform. For Java we have
Swing (and AWT); for Windows we have MFC (and a number of others). In
general, these frameworks include a set of widgets that are used
natively.

<NAME>'s
\citetitle[http://www.pygtk.org/]{PyGTK}, an excellent
set of \citetitle[http://www.gtk.org/]{GTK+} bindings for
\citetitle[http://www.python.org/]{Python}, supports graphical programs
written in Python, but it offers only a set of widgets, not a framework;
you have to do all the work of organizing your application yourself.
{\bf Kiwi wraps PyGTK to offer both a framework to organize your
application, and a set of enhanced widgets} that can be used either from
the framework or directly in your application. You can use as much or as
little of it as you like.

A framework (in the object-oriented programming sense) is a set of
general purpose classes that work together to provide a base upon which
an application is built. Kiwi is a white-box framework; to use this type
of framework, you inherit and customize one or more classes, instantiate
them, and run it. In Kiwi, a high-level class that controls a window,
for instance, is called \class{BaseView}, and it provides a method
called \function{show\_and\_loop()} that renders it and starts the event
processing upon which all GTK+ (and therefore Kiwi) applications are
based.  The Kiwi framework includes a number of classes that can be
adapted to your specific needs, and they are described further in the
next section.

Kiwi is based on the real-world experience of using Python and GTK+
(through PyGTK) to develop a fairly large application,
\citetitle[http://www.stoq.com.br/]{Stoq}, which uses many concepts
common to most graphical applications: multiple windows and dialogs,
forms, data persistence, lists and high-level classes that support
domain objects directly.

\subsection{Why Use Kiwi?}

You should use Kiwi if you develop a graphical software application
where Python is an option. Python is in my opinion the nicest of
the popular high-level languages available today, and I honestly
recommend all new applications be developed in a high-level language
for many reasons; ease of maintenance, speed of implementation and
security being the most important in my experience.

Kiwi implements a number of interesting tweaks to the standard MVC (or
MV+C) architecture, which is the base of most application frameworks
that exist out there, and a lot of research has gone into the framework
and the widgets to make development as convenient as possible. It goes
way beyond providing a basic `document plus view' schema, doing widget
conversion, automatic signal connection, and adjusting behavior
automatically to reduce drastically the amount of code needed to define
the windows and dialogs for your application. Kiwi also includes native
gazpacho support, which allows you to graphically specify (using
Gazpacho, the UI designer) your user interfaces and use them seamlessly
as part of the framework.

The code used in Kiwi has been developed with quite a lot of care, and
though it is complex in parts (even crufty in a few spots), we consider
it to be generally easy to understand and change, and you can hijack and
customize the code to your need if you feel you don't want YAD (yet
another dependency) for your application.

Kiwi is also being actively developed and supported as a building block
in Stoq, and over the past years has grown to become very useful.
We welcome feedback and have been very fast to respond to requests and
bug reports, so you can be sure your application will be relying a
library that is actively supported and that its authors have a
continued interest in maintaining.

\subsection{Getting and Installing Kiwi}

Kiwi is distributed through its official website, at
\url{http://www.async.com.br/projects/kiwi/}. It is released as a
tarball frequently, and the tarball is distributed from that page.
Announcements of the release should go out to \code{pygtk-list},
\citetitle[http://freshmeat.net/]{Freshmeat} and \code{python-announce}.

You will need to install the following packages if they are not
already on your system:

\begin{itemize}
  \item  \citetitle[http://www.python.org/]{Python} 2.3 or newer
  \item  \citetitle[http://www.gtk.org/]{GTK+} 2.6
  \item  \citetitle[http://www.pygtk.org]{PyGTK} 2.6
  \item  \citetitle[http://gazpacho.sicem.biz]{PyGTK} 0.6.5
\end{itemize}

Most of these packages are available on the main distributions,
including Fedora, Ubuntu, Debian, Conectiva and Mandrake, and might even be
preinstalled in your system. If not, you can pull the source code,
compile and install them.

% XXX: Add subversion checkout instructions
You can also use SVN to check out Kiwi, by following the instructions on
the \citetitle[http://www.async.com.br/projects/cvs.php]{Async CVS
page}. The module name is \code{kiwi}.
\citetitle[http://svn.async.com.br/cgi-bin/viewcvs.cgi/kiwi/?view=query&dir=&file=&file_match=exact&who=&who_match=exact&querysort=date&hours=2&date=month&mindate=&maxdate=]{Async's
ViewCVS service} can be used to check development of the kiwi module in
real time, and there is also an
\citetitle[http://svn.async.com.br/cgi-bin/viewcvs.cgi/]{browse source} of the code.
Finally, bugs in kiwi should be reported to
\citetitle[http://bugs.async.com.br/]{Async's installation of Bugzilla}.

Kiwi includes a fair amount of tests in the \file{tests/} directory in
the tarball, and they can be run in-place (no need to install it first),
so you can easily see what sort of application it supports.

Since Kiwi uses Distutils, installing Kiwi should be very simple.  Once
you have installed the dependent packages, run (as root, normally):

% XXX: --prefix and non root installation

    \begin{verbatim}
    python setup.py install
    \end{verbatim}

in the main directory. That's it. To test the installation, do:

{'fraction_non_alphanumeric': 0.0755939524838013, 'fraction_numerical': 0.006155507559395248, 'mean_word_length': 4.4537691401648996, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 21, 'https://': 0, 'lorem ipsum': 0, 'www.': 22, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3569681', 'n_tokens_mistral': 5355, 'n_tokens_neox': 5070, 'n_words': 2555}