Windows and controls
Windows
The windows are the base of all GUI elements in WME. Imagine a window as a
rectangular area on screen, which can can contain one or more other controls
(buttons, editors...) including other (nested) windows. The windows can be
completely "skinned", i.e. you can change their appearance to fit your game's
look and feel.
You define a window by writing a simple text file. The window files use the
.window extension. Let's have a look at an
example of a window definition file. First there is a file header followed by
general window properties. There are lots of possible properties, you don't need
to use all of them, most properties use a reasonable default if you don't define
them. Basically, only define properties you need to change and ignore the
others.
WINDOW
{
NAME = "MyWindow"
TEMPLATE = "templates\MyTemplate.window"
; position and size
X = 200
Y = 200
WIDTH = 240
HEIGHT = 150
; window state
VISIBLE = TRUE
DISABLED = FALSE
; title
TITLE = "My brand new window"
TITLE_RECT { 5,5,235,45 }
TITLE_ALIGN = left
DRAG_RECT { 0,0,215,25 }
; background
BACK = "path\window.image"
BACK_INACTIVE = "path\winow_inactive.image"
IMAGE = "path\window.sprite"
IMAGE_INACTIVE = "path\window_inactive.sprite"
; fonts
FONT = "fonts\outline_white.font"
FONT_INACTIVE = "fonts\outline_gray.font"
; cursor
CURSOR = "path\arrow.sprite"
; script
SCRIPT = "path\MyWindow.script"
; extended properties
TRANSPARENT = FALSE
MENU = FALSE
IN_GAME = FALSE
CLIP_CONTENTS = TRUE
; background fading
FADE_COLOR { 255, 0, 0 }
FADE_ALPHA = 255
PAUSE_MUSIC = TRUE
}
Description:
- NAME - the internal name of this window
- TEMPLATE - a reference to another .window file; if you have lots of
similar windows, you can move all common properties to a separate file and
reference it as a template. It's a good idea to put the template reference
early in the definition, so that you can override inherited properties if
needed.
- X, Y - the initial position of the window
- WIDTH, HEIGHT - the size of the window
- VISIBLE - specifies whether the window is initially visible
- DISABLED - specifies whether the window is initially disabled
- TITLE - the title caption of this window
- TITLE_RECT - specifies the rectangle within the window where the caption
will be placed. The rectangle is defined by four numbers: left, top, right and
bottom (in pixels).
- TITLE_ALIGN - specifies the alignment of the caption, the possible values
are: left, right or center.
- DRAG_RECT - specifies the rectangle within the window which can be dragged
by mouse. The rectangle is defined by four numbers: left, top, right and
bottom (in pixels).
- BACK - specifies a tiled image to be used as a background image of this
window (learn more about tiled images)
- BACK_INACTIVE - specifies a tiled image to be used as a background image
of this window when the window is inactive (learn more about tiled images)
- IMAGE - specifies a sprite to be used as a background image of this window
(learn more about sprites)
- IMAGE_INACTIVE - specifies a sprite to be used as a background image of
this window when the window is inactive (learn
more about sprites)
- FONT - the font file to be used to display window title
- FONT_INACTIVE - the font file to be used to display window title when the
window is inactive
- CURSOR - the sprite file to be used as a mouse cursor when mouse is over this window
- SCRIPT - the script file containing the logic of this window (there can be
multiple SCRIPT lines in the window definition)
- TRANSPARENT - the window marked as transparent doesn't receive click
events, all the mouse clicks go through
- MENU - the window marked as a menu does automatically disappear when the
player clicks outside the window
- IN_GAME - the window marked as in-game is displayed before the inventory
window; otherwise the windows are displayed after the inventory
- CLIP_CONTENTS - this attribute specifies whether the controls contained in
the window are clipped if they overlap the window rectangle
- FADE_COLOR - if the window is displayed the background will be covered by
the specified color; the color is defined as three numbers for red, green and
blue color components
- FADE_ALPHA - specifies the opacity of the color defined by the FADE_COLOR
attribute; it ranges from 0 (completely transparent) to 255 (completely
opaque)
- PAUSE_MUSIC - specifies if the window should pause music when entering the system exlusive mode
opaque)
After those general properties the window definition contains embedded
definitions of the controls to be placed on this window. For example the
following definition will place a button on our window. The controls definitions
are described in detail later in this chapter. Note that windows can contain
other windows in them.
BUTTON
{
NAME = "MyButton"
TEXT = "Button"
X = 40
Y = 100
WIDTH = 70
HEIGHT = 30
}
For an example of a complete window definition please see the "WME demo"
project. There are some windows prepared in the "interface\system" folder. Also,
you don't need to write the definition file from scratch, there is a window
template available in ProjectMan (learn more
about ProjectMan).
See also: Window
scripting reference
Buttons
Buttons in WME can have various appearances. They can be either graphical or
rectangular with a text label, or a combination of those. As in the case of
windows and other controls, the buttons can be "skinned" to fit your game's
appearance.
Button definitions are always part of the .window file (see above). Let's have a look at an
example of a button definition block. First there is a header followed by
general button properties. There are lots of possible properties, you don't need
to use all of them, most properties use a reasonable default if you don't define
them. Basically, only define properties you need to change and ignore the
others.
BUTTON
{
NAME = "MyButton"
TEMPLATE = "templates\MyTemplate.button"
; position and size (relative to the window position)
X = 100
Y = 100
WIDTH = 200
HEIGHT = 50
; button state
VISIBLE = TRUE
DISABLED = FALSE
PRESSED = FALSE
FOCUSABLE = FALSE
; text
TEXT = "My brand new button"
TEXT_ALIGN = "center"
; background
BACK = "path\button.image"
BACK_DISABLE = "path\button_disable.image"
BACK_FOCUS = "path\button_focus.image"
BACK_HOVER = "path\button_hover.image"
BACK_PRESS = "path\button_press.image"
IMAGE = "path\button.sprite"
IMAGE_DISABLE = "path\button_disable.sprite"
IMAGE_FOCUS = "path\button_focus.sprite"
IMAGE_HOVER = "path\button_hover.sprite"
IMAGE_PRESS = "path\button_press.sprite"
CENTER_IMAGE = TRUE
; fonts
FONT = "fonts\outline_white.font"
FONT_DISABLE = "fonts\outline_gray.font"
FONT_FOCUS = "fonts\outline_white.font"
FONT_HOVER = "fonts\outline_red.font"
FONT_PRESS = "fonts\outline_red.font"
; script
SCRIPT = "path\MyButton.script"
; cursor
CURSOR = "path\arrow.sprite"
; extended properties
PARENT_NOTIFY = TRUE
PIXEL_PERFECT = TRUE
}
Description:
- NAME - the internal name of this button
- TEMPLATE - a reference to another file; if you have lots of
similar buttons, you can move all common properties to a separate file and
reference it as a template. It's a good idea to put the template reference
early in the definition, so that you can override inherited properties if
needed.
- X, Y - the initial position of the button (relative to the window
position)
- WIDTH, HEIGHT - the size of the button
- VISIBLE - specifies whether the button is initially visible
- DISABLED - specifies whether the button is initially disabled
- PRESSED - specifies whether the button appears to be pressed all the time
- FOCUSABLE - specifies whether this button can be focused
- TEXT - the text label of this button
- TEXT_ALIGN - specifies the alignment of the label, the possible values
are: left, right or center.
- BACK - specifies a tiled image to be used as a background image of this
button (learn more about tiled images)
- BACK_DISABLE - specifies a tiled image to be used as a background image
of this button when the button is disabled (learn more about tiled images)
- BACK_FOCUS - specifies a tiled image to be used as a background image
of this button when the button is focused (learn more about tiled images)
- BACK_HOVER - specifies a tiled image to be used as a background image
of this button when the mouse cursor is over it (learn more about tiled images)
- BACK_PRESS - specifies a tiled image to be used as a background image
of this button when the button is pressed (learn more about tiled images)
- IMAGE - specifies a sprite to be used as a background image of this button
(learn more about sprites)
- IMAGE_DISABLE - specifies a sprite to be used as a background image of
this button when the button is disabled (learn
more about sprites)
- IMAGE_FOCUS - specifies a sprite to be used as a background image of
this button when the button is focused (learn
more about sprites)
- IMAGE_HOVER - specifies a sprite to be used as a background image of
this button when the mouse cursor is over it (learn
more about sprites)
- IMAGE_PRESS - specifies a sprite to be used as a background image of
this button when the button is pressed (learn
more about sprites
- CENTER_IMAGE - if the button size is bigger than the used image, the image
will be centered
- FONT - the font file to be used to display the button label
- FONT_DISABLE - the font file to be used to display the button label when the
button is disabled
- FONT_FOCUS - the font file to be used to display the button label when the
button is focused
- FONT_HOVER - the font file to be used to display the button label when the
mouse cursor is over it
- FONT_PRESS - the font file to be used to display the button label when the
button is pressed
- SCRIPT - the script file containing the logic of this button (there can be
multiple SCRIPT lines in the button definition)
- CURSOR - the sprite file to be used as a mouse cursor when mouse is over
this button
- PARENT_NOTIFY - when the button is pressed, its parent window will receive
an event with the same name as the button name (this way you can move all the
window logic to the window's script)
- PIXEL_PERFECT - if the button is defined by a sprite, the mouse-over
detection will be pixel perfect
For an example of a complete button definitions please see the "WME demo"
project. There are some windows prepared in the "interface\system" folder
and they contain various types of buttons. Also,
you don't need to write the definition file from scratch, there is a window
template available in ProjectMan (learn more
about ProjectMan) already containing predefined buttons.
See also: Button
scripting reference
Editors
Editor objects represent a single line editor control. The user can enter
text in the editor, select part of the text and copy/paste text to/from
clipboard. As in the case of
windows and other controls, the editors can be "skinned" to fit your game's
appearance.
Editor definitions are always part of the .window file (see above). Let's have a look at an
example of an editor definition block. First there is a header followed by
general editor properties. There are lots of possible properties, you don't need
to use all of them, most properties use a reasonable default if you don't define
them. Basically, only define properties you need to change and ignore the
others.
EDIT
{
NAME = "MyEditor"
TEMPLATE = "templates\MyTemplate.editor"
; position and size (relative to the window position)
X = 100
Y = 100
WIDTH = 200
HEIGHT = 50
; editor state
VISIBLE = TRUE
DISABLED = FALSE
; text
TEXT = "My brand new editor"
; background
BACK = "path\editor.image"
IMAGE = "path\editor.sprite"
; fonts
FONT = "fonts\outline_white.font"
FONT_SELECTED = "fonts\outline_red.font"
; script
SCRIPT = "path\MyEditor.script"
; cursor
CURSOR = "path\beam.sprite"
; extended properties
PARENT_NOTIFY = TRUE
MAX_LENGTH = 100
FRAME_WIDTH = 2
CURSOR_BLINK_RATE = 0
}
Description:
- NAME - the internal name of this editor
- TEMPLATE - a reference to another file; if you have lots of
similar editors, you can move all common properties to a separate file and
reference it as a template. It's a good idea to put the template reference
early in the definition, so that you can override inherited properties if
needed.
- X, Y - the initial position of the editor (relative to the window
position)
- WIDTH, HEIGHT - the size of the editor
- VISIBLE - specifies whether the editor is initially visible
- DISABLED - specifies whether the editor is initially disabled
- TEXT - the text initially contained in the editor
- BACK - specifies a tiled image to be used as a background image of this
editor (learn more about tiled images)
- IMAGE - specifies a sprite to be used as a background image of this editor
(learn more about sprites)
- FONT - the font file to be used to display the text within the editor
- FONT_SELECTED - the font file to be used to display the selected text
within the editor
- SCRIPT - the script file containing the logic of this editor (there can be
multiple SCRIPT lines in the editor definition)
- CURSOR - the sprite file to be used as a mouse cursor when mouse is over
this editor
- PARENT_NOTIFY - when the editor text is changed by the user, its parent window will receive
an event with the same name as the editor name (this way you can move all the
window logic to the window's script)
- MAX_LENGTH - specifies the maximum number of characters the editor can
contain (-1 for infinite length)
- FRAME_WIDTH - specifies the offset of the text from the editor position
(in pixels)
- CURSOR_BLINK_RATE - specifies the cursor blink rate (in milliseconds),
defaults to the Windows setting
For an example of a complete editor definitions please see the "WME demo"
project. There are some windows prepared in the "interface\system" folder
and some of them contain editors.
See also: Editor
scripting reference
Static controls
Static controls represent various non-interactive decoration component of the
windows, such as text labels or icons. As in the case of
windows and other controls, the static controls can be "skinned" to fit your game's
appearance.
Static controls definitions are always part of the .window file (see above). Let's have a look at an
example of a static control definition block. First there is a header followed by
general properties. There are lots of possible properties, you don't need
to use all of them, most properties use a reasonable default if you don't define
them. Basically, only define properties you need to change and ignore the
others.
STATIC
{
NAME = "MyStatic"
TEMPLATE = "templates\MyTemplate.static"
; position and size (relative to the window position)
X = 100
Y = 100
WIDTH = 200
HEIGHT = 50
; state
VISIBLE = TRUE
DISABLED = FALSE
; text
TEXT = "A static control"
TEXT_ALIGN = left
; background
BACK = "path\static.image"
IMAGE = "path\static.sprite"
; fonts
FONT = "fonts\outline_white.font"
; script
SCRIPT = "path\MyStatic.script"
; cursor
CURSOR = "path\arrow.sprite"
}
Description:
- NAME - the internal name of this static control
- TEMPLATE - a reference to another file; if you have lots of
similar controls, you can move all common properties to a separate file and
reference it as a template. It's a good idea to put the template reference
early in the definition, so that you can override inherited properties if
needed.
- X, Y - the initial position of the static control (relative to the window
position)
- WIDTH, HEIGHT - the size of the static control
- VISIBLE - specifies whether the control is initially visible
- DISABLED - specifies whether the control is initially disabled (not used)
- TEXT - the text displayed by the control
- TEXT_ALIGN - specifies the alignment of the text, the possible values are:
left, right or center
- BACK - specifies a tiled image to be used as a background image of this
control (learn more about tiled images)
- IMAGE - specifies a sprite to be used as a background image of this
control
(learn more about sprites)
- FONT - the font file to be used to display the text
- SCRIPT - the script file containing the logic of this control (not used)
- CURSOR - the sprite file to be used as a mouse cursor when mouse is over
this control (not used)
For an example of a complete static control definitions please see the "WME demo"
project. There are some windows prepared in the "interface\system" folder
and some of them contain static controls.
See also: Static
scripting reference
Entity containers
The entity container is a special control, which allows you to incorporate
advanced interactive object (an entity) to your GUI layout. This way you can
have "intelligent" objects placed on your windows. The possible usages are for
example a Runaway style inventory window (with a talking animated character) or
items close-ups (learn more about entities).
Entity container definitions are always part of the .window file (see above). Let's have a look at an
example of an entity container definition block.
ENTITY_CONTAINER
{
NAME = "MyEntity"
TEMPLATE = "templates\MyTemplate.txt"
; position (relative to the window position)
X = 100
Y = 100
; state
VISIBLE = TRUE
DISABLED = FALSE
ENTITY = "path\MyEntity.entity"
}
Description:
- NAME - the internal name of this entity container
- TEMPLATE - a reference to another file; if you have lots of
similar controls, you can move all common properties to a separate file and
reference it as a template. It's a good idea to put the template reference
early in the definition, so that you can override inherited properties if
needed.
- X, Y - the initial position of the entity container (relative to the window
position)
- VISIBLE - specifies whether the control is initially visible
- DISABLED - specifies whether the control is initially disabled (not used)
- ENTITY - a reference to an entity definition file
As you can see, the entity container serves merely as a "bridge" between a
window and an entity object.
See also: Entity
container scripting reference
Tiled images
Although you can specify an image (sprite) as a background for windows and
controls, the image always has a fixed size. Sometimes it's useful to specify a
special kind of image which can be "stretched" when needed. This way you can use
the same background for windows/controls with variable size. There special
images are called "tiled images".
The tiled image consist of a picture and a definition file. The
definition file specifies the "tiles" within the picture. When the engine needs
to resize the image, it uses those tiles and repeats them until the need size is
matched.
For example the following definition divides the picture into nine tiles of
30x30 pixels.
TILED_IMAGE
{
IMAGE="ui_elements\win.bmp"
VERTICAL_TILES {30, 30, 30}
HORIZONTAL_TILES {30, 30, 30}
}
And this is the resulting tiled image:
Of course, if you use a tiled image as a background for your
windows/controls, you can only set the size to multiplies of the tile size.