source: project/wiki/eggref/5/kiwi @ 38650

Last change on this file since 38650 was 38650, checked in by Vasilij Schneidermann, 14 months ago

kiwi: Update doc examples to C5

File size: 31.4 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://depp.brause.cc/kiwi]]
20
21=== Requirements
22
23Both KiWi and SDL2 must be available on your machine.  An Arch Linux
24PKGBUILD is available
25[[https://depp.brause.cc/pkgbuilds/kiwi-git/PKGBUILD|here]].
26The bindings are based on everything up to commit
27[[https://github.com/mobius3/kiwi/commits/77ec0de71a0f365163676a752bc85477be5fae2f|77ec0d]],
28so they might break on API-incompatible changes introduced after
292018-08-20.  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 font 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 this is optional as
163KiWi comes baked in with Source Sans Pro as default font.
164
165===== gui-text-color / gui-text-color-set!
166
167<procedure>(gui-text-color GUI)</procedure>
168<procedure>(gui-text-color-set! GUI TEXT-COLOR)</procedure>
169<setter>(set! (gui-text-color GUI) TEXT-COLOR)</setter>
170
171Retrieves or sets the text color of {{GUI}}.
172
173===== gui-tileset-surface / gui-tileset-surface-set!
174
175<procedure>(gui-tileset-surface GUI)</procedure>
176<procedure>(gui-tileset-surface-set! GUI TILESET-SURFACE)</procedure>
177<setter>(set! (gui-tileset-surface GUI) TILESET-SURFACE)</setter>
178
179Retrieves or sets the tileset surface of {{GUI}}.
180
181==== Rects
182
183===== rect
184
185<procedure>(rect X Y W H)</procedure>
186
187Creates and returns a rectangle at the coordinates {{X}} and {{Y}}
188with the dimensions {{W}} and {{H}}.
189
190===== rect?
191
192<procedure>(rect? ARG)</procedure>
193
194Returns {{#t}} if {{ARG}} is an rect, otherwise {{#f}}.
195
196===== rect-x / rect-x-set!
197
198<procedure>(rect-x RECT)</procedure>
199<procedure>(rect-x-set! RECT X)</procedure>
200<setter>(set! (rect-x RECT) X)</setter>
201
202Retrieves or sets the x coordinate of {{RECT}}.
203
204===== rect-y / rect-y-set!
205
206<procedure>(rect-y RECT)</procedure>
207<procedure>(rect-y-set! RECT Y)</procedure>
208<setter>(set! (rect-y RECT) Y)</setter>
209
210Retrieves or sets the y coordinate of {{RECT}}.
211
212===== rect-w / rect-w-set!
213
214<procedure>(rect-w RECT)</procedure>
215<procedure>(rect-w-set! RECT W)</procedure>
216<setter>(set! (rect-w RECT) W)</setter>
217
218Retrieves or sets the width of {{RECT}}.
219
220===== rect-h / rect-h-set!
221
222<procedure>(rect-h RECT)</procedure>
223<procedure>(rect-h-set! RECT H)</procedure>
224<setter>(set! (rect-h RECT) H)</setter>
225
226Retrieves or sets the height of {{RECT}}.
227
228==== Rect helpers
229
230===== rect-empty?
231
232<procedure>(rect-empty? RECT)</procedure>
233
234Returns {{#t}} if {{RECT}} is empty, otherwise {{#f}}.
235
236===== enclosing-rect
237
238<procedure>(enclosing-rect RECTS)</procedure>
239
240Returns a rectangle enclosing all {{RECTS}}.
241
242===== rect-center-in-parent!
243
244<procedure>(rect-center-in-parent! PARENT INNER)</procedure>
245
246Centers {{INNER}} in {{PARENT}} vertically and horizontally by
247mutating the coordinates of {{INNER}}.
248
249===== rect-center-in-parent-vertically!
250
251<procedure>(rect-center-in-parent-vertically! PARENT INNER)</procedure>
252
253Centers {{INNER}} in {{PARENT}} vertically by mutating the coordinates
254of {{INNER}}.
255
256===== rect-center-in-parent-horizontally!
257
258<procedure>(rect-center-in-parent-horizontally! PARENT INNER)</procedure>
259
260Centers {{INNER}} in {{PARENT}} horizontally by mutating the
261coordinates of {{INNER}}.
262
263===== rect-layout-vertically!
264
265<procedure>(rect-layout-vertically! RECTS PADDING [HALIGN])</procedure>
266
267Layouts {{RECTS}} to be aligned as a vertical list with {{PADDING}}
268pixels between them by mutating their coordinates.  {{HALIGN}} must be
269one of {{(left center right)}} if specified, otherwise the horizontal
270alignment of {{RECTS}} will not be changed.
271
272===== rect-layout-horizontally!
273
274<procedure>(rect-layout-horizontally! RECTS PADDING [VALIGN])</procedure>
275
276Layouts {{RECTS}} to be aligned as a horizontal list with {{PADDING}}
277pixels between them by mutating their coordinates.  {{VALIGN}} must be
278one of {{(top middle bottom)}} if specified, otherwise the vertical
279alignment of {{RECTS}} will not be changed.
280
281===== rect-fill-parent-vertically!
282
283<procedure>(rect-fill-parent-vertically! PARENT RECTS WEIGHTS PADDING)</procedure>
284
285Layouts and resizes {{RECTS}} to fit {{PARENT}} by changing their
286coordinates and height.  {{WEIGHTS}} is a list of fixnums mapped to
287{{RECTS}}.  The higher the weight, the more space a rectangle will
288occupy.  {{PADDING}} specifies the space in pixels between the
289rectangles.  Note that this procedure does no rectangle aligning.
290
291===== rect-fill-parent-horizontally!
292
293<procedure>(rect-fill-parent-horizontally! PARENT RECTS WEIGHTS PADDING VALIGN)</procedure>
294
295Layouts and resizes {{RECTS}} to fit {{PARENT}} by changing their
296coordinates and width.  {{WEIGHTS}} is a list of fixnums mapped to
297{{RECTS}}.  The higher the weight, the more space a rectangle will
298occupy.  {{PADDING}} specifies the space in pixels between the
299rectangles.  {{VALIGN}} must be one of {{(top middle bottom)}}.
300
301===== rect-margin!
302
303<procedure>(rect-margin! PARENT INNER MARGIN)</procedure>
304
305Resizes and repositions {{INNER}} to be centered inside {{PARENT}}
306with {{MARGIN}} pixels of margin.
307
308==== Colors
309
310===== color
311
312<procedure>(color R G B A)</procedure>
313
314Creates and returns a color with the components {{R}}, {{G}}, {{B}}
315and {{A}}.
316
317===== color?
318
319<procedure>(color? ARG)</procedure>
320
321Returns {{#t}} if {{ARG}} is an color, otherwise {{#f}}.
322
323===== color-r / color-r-set!
324
325<procedure>(color-r COLOR)</procedure>
326<procedure>(color-r-set! COLOR R)</procedure>
327<setter>(set! (color-r COLOR) R)</setter>
328
329Retrieves or sets the red component of {{COLOR}}.  {{R}} must be a
330fixnum between 0 and 255 (inclusive).
331
332===== color-g / color-g-set!
333
334<procedure>(color-g COLOR)</procedure>
335<procedure>(color-g-set! COLOR G)</procedure>
336<setter>(set! (color-g COLOR) G)</setter>
337
338Retrieves or sets the green component of {{COLOR}}.  {{G}} must be a
339fixnum between 0 and 255 (inclusive).
340
341===== color-b / color-b-set!
342
343<procedure>(color-b COLOR)</procedure>
344<procedure>(color-b-set! COLOR B)</procedure>
345<setter>(set! (color-b COLOR) B)</setter>
346
347Retrieves or sets the blue component of {{COLOR}}.  {{B}} must be a
348fixnum between 0 and 255 (inclusive).
349
350===== color-a / color-a-set!
351
352<procedure>(color-a COLOR)</procedure>
353<procedure>(color-a-set! COLOR A)</procedure>
354<setter>(set! (color-a COLOR) A)</setter>
355
356Retrieves or sets the alpha component of {{COLOR}}.  {{A}} must be a
357fixnum between 0 and 255 (inclusive).
358
359==== Frame widget
360
361===== frame
362
363<procedure>(frame GUI PARENT GEOMETRY)</procedure>
364
365Creates and returns a frame widget.  {{PARENT}} must either be a
366widget or {{#f}} to create a top-level widget.  {{GEOMETRY}} is a
367rectangle describing the position and dimensions of the widget.
368
369===== frame?
370
371<procedure>(frame? ARG)</procedure>
372
373Returns {{#t}} if {{ARG}} is an frame widget, otherwise {{#f}}.
374
375==== Scrollbox widget
376
377===== scrollbox
378
379<procedure>(scrollbox GUI PARENT GEOMETRY)</procedure>
380
381Creates and returns a scrollbox widget.  {{PARENT}} must either be a
382widget or {{#f}} to create a top-level widget.  {{GEOMETRY}} is a
383rectangle describing the position and dimensions of the widget.
384
385===== scrollbox?
386
387<procedure>(scrollbox? ARG)</procedure>
388
389Returns {{#t}} if {{ARG}} is an scrollbox widget, otherwise {{#f}}.
390
391===== scrollbox-vertical-scroll!
392
393<procedure>(scrollbox-vertical-scroll! SCROLLBOX AMOUNT)</procedure>
394
395Scroll {{SCROLLBOX}} vertically by {{AMOUNT}} pixels.
396
397===== scrollbox-horizontal-scroll!
398
399<procedure>(scrollbox-horizontal-scroll! SCROLLBOX AMOUNT)</procedure>
400
401Scroll {{SCROLLBOX}} horizontally by {{AMOUNT}} pixels.
402
403==== Label widget
404
405===== label
406
407<procedure>(label GUI PARENT TEXT GEOMETRY)</procedure>
408
409Creates and returns a label widget.  {{PARENT}} must either be a
410widget or {{#f}} to create a top-level widget.  {{TEXT}} is a string
411to be used as the label's text.  {{GEOMETRY}} is a rectangle
412describing the position and dimensions of the widget.
413
414===== label?
415
416<procedure>(label? ARG)</procedure>
417
418Returns {{#t}} if {{ARG}} is an label widget, otherwise {{#f}}.
419
420===== label-text-set!
421
422<procedure>(label-text-set! LABEL TEXT)</procedure>
423
424Sets the text of {{LABEL}} to {{TEXT}}.
425
426===== label-icon-set!
427
428<procedure>(label-icon-set! LABEL CLIP)</procedure>
429
430Sets an icon for {{LABEL}}.  {{CLIP}} is a rectangle that will be
431clipped out of the currently active tileset for the icon.
432
433===== label-alignment-set!
434
435<procedure>(label-alignment-set! LABEL HALIGN HOFFSET VALIGN VOFFSET)</procedure>
436
437Sets the alignment of {{LABEL}}.  {{HALIGN}} must be one of {{(left
438center right)}} and {{VALIGN}} one of {{(top middle bottom)}}.
439{{HOFFSET}} and {{VOFFSET}} specify the horizontal and vertical offset
440in pixels.
441
442===== label-style-set!
443
444<procedure>(label-style-set! LABEL STYLE)</procedure>
445
446Sets the text style of {{LABEL}}.  {{STYLE}} must be one of {{(normal
447bold italic underline strikethrough)}}.
448
449===== label-font / label-font-set!
450
451<procedure>(label-font LABEL)</procedure>
452<procedure>(label-font-set! LABEL FONT)</procedure>
453<setter>(set! (label-font LABEL) FONT)</setter>
454
455Retrieves or sets the font of {{LABEL}}.
456
457===== label-text-color / label-text-color-set!
458
459<procedure>(label-text-color LABEL)</procedure>
460<procedure>(label-text-color-set! LABEL TEXT-COLOR)</procedure>
461<setter>(set! (label-text-color LABEL) TEXT-COLOR)</setter>
462
463Retrieves or sets the text color of {{LABEL}}.  Note that this will
464default to black.
465
466===== label-text-color-set?
467
468<procedure>(label-text-color-set? LABEL)</procedure>
469
470Returns {{#t}} if the text color of {{LABEL}} has been set by the
471user.
472
473==== Button widget
474
475===== button
476
477<procedure>(button GUI PARENT TEXT GEOMETRY)</procedure>
478
479Creates and returns a button widget.  {{PARENT}} must either be a
480widget or {{#f}} to create a top-level widget.  {{TEXT}} is a string
481to be used for creating the button's label.  {{GEOMETRY}} is a
482rectangle describing the position and dimensions of the widget.
483
484===== button*
485
486<procedure>(button* GUI PARENT LABEL GEOMETRY)</procedure>
487
488Creates and returns a button widget.  {{PARENT}} must either be a
489widget or {{#f}} to create a top-level widget.  {{LABEL}} is a label
490to be associated with the button and can be {{#f}} to have none.
491{{GEOMETRY}} is a rectangle describing the position and dimensions of
492the widget.
493
494===== button?
495
496<procedure>(button? ARG)</procedure>
497
498Returns {{#t}} if {{ARG}} is an button widget, otherwise {{#f}}.
499
500===== button-label / button-label-set!
501
502<procedure>(button-label BUTTON)</procedure>
503<procedure>(button-label-set! BUTTON LABEL)</procedure>
504<setter>(set! (button-label BUTTON) LABEL)</setter>
505
506Retrieves or sets the label of {{BUTTON}}.  The latter returns the old
507label.
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==== Toggle widget
568
569===== toggle
570
571<procedure>(toggle GUI PARENT GEOMETRY)</procedure>
572
573Creates and returns a toggle widget.  {{PARENT}} must either be a
574widget or {{#f}} to create a top-level widget.  {{GEOMETRY}} is a
575rectangle describing the position and dimensions of the widget.
576
577===== toggle-checked? / toggle-checked?-set!
578
579<procedure>(toggle-checked? TOGGLE)</procedure>
580<procedure>(toggle-checked?-set! TOGGLE CHECKED?)</procedure>
581<setter>(set! (toggle-checked? TOGGLE) CHECKED?)</setter>
582
583Retrieves or sets the activation state of {{TOGGLE}}.  {{CHECKED?}}
584must be either {{#t}} or {{#f}}.
585
586==== Widget helpers
587
588===== widget?
589
590<procedure>(widget? ARG)</procedure>
591
592Returns {{#t}} if {{ARG}} is an widget, otherwise {{#f}}.
593
594===== widget-type
595
596<procedure>(widget-type WIDGET)</procedure>
597
598Returns a symbol describing the widget type.  It will be one of
599{{(frame scrollbox label button editbox)}}.
600
601===== widget-gui
602
603<procedure>(widget-gui WIDGET)</procedure>
604
605Returns the GUI associated with {{WIDGET}}.  This is a convenience
606procedure intended for use in event handlers.
607
608===== widget-driver
609
610<procedure>(widget-driver WIDGET)</procedure>
611
612Returns the driver associated with {{WIDGET}}.  This is a convenience
613procedure intended for use in event handlers.
614
615===== widget-tileset-surface / widget-tileset-surface-set!
616
617<procedure>(widget-tileset-surface WIDGET)</procedure>
618<procedure>(widget-tileset-surface-set! WIDGET TILESET-SURFACE)</procedure>
619<setter>(set! (widget-tileset-surface WIDGET) TILESET-SURFACE)</setter>
620
621Retrieves or sets the tileset surface of {{WIDGET}}.
622
623===== widget-parent
624
625<procedure>(widget-parent WIDGET)</procedure>
626
627Returns the parent widget of {{WIDGET}} or {{#f}} if {{WIDGET}} is a
628top-level widget.
629
630===== widget-children
631
632<procedure>(widget-children WIDGET)</procedure>
633
634Returns the children widgets of {{WIDGET}} as list.  If {{WIDGET}} has
635no children, an empty list is returned.
636
637===== reparent-widget!
638
639<procedure>(reparent-widget! WIDGET PARENT)</procedure>
640
641Changes the parent of {{WIDGET}} to {{PARENT}}.  Note that this will
642not update the geometry of {{WIDGET}}.  To make {{WIDGET}} a top-level
643widget, use {{#f}} as value for {{PARENT}}.
644
645===== bring-widget-to-front!
646
647<procedure>(bring-widget-to-front! WIDGET)</procedure>
648
649Modifies the widget tree to make {{WIDGET}} appear on the front.
650
651===== widget-focus-set!
652
653<procedure>(widget-focus-set! WIDGET)</procedure>
654
655Sets the GUI focus to {{WIDGET}}.
656
657===== widget-clip-children?-set!
658
659<procedure>(widget-clip-children?-set! WIDGET FLAG)</procedure>
660
661Change whether the children of {{WIDGET}} should be clipped to its
662geometry.  {{FLAG}} must be either {{#t}} or {{#f}}.
663
664===== destroy-widget!
665
666<procedure>(destroy-widget! WIDGET [CHILDREN?])</procedure>
667
668Destroys {{WIDGET}} and frees its resources.  If {{CHILDREN?}} is
669{{#t}}, destroy its children as well, otherwise reparent them to the
670parent of {{WIDGET}}.  While this procedure can be used to remove
671widgets while the GUI is still running, consider hiding them instead.
672
673===== hide-widget!
674
675<procedure>(hide-widget! WIDGET)</procedure>
676
677Hides {{WIDGET}} and its children.  This is equivalent to
678{{(enable-widget-hint! WIDGET 'hidden #t)}}.
679
680===== show-widget!
681
682<procedure>(show-widget! WIDGET)</procedure>
683
684Displays {{WIDGET}} and its children again.  This is equivalent to
685{{(disable-widget-hint! WIDGET 'hidden #t)}}.
686
687===== widget-hidden?
688
689<procedure>(widget-hidden? WIDGET)</procedure>
690
691Returns {{#t}} if {{WIDGET}} is hidden, otherwise {{#f}}.  This is
692equivalent to {{(query-widget-hint WIDGET 'hidden)}}.
693
694===== block-widget-input-events!
695
696<procedure>(block-widget-input-events! WIDGET)</procedure>
697
698Blocks {{WIDGET}} and its children from receiving events.  This is
699equivalent to {{(enable-widget-hint! WIDGET 'block-input-events #f)}}.
700
701===== unblock-widget-input-events!
702
703<procedure>(unblock-widget-input-events WIDGET)</procedure>
704
705Unblocks input event blocking for {{WIDGET}}.  This is equivalent to
706{{(disable-widget-hint! WIDGET 'block-input-events #f)}}.
707
708===== widget-input-events-blocked?
709
710<procedure>(widget-input-events-blocked? WIDGET)</procedure>
711
712Returns {{#t}} if events are blocked for {{WIDGET}}, otherwise {{#f}}.
713This is equivalent to {{(query-widget-hint WIDGET
714'block-input-events)}}.
715
716===== enable-widget-hint!
717
718<procedure>(enable-widget-hint! WIDGET HINT RECUR?)</procedure>
719
720Enables the widget hint {{HINT}} for {{WIDGET}}.  If {{RECUR?}} is
721{{#t}}, enable it recursively.  {{HINT}} must be one of
722{{(allow-tile-stretch block-input-events ignore-input-events frameless
723hidden)}}.
724
725===== disable-widget-hint!
726
727<procedure>(disable-widget-hint! WIDGET HINT RECUR?)</procedure>
728
729Disables the widget hint {{HINT}} for {{WIDGET}}.  If {{RECUR?}} is
730{{#t}}, disable it recursively.  {{HINT}} must be one of
731{{(allow-tile-stretch block-input-events ignore-input-events frameless
732hidden)}}.
733
734===== query-widget-hint
735
736<procedure>(query-widget-hint WIDGET HINT)</procedure>
737
738Query {{WIDGET}} for {{HINT}}, returning either {{#t}} if enabled or
739{{#f}} if disabled.  {{HINT}} must be one of {{(allow-tile-stretch
740block-input-events ignore-input-events frameless hidden)}}.
741
742===== widget-geometry / widget-geometry-set!
743
744<procedure>(widget-geometry WIDGET)</procedure>
745<procedure>(widget-geometry-set! WIDGET GEOMETRY)</procedure>
746<setter>(set! (widget-geometry WIDGET) GEOMETRY)</setter>
747
748Retrieves or sets the geometry of {{WIDGET}}.
749
750===== widget-absolute-geometry
751
752<procedure>(widget-absolute-geometry WIDGET)</procedure>
753
754Returns the absolute geometry of {{WIDGET}}.  Its coordinates are
755relative to the root instead of the parent widget.
756
757===== widget-composed-geometry
758
759<procedure>(widget-composed-geometry WIDGET)</procedure>
760
761Returns the composed geometry of {{WIDGET}}.  Its coordinates are
762relative to the root widget and its dimensions are equivalent to those
763of a rectangle enclosing it and its children.
764
765===== widget-center-in-parent!
766
767<procedure>(widget-center-in-parent! PARENT INNER)</procedure>
768
769Centers {{INNER}} in {{PARENT}} vertically and horizontally.
770
771===== widget-center-in-parent-vertically!
772
773<procedure>(widget-center-in-parent-vertically! PARENT INNER)</procedure>
774
775Centers {{INNER}} in {{PARENT}} vertically.
776
777===== widget-center-in-parent-horizontally!
778
779<procedure>(widget-center-in-parent-horizontally! PARENT INNER)</procedure>
780
781Centers {{INNER}} in {{PARENT}} horizontally.
782
783===== widget-layout-vertically!
784
785<procedure>(widget-layout-vertically! WIDGETS PADDING [HALIGN])</procedure>
786
787Layouts {{WIDGETS}} as a vertical list.  See
788{{rect-layout-vertically!}} for further details.
789
790===== widget-layout-horizontally!
791
792<procedure>(widget-layout-horizontally! WIDGETS PADDING [VALIGN])</procedure>
793
794Layouts {{WIDGETS}} as horizontal list.  See
795{{rect-layout-horizontally!}} for further details.
796
797===== widget-fill-parent-vertically!
798
799<procedure>(widget-fill-parent-vertically! PARENT RECTS WEIGHTS PADDING)</procedure>
800
801Layouts and resizes {{WIDGETS}} to fit {{PARENT}}.  See
802{{rect-fill-parent-vertically!}} for further details.
803
804===== widget-fill-parent-horizontally!
805
806<procedure>(widget-fill-parent-horizontally! PARENT RECTS WEIGHTS PADDING VALIGN)</procedure>
807
808Layouts and resizes {{WIDGETS}} to fit {{PARENT}}.  See
809{{rect-fill-parent-horizontally!}} for further details.
810
811===== rect-margin!
812
813<procedure>(widget-margin! PARENT INNER MARGIN)</procedure>
814
815Resizes and repositions {{INNER}} to be centered inside {{PARENT}}
816with {{MARGIN}} pixels of margin.
817
818==== Handlers
819
820===== handler-set!
821
822<procedure>(handler-set! WIDGET TYPE PROC)</procedure>
823
824Sets an event handler of {{TYPE}} for {{WIDGET}} to {{PROC}}.
825{{TYPE}} must be one of {{(mouse-over mouse-leave mouse-down mouse-up
826focus-gain focus-lose text-input drag-start drag-stop drag)}}.
827Depending on {{TYPE}}, {{PROC}} must be a procedure accepting the
828corresponding argument list:
829
830; mouse-over : {{(lambda (widget) ...)}}
831; mouse-leave : {{(lambda (widget) ...)}}
832; mouse-down : {{(lambda (widget button) ...)}}
833; mouse-up : {{(lambda (widget button) ...)}}
834; focus-gain : {{(lambda (widget) ...)}}
835; focus-lose : {{(lambda (widget) ...)}}
836; text-input : {{(lambda (widget text) ...)}}
837; drag-start : {{(lambda (widget x y) ...)}}
838; drag-stop : {{(lambda (widget x y) ...)}}
839; drag : {{(lambda (widget x y relx rely) ...)}}
840
841===== handler-remove!
842
843<procedure>(handler-remove! WIDGET TYPE)</procedure>
844
845Removes an event handler of {{TYPE}} for {{WIDGET}}.  {{TYPE}} must be
846one of {{(mouse-over mouse-leave mouse-down mouse-up focus-gain
847focus-lose text-input drag-start drag-stop drag)}}.
848
849==== SXML interface
850
851===== widgets
852
853<procedure>(widgets GUI [PARENT] SXML)</procedure>
854
855Creates widgets based on {{SXML}}.  If {{PARENT}} is specified, use
856that widget as the parent of the newly created widgets, otherwise
857create top-level widgets.
858
859Elements must be one of {{(frame scrollbox label button editbox toggle)}}.
860Each element has mandatory attributes that correspond to their
861constructor procedures and optional attributes that correspond to
862their other setter procedures plus generic setter procedures.  The
863following definition lists summarizes them for quick reference:
864
865Mandatory attributes for all widget types:
866
867; x : X coordinate
868; y : Y coordinate
869; w : width
870; h : height
871
872Mandatory attributes for specific widget types:
873
874; text : Text for label, button and editbox widgets
875
876Optional attributes for all widget types:
877
878; tileset : Tileset surface
879; hidden? : Hide widget, value must be {{#t}}
880; id : Symbol identifier for lookup with {{widget-by-id}}
881; <event handler type> : Procedure, see {{handler-set!}} for the attribute name and function signature of the value
882
883Optional attributes for specific widget types:
884
885; icon : List of {{x}}, {{y}}, {{w}} and {{h}} attributes for label widgets
886; align : List as specified in {{label-alignment-set!}} for label widgets
887; style : Style symbol as specified in {{label-style-set!}} for label widgets
888; font : Font for label and editbox widgets
889; color : Color for label and editbox widgets
890; position : Index for editbox widgets
891; checked? : Activation state for toggle widgets
892
893===== widget-by-id
894
895<procedure>(widget-by-id ID)</procedure>
896
897Returns either a widget that has been defined previously with the
898{{widgets}} procedure and an {{id}} attribute or {{#f}} if it couldn't
899be found.
900
901=== Examples
902
903Frame with "Hello World!" label (requires a {{tileset.png}} and
904{{Fontin-Regular.ttf}} in your cwd):
905
906<enscript highlight="scheme">
907(import scheme)
908(import (chicken base))
909(import (prefix sdl2 sdl2:))
910(import (prefix kiwi kw:))
911(import (only sdl2-internals unwrap-renderer unwrap-window))
912
913(sdl2:set-main-ready!)
914(sdl2:init! '(everything))
915
916(define width 320)
917(define height 240)
918
919(define-values (window renderer)
920  (sdl2:create-window-and-renderer! width height))
921
922(sdl2:render-draw-color-set! renderer (sdl2:make-color 100 100 100))
923
924(define driver (kw:create-sdl2-driver (unwrap-renderer renderer)
925                                      (unwrap-window window)))
926
927(define tileset (kw:load-surface driver "tileset.png"))
928(define gui (kw:init! driver tileset))
929
930(define font (kw:load-font driver "Fontin-Regular.ttf" 12))
931(kw:gui-font-set! gui font)
932
933(define geometry (kw:rect 0 0 width height))
934(define frame (kw:frame gui #f geometry))
935(define label (kw:label gui frame "Hello World!" geometry))
936
937(let loop ()
938  (when (not (sdl2:quit-requested?))
939    (sdl2:render-clear! renderer)
940    (kw:process-events! gui)
941    (kw:paint! gui)
942    (sdl2:delay! 1)
943    (sdl2:render-present! renderer)
944    (loop)))
945
946(kw:quit! gui)
947(sdl2:quit!)
948</enscript>
949
950Same example, but with the SXML interface:
951
952<enscript highlight="scheme">
953(import scheme)
954(import (chicken base))
955(import (prefix sdl2 sdl2:))
956(import (prefix kiwi kw:))
957(import (only sdl2-internals unwrap-renderer unwrap-window))
958
959(sdl2:set-main-ready!)
960(sdl2:init! '(everything))
961
962(define width 320)
963(define height 240)
964
965(define-values (window renderer)
966  (sdl2:create-window-and-renderer! width height))
967
968(sdl2:render-draw-color-set! renderer (sdl2:make-color 100 100 100))
969
970(define driver (kw:create-sdl2-driver (unwrap-renderer renderer)
971                                      (unwrap-window window)))
972
973(define tileset (kw:load-surface driver "tileset.png"))
974(define gui (kw:init! driver tileset))
975
976(define font (kw:load-font driver "Fontin-Regular.ttf" 12))
977(kw:gui-font-set! gui font)
978
979(kw:widgets gui
980 `(frame
981   (@ (x 0) (y 0) (w ,width) (h ,height))
982   (label
983    (@ (x 0) (y 0) (w ,width) (h ,height)
984       (text "Hello World!")))))
985
986(let loop ()
987  (when (not (sdl2:quit-requested?))
988    (sdl2:render-clear! renderer)
989    (kw:process-events! gui)
990    (kw:paint! gui)
991    (sdl2:delay! 1)
992    (sdl2:render-present! renderer)
993    (loop)))
994
995(kw:quit! gui)
996(sdl2:quit!)
997</enscript>
998
999Further examples can be found in
1000[[https://depp.brause.cc/kiwi/examples|the repository]] and contain
1001[[https://github.com/mobius3/KiWi/tree/master/examples|the original
1002set of examples]] as well as two new ones, a more advanced "Hello
1003World!" and a simple image viewer. The [[sdl2]] and [[sdl2-image]]
1004eggs are required to compile and run them.
1005
1006=== Notes
1007
1008* Unlike many other GUI toolkits, KiWi requires you to use your own
1009  resources.  Make sure your tileset can be found when running your
1010  application, otherwise it will segfault.
1011* There is no ready-made main loop implementation, therefore you'll
1012  have to write your own.  While this is sort of a hassle, it allows
1013  for more flexibility and better integration with your application
1014  than with GUI toolkits not offering that option.
1015* Increase the delay time in your main loop to lower the FPS and
1016  overall CPU usage.
1017* It's strongly recommended to use top-level definitions for the
1018  driver, GUI and its font and tileset to avoid references to them
1019  being garbage-collected early, possibly resulting in a segfault.
1020* Refer to [[https://github.com/mobius3/KiWi/tree/master/src|the KiWi
1021  headers]] for documentation on details not covered in this wiki
1022  page, such as how geometries work, creation of custom widgets and
1023  any functionality without bindings.
1024* If you want to create a new tileset, use
1025  [[https://github.com/mobius3/KiWi/raw/master/examples/tileset/tileset.xcf|tileset.xcf]]
1026  from the KiWi repository as basis.
1027* It's strongly recommended to use the {{(on-exit)}} and
1028  {{(current-exception-handler)}} parameters during development to
1029  exit the application properly at all times.  This has been omitted
1030  from the examples for brevity.  See
1031  [[http://wiki.call-cc.org/eggref/4/sdl2#ensuring-proper-clean-up|the
1032  relevant sdl2 egg section]] for further details.
1033
1034=== License
1035
1036 Copyright (c) 2016, Vasilij Schneidermann
1037 
1038 This software is provided 'as-is', without any express or implied
1039 warranty. In no event will the authors be held liable for any damages
1040 arising from the use of this software.
1041 
1042 Permission is granted to anyone to use this software for any purpose,
1043 including commercial applications, and to alter it and redistribute it
1044 freely, subject to the following restrictions:
1045 
1046 1. The origin of this software must not be misrepresented; you must not
1047    claim that you wrote the original software. If you use this software
1048    in a product, an acknowledgement in the product documentation would be
1049    appreciated but is not required.
1050 2. Altered source versions must be plainly marked as such, and must not be
1051    misrepresented as being the original software.
1052 3. This notice may not be removed or altered from any source distribution.
1053
1054=== Version history
1055
1056==== 1.0
1057
1058* C5 port
1059* Sync to newer version of the library
1060* Support for checkbox, debug, cursor state, debug-gizmos, toggle functions
1061* Added widgets example
1062
1063==== 0.3
1064
1065* Simplified examples
1066* Improve memory management for color and rectangle types
1067* Support for toggle widget, new button API and default font
1068* Added {{rect-margin!}} and {{widget-margin!}} helper
1069
1070==== 0.2
1071
1072* Fix compilation warning (thanks, evhan!)
1073* Minor code cleanup
1074
1075==== 0.1
1076
1077* Initial release
Note: See TracBrowser for help on using the repository browser.