Widget Specification Text

Widget Specification Line
Hand Edits
Macros

Widget Specification Line

The text specification of the widgets that make up the starting configuration of a game (or in one case, GameMaker) is a sequence of lines, each specifying one widget, followed by a blank line, then optionally a sequence of comma-separated numbers that define the macros that can be used to build groups of widgets in the input widget specs.

The general form of each line is this:

n f v h t w c i p d data 'label' '[name]' `anID`

Each line begins with these ten separate numbers:

nThe line number must be in sequence; it also becomes the RefNum, and should also be listed in the parent's widget list, shown here as data
fThis number is a combination of the widget type (or macto number) and flags, and becomes Gtype
vThis number is the vertical position, which becomes Gtop
hThis number is the horizontal position, which becomes Gleft
tThis number is the widget height, which becomes Gtall
wThis number is the widget width, which becomes Gwide
cThis number is the color (or -1 if none), which becomes Gcolor
iThis number is the information value, which becomes Ginfo
pThis number is the line number for this widget's parent (or zero if none), which becomes Parent
dThe tenth number specifies the number of Gdata integers; if greater than zero, it must be followed with that many additional numbers, usually either zero or line numbers of other widgets, shown here as data
GameTxLn items expect to find the actual text inside the first pair of single-quotes, shown here as 'label'
In a macro, the child text items take their actual text from the host line. The Gdata size should be specified with a zero because the text insertion code will allocate as much as needed for the given text line.
When there is a name in brackets or braces, shown here as [name], it can be used in the startup code to link this unique name to a particular widget reference.
Then there is a distinctive 4-letter ID field in reverse single quotes like `anID`, which the mechanism can use that ID to find a child widget nested inside some macro, for example to set display text or to recognize an OK button clicked.

Macros are specified with "type numbers" greater than 222. Each macro is converted into a group widget over whatever the number of child widgets specified in that macro's definition, as indicated in the next section.

Hand Edits

Because widgets are drawn on the screen only if they are properly the child of a parent widget in the hierarchy, it is important to make sure that any manually inserted widget specifications are properly connected, that is, their Parent link is the number of a widget line that lists it as a child. However, widget links may be forward or backward and still work OK, so long as the line numbers are strictly sequential.

If you need to manually create a widget type not supported in this release of GameMaker, you can put in a dummy rect or ball, then change the type or other properties of the generated line in the generated "GameMaker.txt" file. You are on your own, but some of it might work. If it does not survive the Build step, you can manually edit the copy of the "GameMaker.txt" file that is returned by the generated GameList method.

Macros

The macro segment of the input text begins with a line containing only the 11 characters "WgtMacros.." followed by any number of macro specifications, each beginning with the macro number then the number of 7-number component widgets to follow, one or more per line, all separated by commas and optional spaces. Lines may end with Java-style line-end comments (beginning "//" and ending at the end of the line). The macro list is terminated by a macro with no component child widgets, that is the second number in the group is zero.

If there is no macro segment in the input text, the default Wgt_Macros array in JavaGame.java is used. Basically the macro component of the input text is there for developing new macros without continually recompiling the program, but you can use it for your own novel macros.

Most of the macros have their associated support code in GameEngine, partly to deal with specifics of the widget creation needed for each respective macro, and mostly to deal with processing the needs of that cluster of widgets. There is an overridable method UserMacro in class GameEvent, but it has not yet been tested. When it works, it lets your code do the input particularization for your own new macros.

Macros are defined by widget type numbers greater than 222. Each widget in the macro is defined by seven numbers, the type number (possibly a nested macro), followed by numbers for its top, left, tall, wide, color and info fields. The type number should be 0, 2, or 4, or else another macro, because the mechanism offers only limited ways to define the contents of the Gdata array.

GameTxLn widgets are expected to specify the font widget number in their Ginfo field; this might not be known when the macro is defined, so the mechanism also accepts a negative font letter value in its place, for example -84 for 'T' = Text font (see method ChoseFont).

The GameIcon widgets have a limited way to specify their Gdata, one of several negative numbers in Ginfo representing code selectors for entering an appropriate predefined array reference

-2: marching ants pattern
-3: choose a circle to fit specified size
-4: drag-arrow icon
-5: checkerboard "no color" pattern
-6: red checkmark
-7: black box for checkbox
-8: radio button

The following eight macros are defined and working (there are five more stubs for scrolled fields that are still incomplete) in the initial release:

254Labelled Text Entry Panel, 3 widgets

4,2,0,12,16,0x0,-66, // Tx @ 2/0 +12/16, black, font 'B'
0,0,8,20,32,0xFFFFFF,0x42616B46, // Rc @ 0/8 +20/32, white, ID='BakF'
1540,3,12,12,20,0x0,-77, // Tx+Clk+Ky @ 3/12 + 12/20, black, font 'M'

