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

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

Publish kiwi documentation

File size: 25.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 : 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 : Adds an 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 : Label and button widgets
860; align : Label widgets
861; style : Label widgets
862; font : Label, button and editbox widgets
863; color : Label, button and editbox widgets
864; position : 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
876Examples can be found in the repository and contain
877[[https://github.com/mobius3/KiWi/tree/master/examples|the original
878set of examples]] as well as two new ones. The [[sdl2]] and
879[[sdl2-image]] eggs are required to compile and run them.
880
881=== License
882
883 Copyright (c) 2016, Vasilij Schneidermann
884 
885 This software is provided 'as-is', without any express or implied
886 warranty. In no event will the authors be held liable for any damages
887 arising from the use of this software.
888 
889 Permission is granted to anyone to use this software for any purpose,
890 including commercial applications, and to alter it and redistribute it
891 freely, subject to the following restrictions:
892 
893 1. The origin of this software must not be misrepresented; you must not
894    claim that you wrote the original software. If you use this software
895    in a product, an acknowledgement in the product documentation would be
896    appreciated but is not required.
897 2. Altered source versions must be plainly marked as such, and must not be
898    misrepresented as being the original software.
899 3. This notice may not be removed or altered from any source distribution.
900
901=== Version history
902
903==== 0.1
904
905* Initial release
Note: See TracBrowser for help on using the repository browser.