@menu
* Gtk+ Main loop::
+* Widgets::
+* Gtk+ Interfaces::
+* Gtk+ Objects::
+* Gtk+ Structs::
+* Gtk+ Enums::
+* Gtk+ Flags::
+* Gtk+ Embedded UI Mini-language::
@end menu
All symbols of Gtk+ binding in cl-gtk2 reside in @code{gtk} package.
@node Gtk+ Main loop
@chapter Gtk+ Main loop
-Gtk+ is an event-driven toolkit and it naturally is built around the event dispatching loop. The Gtk+ Main loop is a @ref{GLib Main loop}. This section describes Gtk+-specific usage of the main loop.
+@include gtk.main_loop.texi
-Gtk+ main loop is run in a background thread that is launched by @ref{ensure-gtk-main} (however it is also possible to launch Gtk+ main loop with @ref{gtk-main} that does not spawn threads). This allows interactive development: while the Gtk+ thread is blocked by waiting for events or processing them, REPL thread is alive.
+@node Widgets
+@chapter Widgets
-Gtk+ is not thread-safe, but thread-aware. This means that any access to Gtk+ from the thread different from the thread running the main loop must be explicitly synchronized with Gtk+. There are two ways to call Gtk+ from another thread:
-@itemize
-@item Use @code{gdk_threads_enter}, @code{gdk_threads_leave}. This is unsupported at this time on cl-gtk2.
-@item Use @ref{within-main-loop} and related macros and functions.
-@end itemize
+@include gtk.widgets.texi
-@RFunction gtk-main
-@lisp
-(gtk-main)
-@end lisp
-This function runs the main loop and returns when the main loop is terminated. (see @ref{gtk-main-quit} and @ref{ensure-gtk-main})
+@node Gtk+ Interfaces
+@chapter Gtk+ Interfaces
-@RFunction gtk-main-quit
-@lisp
-(gtk-main-quit)
-@end lisp
-This function causes the main loop to terminate and causes @ref{gtk-main} to return.
+@include gtk.interfaces.texi
-@RFunction ensure-gtk-main
-@lisp
-(ensure-gtk-main)
-@end lisp
-This function ensures that the Gtk+ main loop is started in background thread. If the loop has not been started or if had been terminated, restarts the background thread.
+@node Gtk+ Objects
+@chapter Gtk+ Objects
-@RFunction join-main-thread
-@lisp
-(join-main-thread)
-@end lisp
-This function waits for the background thread that runs the Gtk+ main loop to quit.
+@include gtk.objects.texi
-@RFunction gtk-main-iteration
-@lisp
-(gtk-main-iteration) @result{} boolean
-@end lisp
-Runs a single iteration of the mainloop. If no events are waiting to be processed Gtk+ will block until the next event is noticed. If you don't want to block look at @ref{gtk-main-iteration-do} or check if any events are pending with @ref{gtk-events-pending} first.
+@node Gtk+ Structs
+@chapter Gtk+ Structs
-Returns a boolean that is true if @ref{gtk-main-quit} has been called for the innermost mainloop.
+@include gtk.structs.texi
-@RFunction gtk-main-iteration-do
-@lisp
-(gtk-main-iteration-do blocking) @result{} boolean
-@end lisp
+@node Gtk+ Enums
+@chapter Gtk+ Enums
-@table @var
-@item @var{blocking}
-True if you want Gtk+ to block if no events are pending
-@end table
+@include gtk.enums.texi
-Runs a single iteration of the mainloop. If no events are available either return or block dependent on the value of @var{blocking}.
+@node Gtk+ Flags
+@chapter Gtk+ Flags
-Returns a boolean that is true if @ref{gtk-main-quit} has been called for the innermost mainloop.
+@include gtk.flags.texi
+@node Gtk+ Embedded UI Mini-language
+@chapter Gtk+ Embedded UI Mini-language
-@RFunction gtk-events-pending
-@lisp
-(gtk-events-pending) @result{} boolean
-@end lisp
-Checks if any events are pending. This can be used to update the GUI and invoke timeouts etc. while doing some time intensive computation. Note that this is not the best way to have a responsive GUI - it is usually better to do work in background thread.
+For convenience of specifying widgets hierarchy in Lisp code, the @ref{let-ui} macro is introduced.
-@RFunction gtk-main-add-timeout
+@RMacro let-ui
@lisp
-(gtk-main-add-timeout milliseconds function &key (priority +g-priority-default+)) @result{} source-id
+(let-ui ui-description &body body)
+
+ui-description ::= widget
+widget ::= (class properties child*)
+properties ::= @{:prop-name prop-value@}*
+child ::= widget properties
+child ::= (:expr expr) properties
@end lisp
@table @var
-@item @var{milliseconds}
-An integer specifying the time between calls to the function, in milliseconds (1/1000ths of a second.)
-@item @var{function}
-The function to call periodically. This function accepts zero arguments and returns a boolean.
-@item @var{priority}
-An integer specifying the priority of the timeout. Typically this will be in the range between @ref{+g-priority-default+} and @ref{+g-priority-high+}.
-@item @var{source-id}
-An integer identifier of GLib event source.
+@item @var{class}
+Name of class of a widget
+@item @var{:prop-name}
+Name of class's slot or a @code{:var} for specifying the variable name to which the object will be bound
+@item @var{prop-value}
+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}
+@item @var{expr}
+An expression that will be evaluated to obtain the widget
@end table
-Registers a @var{function} to be called periodically. The function will be called repeatedly after once per @var{milliseconds} until it returns False at which point the timeout is destroyed and will not be called again. Timeout can also be removed by passing @var{source-id} to @ref{g-source-remove}.
-@RMacro within-main-loop
-@lisp
-(within-main-loop &body body)
-@end lisp
-Schedules the @var{body} to be evaluated within the main loop. Expression inside @var{body} are run inside the main loop, so they can call any Gtk+ functions. This expression may be evaluated in any thread.
+This macro creates widgets and evaluates the @var{body}. Widgets that have @code{:var} specified are bound to lexical variables with specified names.
-Returns immediately. If the main loop was not started, uses @ref{ensure-gtk-main} to start it.
+@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.
-@RMacro within-main-loop-and-wait
-@lisp
-(within-main-loop-and-wait &body body) @result{} results
-@end lisp
-Schedules the @var{body} to be evaluated within the main loop. Expression inside @var{body} are run inside the main loop, so they can call any Gtk+ functions. This expression may be evaluated in any thread.
+@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.
-Returns the values produced by evaluating @var{body}. If the evaluation of @var{body} results in unhandled error, the @ref{gtk-call-aborted} error condition is signaled.
+@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}.
-If the main loop was not started, uses @ref{ensure-gtk-main} to start it.
+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:
+@itemize
+@item @ref{box} specifies @code{:expand}, @code{:fill}. See @ref{box-pack-start} for information.
+@item @ref{paned} specifies @code{:resize}, @code{:shrink}. See @ref{paned-pack-1} for information.
+@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.
+@end itemize
-@RFunction call-from-gtk-main-loop
+An example:
@lisp
-(call-from-gtk-main-loop function &key (priority +g-priority-default-idle+))
+(let-ui (gtk-window :title "Hello" :position :center :var w
+ (v-box
+ (label :label "Hello, world!")
+ (button :label "gtk-ok" :use-stock t) :expand nil))
+ (widget-show w))
@end lisp
+produces this output:
-@table @var
-@item @var{function}
-The function to be called. Accepts zero arguments.
-@item @var{priority}
-An integer specifying the priority of the call.
-@end table
-
-Schedules the @var{function} to be called within the main loop. @var{function} is evaluated inside the main loop, so it can call any Gtk+ functions. This function may be called from any thread.
+@image{let-ui,,,,png}
-If the main loop was not started, uses @ref{ensure-gtk-main} to start it.
-
-@RFunction call-within-main-loop-and-wait
+More complex example from demo of cl-gtk2-gtk-glext:
@lisp
-(call-from-gtk-main-loop-and-wait function)
+(let-ui (v-paned :var v
+ (:expr (opengl-window-drawing-area window))
+ :resize t :shrink nil
+ (v-box
+ (h-paned
+ (scrolled-window
+ :hscrollbar-policy :automatic
+ :vscrollbar-policy :automatic
+ (:expr (opengl-window-expose-fn-text-view window)))
+ :resize t :shrink nil
+ (scrolled-window
+ :hscrollbar-policy :automatic
+ :vscrollbar-policy :automatic
+ (:expr (opengl-window-resize-fn-text-view window)))
+ :resize t :shrink nil)
+ (h-box
+ (button :label "Update functions" :var update-fns-button) :expand nil
+ (button :label "Redraw" :var redraw-button) :expand nil)
+ :expand nil)
+ :resize t :shrink nil)
+ (container-add window v)
+ (connect-signal update-fns-button "clicked"
+ (lambda (b)
+ (declare (ignore b))
+ (update-fns window)))
+ (connect-signal redraw-button "clicked"
+ (lambda (b)
+ (declare (ignore b))
+ (widget-queue-draw (opengl-window-drawing-area window))))
+ (let ((area (opengl-window-drawing-area window)))
+ (setf (gl-drawing-area-on-expose area)
+ (lambda (w e)
+ (declare (ignore w e))
+ (opengl-interactive-on-expose window))
+ (gl-drawing-area-on-resize area)
+ (lambda (widget w h)
+ (declare (ignore widget))
+ (opengl-interactive-on-resize window w h)))))
@end lisp
+produces this output:
-@table @var
-@item @var{function}
-The function to be called. Accepts zero arguments and returns zero, one or more values.
-@end table
-
-Schedules the @var{function} to be called within the main loop. @var{function} is evaluated inside the main loop, so it can call any Gtk+ functions. This function may be called from any thread.
-
-Returns the values produced by calling @var{function}. If the evaluation of @var{function} results in unhandled error, the @ref{gtk-call-aborted} error condition is signaled.
-
-If the main loop was not started, uses @ref{ensure-gtk-main} to start it.
-
-@RCondition gtk-call-aborted
-
-A condition inheriting from @code{error} that is used to signal the fact that the evaluation of expression or function in main loop by @ref{within-main-loop}, @ref{within-main-loop-and-wait}, @ref{call-from-gtk-main-loop}, @ref{call-within-main-loop-and-wait} was interrupted by error.
-
-@RFunction gtk-call-aborted-condition
+@image{let-ui-glext,,,,png}
-Returns the error that caused call to aborted.
+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))}.
projects / cl-gtk2.git / blobdiff