The first child widget is the label GameTxLn, the third is the input GameTxLn (flagged for mouse clicks and keyboard entry), and the second is a white rectangle back panel behind the input field. The macro processing code looks at the container height, and if twice the nominal panel height (or more), it moves the input field to be under the label instead of to its right.

The parent line should be specified at 20 (or 40) pixels tall, as wide as needed for the label and entry text to fit, and whatever background color you want (I usually let the existing background do that, and leave its color at -1 = none).

253Checkbox, 4 widgets

0,3,1,12,12,0xFFFFFF,0, // Rc @ 3/1 + 12/12, white
2,3,1,12,12,0x0,-7, // Ic @ 3/1 + 12/12, black, open square
2,1,2,16,12,0xFF0000,-6, // Ic @ 1/2 + 16/12, red, checkmark
4,4,16,16,24,0x0,-66, // Tx @ 4/16 +16/24, black, font 'B'

A white square background is layered under a black open square icon under a red checkmark, with a black bold text label to the right of the checkbox. The macro setup code creates the appropriate data arrays for the icons, and the (user) StartUp code initializes the checkbox to unchecked.

The parent line should be specified at 20 pixels tall, as wide as needed for the label to fit, and whatever background color you want (I usually let the existing background do that, and leave its color at -1 = none).

252Pushbutton, 9 widgets

4,5,8,16,24,0x0,-66, // Tx @ 4/16 +16/24, black, font 'B'
0,1,1,2,30,0xFFFFFF,0, // Rc @ 1/1 +2/30, white, top bezel
0,1,1,18,2,0xFFFFFF,0, // Rc @ 1/1 +18/2, white, left bezel
0,17,2,2,30,0x999999,0, // Rc @ 17/2 +2/30, gray, bottom bezel
0,2,28,17,2,0x999999,0, // Rc @ 2/28 +17/2, gray, right bezel
0,0,0,1,32,0x0,0,     // Rc @ 0/0 +1/32, black, top border
0,0,30,20,1,0x0,0,    // Rc @ 0/30 +20/1, black, right border
0,0,0,20,1,0x0,0,     // Rc @ 0/0 +20/1, black, left border
0,19,0,1,32,0x0,0,    // Rc @ 19/0 +1/32, black, bottom border

The button label is centered in its rectangle (horizontal centering is done in the macro code), surrounded by a pop-out bezel that is white on the top and left (for a presumed upper left light source) and darker gray on the bottom and right, with a black border surrounding it.

If you give the parent macro line an information value of 1, it will generate an "OK" button, and for 2 it will generate a "Cancel" button. Otherwise it takes whatever button label you enclosed in single quotes on the macro line.

The parent line should be specified at 22 pixels tall, as wide as needed for the label to fit, and a color something like light gray (0x999999) to contrast with the surrounding background.

251Color Swatch, 5 widgets

2,0,0,16,16,0x0,-5, // Ic @ 0/0 + 16/16, black, checkerboard pattern
0,0,0,1,16,0x0,0, // Rc @ 0/0 +1/16, black, top border
0,0,15,16,1,0x0,0, // Rc @ 0/15 +16/1, black, right border
0,0,0,16,1,0x0,0, // Rc @ 0/0 +16/1, black, left border
0,15,0,1,16,0x0,0, // Rc @ 15/0 +1/16, black, bottom border

The color swatch either shows some specified color on the background (container) group widget with the checkerbord transparent, or else white on the background and black on the checkerboard, as set by the SetSwatchColor method.

The parent line should be specified at 16 pixels tall and wide. The parent color will be set the first time you use it.

250Marching Ants (Rectangular) Border, 28 widgets

0,0,0,1,1024,0x0,0, // Rc @ 0/0 +1/1024, black, top border
0,0,0,256,1,0x0,0, // Rc @ 0/0 +256/1, black, left border
0,31,0,3,1024,0x0,0, // Rc @ 31/0 +3/1024, black, bottom border
0,0,31,256,3,0x0,0, // Rc @ 0/31 +256/3, black, right border
2,15,0,3,256,0xFFFFFF,-2, // Ic @ 15/0 + 3/256, white, ants pattern for bottom
2,0,15,32,3,0xFFFFFF,-2, // Ic @ 0/15 + 32/3, white, ants pattern for right
2,0,0,1,256,0xFFFFFF,-2, // Ic @ 0/0 + 1/256, white, ants pattern for top
2,0,0,32,1,0xFFFFFF,-2, // Ic @ 0/0 + 32/1, white, ants pattern for left
...

