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

Last change on this file since 39772 was 39772, checked in by Vasilij Schneidermann, 3 months ago

kiwi: Release 1.0.1

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