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

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

Add wiki-specific example with and without SXML interface, add notes section

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