There are two kinds of marching ants selection borders, those for rectangles which use the widgets created by this macro and moved about from parent to parent as needed, and those for odd shapes that are created in place using the MkSpriteAnts method. This macro builds enough icons to fully surround a rectangular region 256 pixels tall and 1K pixels wide (not all of them shown above). You only need one copy of the widgets created by this macro, because the deployment code moves them to whatever host currently has focus.

Icons are limited to 32 pixels tall, so we need eight widgets each, joined end-to-end for the left and right (vertical) edges; the pixel array is 256 pixels wide, so four widgets joined end-to-end suffice for the horizontal top and bottom edges. The deployment method Antsify adjusts the right and bottom edges for the specified parent width and height, and hides the unneeded excess widgets beyond that. The right and bottom edge widgets have a specified width or height of three pixels, which Antisfy recognizes to know that they need adjustment; the extra pixel is outside the parent rectangle, so only the single-pixel border actually shows.

249Radio Button, 3 widgets

2,3,1,12,12,0xFFFFFF,-8, // Ic @ 3/1 + 12/12, white, 12-pixel diameter (solid) circle
2,3,1,12,12,0x0,-8, // Ic @ 3/1 + 12/12, black, 12-pixel circle with radio button
4,4,16,16,44,0x0,-66, // Tx @ 4/16 +16/24, black, font 'B'

Radio buttons are like checkboxes, except that several of them are grouped together, so that when the user selects one from the group, all the others in the same group are deselected. The widget method RadioBtn knows how to do this with radio buttons created by this macro and arranged under a group widget with the ID `RdB!`. Each button in that group should be a clickable radio button macro (type+flags = 1273) with a specified ID `Rd_X` where 'X' is the unique code (letter or digit) for that button in its group.

The macro generates three widgets, the first two circular icons, a white solid background, the second a hollow outline with a second image showing the button selected. The third widget is the text label for this radio button.

The parent line should be specified at 16 pixels tall, as wide as needed for the label to fit, and whatever background color you want (I usually let the existing background do that, and leave its color at -1 = none). The parent group should be big enough to encompass all the radio buttons in its group, and again I leave its color transparent.

241Alert (Dialog), 7 widgets

4,10,8,16,252,0x0,-66, // Tx @ 10/8 +16/252, black, font 'B'
1276,36,192,20,40,0xCCCCCC,1, // Pushbtn+Clik @ 36/192 + 20/40, light gray, 'OK'
1276,36,8,20,60,0xCCCCCC,2, // Pushbtn+Clik @ 36/8 + 20/60, light gray, 'Cancel'
0,0,0,2,240,0x0,0, // Rc @ 0/0 +2/240, black, top border
0,0,238,64,2,0x0,0, // Rc @ 0/238 +64/2, black, right border
0,0,0,64,2,0x0,0, // Rc @ 0/0 +64/2, black, left border
0,62,0,2,240,0x0,0, // Rc @ 62/0 +2/240, black, bottom border

When you check the "Alert+InputDlog" checkbox in the game widget presentation of GameMaker, it will automatically generate this macro call, which creates a standard Alert box for your game to call up and require user response. It consists of a text message with OK and Cancel buttons and a heavy black border around it. The GameEngine has methods for opening (GameAlert) and reacting to the Alert box (IsDlgEvent).

This macro is designed for a parent size 64 pixels tall by 276 wide (the internal organs are adjusted to the wider than nominal size) with a background color white, but you would normally let the GameMaker generated code do that.

240Input Dialog, 8 widgets

254,8,8,40,208,-1,0, // ePanel @ 8/8 +40/208, transparent
1276,8,192,20,40,0xCCCCCC,1, // Pushbtn+Clik @ 8/192 + 20/40, gray, 'OK'
1276,36,172,20,60,0xCCCCCC,2, // Pushbtn+Clik @ 36/172 + 20/60, gray, 'Cancel'
2,9,208,16,16,0x0,-4, // Ic @ 9/208 +16/16, black, navigation icon
0,0,0,2,240,0x0,0,    // Rc @ 0/0 +2/240, black, top border
0,0,238,64,2,0x0,0,   // Rc @ 0/238 +64/2, black, right border
0,0,0,64,2,0x0,0,     // Rc @ 0/0 +64/2, black, left border
0,62,0,2,240,0x0,0,   // Rc @ 62/0 +2/240, black, bottom border

When you check the "Alert+InputDlog" checkbox in the game widget presentation of GameMaker, it will automatically generate this macro call, which creates a standard input dialog box for your game to call up and require user input. It consists of a text imput panel with a prompt (supplied by you) with OK and Cancel buttons and a heavy black border around it, plus an icon to let the user know they can drag the box around if it happens to cover up what they need to look at. The GameEngine has methods for opening (OpenInputDlog) and reacting to the input dialog (IsDlgEvent, GetInputTxt).

Rev. 2021 May 24