source: project/wiki/eggref/4/kiwi @ 33375

Last change on this file since 33375 was 33375, checked in by Vasilij Schneidermann, 5 years ago

Mention which commit the bindings are based on, add contact info

File size: 30.2 KB
Line 
1== kiwi
2
3[[toc:]]
4
5=== Introduction
6
7This egg provides a fairly complete set of low-level bindings and a
8high-level SXML widget interface to the
9[[https://github.com/mobius3/KiWi|KiWi]] library.  It is intended to
10be used in combination with the [[sdl2]] egg to create simple user
11interfaces for games and GUI applications.
12
13=== Author
14
15Vasilij Schneidermann
16
17=== Repository
18
19[[https://github.com/wasamasa/kiwi]]
20
21=== Requirements
22
23Both KiWi and SDL2 must be available on your machine.  An Arch Linux
24PKGBUILD is available
25[[https://github.com/wasamasa/pkgbuilds/blob/master/kiwi-git/PKGBUILD|here]].
26The bindings are based on everything up to commit
27[[https://github.com/mobius3/KiWi/commit/de9c5d2211ac57c199570a1776aa4634db32a5fb|de9c5d]],
28so they might break on API-incompatible changes introduced after
292016-06-04.  Please contact me on the {{#chicken}} channel or open a
30GitHub issue if this happens to you.
31
32The installation script tries autodetecting their location with
33{{cmake}} and {{sdl2-config}}.  This can be overridden by using the
34{{KIWI_FLAGS}} and {{SDL2_FLAGS}} environment variables.  The bindings
35themselves require the [[clojurian]] and [[matchable]] eggs.
36
37=== API
38
39==== Setup and teardown
40
41===== create-sdl2-driver
42
43<procedure>(create-sdl2-driver RENDERER WINDOW)</procedure>
44
45Creates and returns a SDL2-backed driver.  {{RENDERER}} and {{WINDOW}}
46must be raw pointers to a SDL2 renderer and window and can be obtained
47by using the {{unwrap-renderer}} and {{unwrap-window}} procedures from
48the
49[[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/using-sdl2-internals.md|sdl2-internals]]
50module of the [[sdl2]] egg.
51
52===== driver?
53
54<procedure>(driver? ARG)</procedure>
55
56Returns {{#t}} if {{ARG}} is an driver, otherwise {{#f}}.
57
58===== driver-sdl2-renderer
59
60<procedure>(driver-sdl2-renderer DRIVER)</procedure>
61
62Returns the raw SDL2 renderer pointer associated with {{DRIVER}}.
63
64===== driver-sdl2-window
65
66<procedure>(driver-sdl2-window DRIVER)</procedure>
67
68Returns the raw SDL2 window pointer associated with {{DRIVER}}.
69
70===== release-driver!
71
72<procedure>(release-driver! DRIVER)</procedure>
73
74Frees the resources of {{DRIVER}}.  This is called implicitly as
75finalizer for driver records.
76
77===== load-surface
78
79<procedure>(load-surface DRIVER FILENAME)</procedure>
80
81Creates and returns a surface based on an image found at {{FILENAME}}.
82Supported image formats are the same as for the [[sdl2-image]] egg.
83If the image could not be loaded, an exception of the type {{(exn
84sdl2)}} is thrown.
85
86===== surface?
87
88<procedure>(surface? ARG)</procedure>
89
90Returns {{#t}} if {{ARG}} is an surface, otherwise {{#f}}.
91
92===== release-surface!
93
94<procedure>(release-surface! DRIVER SURFACE)</procedure>
95
96Frees the resources of {{SURFACE}}.  This is called implicitly as
97finalizer for surface records.
98
99===== load-font
100
101<procedure>(load-font DRIVER FONTNAME SIZE)</procedure>
102
103Creates and returns a font based on the TTF font found at {{FILENAME}}
104with the font size {{SIZE}}.  If the font could not be loaded, an
105exception of the type {{(exn sdl2)}} is thrown.
106
107===== font?
108
109<procedure>(font? ARG)</procedure>
110
111Returns {{#t}} if {{ARG}} is an font, otherwise {{#f}}.
112
113===== release-font!
114
115<procedure>(release-font! DRIVER FONT)</procedure>
116
117Frees the resources of {{FONT}}.  This is called implicitly as
118finalizer for surface records.
119
120===== init!
121
122<procedure>(init! DRIVER TILESET-SURFACE)</procedure>
123
124Initializes and returns a GUI.  {{TILESET-SURFACE}} must be a surface
125to be used as tileset.
126
127===== process-events!
128
129<procedure>(process-events! GUI)</procedure>
130
131Process events for {{GUI}} and trigger all event handlers involved.
132
133===== paint!
134
135<procedure>(paint! GUI)</procedure>
136
137Repaint all widgets associated with {{GUI}}.
138
139===== quit!
140
141<procedure>(quit! GUI)</procedure>
142
143Terminates {{GUI}} and frees the resources of all associated widgets.
144This procedure ''must'' be called explicitly at the end of the program
145before terminating SDL2 and is therefore a candidate for an
146{{on-exit}} handler.
147
148===== gui-driver / gui-driver-set!
149
150<procedure>(gui-driver GUI)</procedure>
151<procedure>(gui-driver-set! GUI DRIVER)</procedure>
152<setter>(set! (gui-driver GUI) DRIVER)</setter>
153
154Retrieves or sets the driver of {{GUI}}.
155
156===== gui-font / gui-font-set!
157
158<procedure>(gui-font GUI)</procedure>
159<procedure>(gui-font-set! GUI FONT)</procedure>
160<setter>(set! (gui-font GUI) FONT)</setter>
161
162Retrieves or sets the font of {{GUI}}.  Note that the GUI font needs
163to be set after calling the {{init!}} procedure, otherwise your
164application will crash with a segmentation violation once you attempt
165using a widget with text.
166
167===== gui-text-color / gui-text-color-set!
168
169<procedure>(gui-text-color GUI)</procedure>
170<procedure>(gui-text-color-set! GUI TEXT-COLOR)</procedure>
171<setter>(set! (gui-text-color GUI) TEXT-COLOR)</setter>
172
173Retrieves or sets the text color of {{GUI}}.
174
175===== gui-tileset-surface / gui-tileset-surface-set!
176
177<procedure>(gui-tileset-surface GUI)</procedure>
178<procedure>(gui-tileset-surface-set! GUI TILESET-SURFACE)</procedure>
179<setter>(set! (gui-tileset-surface GUI) TILESET-SURFACE)</setter>
180
181Retrieves or sets the tileset surface of {{GUI}}.
182
183==== Rects
184
185===== rect
186
187<procedure>(rect X Y W H)</procedure>
188
189Creates and returns a rectangle at the coordinates {{X}} and {{Y}}
190with the dimensions {{W}} and {{H}}.
191
192===== rect?
193
194<procedure>(rect? ARG)</procedure>
195
196Returns {{#t}} if {{ARG}} is an rect, otherwise {{#f}}.
197
198===== rect-x / rect-x-set!
199
200<procedure>(rect-x RECT)</procedure>
201<procedure>(rect-x-set! RECT X)</procedure>
202<setter>(set! (rect-x RECT) X)</setter>
203
204Retrieves or sets the x coordinate of {{RECT}}.
205
206===== rect-y / rect-y-set!
207
208<procedure>(rect-y RECT)</procedure>
209<procedure>(rect-y-set! RECT Y)</procedure>
210<setter>(set! (rect-y RECT) Y)</setter>
211
212Retrieves or sets the y coordinate of {{RECT}}.
213
214===== rect-w / rect-w-set!
215
216<procedure>(rect-w RECT)</procedure>
217<procedure>(rect-w-set! RECT W)</procedure>
218<setter>(set! (rect-w RECT) W)</setter>
219
220Retrieves or sets the width of {{RECT}}.
221
222===== rect-h / rect-h-set!
223
224<procedure>(rect-h RECT)</procedure>
225<procedure>(rect-h-set! RECT H)</procedure>
226<setter>(set! (rect-h RECT) H)</setter>
227
228Retrieves or sets the height of {{RECT}}.
229
230==== Rect helpers
231
232===== rect-empty?
233
234<procedure>(rect-empty? RECT)</procedure>
235
236Returns {{#t}} if {{RECT}} is empty, otherwise {{#f}}.
237
238===== enclosing-rect
239
240<procedure>(enclosing-rect RECTS)</procedure>
241
242Returns a rectangle enclosing all {{RECTS}}.
243
244===== rect-center-in-parent!
245
246<procedure>(rect-center-in-parent! PARENT INNER)</procedure>
247
248Centers {{INNER}} in {{PARENT}} vertically and horizontally by
249mutating the coordinates of {{INNER}}.
250
251===== rect-center-in-parent-vertically!
252
253<procedure>(rect-center-in-parent-vertically! PARENT INNER)</procedure>
254
255Centers {{INNER}} in {{PARENT}} vertically by mutating the coordinates
256of {{INNER}}.
257
258===== rect-center-in-parent-horizontally!
259
260<procedure>(rect-center-in-parent-horizontally! PARENT INNER)</procedure>
261
262Centers {{INNER}} in {{PARENT}} horizontally by mutating the
263coordinates of {{INNER}}.
264
265===== rect-layout-vertically!
266
267<procedure>(rect-layout-vertically! RECTS PADDING [HALIGN])</procedure>
268
269Layouts {{RECTS}} to be aligned as a vertical list with {{PADDING}}
270pixels between them by mutating their coordinates.  {{HALIGN}} must be
271one of {{(left center right)}} if specified, otherwise the horizontal
272alignment of {{RECTS}} will not be changed.
273
274===== rect-layout-horizontally!
275
276<procedure>(rect-layout-horizontally! RECTS PADDING [VALIGN])</procedure>
277
278Layouts {{RECTS}} to be aligned as a horizontal list with {{PADDING}}
279pixels between them by mutating their coordinates.  {{VALIGN}} must be
280one of {{(top middle bottom)}} if specified, otherwise the vertical
281alignment of {{RECTS}} will not be changed.
282
283===== rect-fill-parent-vertically!
284
285<procedure>(rect-fill-parent-vertically! PARENT RECTS WEIGHTS PADDING)</procedure>
286
287Layouts and resizes {{RECTS}} to fit {{PARENT}} by changing their
288coordinates and height.  {{WEIGHTS}} is a list of fixnums mapped to
289{{RECTS}}.  The higher the weight, the more space a rectangle will
290occupy.  {{PADDING}} specifies the space in pixels between the
291rectangles.  Note that this procedure does no rectangle aligning.
292
293===== rect-fill-parent-horizontally!
294
295<procedure>(rect-fill-parent-horizontally! PARENT RECTS WEIGHTS PADDING VALIGN)</procedure>
296
297Layouts and resizes {{RECTS}} to fit {{PARENT}} by changing their
298coordinates and width.  {{WEIGHTS}} is a list of fixnums mapped to
299{{RECTS}}.  The higher the weight, the more space a rectangle will
300occupy.  {{PADDING}} specifies the space in pixels between the
301rectangles.  {{VALIGN}} must be one of {{(top middle bottom)}}.
302
303==== Colors
304
305===== color
306
307<procedure>(color R G B A)</procedure>
308
309Creates and returns a color with the components {{R}}, {{G}}, {{B}}
310and {{A}}.
311
312===== color?
313
314<procedure>(color? ARG)</procedure>
315
316Returns {{#t}} if {{ARG}} is an color, otherwise {{#f}}.
317
318===== color-r / color-r-set!
319
320<procedure>(color-r COLOR)</procedure>
321<procedure>(color-r-set! COLOR R)</procedure>
322<setter>(set! (color-r COLOR) R)</setter>
323
324Retrieves or sets the red component of {{COLOR}}.  {{R}} must be a
325fixnum between 0 and 255 (inclusive).
326
327===== color-g / color-g-set!
328
329<procedure>(color-g COLOR)</procedure>
330<procedure>(color-g-set! COLOR G)</procedure>
331<setter>(set! (color-g COLOR) G)</setter>
332
333Retrieves or sets the green component of {{COLOR}}.  {{G}} must be a
334fixnum between 0 and 255 (inclusive).
335
336===== color-b / color-b-set!
337
338<procedure>(color-b COLOR)</procedure>
339<procedure>(color-b-set! COLOR B)</procedure>
340<setter>(set! (color-b COLOR) B)</setter>
341
342Retrieves or sets the blue component of {{COLOR}}.  {{B}} must be a
343fixnum between 0 and 255 (inclusive).
344
345===== color-a / color-a-set!
346
347<procedure>(color-a COLOR)</procedure>
348<procedure>(color-a-set! COLOR A)</procedure>
349<setter>(set! (color-a COLOR) A)</setter>
350
351Retrieves or sets the alpha component of {{COLOR}}.  {{A}} must be a
352fixnum between 0 and 255 (inclusive).
353
354==== Frame widget
355
356===== frame
357
358<procedure>(frame GUI PARENT GEOMETRY)</procedure>
359
360Creates and returns a frame widget.  {{PARENT}} must either be a
361widget or {{#f}} to create a top-level widget.  {{GEOMETRY}} is a
362rectangle describing the position and dimensions of the widget.
363
364===== frame?
365
366<procedure>(frame? ARG)</procedure>
367
368Returns {{#t}} if {{ARG}} is an frame widget, otherwise {{#f}}.
369
370==== Scrollbox widget
371
372===== scrollbox
373
374<procedure>(scrollbox GUI PARENT GEOMETRY)</procedure>
375
376Creates and returns a scrollbox widget.  {{PARENT}} must either be a
377widget or {{#f}} to create a top-level widget.  {{GEOMETRY}} is a
378rectangle describing the position and dimensions of the widget.
379
380===== scrollbox?
381
382<procedure>(scrollbox? ARG)</procedure>
383
384Returns {{#t}} if {{ARG}} is an scrollbox widget, otherwise {{#f}}.
385
386===== scrollbox-vertical-scroll!
387
388<procedure>(scrollbox-vertical-scroll! SCROLLBOX AMOUNT)</procedure>
389
390Scroll {{SCROLLBOX}} vertically by {{AMOUNT}} pixels.
391
392===== scrollbox-horizontal-scroll!
393
394<procedure>(scrollbox-horizontal-scroll! SCROLLBOX AMOUNT)</procedure>
395
396Scroll {{SCROLLBOX}} horizontally by {{AMOUNT}} pixels.
397
398==== Label widget
399
400===== label
401
402<procedure>(label GUI PARENT TEXT GEOMETRY)</procedure>
403
404Creates and returns a label widget.  {{PARENT}} must either be a
405widget or {{#f}} to create a top-level widget.  {{TEXT}} is a string
406to be used as the label's text.  {{GEOMETRY}} is a rectangle
407describing the position and dimensions of the widget.
408
409===== label?
410
411<procedure>(label? ARG)</procedure>
412
413Returns {{#t}} if {{ARG}} is an label widget, otherwise {{#f}}.
414
415===== label-text-set!
416
417<procedure>(label-text-set! LABEL TEXT)</procedure>
418
419Sets the text of {{LABEL}} to {{TEXT}}.
420
421===== label-icon-set!
422
423<procedure>(label-icon-set! LABEL CLIP)</procedure>
424
425Sets an icon for {{LABEL}}.  {{CLIP}} is a rectangle that will be
426clipped out of the currently active tileset for the icon.
427
428===== label-alignment-set!
429
430<procedure>(label-alignment-set! LABEL HALIGN HOFFSET VALIGN VOFFSET)</procedure>
431
432Sets the alignment of {{LABEL}}.  {{HALIGN}} must be one of {{(left
433center right)}} and {{VALIGN}} one of {{(top middle bottom)}}.
434{{HOFFSET}} and {{VOFFSET}} specify the horizontal and vertical offset
435in pixels.
436
437===== label-style-set!
438
439<procedure>(label-style-set! LABEL STYLE)</procedure>
440
441Sets the text style of {{LABEL}}.  {{STYLE}} must be one of {{(normal
442bold italic underline strikethrough)}}.
443
444===== label-font / label-font-set!
445
446<procedure>(label-font LABEL)</procedure>
447<procedure>(label-font-set! LABEL FONT)</procedure>
448<setter>(set! (label-font LABEL) FONT)</setter>
449
450Retrieves or sets the font of {{LABEL}}.
451
452===== label-text-color / label-text-color-set!
453
454<procedure>(label-text-color LABEL)</procedure>
455<procedure>(label-text-color-set! LABEL TEXT-COLOR)</procedure>
456<setter>(set! (label-text-color LABEL) TEXT-COLOR)</setter>
457
458Retrieves or sets the text color of {{LABEL}}.  Note that this will
459default to black.
460
461===== label-text-color-set?
462
463<procedure>(label-text-color-set? LABEL)</procedure>
464
465Returns {{#t}} if the text color of {{LABEL}} has been set by the
466user.
467
468==== Button widget
469
470===== button
471
472<procedure>(button GUI PARENT TEXT GEOMETRY)</procedure>
473
474Creates and returns a button widget.  {{PARENT}} must either be a
475widget or {{#f}} to create a top-level widget.  {{TEXT}} is a string
476to be used as the button's text.  {{GEOMETRY}} is a rectangle
477describing the position and dimensions of the widget.
478
479===== button?
480
481<procedure>(button? ARG)</procedure>
482
483Returns {{#t}} if {{ARG}} is an button widget, otherwise {{#f}}.
484
485===== button-text-set!
486
487<procedure>(button-text-set! BUTTON TEXT)</procedure>
488
489Sets the text of {{BUTTON}} to {{TEXT}}.
490
491===== button-icon-set!
492
493<procedure>(button-icon-set! BUTTON CLIP)</procedure>
494
495Sets an icon for {{BUTTON}}.  {{CLIP}} is a rectangle that will be
496clipped out of the currently active tileset for the icon.
497
498===== button-text-color / button-text-color-set!
499
500<procedure>(button-text-color BUTTON)</procedure>
501<procedure>(button-text-color-set! BUTTON TEXT-COLOR)</procedure>
502<setter>(set! (button-text-color BUTTON) TEXT-COLOR)</setter>
503
504Retrieves or sets the text color of {{BUTTON}}.  Note that this will
505default to black.
506
507===== button-text-color-set?
508
509<procedure>(button-text-color-set? BUTTON)</procedure>
510
511Returns {{#t}} if the text color of {{BUTTON}} has been set by the
512user.
513
514==== Editbox widget
515
516===== editbox
517
518<procedure>(editbox GUI PARENT TEXT GEOMETRY)</procedure>
519
520Creates and returns a editbox widget.  {{PARENT}} must either be a
521widget or {{#f}} to create a top-level widget.  {{TEXT}} is a string
522to be used as the button's text.  {{GEOMETRY}} is a rectangle
523describing the position and dimensions of the widget.
524
525===== editbox?
526
527<procedure>(editbox? ARG)</procedure>
528
529Returns {{#t}} if {{ARG}} is an editbox widget, otherwise {{#f}}.
530
531===== editbox-text / editbox-text-set!
532
533<procedure>(editbox-text EDITBOX)</procedure>
534<procedure>(editbox-text-set! EDITBOX TEXT)</procedure>
535<setter>(set! (editbox-text EDITBOX) TEXT)</setter>
536
537Retrieves or sets the text of {{EDITBOX}}.
538
539===== editbox-cursor-position / editbox-cursor-position-set!
540
541<procedure>(editbox-cursor-position EDITBOX)</procedure>
542<procedure>(editbox-cursor-position-set! EDITBOX POS)</procedure>
543<setter>(set! (editbox-cursor-position EDITBOX) POS)</setter>
544
545Retrieves or sets the cursor position of {{EDITBOX}}.  {{POS}} must be
546a fixnum specifying a valid index into the existing editbox text.
547
548===== editbox-font / editbox-font-set!
549
550<procedure>(editbox-font EDITBOX)</procedure>
551<procedure>(editbox-font-set! EDITBOX FONT)</procedure>
552<setter>(set! (editbox-font EDITBOX) FONT)</setter>
553
554Retrieves or sets the font of {{EDITBOX}}.
555
556===== editbox-text-color / editbox-text-color-set!
557
558<procedure>(editbox-text-color EDITBOX)</procedure>
559<procedure>(editbox-text-color-set! EDITBOX TEXT-COLOR)</procedure>
560<setter>(set! (editbox-text-color EDITBOX) TEXT-COLOR)</setter>
561
562Retrieves or sets the text color of {{EDITBOX}}.  Note that this will
563default to black.
564
565===== editbox-text-color-set?
566
567<procedure>(editbox-text-color-set? EDITBOX)</procedure>
568
569Returns {{#t}} if the text color of {{EDITBOX}} has been set by the
570user.
571
572==== Widget helpers
573
574===== widget?
575
576<procedure>(widget? ARG)</procedure>
577
578Returns {{#t}} if {{ARG}} is an widget, otherwise {{#f}}.
579
580===== widget-type
581
582<procedure>(widget-type WIDGET)</procedure>
583
584Returns a symbol describing the widget type.  It will be one of
585{{(frame scrollbox label button editbox)}}.
586
587===== widget-gui
588
589<procedure>(widget-gui WIDGET)</procedure>
590
591Returns the GUI associated with {{WIDGET}}.  This is a convenience
592procedure intended for use in event handlers.
593
594===== widget-driver
595
596<procedure>(widget-driver WIDGET)</procedure>
597
598Returns the driver associated with {{WIDGET}}.  This is a convenience
599procedure intended for use in event handlers.
600
601===== widget-tileset-surface / widget-tileset-surface-set!
602
603<procedure>(widget-tileset-surface WIDGET)</procedure>
604<procedure>(widget-tileset-surface-set! WIDGET TILESET-SURFACE)</procedure>
605<setter>(set! (widget-tileset-surface WIDGET) TILESET-SURFACE)</setter>
606
607Retrieves or sets the tileset surface of {{WIDGET}}.
608
609===== widget-parent
610
611<procedure>(widget-parent WIDGET)</procedure>
612
613Returns the parent widget of {{WIDGET}} or {{#f}} if {{WIDGET}} is a
614top-level widget.
615
616===== widget-children
617
618<procedure>(widget-children WIDGET)</procedure>
619
620Returns the children widgets of {{WIDGET}} as list.  If {{WIDGET}} has
621no children, an empty list is returned.
622
623===== reparent-widget!
624
625<procedure>(reparent-widget! WIDGET PARENT)</procedure>
626
627Changes the parent of {{WIDGET}} to {{PARENT}}.  Note that this will
628not update the geometry of {{WIDGET}}.  To make {{WIDGET}} a top-level
629widget, use {{#f}} as value for {{PARENT}}.
630
631===== bring-widget-to-front!
632
633<procedure>(bring-widget-to-front! WIDGET)</procedure>
634
635Modifies the widget tree to make {{WIDGET}} appear on the front.
636
637===== widget-focus-set!
638
639<procedure>(widget-focus-set! WIDGET)</procedure>
640
641Sets the GUI focus to {{WIDGET}}.
642
643===== widget-clip-children?-set!
644
645<procedure>(widget-clip-children?-set! WIDGET FLAG)</procedure>
646
647Change whether the children of {{WIDGET}} should be clipped to its
648geometry.  {{FLAG}} must be either {{#t}} or {{#f}}.
649
650===== destroy-widget!
651
652<procedure>(destroy-widget! WIDGET [CHILDREN?])</procedure>
653
654Destroys {{WIDGET}} and frees its resources.  If {{CHILDREN?}} is
655{{#t}}, destroy its children as well, otherwise reparent them to the
656parent of {{WIDGET}}.  While this procedure can be used to remove
657widgets while the GUI is still running, consider hiding them instead.
658
659===== hide-widget!
660
661<procedure>(hide-widget! WIDGET)</procedure>
662
663Hides {{WIDGET}} and its children.  This is equivalent to
664{{(enable-widget-hint! WIDGET 'hidden #t)}}.
665
666===== show-widget!
667
668<procedure>(show-widget! WIDGET)</procedure>
669
670Displays {{WIDGET}} and its children again.  This is equivalent to
671{{(disable-widget-hint! WIDGET 'hidden #t)}}.
672
673===== widget-hidden?
674
675<procedure>(widget-hidden? WIDGET)</procedure>
676
677Returns {{#t}} if {{WIDGET}} is hidden, otherwise {{#f}}.  This is
678equivalent to {{(query-widget-hint WIDGET 'hidden)}}.
679
680===== block-widget-input-events!
681
682<procedure>(block-widget-input-events! WIDGET)</procedure>
683
684Blocks {{WIDGET}} and its children from receiving events.  This is
685equivalent to {{(enable-widget-hint! WIDGET 'block-input-events #f)}}.
686
687===== unblock-widget-input-events!
688
689<procedure>(unblock-widget-input-events WIDGET)</procedure>
690
691Unblocks input event blocking for {{WIDGET}}.  This is equivalent to
692{{(disable-widget-hint! WIDGET 'block-input-events #f)}}.
693
694===== widget-input-events-blocked?
695
696<procedure>(widget-input-events-blocked? WIDGET)</procedure>
697
698Returns {{#t}} if events are blocked for {{WIDGET}}, otherwise {{#f}}.
699This is equivalent to {{(query-widget-hint WIDGET
700'block-input-events)}}.
701
702===== enable-widget-hint!
703
704<procedure>(enable-widget-hint! WIDGET HINT RECUR?)</procedure>
705
706Enables the widget hint {{HINT}} for {{WIDGET}}.  If {{RECUR?}} is
707{{#t}}, enable it recursively.  {{HINT}} must be one of
708{{(allow-tile-stretch block-input-events ignore-input-events frameless
709hidden)}}.
710
711===== disable-widget-hint!
712
713<procedure>(disable-widget-hint! WIDGET HINT RECUR?)</procedure>
714
715Disables the widget hint {{HINT}} for {{WIDGET}}.  If {{RECUR?}} is
716{{#t}}, disable it recursively.  {{HINT}} must be one of
717{{(allow-tile-stretch block-input-events ignore-input-events frameless
718hidden)}}.
719
720===== query-widget-hint
721
722<procedure>(query-widget-hint WIDGET HINT)</procedure>
723
724Query {{WIDGET}} for {{HINT}}, returning either {{#t}} if enabled or
725{{#f}} if disabled.  {{HINT}} must be one of {{(allow-tile-stretch
726block-input-events ignore-input-events frameless hidden)}}.
727
728===== widget-geometry / widget-geometry-set!
729
730<procedure>(widget-geometry WIDGET)</procedure>
731<procedure>(widget-geometry-set! WIDGET GEOMETRY)</procedure>
732<setter>(set! (widget-geometry WIDGET) GEOMETRY)</setter>
733
734Retrieves or sets the geometry of {{WIDGET}}.
735
736===== widget-absolute-geometry
737
738<procedure>(widget-absolute-geometry WIDGET)</procedure>
739
740Returns the absolute geometry of {{WIDGET}}.  Its coordinates are
741relative to the root instead of the parent widget.
742
743===== widget-composed-geometry
744
745<procedure>(widget-composed-geometry WIDGET)</procedure>
746
747Returns the composed geometry of {{WIDGET}}.  Its coordinates are
748relative to the root widget and its dimensions are equivalent to those
749of a rectangle enclosing it and its children.
750
751===== widget-center-in-parent!
752
753<procedure>(widget-center-in-parent! PARENT INNER)</procedure>
754
755Centers {{INNER}} in {{PARENT}} vertically and horizontally.
756
757===== widget-center-in-parent-vertically!
758
759<procedure>(widget-center-in-parent-vertically! PARENT INNER)</procedure>
760
761Centers {{INNER}} in {{PARENT}} vertically.
762
763===== widget-center-in-parent-horizontally!
764
765<procedure>(widget-center-in-parent-horizontally! PARENT INNER)</procedure>
766
767Centers {{INNER}} in {{PARENT}} horizontally.
768
769===== widget-layout-vertically!
770
771<procedure>(widget-layout-vertically! WIDGETS PADDING [HALIGN])</procedure>
772
773Layouts {{WIDGETS}} as a vertical list.  See
774{{rect-layout-vertically!}} for further details.
775
776===== widget-layout-horizontally!
777
778<procedure>(widget-layout-horizontally! WIDGETS PADDING [VALIGN])</procedure>
779
780Layouts {{WIDGETS}} as horizontal list.  See
781{{rect-layout-horizontally!}} for further details.
782
783===== widget-fill-parent-vertically!
784
785<procedure>(widget-fill-parent-vertically! PARENT RECTS WEIGHTS PADDING)</procedure>
786
787Layouts and resizes {{WIDGETS}} to fit {{PARENT}}.  See
788{{rect-fill-parent-vertically!}} for further details.
789
790===== widget-fill-parent-horizontally!
791
792<procedure>(widget-fill-parent-horizontally! PARENT RECTS WEIGHTS PADDING VALIGN)</procedure>
793
794Layouts and resizes {{WIDGETS}} to fit {{PARENT}}.  See
795{{rect-fill-parent-horizontally!}} for further details.
796
797==== Handlers
798
799===== handler-set!
800
801<procedure>(handler-set! WIDGET TYPE PROC)</procedure>
802
803Sets an event handler of {{TYPE}} for {{WIDGET}} to {{PROC}}.
804{{TYPE}} must be one of {{(mouse-over mouse-leave mouse-down mouse-up
805focus-gain focus-lose text-input drag-start drag-stop drag)}}.
806Depending on {{TYPE}}, {{PROC}} must be a procedure accepting the
807corresponding argument list:
808
809; mouse-over : {{(lambda (widget) ...)}}
810; mouse-leave : {{(lambda (widget) ...)}}
811; mouse-down : {{(lambda (widget button) ...)}}
812; mouse-up : {{(lambda (widget button) ...)}}
813; focus-gain : {{(lambda (widget) ...)}}
814; focus-lose : {{(lambda (widget) ...)}}
815; text-input : {{(lambda (widget text) ...)}}
816; drag-start : {{(lambda (widget x y) ...)}}
817; drag-stop : {{(lambda (widget x y) ...)}}
818; drag : {{(lambda (widget x y relx rely) ...)}}
819
820===== handler-remove!
821
822<procedure>(handler-remove! WIDGET TYPE)</procedure>
823
824Removes an event handler of {{TYPE}} for {{WIDGET}}.  {{TYPE}} must be
825one of {{(mouse-over mouse-leave mouse-down mouse-up focus-gain
826focus-lose text-input drag-start drag-stop drag)}}.
827
828==== SXML interface
829
830===== widgets
831
832<procedure>(widgets GUI [PARENT] SXML)</procedure>
833
834Creates widgets based on {{SXML}}.  If {{PARENT}} is specified, use
835that widget as the parent of the newly created widgets, otherwise
836create top-level widgets.
837
838Elements must be one of {{(frame scrollbox label button editbox)}}.
839Each element has mandatory attributes that correspond to their
840constructor procedures and optional attributes that correspond to
841their other setter procedures plus generic setter procedures.  The
842following definition lists summarizes them for quick reference:
843
844Mandatory attributes for all widget types:
845
846; x : X coordinate
847; y : Y coordinate
848; w : width
849; h : height
850
851Mandatory attributes for specific widget types:
852
853; text : Text for label, button and editbox widgets
854
855Optional attributes for all widget types:
856
857; tileset : Tileset surface
858; hidden? : Hide widget, value must be {{#t}}
859; id : Symbol identifier for lookup with {{widget-by-id}}
860; <event handler type> : Procedure, see {{handler-set!}} for the attribute name and function signature of the value
861
862Optional attributes for specific widget types:
863
864; icon : List of {{x}}, {{y}}, {{w}} and {{h}} attributes for label and button widgets
865; align : List as specified in {{label-alignment-set!}} for label widgets
866; style : Style symbol as specified in {{label-style-set!}} for label widgets
867; font : Font for label, button and editbox widgets
868; color : Color for label, button and editbox widgets
869; position : Index for editbox widgets
870
871===== widget-by-id
872
873<procedure>(widget-by-id ID)</procedure>
874
875Returns either a widget that has been defined previously with the
876{{widgets}} procedure and an {{id}} attribute or {{#f}} if it couldn't
877be found.
878
879=== Examples
880
881Frame with "Hello World!" label (requires a {{tileset.png}} and
882{{Fontin-Regular.ttf}} in your cwd):
883
884<enscript highlight="scheme">
885(use (prefix sdl2 sdl2:)
886     (prefix kiwi kw:))
887
888(import (only sdl2-internals unwrap-renderer unwrap-window))
889
890(sdl2:set-main-ready!)
891(sdl2:init! '(everything))
892
893(define width 320)
894(define height 240)
895
896(define-values (window renderer)
897  (sdl2:create-window-and-renderer! width height))
898
899(sdl2:render-draw-color-set! renderer (sdl2:make-color 100 100 100))
900
901(define driver (kw:create-sdl2-driver (unwrap-renderer renderer)
902                                      (unwrap-window window)))
903
904(define tileset (kw:load-surface driver "tileset.png"))
905(define gui (kw:init! driver tileset))
906
907(define font (kw:load-font driver "Fontin-Regular.ttf" 12))
908(kw:gui-font-set! gui font)
909
910(define geometry (kw:rect 0 0 width height))
911(define frame (kw:frame gui #f geometry))
912(define label (kw:label gui frame "Hello World!" geometry))
913
914(let loop ()
915  (when (not (sdl2:quit-requested?))
916    (sdl2:render-clear! renderer)
917    (kw:process-events! gui)
918    (kw:paint! gui)
919    (sdl2:delay! 1)
920    (sdl2:render-present! renderer)
921    (loop)))
922
923(kw:quit! gui)
924(sdl2:quit!)
925</enscript>
926
927Same example, but with the SXML interface:
928
929<enscript highlight="scheme">
930(use (prefix sdl2 sdl2:)
931     (prefix kiwi kw:))
932
933(import (only sdl2-internals unwrap-renderer unwrap-window))
934
935(sdl2:set-main-ready!)
936(sdl2:init! '(everything))
937
938(define width 320)
939(define height 240)
940
941(define-values (window renderer)
942  (sdl2:create-window-and-renderer! width height))
943
944(sdl2:render-draw-color-set! renderer (sdl2:make-color 100 100 100))
945
946(define driver (kw:create-sdl2-driver (unwrap-renderer renderer)
947                                      (unwrap-window window)))
948
949(define tileset (kw:load-surface driver "tileset.png"))
950(define gui (kw:init! driver tileset))
951
952(define font (kw:load-font driver "Fontin-Regular.ttf" 12))
953(kw:gui-font-set! gui font)
954
955(kw:widgets gui
956 `(frame
957   (@ (x 0) (y 0) (w ,width) (h ,height))
958   (label
959    (@ (x 0) (y 0) (w ,width) (h ,height)
960       (text "Hello World!")))))
961
962(let loop ()
963  (when (not (sdl2:quit-requested?))
964    (sdl2:render-clear! renderer)
965    (kw:process-events! gui)
966    (kw:paint! gui)
967    (sdl2:delay! 1)
968    (sdl2:render-present! renderer)
969    (loop)))
970
971(kw:quit! gui)
972(sdl2:quit!)
973</enscript>
974
975Further examples can be found in
976[[https://github.com/wasamasa/kiwi/examples|the repository]] and
977contain [[https://github.com/mobius3/KiWi/tree/master/examples|the
978original set of examples]] as well as two new ones, a more advanced
979"Hello World!" and a simple image viewer. The [[sdl2]] and
980[[sdl2-image]] eggs are required to compile and run them.
981
982=== Notes
983
984* Unlike many other GUI toolkits, KiWi requires you to use your own
985  resources.  Make sure your font and tileset can be found when
986  running your application, otherwise it will segfault.
987* There is no ready-made main loop implementation, therefore you'll
988  have to write your own.  While this is sort of a hassle, it allows
989  for more flexibility and better integration with your application
990  than with GUI toolkits not offering that option.
991* Increase the delay time in your main loop to lower the FPS and
992  overall CPU usage.
993* It's strongly recommended to use top-level definitions for the
994  driver, GUI and its font and tileset to avoid references to them
995  being garbage-collected early, possibly resulting in a segfault.
996* Refer to [[https://github.com/mobius3/KiWi/tree/master/src|the KiWi
997  headers]] for documentation on details not covered in this wiki
998  page, such as how geometries work, creation of custom widgets and
999  any functionality without bindings.
1000* If you want to create a new tileset, use
1001  [[https://github.com/mobius3/KiWi/raw/master/examples/tileset/tileset.xcf|tileset.xcd]]
1002  from the KiWi repository as basis.
1003* It's strongly recommended to use the {{(on-exit)}} and
1004  {{(current-exception-handler)}} parameters during development to
1005  exit the application properly at all times.  This has been omitted
1006  from the examples for brevity.  See
1007  [[http://wiki.call-cc.org/eggref/4/sdl2#ensuring-proper-clean-up|the
1008  relevant sdl2 egg section]] for further details.
1009
1010=== License
1011
1012 Copyright (c) 2016, Vasilij Schneidermann
1013 
1014 This software is provided 'as-is', without any express or implied
1015 warranty. In no event will the authors be held liable for any damages
1016 arising from the use of this software.
1017 
1018 Permission is granted to anyone to use this software for any purpose,
1019 including commercial applications, and to alter it and redistribute it
1020 freely, subject to the following restrictions:
1021 
1022 1. The origin of this software must not be misrepresented; you must not
1023    claim that you wrote the original software. If you use this software
1024    in a product, an acknowledgement in the product documentation would be
1025    appreciated but is not required.
1026 2. Altered source versions must be plainly marked as such, and must not be
1027    misrepresented as being the original software.
1028 3. This notice may not be removed or altered from any source distribution.
1029
1030=== Version history
1031
1032==== 0.2
1033
1034* Fix compilation warning (thanks, evhan!)
1035* Minor code cleanup
1036
1037==== 0.1
1038
1039* Initial release
Note: See TracBrowser for help on using the repository browser.