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:

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:

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:

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:

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:

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.