Source

LuaTools / Docs / LuaGUI.xml

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
<?xml version="1.0" encoding="UTF-8"?>
<?oxygen RNGSchema="http://docbook.org/xml/5.0/rng/docbookxi.rng" type="xml"?>
<?oxygen SCHSchema="http://docbook.org/xml/5.0/rng/docbookxi.rng"?>
<article xmlns="http://docbook.org/ns/docbook" version="5.0">
    <title>LuaGUI Documentation</title>
    <para>LuaGUI is a Lua module tool for creating windowed applications. It is built on wxLua,
        which itself is built on wxWidgets.</para>
    <para>The idea behind the tool is very simple. You define a window using XML. You define
        controls with the XML file, as well as the script functions that you use to interact with
        the controls. Controls can be accessed directly, based on what was entered into the XML
        files.</para>
    <note>
        <para>While this sounds suspiciously like XAML definitions for WPF, this tool is not
            analogous to that. XAML and WPF are rather more powerful than this.</para>
    </note>
    <para>The purpose of this tool is not to replace wxLua/wxWidgets; you will still need to use
        wxLua directly to access controls and the like. The purpose of this tool is to make it
        easier to define the layout of windows. Using wxLua to do layout is somewhat cumbersome.
        With LuaGUI, this is much easier, allowing you to define the important part of your
        application.</para>
    <section>
        <title>Accessing</title>
        <para>The module is called <literal>LuaGUI</literal>, and it is included using the standard
                <function>require</function> function.</para>
        <para>To load an XML file, call the function <function>LuaGUI.ParseFile</function>. This
            function takes the filename of the XML file representing the data, and returns a table
            containing the window data. It may also take additional parameters to be passed along to
            any application scripts. The main frame window created by this function is also shown to
            the user. All the user needs to do after calling this function is to call
                <function>wx.wxGetApp():MainLoop()</function> to start the main loop. They may of
            course post-pone this to do some setup work of their own.</para>
        <para>The return value of this function is a table. This table contains a number of members.
            All of these should be called with <quote>:</quote> instead of <quote>.</quote></para>
        <glosslist>
            <glossentry>
                <glossterm>GetMainWindow</glossterm>
                <glossdef>
                    <para>A member function that returns the wxFrame object representing the main
                        window.</para>
                </glossdef>
            </glossentry>
            <glossentry>
                <glossterm>GetMainAuiManager</glossterm>
                <glossdef>
                    <para>A member function that returns the AUI manager for the main wxFrame
                        window.</para>
                </glossdef>
            </glossentry>
            <glossentry>
                <glossterm>GetWindow</glossterm>
                <glossdef>
                    <para>A member function that takes a control ID. It returns the wxLua object
                        that is referenced by that ID.</para>
                </glossdef>
            </glossentry>
            <glossentry>
                <glossterm>GetDialog</glossterm>
                <glossdef>
                    <para>A member function that retrieves the wxDialog by control ID.</para>
                </glossdef>
            </glossentry>
            <glossentry>
                <glossterm>DoModalData</glossterm>
                <glossdef>
                    <para>A member function that displays a dialog modally. It takes two parameters:
                        the ID of the dialog, and a table describing the starting data to be stored
                        in the dialog. If the user presses the OK or Yes buttons, the data in the
                        table will be filled in by the new values entered by the user.</para>
                </glossdef>
            </glossentry>
        </glosslist>
        <para>There are other members to this table, but the system reserves the right to change
            them in the future.</para>
        <para>wxLua does something considered to be unfortunate. It replaces the standard Lua print
            function with its own. The wxLua version displays a message box. However, most wxLua
            windows are required to have a console, so there is no real point to this. LuaGUI undoes
            this replacement by saving the standard Lua print function's pointer before including
            wxLua, then overwriting wxLua's version. To get this behavior to work correctly, you
            must not <function>require</function> wxLua yourself before requiring LuaGUI.</para>
        <para>You may actually want the message box version. It is accessible from the LuaGUI table,
            in the function <function>LuaGUI.MsgBoxPrint.</function></para>
    </section>
    <section>
        <title>XML Format</title>
        <para>The XML file format defines the arrangements of controls in the main window and any
            dialogs. There is a RelaxNG schema available, if you would like guided editing.</para>
        <para>The root element is called <classname>app</classname>. It is not in a namespace. This
            element defines the entire application. It may have an attribute
            <literal>show</literal>, which can be <quote><literal>true</literal></quote> or
                    <quote><literal>false</literal></quote>. If it is
                    <quote><literal>false</literal>,</quote> then the main window will not be shown
            to the user. This allows the application to resize it later.</para>
        <formalpara>
            <title>Accelerators</title>
            <para>The first children of <classname>appWnd</classname> are an optional set of
                    <classname>accelerator</classname> elements. Each of these elements has a
                    <literal>key</literal> and <literal>action</literal> attribute. The
                    <literal>key</literal> attribute specifies the key combination that invokes the
                action. These are things like <quote><literal>CTRL + F1</literal></quote> or
                        <quote><literal>SHIFT + ALT + R</literal></quote>. You can use
                        <quote><literal>CTRL</literal>,</quote>
                <quote><literal>ALT</literal>,</quote> or <quote><literal>SHIFT</literal></quote> as
                modifiers to the key. The available keys that can be used in the accelerator are
                found in the appendices.</para>
        </formalpara>
        <para>The <literal>action</literal> attribute is a Lua chunk that is executed when this key
            combination is pressed while the main window has focus. The function is given no
            parameters.</para>
        <formalpara>
            <title>Frame Window</title>
            <para>After any accelerators, there must be a single <classname>frame</classname>
                element. This defines the main window of the application.</para>
        </formalpara>
        <para>It must have a <literal>title</literal> attribute, which defines the text that goes
            into the main window title bar. It must also have <literal>width</literal> and
                <literal>height</literal> attributes that define the pixel size of the frame
            window.</para>
        <note>
            <title>wxWindows Note</title>
            <para>The main wxFrame window created by the code is managed by an AUI Manager. All of
                the direct children of this window are given to this AUI Manager to manage.</para>
        </note>
        <formalpara>
            <title>Dialog Windows</title>
            <para>After the frame window is an optional number of <classname>dialog</classname>
                elements. These define the layout of dialogs that the user can access with the
                    <function>GetDialog</function> and <function>DoModalData</function> functions.
                These elements must have an <literal>id</literal> attribute, a unique string that
                identifies this particular dialog. These will be detailed in their own
                section.</para>
        </formalpara>
        <formalpara>
            <title>Application Scripts</title>
            <para>After any dialog elements are zero or more <classname>execute</classname>
                elements. These elements represent scripts that will be run after the entire file is
                processed and all windows and controls have been created. All scripts are executed
                in the order they are presented in the XML file.</para>
        </formalpara>
        <para>These scripts can be defined in one of two ways. They can be defined inline, as the
            textual content of the <classname>execute</classname> element. You may use CDATA to
            write longer Lua scripts without escaping them. If they are defined inline, they can be
            given an optional <literal>name</literal> attribute. This attribute is the name that Lua
            will call the script on any compile errors or asserts.</para>
        <para>Alternatively, the <classname>execute</classname> element can refer to a file to be
            loaded. This path is always relative to the XML file itself.</para>
        <para>The script function is given two parameters. The first is the table containing the
            methods above, so that the script can use the data. The second is the relative directory
            path from the current directory to the XML file (ending in a <quote>\</quote>). If you
            prepend this path to any filenames you want to load, you can load files relative to this
            directory. Any additional parameters passed to <function>ParseFilename</function> will
            also be given after these two parameters.</para>
        <para>These scripts are useful for many things. They can define functions that would
            generally be too long or complex for XML attributes. They can also be used to make the
            XML file completely self-contained, holding both the arrangement of windows and how
            those windows work. This makes the XML file itself very much like an application.</para>
        <section>
            <title>Windows</title>
            <para>A number of XML elements in this system define windows. All windows share a set of
                attributes.</para>
            <para>Every window except the frame can have an <literal>id</literal> attribute; this is
                a string that is unique. Windows that have an id can be queried by this id, using
                the <function>GetWindow</function> function. Windows that do not have an
                    <literal>id</literal> attribute cannot be queried by the system.</para>
            <para>The uniqueness of an identifier is within either frame containers or dialogs. That
                is, if you have a id in the main window, it must be unique to all other ids in the
                main window. But a dialog can have the same id. Two dialogs can also have the same
                id without incident.</para>
            <para>Every window except the frame and dialog windows can have an
                    <literal>tip</literal> attribute. This is a string that represents the tooltip
                to be displayed for that window.</para>
            <para>Windows can be grouped into 4 classifications: frames (including dialogs), frame
                containers, non-frame containers, and controls.</para>
        </section>
        <section>
            <title>Frame Containers</title>
            <para>The frame window, defined by the <classname>frame</classname> element, represents
                the main application window. It may have a <classname>menubar</classname> element as
                a child; if so, this menubar element must come <emphasis>first</emphasis>. This
                element defines the window's menus.</para>
            <para>Outside of the optional <classname>menubar</classname> element, the direct
                children of the frame element are collectively referred to as <glossterm>frame
                    containers.</glossterm> There are two kinds of frame container elements:
                    <classname>panel</classname> and <classname>toolbar</classname>.</para>
            <para>A toolbar is what it sounds like, though it is not as limited as it sounds. A
                toolbar is a window that is anchored to a side of the frame window that contains
                controls. You are generally familiar with toolbars containing buttons, and perhaps
                dropdowns. But toolbars in this system can contain anything. Conceptually, a toolbar
                should contain commonly used functions, and the state of these should update based
                on the state of the application data.</para>
            <para>A panel is a more general-purpose container. Panels and toolbars can contain the
                exact same elements. The difference between the lies in how the user can interact
                with the two kinds of frame containers, and how they are laid out within the main
                frame window.</para>
            <para>The frame containers are all attached to a specific side of the main window. This
                side is noted by the <literal>direction</literal> attribute. This can be
                        <quote><literal>left</literal>,</quote>
                <quote><literal>right</literal>,</quote>
                <quote><literal>top</literal>,</quote> or
                <quote><literal>bottom</literal>.</quote></para>
            <para>These containers can be given a row number. If the row number for containers that
                are on the same side match up, then the containers are stacked top-to-bottom for
                containers on the left or right side and left-to-right for containers on the top and
                bottom. They are stacked in the order they appear in the document. The row is
                specified by the <literal>row</literal> attribute, and it can be any number 0 or
                greater. Higher rows will be more towards the center than lower rows. If the
                attribute is not specified, it defaults to 0.</para>
            <para>When panels and toolbars are attached to the same side of a window, toolbars
                always take precedence, regardless of order. Toolbars will be assigned first,
                according to their rows. Then panels will be assigned according to their rows. Thus,
                toolbars are always farther away from the center than panels. Toolbar rows and panel
                rows are different; you cannot put a toolbar in a panel row or vice-versa. If you
                use the same row number for a toolbar and a panel on the same side, the two will
                still be beside each other.</para>
            <para>One frame container can be designated the center pane; this can only be given to a
                    <classname>panel</classname> container. This panel will have all of the room
                that is left after all of the non-center containers are given their sizes. The
                center panel is designated by the setting the <literal>centerpane</literal>
                attribute to <quote>true.</quote> This will override the
                    <literal>direction</literal> attribute.</para>
            <para>Panels can have a title, defined by the <literal>title</literal> attribute.
                Whether they have a title or not, all panels are "tearaway"; you can grab them by
                their title bar, pull them off of the side of the window, and attach them to a
                different side. A panel can even be made a free-standing window. There is no way to
                remove or prevent this behavior. The only panel that cannot be pulled away is the
                single panel designated the center panel.</para>
            <para>Toolbars <emphasis>can</emphasis> have this ability, but it is optional. It is set
                by the <classname>toolbar</classname>-only <literal>gripper</literal> attribute.
                This attribute defaults to <quote><literal>true</literal></quote>; if it is
                        <quote><literal>false</literal>,</quote> then the toolbar will be fixed in
                place and cannot move.</para>
            <note>
                <title>Gripper Bug</title>
                <para>Toolbars with a gripper can be made into free-standing windows. When they are,
                    they have a close button that can cause the toolbar to be removed. There is no
                    LuaGUI API to detect this as of yet, so you will have to use wxLua APIs to
                    prevent it from happening or restore the toolbar when it does.</para>
            </note>
            <para>Another important difference between panels and toolbars is that panels are
                resizeable. Two panels adjacent to each other will have a resizing bar between them.
                This is true for the center panel as well. Because of this, panels only need one
                size specified: the size in the dimension that they expand on. The other size is
                automatic; panels are stretched to fill the available space. Toolbars have an innate
                size that must be specified. And no matter where the toolbar is placed, it will be
                of that size. Any empty space will be the window's background color.</para>
            <para>Panels can have a maximize button. This button causes the panel to take up all of
                the available area, including the center pane (but not covering any toolbars). To
                allow a panel to have this button, use the <literal>maximizebutton</literal>; it
                defaults to <quote><literal>false</literal></quote>. If it is
                        <quote><literal>true</literal>,</quote> then the panel will have a maximize
                button. Toolbars cannot have this.</para>
            <para>Other than these features, panels and toolbars behave like any other container
                control. They can contain any container control or leaf control. However, panels and
                toolbars cannot be contained by anything except the <classname>appWnd</classname>
                element.</para>
            <para>Frame containers also count as containers, so they have all of the attributes that
                regular containers do as well.</para>
        </section>
        <section>
            <title>Menus</title>
            <para>Frame windows can have a set of menus. This is defined by the
                    <classname>menubar</classname> element that is a child of the
                    <classname>frame</classname>. Only the frame window can have menus. If a frame
                window has a <classname>menubar</classname> element, then it must be the
                    <emphasis>first</emphasis> child of the frame. It may only have one
                menubar.</para>
            <para>The <classname>menubar</classname> element has no attributes. It has a number of
                    <classname>menu</classname> elements as children. These represent top-level
                menus. Menubars must have at least one <classname>menu</classname> element.</para>
            <para>The <classname>menu</classname> element must have a name, given with the
                    <literal>name</literal> attribute. Menus have a series of child elements. Menu
                children can be <classname>menuitem</classname>, <classname>menuspacer</classname>,
                or a nested <classname>menu</classname>, which acts as a submenu. Menus must have at
                least one child.</para>
            <para>The <classname>menuitem</classname> element represents a single entry in the menu
                that the user can click on to expect something to happen. This element has no
                children, but it may have the following attributes:</para>
            <glosslist>
                <title>Menuitem Attributes</title>
                <glossentry>
                    <glossterm>name</glossterm>
                    <glossdef>
                        <para>The name of the item, as shown to the user. Required.</para>
                    </glossdef>
                </glossentry>
                <glossentry>
                    <glossterm>tip</glossterm>
                    <glossdef>
                        <para>Tooltip text to show the user if he hovers over the item.
                            Optional.</para>
                    </glossdef>
                </glossentry>
                <glossentry>
                    <glossterm>action</glossterm>
                    <glossdef>
                        <para>A Lua chuck that will be called when the user presses this menu item.
                            It is given no parameters. Optional.</para>
                    </glossdef>
                </glossentry>
            </glosslist>
            <para>The <classname>menuspacer</classname> element represents a separator between menu
                items. This is useful for grouping. It has no attributes or child elements.</para>
        </section>
        <section>
            <title>Containers</title>
            <para>Container windows are windows that contain other windows. Containers can be nested
                within other containers. Frame containers are container windows, but they cannot be
                contained by any other container windows.</para>
            <para>Unless otherwise noted, a container can contain any other container or control
                element.</para>
            <para>Containers also count as controls; as such, they have all of the attributes that a
                control can have.</para>
            <section>
                <title>Child Arrangement</title>
                <para>All container windows share a set of common attributes. These attributes
                    define how the windows they contain are arranged within the window.</para>
                <para>There are several sizing and positioning scheme that LuaGUI supports, based on
                    wxWidget's sizers. The default is the box sizing scheme.</para>
                <para>The box sizing scheme is controlled by the <literal>box.orient</literal>
                    attribute. This attribute defines the stacking direction of child windows of
                    this container. It can be <quote><literal>horizontal</literal></quote> or
                            <quote><literal>vertical</literal></quote>. If the orientation is
                    horizontal, then each child window will be placed left-to-right in this
                    container, in the order in which the windows appear in the XML file. If the
                    orientation is vertical, then each child will be stacked top-to-bottom, again in
                    the order in which the windows appear in the XML file. If this attribute is not
                    present, then the default is vertical.</para>
                <para>Another arrangement scheme is the grid arrangement scheme. This arrangement is
                    active if either the <literal>grid.numCols</literal> or
                        <literal>grid.numRows</literal> scheme is present. Both can be present. The
                    way it works is that the container's children are arranged in a grid. The number
                    of columns in the grid is set by the <literal>grid.numCols</literal> attribute,
                    and the number of rows is set by the <literal>grid.numRows</literal> attribute.
                    If one of these is not set, or is set to zero, then the container can have any
                    number of that attribute.</para>
                <para>For example, if you set the container to have 4 columns, and it has 7
                    children, then it will automatically have 2 rows. If you set the container to
                    have 2 rows, and it has 5 children, then it will have 3 columns.</para>
                <para>The entries in the grid are always filled in row-major order. That is, if you
                    have a 2x3 grid, the second child will be in the first row, second column. The
                    fourth child will be in the second row, first column. And so on.</para>
                <para>A gap can be added between the columns and rows. The
                        <literal>grid.hGap</literal> attribute specifies the number of pixels
                    between columns, while the <literal>grid.vGap</literal> attribute specifies the
                    number of pixels between rows.</para>
                <para>The area given to each control can be portioned in one of two ways. The
                    default way is to let each column and row be independent of each other. The
                    width of any column is the largest width of any item in the column. And the
                    height of a row is the largest height of any item in the row.</para>
                <para>The other way is specified by setting the attribute
                        <literal>grid.fixed</literal> to <quote><literal>true</literal></quote>.
                    When this happens, the width of any column becomes the largest width of
                        <emphasis>any</emphasis> item in the grid, regardless of what column it is.
                    The same goes for rows. This means that each control gets as much space as the
                    largest control, and the space for every cell in the grid is the same.</para>
                <para>The <literal>proportion</literal> attribute on children of a container is used
                    in box layout to determine how much space to give each control. This does not
                    work in grid layout. When using non-fixed grid layout, it is possible to specify
                    something similar using the <literal>grid.colProportion</literal> and
                        <literal>grid.rowProportion</literal> attributes. This allows the user to
                    specify the proportions for particular columns and rows.</para>
                <para>The way this works is as follows. The width of a column is determined by the
                    largest width item in that column. This is the normal way that sizing works.
                    However, if the column's proportion is set, this changes. The width of that
                    column is proportionate to the width of other columns that have a proportion
                    value set. So if column 0 has a proportion value of 2 and column 1 has a
                    proportion value of 1, then column 0 will be 2x the width of column 1. This
                    works for rows and height as well.</para>
                <para>This works almost exactly like the <literal>proportion</literal> attribute.
                    There is one difference however: the treatment of 0. In grid layout, a
                    proportion of 0 means to give that column or row no actual room in layout.
                    Unless all columns have a proportion of 0, which then works like giving all
                    columns or rows the same proportion value: each row or column will be the same
                    size.</para>
                <para>This only serves to increase the available area provided by the grid to a
                    control. To actually have a control take advantage of the extra space, you must
                    use the usual layout attributes on that control, as specified below (alignment,
                    expand, etc).</para>
                <para>The contents of the attributes are a bit complicated, due to the need to
                    support the ability to set multiple column or row proportions. The attributes
                    contain a sequence of <quote>column/row number = proportion</quote> values.
                    These values can be separated by spaces, commas, or whatever you want except for
                    actual numbers. There can be no spaces or non-number characters between the
                    column/row number, the proportion value, and the equals sign. So the following
                    is correct: <quote>1=2 0=3,4=2 dhosaha</quote>. This is not correct: <quote>1
                        =2</quote>.</para>
                <para>You can specify the column or row proportions in any order.</para>
                <para>You cannot use box and grid sizing attributes on the same element.</para>
            </section>
            <section>
                <title>Tabs</title>
                <para>Tabs containers are defined by the <classname>tabs</classname> element. These
                    represent a series of windows, all of the same size, that take up the same area
                    of the screen. At the top of the tabs window is a list of, well, tabs; the user
                    can bring forward the corresponding window by pressing its named tab.</para>
                <para>This container's children are all <classname>tab</classname> elements. A
                        <classname>tab</classname> element is a container of arbitrary windows,
                    representing one of the tabs in the overall set of tabs.</para>
                <glosslist>
                    <title>Tab Attributes</title>
                    <glossentry>
                        <glossterm>text</glossterm>
                        <glossdef>
                            <para>The text displayed on the corresponding tab for the window.
                                Required.</para>
                        </glossdef>
                    </glossentry>
                </glosslist>
                <para>All <classname>tab</classname> elements must have a <literal>text</literal>
                    attribute; this represents the text that is displayed on the corresponding tab
                    for this window.</para>
                <para>The <classname>tabs</classname> element (the parent of the individual
                        <classname>tab</classname> windows) can have an
                        <literal>onselchange</literal> attribute. This attribute is a Lua chunk
                    representing a function that will be called whenever the user changes which tab
                    is in the foreground. This function is given one parameter: a wxNotebookEvent
                    object. To get the previous tab, call
                        <function>wxNotebookEvent::GetOldSelection()</function>, and to get the tab
                    that is being made current, call
                        <function>wxNotebookEvent::GetNewSelection()</function>.</para>
                <glosslist>
                    <title>Tabs Attributes</title>
                    <glossentry>
                        <glossterm>onselchange</glossterm>
                        <glossdef>
                            <para>A Lua chunk that will be called whenever the user changes which
                                tab is in the foreground. The chunk is given the wxNotebookEvent
                                object as a parameter. To get the previous tab, call
                                    <function>wxNotebookEvent::GetOldSelection()</function>, and to
                                get the tab that is being made current, call
                                    <function>wxNotebookEvent::GetNewSelection()</function>.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                </glosslist>
            </section>
            <section>
                <title>Collapsible Pane</title>
                <para>A collapsible pane is defined by the <classname>collpane</classname> element.
                    A collapsible pane is a container who's contents can be shown or hidden at the
                    press of a button at the top-left corner of the container. When the window's
                    contents are hidden, other windows below or to the side of the collapsible pane
                    will adjust themselves accordingly.</para>
                <glosslist>
                    <title>Collapsible Pane Attributes</title>
                    <glossentry>
                        <glossterm>text</glossterm>
                        <glossdef>
                            <para>The text shown in the button that exposes or hides the contents of
                                the pane.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>collapsed</glossterm>
                        <glossdef>
                            <para>If this is set to <quote><literal>true</literal>,</quote> then the
                                collapsible pane will start off in the collapsed state. If it is set
                                to <quote><literal>false</literal>,</quote> it will start off
                                revealed.</para>
                            <para>Optional. Defaults to
                                <quote><literal>false</literal>.</quote></para>
                        </glossdef>
                    </glossentry>
                </glosslist>
            </section>
            <section>
                <title>Box</title>
                <para>A box is defined by the <classname>box</classname> element. This is a fairly
                    simple container; it draws a box around its contents, visually separating them
                    from the windows around it.</para>
                <glosslist>
                    <title>Box Attributes</title>
                    <glossentry>
                        <glossterm>text</glossterm>
                        <glossdef>
                            <para>The text to be shown in the top-left corner of the box.
                                Required.</para>
                        </glossdef>
                    </glossentry>
                </glosslist>
            </section>
            <section>
                <title>Sizer</title>
                <para>A sizer, defined by the <classname>sizer</classname> element, is the simplest
                    of all containers. It offers no visual notation about its contents whatsoever,
                    and it takes up no space. Sizers are mostly used as layout tools, to change
                    layout among a certain set of controls within a larger set.</para>
                <para>Sizers have no special, unique attributes, other than the standard ones for
                    containers and windows.</para>
            </section>
        </section>
        <section>
            <title>Controls</title>
            <para>Controls are terminal windows; they have no child windows (technically). Controls
                typically allow the user to input or modify data.</para>
            <section>
                <title>Spacer</title>
                <para>Spacer controls, created by the <classname>spacer</classname> attribute,
                    simply takes up space. It's used primarily to help organize controls into
                    logical groups.</para>
                <para>Spacers are special, as they are not technically windows. They have none of
                    the standard window or layout attributes. Instead, they have only these
                    attributes.</para>
                <glosslist>
                    <title>Spacer Attributes</title>
                    <glossentry>
                        <glossterm>size</glossterm>
                        <glossdef>
                            <para>The quantity of space that the spacer takes up, in pixels. This
                                room is always added in the direction of the current layout.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>proportion</glossterm>
                        <glossdef>
                            <para>Identical to the standard layout attribute.</para>
                        </glossdef>
                    </glossentry>
                </glosslist>
            </section>
            <section>
                <title>Button</title>
                <para>Button controls, created by the <classname>button</classname> element,
                    provides a region of space that the user can click on to cause some
                    effect.</para>
                <glosslist>
                    <title>Button Attributes</title>
                    <glossentry>
                        <glossterm>text</glossterm>
                        <glossdef>
                            <para>The text that will be displayed in the button. Required</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>enabled</glossterm>
                        <glossdef>
                            <para>Determines whether the button is initially enabled or not. If set
                                to <quote><literal>true</literal>,</quote> then it means the button
                                is enabled by default; to disable the button by default, set it to
                                        <quote><literal>false</literal>.</quote></para>
                            <para>Optional. Defaults to
                                <quote><literal>true</literal>.</quote></para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>action</glossterm>
                        <glossdef>
                            <para>A Lua chunk that will be called when the button is clicked. It is
                                given the button click event as a parameter.</para>
                        </glossdef>
                    </glossentry>
                </glosslist>
            </section>
            <section>
                <title>Static Text</title>
                <para>Static text controls, created by the <classname>static</classname> element,
                    simply display text. This is useful for labeling controls that don't come with
                    labels.</para>
                <glosslist>
                    <title>Static Text Attributes</title>
                    <glossentry>
                        <glossterm>text</glossterm>
                        <glossdef>
                            <para>The text that will be displayed in the control. Required.</para>
                        </glossdef>
                    </glossentry>
                </glosslist>
            </section>
            <section>
                <title>Check Box</title>
                <para>A checkbox is a control, created by the <classname>checkbox</classname>
                    element, that displays a box next to some text. The user can click in the box to
                    set or unset a check mark.</para>
                <glosslist>
                    <title>Checkbox Attributes</title>
                    <glossentry>
                        <glossterm>text</glossterm>
                        <glossdef>
                            <para>A string representing the text to display next to the check
                                box.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>default</glossterm>
                        <glossdef>
                            <para>Defines the initial state of the box. If
                                        <quote><literal>true</literal>,</quote> then the checkbox
                                will be initially checked. If
                                    <quote><literal>false</literal>,</quote> then it will be
                                initially unchecked.</para>
                            <para>Optional; defaults to
                                <quote><literal>false</literal>.</quote></para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>oncheck, onuncheck</glossterm>
                        <glossdef>
                            <para>These are Lua chunks that are called with the check box is set to
                                the checked or unchecked state, respectively. These chunks receive
                                the command event for the checkbox as a parameter when
                                called.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                </glosslist>
            </section>
            <section>
                <title>3-State Check Box</title>
                <para>A 3-state checkbox, created by the <classname>checkbox3</classname> element,
                    is like a regular checkbox, except that there is a third, undefined state that
                    the check can be in.</para>
                <glosslist>
                    <title>Checkbox Attributes</title>
                    <glossentry>
                        <glossterm>text</glossterm>
                        <glossdef>
                            <para>A string representing the text to display next to the check
                                box.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>default</glossterm>
                        <glossdef>
                            <para>Defines the initial state of the box. If
                                        <quote><literal>true</literal>,</quote> then the checkbox
                                will be initially checked. If
                                    <quote><literal>false</literal>,</quote> then it will be
                                initially unchecked. If <quote><literal>undef</literal>,</quote>
                                then the checkbox will be in the undefined state initially.</para>
                            <para>Optional; defaults to
                                <quote><literal>false</literal>.</quote></para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>user</glossterm>
                        <glossdef>
                            <para>If <quote><literal>true</literal>,</quote> then the user will be
                                able to set the user will be able to set the check to undefined
                                manually. If <quote><literal>false</literal>,</quote> then the user
                                can only set the checkbox to on or off.</para>
                            <para>Optional; defaults to
                                <quote><literal>false</literal>.</quote></para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>action</glossterm>
                        <glossdef>
                            <para>A Lua chunk that will be called when the check box is changed. The
                                first parameter is the new state (as the enumerant, not boolean),
                                and the second parameter is the command event.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                </glosslist>
            </section>
            <section>
                <title>Radio Box</title>
                <para>You may have used GUI systems that have a separate radio button-type control.
                    Radio buttons are a series of options that only one of which can be active.
                    These GUI systems often have elaborate ways of connecting individual radio
                    buttons together, so that the limitation of having one of them selected is
                    preserved.</para>
                <para>This system takes a much simpler approach, though it may be less visually
                    elegant. All connected radio buttons are simply sub-elements of a single radio
                    box. A radio box, defined by the <classname>radiobuttons</classname> element, is
                    a sequence of radio buttons, only one of which can be considered active. These
                    radio buttons are wrapped by a box very similar to a <literal>box</literal>
                    container element, with a label and everything.</para>
                <para>The sequence of radio buttons are defined statically as part of the XML
                    document. The <classname>radiobuttons</classname> element has child
                        <classname>radio</classname> elements; it must have at least one. Each
                        <classname>radio</classname> element represents one of the possible
                    choices.</para>
                <para>The <classname>radio</classname> element must have a <literal>name</literal>
                    attribute. This specifies the text shown next to this option. It may also have a
                        <literal>value</literal> attribute. The value of a radio element represents
                    a string that Lua code connected to this control receives. The name is what
                    should be shown to the user; the value is what it means to the Lua code that
                    implements what needs to be done. If an element does not have a
                        <literal>value</literal> attribute, the string used for that option will be
                    the <literal>name</literal>.</para>
                <glosslist>
                    <title>Radio Box Attributes</title>
                    <glossentry>
                        <glossterm>orient</glossterm>
                        <glossdef>
                            <para>Defines the stacking direction of the radio buttons. If this is
                                        <quote><literal>horizontal</literal>,</quote> then the radio
                                buttons are stacked left-to-right, and if this is
                                        <quote><literal>vertical</literal>,</quote> they are stacked
                                top-to-bottom.</para>
                            <para>Optional. Defaults to
                                <quote><literal>vertical</literal>.</quote></para>
                            <note>
                                <para>This attribute does not mean the same thing as
                                        <literal>box.orient</literal>, though it does have similar
                                    effects.</para>
                            </note>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>text</glossterm>
                        <glossdef>
                            <para>The text label for this set of radio buttons.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>default</glossterm>
                        <glossdef>
                            <para>Text that represents the value of the radio button that should
                                initially be set. Note that this represents the
                                    <emphasis>value</emphasis> of the radio button; this text must
                                match the <literal>value</literal> attribute of one of the child
                                    <classname>radio</classname> elements. It can also match the
                                    <literal>name</literal> attribute of one if that
                                    <classname>radio</classname> element does not have a
                                value.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>action</glossterm>
                        <glossdef>
                            <para>A Lua chunk that will be called whenever the user selects one of
                                the radio buttons. The function will receive the
                                    <emphasis>value</emphasis> of the new choice as the first
                                parameter, and the radiobox event as the second parameter.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                </glosslist>
            </section>
            <section>
                <title>Edit Box</title>
                <para>An edit box is a control used to allow the user to enter or modify a string of
                    text. Edit boxes are defined by the <classname>editbox</classname> element. This
                    is a <emphasis linkend="labeled_control">labeled</emphasis> control.</para>
                <glosslist>
                    <title>Edit Box Attributes</title>
                    <glossentry>
                        <glossterm>multiline</glossterm>
                        <glossdef>
                            <para>When this option is set to <literal>true</literal>, the edit box
                                will be able to have multiple lines. Pressing the enter key will add
                                a carriage return to the text, rather than activating something
                                else. If this is <literal>false</literal>, then the edit box can
                                only hold a single line of text, and pressing enter will cause the
                                entry of the text in the box.</para>
                            <para>Optional. Defaults to <literal>false</literal>.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>readonly</glossterm>
                        <glossdef>
                            <para>When this option is set to <literal>true</literal>, the edit box's
                                text cannot be changed by the user. If this is set to
                                    <literal>false</literal>, the edit box's text can be changed by
                                the user. This is usually for making an edit box read-only
                                temporarily; a static text control is better for permanently
                                inactive text.</para>
                            <para>Optional. Defaults to <literal>false</literal>.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>default</glossterm>
                        <glossdef>
                            <para>This is a string that will be the initial text in the edit
                                box.</para>
                            <para>Optional. Defaults to the empty string.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>onentry</glossterm>
                        <glossdef>
                            <para>A Lua chunk that will be called when the user presses the enter
                                key while in a list box. It is given the text in the box as the
                                first parameter, and the event as the second.</para>
                            <para>This function does not get called for edit boxes if
                                    <literal>multiline</literal> is set to
                                <literal>true</literal>.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>onchange</glossterm>
                        <glossdef>
                            <para>A Lua chunk that will be called when the user changes the text in
                                any way. It is given the text in the box as the first parameter, and
                                the event as the second.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                </glosslist>
            </section>
            <section>
                <title>List Box</title>
                <para>A list box is a control used to allow the user to select one (or more) of a
                    number of options. Each option in the list box is defined by a string. List
                    boxes are defined by the <classname>listbox</classname> element. This is a
                        <emphasis linkend="labeled_control">labeled</emphasis> control.</para>
                <glosslist>
                    <title>List Box Attributes</title>
                    <glossentry>
                        <glossterm>type</glossterm>
                        <glossdef>
                            <para>This defines the style of listbox. This can be one of three types:
                                    <literal>single</literal>, <literal>multiple</literal>, or
                                    <literal>multichoice</literal>. A single listbox can only have
                                one item selected at a time. A multiple list box can have many items
                                selected; you select items using the shift key to select a range and
                                the control key to select individual items.</para>
                            <para>A multichoice list box is a different style of multi-selection
                                list. You select and deselect individual elements by left-clicking
                                on them; the selection of other items is not changed when you click
                                on an item.</para>
                            <para>Optional. Defaults to
                                <quote><literal>single</literal></quote></para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>sort</glossterm>
                        <glossdef>
                            <para>This tells whether the list box is sorted by string or not. If
                                this is <literal>false</literal>, then the order of the items in the
                                box is defined by the user of the list box. If this is
                                    <literal>true</literal>, then the order of the items is sorted
                                by the string.</para>
                            <para>Optional. Defaults to <literal>false</literal>.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>oncreate</glossterm>
                        <glossdef>
                            <para>A Lua chunk that is called after this control is created. It is
                                given the list box as a parameter. This is useful for initializing
                                the list box.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>onselchange</glossterm>
                        <glossdef>
                            <para>A Lua chunk that is called whenever the set of selected items
                                changes. It is given the selection changed event as a
                                parameter.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>ondblclick</glossterm>
                        <glossdef>
                            <para>A Lua chunk that is called whenever an item in the list box is
                                double clicked. It is given the selection changed event as a
                                parameter.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                </glosslist>
            </section>
            <section>
                <title>Dropdown Box</title>
                <para>A dropdown box is much like a single-selection list box, except that it takes
                    up much less room. It is an edit control connected to a button; when the user
                    clicks in the edit control or the button, then the list box will appear below
                    the edit box, allowing the user to select an item. The edit control shows the
                    currently selected item. Dropdowns are defined by the
                        <classname>dropdown</classname> element. This is a <emphasis
                        linkend="labeled_control">labeled</emphasis> control.</para>
                <glosslist>
                    <title>Dropdown Box Attributes</title>
                    <glossentry>
                        <glossterm>edit</glossterm>
                        <glossdef>
                            <para>Tells whether the user can enter strings in the dropdown or not.
                                If it is <literal>true</literal>, then the user can enter strings.
                                If it is <literal>false</literal>, then the user cannot.</para>
                            <para>Optiona. Defaults to <literal>false</literal>.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>sort</glossterm>
                        <glossdef>
                            <para>This tells whether the dropdown box is sorted by string or not. If
                                this is <literal>false</literal>, then the order of the items in the
                                box is defined by the user of the dropdown box. If this is
                                    <literal>true</literal>, then the order of the items is sorted
                                by the string.</para>
                            <para>Optional. Defaults to <literal>false</literal>.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>oncreate</glossterm>
                        <glossdef>
                            <para>A Lua chunk that is called after this control is created. It is
                                given the list box as a parameter. This is useful for initializing
                                the dropdown box with a list of options.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>onselchange</glossterm>
                        <glossdef>
                            <para>A Lua chunk that is called whenever the user selects a new item
                                from the dropdown.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>onentry</glossterm>
                        <glossdef>
                            <para>A Lua chunk that will be called when the user presses the enter
                                key while in a list box. It is given the text in the box as the
                                first parameter, and the event as the second.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                </glosslist>
            </section>
            <section>
                <title>Spinner</title>
                <para>A spinner resembles an edit box with up and down arrows beside it. It is used
                    to select integer numbers between a certain numerical range. Spinners are
                    defined by the <classname>spinner</classname> element. This is a <emphasis
                        linkend="labeled_control">labeled</emphasis> control.</para>
                <glosslist>
                    <title>Spinner Attributes</title>
                    <glossentry>
                        <glossterm>min</glossterm>
                        <glossdef>
                            <para>The smallest allowed numerical value.</para>
                            <para>Optional. Defaults to 0.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>max</glossterm>
                        <glossdef>
                            <para>The largest allowed numerical value.</para>
                            <para>Optional. Defaults to 100.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>default</glossterm>
                        <glossdef>
                            <para>The initial numerical value of the spinner. Automatically clamped
                                be between min and max.</para>
                            <para>Optional. Defaults to 50.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>wrap</glossterm>
                        <glossdef>
                            <para>If set to <quote><literal>true</literal>,</quote> then the values
                                in the control will wrap around. If
                                    <quote><literal>false</literal>,</quote> then no wrap around
                                will occur.</para>
                            <para>Optional. Defaults to
                                <quote><literal>false</literal></quote>.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>onchange</glossterm>
                        <glossdef>
                            <para>A Lua chunk that will be called every time the value in the
                                control is changed. The first parameter is the new value, and the
                                second is the event.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                </glosslist>
            </section>
            <section>
                <title>Slider</title>
                <para>A slider control is a lot like a spinner. It is a way of choosing integer
                    values over a specific range. Instead of an edit box with arrow buttons, this is
                    a bar that has a tab that can be moved to pick the value. Sliders are defined by
                    the <classname>slider</classname> element. This is a <emphasis
                        linkend="labeled_control">labeled</emphasis> control.</para>
                <glosslist>
                    <title>Slider Attributes</title>
                    <glossentry>
                        <glossterm>direction</glossterm>
                        <glossdef>
                            <para>A slider can be oriented horizontally or vertically, so that the
                                tab moves left and right or up and down. That property is set by
                                this attribute. Acceptable values are
                                        <quote><literal>horizontal</literal></quote> or
                                        <quote><literal>vertical</literal></quote></para>
                            <para>Optional. Defaults to
                                <quote><literal>horizontal</literal></quote></para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>min</glossterm>
                        <glossdef>
                            <para>The smallest allowed numerical value.</para>
                            <para>Optional. Defaults to 0.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>max</glossterm>
                        <glossdef>
                            <para>The largest allowed numerical value.</para>
                            <para>Optional. Defaults to 100.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>default</glossterm>
                        <glossdef>
                            <para>The initial numerical value of the spinner. Automatically clamped
                                be between min and max.</para>
                            <para>Optional. Defaults to 50.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>ticks</glossterm>
                        <glossdef>
                            <para>If <quote><literal>true</literal>,</quote> the slider will display
                                a number of tick-marks to the side of the tab at regular increments.
                                If <quote><literal>false</literal>,</quote> then tick marks will not
                                be automatically drawn.</para>
                            <para>Optional. Defaults to
                                <quote><literal>true</literal></quote></para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>numticks</glossterm>
                        <glossdef>
                            <para>In lieu of automatic ticks, this attribute allows the user to
                                define a particular interval for tick marks. This value is a number,
                                representing the total number of ticks that should be drawn in the
                                slider.</para>
                            <para>Optional. Defaults to 3.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>onchange</glossterm>
                        <glossdef>
                            <para>A Lua chunk that will be called every time the value in the
                                control is changed. The first parameter is the new value, and the
                                second is the event.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                </glosslist>
            </section>
            <section xml:id="labeled_control">
                <title>Labeled Controls</title>
                <para>Some controls are <glossterm>labeled</glossterm>. This is a term used
                    specifically for a certain scheme of attaching a string to a control that might
                    otherwise not have one. These controls can have one of the following attributes
                    that define the label for that control:</para>
                <glosslist>
                    <title>Label Attributes</title>
                    <glossentry>
                        <glossterm>label</glossterm>
                        <glossdef>
                            <para>If this is present, it places a label to the left of a control.
                                The text in this label is the text of this attribute.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                    <glossentry>
                        <glossterm>vlabel</glossterm>
                        <glossdef>
                            <para>If this is present, it places a label above the control (a
                                vertical label). The text in this label is the text of this
                                attribute.</para>
                            <para>Optional.</para>
                        </glossdef>
                    </glossentry>
                </glosslist>
            </section>
            <section>
                <title>User Defined</title>
                <para>While this is a certainly usable subset of controls, it is not all of the
                    controls in wxWindows. You can insert an element named
                        <classname>luacontrol</classname> at the control level. It must have a
                        <literal>script</literal> attribute. This attribute is a Lua chunk that will
                    create the window, returning it. The <classname>luacontrol</classname> element
                    can have any attributes, and it can have any child control elements (including
                    other <classname>luacontrol</classname> elements).</para>
                <para>The parameters received by this function are in the script file. Because this
                    is a low-level function, you will need to be familiar with how the LuaGUI script
                    works. Due to the fluid nature of this feature, the specific parameters and
                    their use will not be detailed in this documentation.</para>
            </section>
        </section>
        <section>
            <title>Window Layout and Layout Attributes</title>
            <para>When doing layout, every window has a minimum size. This represents the smallest
                size that the window needs. The layout system can give it more room than this, but
                it will almost always give it at least this much room.</para>
            <para>Depending on the layout scheme, a control can be assigned more than this room.
                This room is called the <glossterm>available area</glossterm> for the control. The
                layout attributes specify how to use this extra room.</para>
            <para>When doing box layout, the system tries to tightly pack the attributes together in
                the stacking direction. The stacking direction can be called the
                    <glossterm>progression direction</glossterm>. The other direction is the fixed
                direction. In a horizontal orientation, controls are stacked left-to-right. So the
                left and right direction is the progression direction, and up/down is the fixed
                direction. Vice-versa for vertical orientations.</para>
            <para>The available area in the progression direction is always the minimum size the
                control asks for, plus any padding. Thus, layout attributes that affect the
                control's position within the available area in this direction have no visual
                effect. However, the available area in the fixed direction is the size of the
                largest control in that direction (or the size of the parent's area, whichever comes
                first). So attributes that affect the control's position in this direction can have
                an affect.</para>
            <para>Grid layout works a bit differently. There is no progression direction or fixed
                direction, even though it can seem that way by specifying only the number of columns
                or rows. Instead, the available area for a control is based on the minimum sizes
                (plus padding) for each control horizontally or vertically. Thus, it is possible for
                a control to be smaller in both the horizontal and vertical direction in a
                grid.</para>
            <para>Every non-frame window can have a number of layout attributes. These define
                spacing, size, and how the size of controls react to the size of other controls in
                the container.</para>
            <glosslist>
                <title>Layout Attributes</title>
                <glossentry>
                    <glossterm>width</glossterm>
                    <glossdef>
                        <para>This defines the minimum width of the control in pixels. Other options
                            can cause the width to be larger than this, but this is the narrowest
                            the control is allowed to be.</para>
                        <para>Optional. If not present, then the minimum width will be automatically
                            determined.</para>
                    </glossdef>
                </glossentry>
                <glossentry>
                    <glossterm>height</glossterm>
                    <glossdef>
                        <para>This defines the minimum height of the control in pixels. Other
                            options can cause the height of the control to be larger than this, but
                            this is the shortest the control is allowed to be.</para>
                        <para>Optional. If not present, then the minimum height will be
                            automatically determined.</para>
                    </glossdef>
                </glossentry>
                <glossentry>
                    <glossterm>align, halign</glossterm>
                    <glossdef>
                        <para>This defines the position of the control horizontally relative to the
                            available area. The control can be anchored to one of the sides or
                            centered horizontally.</para>
                        <para>If this value is <quote><literal>left</literal>,</quote> then the
                            control is anchored to the left side. If this value is
                                    <quote><literal>right</literal></quote>, then the control is
                            anchored to the right side. If this value is
                                    <quote><literal>center</literal></quote>, then the control will
                            be placed in the center horizontally.</para>
                        <para>Note that, when in a horizontal box layout, these flags will not do a
                            great deal.</para>
                        <para>Optional. Defaults to left alignment</para>
                    </glossdef>
                </glossentry>
                <glossentry>
                    <glossterm>valign</glossterm>
                    <glossdef>
                        <para>This defines the position of the control vertically relative to the
                            available area. The control can be anchored to the top, bottom, or
                            centered vertically.</para>
                        <para>If this value is <quote><literal>top</literal>,</quote> then the
                            control is anchored to the top of the available area. If this value is
                                    <quote><literal>bottom</literal>,</quote> then the control is
                            anchored to the bottom of the available area. If the value is
                                    <quote><literal>center</literal>,</quote> then the control will
                            be placed in the center vertically.</para>
                        <para>Note that, when in a vertical box layout, these flags will not do a
                            great deal.</para>
                        <para>Optional. Defaults to top alignment.</para>
                    </glossdef>
                </glossentry>
                <glossentry>
                    <glossterm>expand</glossterm>
                    <glossdef>
                        <para>If this is set to <quote><literal>true</literal>,</quote> then the
                            control's size will be expanded to fill all of the available
                            area.</para>
                        <para>This overrides the width or height attribute. It also makes the
                            alignment attributes useless, since the control will be the width and
                            height of the available area.</para>
                        <para>If this is set to <quote><literal>false</literal>,</quote> then the
                            control's width or height will be taken from the appropriate attribute,
                            or from the automatic calculations if those attributes are not
                            present..</para>
                        <para>Optional. Defaults to <quote><literal>false</literal>.</quote></para>
                    </glossdef>
                </glossentry>
                <glossentry>
                    <glossterm>border, vborder, hborder</glossterm>
                    <glossdef>
                        <para>These attributes put extra space around the control. The
                                <literal>border</literal> defines the space, in pixels, to be placed
                            around the control on all four sides. Each side must have the same
                            border. The <literal>hborder</literal> puts space around just the
                            horizontal sides (left and right), while <literal>vborder</literal> puts
                            space only around the vertical sides (top and bottom).</para>
                        <para>You can only use one of these attributes on a single control.</para>
                        <para>Optional. Defaults to a border of 0 pixels.</para>
                    </glossdef>
                </glossentry>
                <glossentry>
                    <glossterm>proportion</glossterm>
                    <glossdef>
                        <para>This attribute controls how much of the space in the progression
                            direction is taken up by the control. It only has a function when using
                            box layout. This is an integer value relative to all other controls that
                            are children of this parent.</para>
                        <para>If this value is 0, then the control will take up its minimum size in
                            the progression direction. If it is non-zero, then the amount of space
                            that is taken up depends on the proportion values of all of the controls
                            with non-zero space.</para>
                        <para>Given a quantity of space available, first all controls with a 0
                            proportion are given their minimum space. Then, each control is alloted
                            space in proportion with this value. So if you have 5 controls, with
                            proportion values (0, 1, 3, 0, 1), then the system guarantees that the
                            middle control will be 3x as big as the second and fifth controls. How
                            big they are relative to the two 0 proportions is not guaranteed.</para>
                        <para>Thus, if you want a single control to take up all of the space left
                            over, simply set its proportion to 1, and leave the others to the
                            default of 0.</para>
                        <para>Remember: all of the controls with non-zero proportions will expand
                            and shrink with respect to the direct parent
                            <emphasis>only</emphasis>.</para>
                        <para>The proportion value must be a positive integer or 0. You can simulate
                            fractions by using larger proportions. To get a 1:1.25 proportion ratio,
                            you would use 4 and 5 as proportion values.</para>
                        <para>Optional. Defaults to 0.</para>
                    </glossdef>
                </glossentry>
            </glosslist>
        </section>
        <section>
            <title>Dialogs</title>
            <para>Dialogs are windows that you can show or hide. They are typically used to get
                supplemental information from the user, or allow the user to insert some specific
                set of information.</para>
            <para>Dialogs are created with the <classname>dialog</classname> element. These elements
                must be children of the root <classname>appWnd</classname> element, and if present,
                must be after all of the frame container elements. The <classname>dialog</classname>
                element must have an attribute <literal>id</literal>, which represents the dialog's
                identifier.</para>
            <para>Dialogs can be retrieved using the <function>GetDialog</function> method, passing
                in the identifier for the dialog. This returns a wxDialog object that you can
                display either modally or non-modally.</para>
            <section>
                <title>Dialog Button Panel</title>
                <para>The direct child elements of the <classname>dialog</classname> element can be
                    any of the non-frame container windows. In addition, one of the direct children
                    can be a <classname>dialog-panel</classname> element.</para>
                <para>The dialog panel represents the standard set of buttons for most dialogs: OK,
                    Cancel, Yes, etc. The dialog panel itself is not really a window. It only has
                    the layout attributes; it does not even have an <literal>id</literal>
                    attribute.</para>
                <para>The children of the dialog panel are elements representing the standard
                    buttons. There can only be one element for each special button. These elements
                    can appear in any order, but wxWindows will arrange them in a standard order.
                    The child elements can be:</para>
                <itemizedlist>
                    <listitem>
                        <para><classname>ok</classname></para>
                    </listitem>
                    <listitem>
                        <para><classname>cancel</classname></para>
                    </listitem>
                    <listitem>
                        <para><classname>yes</classname></para>
                    </listitem>
                    <listitem>
                        <para><classname>no</classname></para>
                    </listitem>
                </itemizedlist>
                <para>All of these elements can have one attribute: <literal>script</literal>. This
                    is a Lua chunk that will be executed when the button is clicked. It will be
                    passed the button clicked event as a parameter. If the function returns
                    something that resolves to true, then the event will stop being propagated.
                    Stopping the propagation of the event is usually not good for modal windows, as
                    this is how modality is ended. You can do so conditionally; for example, if the
                    data entered is not acceptable in some way.</para>
            </section>
            <section>
                <title>Modal Data</title>
                <para>The purpose of modal dialogs is usually to allow the user the ability to enter
                    certain data for some purpose. Dialogs with controls are typically the way to do
                    this.</para>
                <para>In this system, this involves a multi-step process:</para>
                <orderedlist>
                    <listitem>
                        <para>Get the wxDialog with <function>GetDialog</function>.</para>
                    </listitem>
                    <listitem>
                        <para>For each control that stores a piece of the data:</para>
                        <orderedlist>
                            <listitem>
                                <para>Get the control with <function>GetWindow</function>.</para>
                            </listitem>
                            <listitem>
                                <para>Set the piece of data into the control.</para>
                            </listitem>
                        </orderedlist>
                    </listitem>
                    <listitem>
                        <para>Call wxDialog::ShowModal; if the return value is to accept the data,
                            then for each control:</para>
                        <orderedlist>
                            <listitem>
                                <para>Get the control with <function>GetWindow</function>.</para>
                            </listitem>
                            <listitem>
                                <para>Get the piece of data from the control, converting it as
                                    necessary into the form we need.</para>
                            </listitem>
                        </orderedlist>
                    </listitem>
                </orderedlist>
                <para>The <function>DoModalData</function> function exists to simplify this process.
                    The function takes a dialog ID and a data table. The keys in the table use the
                    same names as ids for controls in the dialog. This function will iterate through
                    the table; for each key in the table, it will find a corresponding control in
                    the dialog. If there is no control, it skips that particular key.</para>
                <para>It then uploads the value for that key to that control. This is done by
                    interpreting the data as is most reasonable for the kind of control. Spinners
                    can take numbers or strings representing numbers. Edit controls can take
                    strings. And so forth. Radio box controls take the <emphasis>value</emphasis> of
                    one of the radio buttons in the control.</para>
                <para>After uploading the data, it displays the dialog modally. If the user presses
                    one of the accept buttons, the dialog will close. Any data in the controls that
                    had keys will be transferred back to the data table.</para>
                <para>There are some controls that are (currently) incompatible with this
                    transference mechanism. Namely list boxes and combo boxes. Other than that, they
                    all work as expected.</para>
            </section>
        </section>
    </section>
    <appendix xml:id="accelerator_keys">
        <title>Accelerator Keys</title>
        <para>The available accelerator keys include all of the letters, numbers, and symbols you
            can type. They also include all of the function keys, named
                <quote><literal>F1</literal></quote> through <quote><literal>F12</literal></quote>.
            Additionally, there are the following special strings:</para>
        <table frame="none">
            <title>Special Accelerator Keys</title>
            <tgroup cols="3">
                <tbody>
                    <row>
                        <entry>
                            <para>INS</para>
                        </entry>
                        <entry>
                            <para>HOME</para>
                        </entry>
                        <entry>
                            <para>PGUP</para>
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <para>DEL</para>
                        </entry>
                        <entry>
                            <para>END</para>
                        </entry>
                        <entry>
                            <para>PGDN</para>
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <para>TAB</para>
                        </entry>
                        <entry>
                            <para>ESC</para>
                        </entry>
                        <entry/>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </appendix>
</article>
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.