doc/gtk.texi

   1 \input texinfo  @c -*-texinfo-*-
   2 @c %**start of header (This is for running texinfo on a region.)
   3 @setfilename gtk.info
   4 @settitle CL-Gtk2
   5 @c %**end of header (This is for running texinfo on a region.)
   6
   7 @c @documentencoding utf-8
   8
   9 @macro Function {name}
  10 @defun \name\
  11 @end defun
  12 @end macro
  13
  14 @macro Macro {name}
  15 @defmac \name\
  16 @end defmac
  17 @end macro
  18
  19 @macro Struct {name}
  20 @deftp {Structure} \name\
  21 @end deftp
  22 @end macro
  23
  24 @macro Class {name}
  25 @deftp {Class} \name\
  26 @end deftp
  27 @end macro
  28
  29 @macro Superclass {name}
  30 Superclass: @ref{\name\}
  31 @end macro
  32
  33 @macro Enum {name}
  34 @deftp {Enum} \name\
  35 @end deftp
  36 @end macro
  37
  38 @macro EnumVRef {name,value}
  39 @ref{enum.\name\.\value\,@code{:\value\}}
  40 @end macro
  41
  42 @macro Flags {name}
  43 @deftp {Flags} \name\
  44 @end deftp
  45 @end macro
  46
  47 @macro FlagsVRef {name,value}
  48 @ref{flags.\name\.\value\,@code{:\value\}}
  49 @end macro
  50
  51 @macro Accessor {name}
  52 @deffn {Accessor} \name\
  53 @end deffn
  54 @end macro
  55
  56 @macro TypedAccessor {name, class, type}
  57 @deffn {Accessor} \name\ \class\
  58 For class: @ref{\class\}
  59
  60 Type: \type\
  61 @end deffn
  62 @end macro
  63
  64 @macro GenericFunction {name}
  65 @deffn {Generic Function} \name\
  66 @end deffn
  67 @end macro
  68
  69 @macro Method {name}
  70 @deffn {Method} \name\
  71 @end deffn
  72 @end macro
  73
  74 @macro ForeignType {name}
  75 @deftp {Foreign Type} \name\
  76 @end deftp
  77 @end macro
  78
  79 @macro Variable {name}
  80 @defvr {Special Variable} \name\
  81 @end defvr
  82 @end macro
  83
  84 @macro Condition {name}
  85 @deftp {Condition Type} \name\
  86 @end deftp
  87 @end macro
  88
  89 @macro Constant {name}
  90 @defvr {Constant} \name\
  91 @end defvr
  92 @end macro
  93
  94 @macro RFunction {name}
  95 @anchor{\name\}@defun \name\
  96 @end defun
  97 @end macro
  98
  99 @macro RMacro {name}
 100 @anchor{\name\}@defmac \name\
 101 @end defmac
 102 @end macro
 103
 104 @macro RStruct {name}
 105 @anchor{\name\}@deftp {Structure} \name\
 106 @end deftp
 107 @end macro
 108
 109 @macro RClass {name}
 110 @anchor{\name\}@deftp {Class} \name\
 111 @end deftp
 112 @end macro
 113
 114 @macro RSuperclass {name}
 115 @anchor{\name\}Superclass: @ref{\name\}
 116 @end macro
 117
 118 @macro REnum {name}
 119 @anchor{\name\}@deftp {Enum} \name\
 120 @end deftp
 121 @end macro
 122
 123 @macro RFlags {name}
 124 @anchor{\name\}@deftp {Flags} \name\
 125 @end deftp
 126 @end macro
 127
 128 @macro RAccessor {name}
 129 @anchor{\name\}@deffn {Accessor} \name\
 130 @end deffn
 131 @end macro
 132
 133 @macro RTypedAccessor {name, class, type}
 134 @anchor{\name\}@deffn {Accessor} \name\ \class\
 135 For class: @ref{\class\}
 136
 137 Type: \type\
 138 @end deffn
 139 @end macro
 140
 141 @macro RGenericFunction {name}
 142 @anchor{\name\}@deffn {Generic Function} \name\
 143 @end deffn
 144 @end macro
 145
 146 @macro RMethod {name}
 147 @anchor{\name\}@deffn {Method} \name\
 148 @end deffn
 149 @end macro
 150
 151 @macro RForeignType {name}
 152 @anchor{\name\}@deftp {Foreign Type} \name\
 153 @end deftp
 154 @end macro
 155
 156 @macro RVariable {name}
 157 @anchor{\name\}@defvr {Special Variable} \name\
 158 @end defvr
 159 @end macro
 160
 161 @macro RCondition {name}
 162 @anchor{\name\}@deftp {Condition Type} \name\
 163 @end deftp
 164 @end macro
 165
 166 @macro RConstant {name}
 167 @anchor{\name\}@defvr {Constant} \name\
 168 @end defvr
 169 @end macro
 170
 171 @macro SlotRef {class, slot}
 172 @ref{slot.\class\.\slot\,\class\-\slot\}
 173 @end macro
 174
 175 @macro SignalRef {class, signal}
 176 @ref{signal.\class\.\signal\,\class\::\signal\}
 177 @end macro
 178
 179 @macro cffi
 180 @acronym{CFFI}
 181 @end macro
 182
 183 @macro impnote {text}
 184 @quotation
 185 @strong{Implementor's note:} @emph{\text\}
 186 @end quotation
 187 @end macro
 188
 189 @c Info "requires" that x-refs end in a period or comma, or ) in the
 190 @c case of @pxref.  So the following implements that requirement for
 191 @c the "See also" subheadings that permeate this manual, but only in
 192 @c Info mode.
 193 @ifinfo
 194 @macro seealso {name}
 195 @ref{\name\}.
 196 @end macro
 197 @end ifinfo
 198
 199 @c @ifnotinfo
 200 @c @alias seealso = ref
 201 @c @end ifnotinfo
 202
 203 @c Typeset comments in roman font for the TeX output.
 204 @c @iftex
 205 @c @alias lispcmt = r
 206 @c @end iftex
 207 @c @ifnottex
 208 @c @alias lispcmt = asis
 209 @c @end ifnottex
 210
 211 @c My copy of makeinfo is not generating any HTML for @result{} for
 212 @c some odd reason. (It certainly used to...)
 213 @ifhtml
 214 @macro result
 215 =>
 216 @end macro
 217 @end ifhtml
 218
 219 @c Similar macro to @result. Its purpose is to work around the fact
 220 @c that &rArr; does not work properly inside @lisp.
 221 @ifhtml
 222 @macro res
 223 @html
 224 &rArr;
 225 @end html
 226 @end macro
 227 @end ifhtml
 228
 229 @ifnothtml
 230 @alias res = result
 231 @end ifnothtml
 232
 233 @c ============================= Macros =============================
 234
 235
 236 @c Show types, functions, and concepts in the same index.
 237 @syncodeindex tp cp
 238 @syncodeindex fn cp
 239
 240 @titlepage
 241 @title CL-GTK2
 242 @subtitle A Common Lisp binding for Gtk+
 243 @author Dmitry Kalyanov
 244 @end titlepage
 245
 246 @contents
 247
 248 @ifnottex
 249 @node Top
 250 @top cl-gtk2-gtk
 251 @end ifnottex
 252
 253 @menu
 254 * Overview::
 255 * Installation::
 256 * GLib Reference::
 257 * GObject Reference::
 258 * Gdk Reference::
 259 * Gtk Reference::
 260 @end menu
 261
 262 @node Overview
 263 @chapter Overview
 264
 265 @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.
 266
 267 As @code{Gtk+} is based on object system GObject, @code{cl-gtk2} is based on a binding to this object system called @code{cl-gtk2-gobject}.
 268
 269 @code{cl-gtk2} provides a thin wrapper around @code{Gtk+} functionality, mostly retaining the same set of classes, properties and methods.
 270
 271 The important parts of @code{Gtk+} are:
 272 @itemize
 273 @item GObject type system
 274 @itemize
 275 @item Classes
 276 @item Objects
 277 @item Signals
 278 @end itemize
 279 @item Events
 280 @item Layout and composition of widgets
 281 @item Widget set
 282 @item Using Gtk+ with threads
 283 @item Building stand-alone applications
 284 @end itemize
 285
 286 @node Installation
 287 @chapter Installation
 288
 289 @code{cl-gtk2} has the following dependencies. They all must be installed before installing @code{cl-gtk2}.
 290
 291 @itemize
 292 @item @uref{http://common-lisp.net/project/cffi/,,CFFI} (version >= 0.10.4)
 293 @item @uref{http://www.cliki.net/trivial-garbage,,Trivial-Garbage} (version >= 0.18)
 294 @item @uref{http://common-lisp.net/project/iterate/,,Iterate} (version >= 1.4.3)
 295 @item @uref{http://common-lisp.net/project/bordeaux-threads/,,Bordeaux-Threads} (version >= 0.6.0)
 296 @item @uref{http://common-lisp.net/project/closer/closer-mop.html,,Closer-MOP} (version >= 0.55)
 297 @item @uref{http://common-lisp.net/project/cl-opengl/,,cl-opengl} (if you intend to use <code>cl-gtk2-cairo</code>)
 298 @item @uref{http://common-lisp.net/project/cl-cairo2/,,cl-cairo2} (if you intend to use <code>cl-gtk2-gtkglext</code>)
 299 @end itemize
 300
 301 At first, source code should be downloded. Current version of CL-GTK2 can be downloaded from @uref{http://common-lisp.net/project/cl-gtk2/files/cl-gtk2-0.1.tar.gz}.
 302
 303 Development tree of CL-GTK2 can be cloned with @uref{http://git-scm.org/,,Git}:
 304 @example
 305 git clone git://repo.or.cz/cl-gtk2.git
 306 @end example
 307 or, using the mirror:
 308 @example
 309 git clone git://github.com/dmitryvk/cl-gtk2.git
 310 @end example
 311
 312 To be able to compile, load and use @code{cl-gtk2}, you should register the @code{ASDF} system definitions.
 313
 314 To do this, either add @code{glib}, @code{gdk} and @code{gtk} directories to @code{asdf:*central-registry*}:
 315 @lisp
 316 (push "/path/to/cl-gtk2/glib" asdf:*central-registry*)
 317 (push "/path/to/cl-gtk2/pango/" asdf:*central-registry*)
 318 (push "/path/to/cl-gtk2/gdk" asdf:*central-registry*)
 319 (push "/path/to/cl-gtk2/gtk" asdf:*central-registry*)
 320 (push "/path/to/cl-gtk2/gtk-glext/" asdf:*central-registry*)
 321 (push "/path/to/cl-gtk2/cairo/" asdf:*central-registry*)
 322 @end lisp
 323 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):
 324 @example
 325 cd ~/.sbcl/systems           # depends on your system
 326 ln -s /path/to/cl-gtk2/glib/cl-gtk2-glib.asd .
 327 ln -s /path/to/cl-gtk2/pango/cl-gtk2-pango.asd .
 328 ln -s /path/to/cl-gtk2/gdk/cl-gtk2-gdk.asd .
 329 ln -s /path/to/cl-gtk2/gtk/cl-gtk2-gtk.asd .
 330 ln -s /path/to/cl-gtk2/gtkglext/cl-gtk2-gtkglext.asd .
 331 ln -s /path/to/cl-gtk2/cairo/cl-gtk2-cairo.asd .
 332 @end example
 333
 334 In Gentoo Linux, it is possible to use layman (see @uref{http://www.gentoo.org/proj/en/overlays/userguide.xml,,Gentoo Overlays Users' Guide}) to add @code{lisp} and @code{cl-gtk2} overlays that contains neccessary ebuilds:
 335 @example
 336 layman -a lisp
 337 layman --overlays=http://github.com/dmitryvk/cl-gtk2-overlay/raw/master/layman-list.xml -a cl-gtk2
 338 emerge cl-gtk2
 339 @end example
 340
 341
 342 @node GLib Reference
 343 @chapter GLib Reference
 344
 345 @lowersections
 346 @include glib.ref.texi
 347 @raisesections
 348
 349 @node GObject Reference
 350 @chapter GObject Reference
 351
 352 @lowersections
 353
 354 @include gobject.ref.texi
 355
 356 @raisesections
 357
 358 @node Gdk Reference
 359 @chapter Gdk Reference
 360
 361 @include gdk.ref.texi
 362
 363 @node Gtk Reference
 364 @chapter Gtk Reference
 365
 366 @lowersections
 367 @include gtk.ref.texi
 368 @raisesections
 369
 370 @bye