doc: added Github mirror

[cl-gtk2.git] / doc / gtk.texi

\input texinfo  @c -*-texinfo-*-
@c %**start of header (This is for running texinfo on a region.)
@setfilename gtk.info
@settitle CL-Gtk2
@c %**end of header (This is for running texinfo on a region.)

@c @documentencoding utf-8

@macro Function {args}
@defun \args\
@end defun
@end macro

@macro Macro {args}
@defmac \args\
@end defmac
@end macro

@macro Struct {args}
@deftp {Structure} \args\
@end deftp
@end macro

@macro Class {name}
@deftp {Class} \name\
@end deftp
@end macro

@macro Superclass {name}
Superclass: @ref{\name\}
@end macro

@macro Enum {args}
@deftp {Enum} \args\
@end deftp
@end macro

@macro Flags {args}
@deftp {Flags} \args\
@end deftp
@end macro

@macro Accessor {args}
@deffn {Accessor} \args\
@end deffn
@end macro

@macro TypedAccessor {name, class, type}
@deffn {Accessor} \name\ \class\
For class: @ref{\class\}

Type: \type\
@end deffn
@end macro

@macro GenericFunction {args}
@deffn {Generic Function} \args\
@end deffn
@end macro

@macro ForeignType {args}
@deftp {Foreign Type} \args\
@end deftp
@end macro

@macro Variable {args}
@defvr {Special Variable} \args\
@end defvr
@end macro

@macro Condition {args}
@deftp {Condition Type} \args\
@end deftp
@end macro

@macro cffi
@acronym{CFFI}
@end macro

@macro impnote {text}
@quotation
@strong{Implementor's note:} @emph{\text\}
@end quotation
@end macro

@c Info "requires" that x-refs end in a period or comma, or ) in the
@c case of @pxref.  So the following implements that requirement for
@c the "See also" subheadings that permeate this manual, but only in
@c Info mode.
@ifinfo
@macro seealso {name}
@ref{\name\}.
@end macro
@end ifinfo

@ifnotinfo
@alias seealso = ref
@end ifnotinfo

@c Typeset comments in roman font for the TeX output.
@iftex
@alias lispcmt = r
@end iftex
@ifnottex
@alias lispcmt = asis
@end ifnottex

@c My copy of makeinfo is not generating any HTML for @result{} for
@c some odd reason. (It certainly used to...)
@ifhtml
@macro result
=>
@end macro
@end ifhtml

@c Similar macro to @result. Its purpose is to work around the fact
@c that ⇒ does not work properly inside @lisp.
@ifhtml
@macro res
@html
⇒
@end html
@end macro
@end ifhtml

@ifnothtml
@alias res = result
@end ifnothtml

@c ============================= Macros =============================


@c Show types, functions, and concepts in the same index.
@syncodeindex tp cp
@syncodeindex fn cp

@titlepage
@title CL-GTK2
@subtitle A Common Lisp binding for Gtk+
@author Dmitry Kalyanov
@end titlepage

@contents

@ifnottex
@node Top
@top cl-gtk2-gtk
@end ifnottex

@menu
* Overview::
* Installation::
* GObject Reference::
* Gdk Reference::
@end menu

@node Overview
@chapter Overview

@code{cl-gtk2} is the GUI library for Common Lisp. @code{cl-gtk2} is based on @uref{http://www.gtk.org/,,Gtk+} GUI library and is Common Lisp binding for it. @code{cl-gtk2} allows you to create graphical user interfaces for Common Lisp applications.

As @code{Gtk+} is based on object system GObject, @code{cl-gtk2} is based on a binding to this object system called @uref{../gobject/index.html,,cl-gtk2-gobject}.

@code{cl-gtk2} provides a thin wrapper around @code{Gtk+} functionality, mostly retaining the same set of classes, properties and methods.

The important parts of @code{Gtk+} are:
@itemize
@item GObject type system
@itemize
@item Classes
@item Objects
@item Signals
@end itemize
@item Events
@item Layout and composition of widgets
@item Widget set
@item Using Gtk+ with threads
@item Building stand-alone applications
@end itemize

@node Installation
@chapter Installation

@code{cl-gtk2} has the following dependencies. They all must be installed before installing @code{cl-gtk2}.

@itemize
@item @uref{http://common-lisp.net/project/cffi/,,CFFI} (version >= 0.10.4)
@item @uref{http://www.cliki.net/trivial-garbage,,Trivial-Garbage} (version >= 0.18)
@item @uref{http://common-lisp.net/project/iterate/,,Iterate} (version >= 1.4.3)
@item @uref{http://common-lisp.net/project/bordeaux-threads/,,Bordeaux-Threads} (version >= 0.6.0)
@item @uref{http://common-lisp.net/project/closer/closer-mop.html,,Closer-MOP} (version >= 0.55)
@end itemize

At first, source code of @code{cl-gtk2} needs to be downloaded. There are two options to download the sources: use @uref{http://git-scm.org/,,Git} or download @code{tar.gz} archive.

To get sources with Git, clone @code{cl-gtk2} repository:
@example
git clone git://repo.or.cz/cl-gtk2.git
@end example
or the mirror:
@example
git clone git://github.com/dmitryvk/cl-gtk2.git
@end example

Or download and unpack the @code{tar.gz}-archived @uref{http://repo.or.cz/w/cl-gtk2.git?a=snapshot;h=HEAD;sf=tgz,,snapshot} of @code{cl-gtk2}.

To be able to compile, load and use @code{cl-gtk2}, you should register the @code{ASDF} system definitions.

To do this, either add @code{glib}, @code{gdk} and @code{gtk} directories to @code{asdf:*central-registry*}:
@lisp
(push "/path/to/cl-gtk2/glib" asdf:*central-registry*)
(push "/path/to/cl-gtk2/gdk" asdf:*central-registry*)
(push "/path/to/cl-gtk2/gtk" asdf:*central-registry*)
@end lisp
or create symlinks to @code{cl-gtk2-glib.asd}, @code{cl-gtk2-gdk.asd} and @code{cl-gtk2-gtk.asd} files in a directory where @code{ASDF} systems are located (it might be @code{/usr/share/common-lisp/systems/} for system-wide installation in Gentoo Linux and Debian Linux, @code{~/.sbcl/systems/} for user installation for SBCL compiler):
@example
cd ~/.sbcl/systems           # depends on your system
ln -s /path/to/cl-gtk2/glib/cl-gtk2-glib.asd .
ln -s /path/to/cl-gtk2/gdk/cl-gtk2-gdk.asd .
ln -s /path/to/cl-gtk2/gtk/cl-gtk2-gtk.asd .
@end example

@node GObject Reference
@chapter GObject Reference

@lowersections

@include gobject.ref.texi

@raisesections

@node Gdk Reference
@chapter Gdk Reference

@include gdk.ref.texi

@bye