doc/gtk.ref.texi

   1 @menu
   2 * Gtk+ Main loop::
   3 * Widgets::
   4 * Gtk+ Interfaces::
   5 * Gtk+ Objects::
   6 * Gtk+ Structs::
   7 * Gtk+ Enums::
   8 * Gtk+ Flags::
   9 * Gtk+ Embedded UI Mini-language::
  10 @end menu
  11
  12 All symbols of Gtk+ binding in cl-gtk2 reside in @code{gtk} package.
  13
  14 @node Gtk+ Main loop
  15 @chapter Gtk+ Main loop
  16
  17 @include gtk.main_loop.texi
  18
  19 @node Widgets
  20 @chapter Widgets
  21
  22 @include gtk.widgets.texi
  23
  24 @node Gtk+ Interfaces
  25 @chapter Gtk+ Interfaces
  26
  27 @include gtk.interfaces.texi
  28
  29 @node Gtk+ Objects
  30 @chapter Gtk+ Objects
  31
  32 @include gtk.objects.texi
  33
  34 @node Gtk+ Structs
  35 @chapter Gtk+ Structs
  36
  37 @include gtk.structs.texi
  38
  39 @node Gtk+ Enums
  40 @chapter Gtk+ Enums
  41
  42 @include gtk.enums.texi
  43
  44 @node Gtk+ Flags
  45 @chapter Gtk+ Flags
  46
  47 @include gtk.flags.texi
  48
  49 @node Gtk+ Embedded UI Mini-language
  50 @chapter Gtk+ Embedded UI Mini-language
  51
  52 For convenience of specifying widgets hierarchy in Lisp code, the @ref{let-ui} macro is introduced.
  53
  54 @RMacro let-ui
  55 @lisp
  56 (let-ui ui-description &body body)
  57
  58 ui-description ::= widget
  59 widget ::= (class properties child*)
  60 properties ::= @{:prop-name prop-value@}*
  61 child ::= widget properties
  62 child ::= (:expr expr) properties
  63 @end lisp
  64
  65 @table @var
  66 @item @var{class}
  67 Name of class of a widget
  68 @item @var{:prop-name}
  69 Name of class's slot or a @code{:var} for specifying the variable name to which the object will be bound
  70 @item @var{prop-value}
  71 A Lisp expression that will be evaluated to obtain the initarg for slot of a class; or a symbol if @code{:prop-name} is @code{:var}
  72 @item @var{expr}
  73 An expression that will be evaluated to obtain the widget
  74 @end table
  75
  76 This macro creates widgets and evaluates the @var{body}. Widgets that have @code{:var} specified are bound to lexical variables with specified names.
  77
  78 @var{ui-description} specifies the hierarchy of widgets in a window. It can specify either the entire top-level window or other kind of widgets. @var{ui-description} is a mini-language for specifying widgets. @ref{let-ui} creates specified widgets, lexically binds specified variables to widgets and evaluates the @var{body}. The @var{body} my refer to these widgets.
  79
  80 @var{widget} is the specification of a single widget. It may specify some properties (slots of objects) and their values (the expressions to be evaluated), a variable name that will be bound to the widget (the @code{:var} property whose @var{prop-value} must be a symbol) and widget's children.
  81
  82 @var{class} specifies the class of the widget (e.g., @ref{label}, @ref{button}, @ref{gtk-window}). @var{:prop-name} may be any slot of the class. If @var{:var} property is specified, then corresponding variable is accessible in @var{body} and its value is the widget on which it is specified as @var{:var}.
  83
  84 Container widgets may specify their @var{children} along with their @var{child properties}. Child properties specify how @var{children} are used in @var{widget}. They are specific to the type of the container:
  85 @itemize
  86 @item @ref{box} specifies @code{:expand}, @code{:fill}. See @ref{box-pack-start} for information.
  87 @item @ref{paned} specifies @code{:resize}, @code{:shrink}. See @ref{paned-pack-1} for information.
  88 @item @ref{table} specifies @code{:left}, @code{:right}, @code{:top}, @code{:bottom}, @code{:x-options}, @code{:y-options}, @code{x-padding}, @code{y-padding}. Of these, @code{:left}, @code{:right}, @code{:top} and @code{:bottom} are mandatory. See @ref{table-attach} for information.
  89 @end itemize
  90
  91 An example:
  92 @lisp
  93 (let-ui (gtk-window :title "Hello" :position :center :var w
  94                     (v-box
  95                      (label :label "Hello, world!")
  96                      (button :label "gtk-ok" :use-stock t) :expand nil))
  97   (widget-show w))
  98 @end lisp
  99 produces this output:
 100
 101 @image{let-ui,,,,png}
 102
 103 More complex example from demo of cl-gtk2-gtk-glext:
 104 @lisp
 105 (let-ui (v-paned :var v
 106                  (:expr (opengl-window-drawing-area window))
 107                  :resize t :shrink nil
 108                  (v-box
 109                   (h-paned
 110                    (scrolled-window
 111                     :hscrollbar-policy :automatic
 112                     :vscrollbar-policy :automatic
 113                     (:expr (opengl-window-expose-fn-text-view window)))
 114                    :resize t :shrink nil
 115                    (scrolled-window
 116                     :hscrollbar-policy :automatic
 117                     :vscrollbar-policy :automatic
 118                     (:expr (opengl-window-resize-fn-text-view window)))
 119                    :resize t :shrink nil)
 120                   (h-box
 121                    (button :label "Update functions" :var update-fns-button) :expand nil
 122                    (button :label "Redraw" :var redraw-button) :expand nil)
 123                   :expand nil)
 124                  :resize t :shrink nil)
 125   (container-add window v)
 126   (connect-signal update-fns-button "clicked"
 127                   (lambda (b)
 128                     (declare (ignore b))
 129                     (update-fns window)))
 130   (connect-signal redraw-button "clicked"
 131                   (lambda (b)
 132                     (declare (ignore b))
 133                     (widget-queue-draw (opengl-window-drawing-area window))))
 134   (let ((area (opengl-window-drawing-area window)))
 135     (setf (gl-drawing-area-on-expose area)
 136           (lambda (w e)
 137             (declare (ignore w e))
 138             (opengl-interactive-on-expose window))
 139           (gl-drawing-area-on-resize area)
 140           (lambda (widget w h)
 141             (declare (ignore widget))
 142             (opengl-interactive-on-resize window w h)))))
 143 @end lisp
 144 produces this output:
 145
 146 @image{let-ui-glext,,,,png}
 147
 148 In this example, not top-level window, but a widget is created and then added to already existing window. This UI also uses some already created widgets: @code{(:expr (opengl-window-resize-fn-text-view window))}.