Knowledgebase Article 75

Defining the user interface

The graphical user interface (GUI) of ASC consists of two kinds of objects: windows and panels.

A window has exclusive control over the input devices, while a Panel can be open while the player plays on the map.

Panels

The panels are composed of widgets, which are defined in .ascgui files. These files have the syntax of .asctxt files, but don't support the kind of inheritance used for example for vehicle types. Their content is also not cached, but parsed every time a panel is opened, which allows to edit the .ascgui files in a running ASC session and see the results by closing and reopening the panel.

ascgui {
   height = 550
   width = 170
   ChildWidgets = MyDisplay TheOutput
   ; you can give any names heres, important is only that they are detailed below
   MyDisplay {
      x = 10
      y = 10
      width = 20
      height = 40
      x2 = 30
      y2 = 50
      type = SomeType
      name = PARENT
      
      ChildWidgets = SubWidget
      SubWidget {
	 x = 10
	 y = 10
	 type = TYPE
	 name = CHILD
      } SubWidget
      
   } MyDisplay
   TheOutput {
      x = 10
      y = 10
      width = 20
      height = 40
      x2 = 30
      y2 = 50
      type = TYPE
      name = FooBar
      ToolTipHelp = HelpMessage
   } TheOutput
} ascgui

As you can see, Widgets can be nested arbitrarily. The widget CHILD inherits its properties from PARENT. A child can not be larger than the parent on the screen, it's not possible to make a widget that overlaps the border of its parent.

General Widget Properties

type

Possible values: "image", "area", "statictext", "textoutput", "bargraph", "specialDisplay", "specialInput", "dummy", "multilinetext", "scrollarea", "button", "radiobutton", "checkbox", "lineedit", "slider", "plain", "listbox"

x, y, width, height, x2, y2

Specifies the size of the widget relative to the parent widget. X and Y are mandatory and define the upper left corner of the widget. You can then either use width or x2, and either height or y2. With x2/y2 you define the lower right corner.

If X, Y, X2 or Y2 are negative, the position is calculated from the right side of the parent widget. Example: parent has a width of 100 and you specify x = -30 ; width = 20, then the left border is at 70 and the right border at 90. Which is exactly the same as x = -30 ; x2 = -10 or x = 70 ; x2 = 90

If Width or Height are not specified, the right and lower border of the widget will be the same as the parent widget.

ToolTipHelp

The message that will be be shown when the mouse hovers over the widget

The following properties are inherited through all widgets. If a property is not specified, the property's value of the widget's parent is used. Because of this inheritance, you often don't need to specify properties at all for a widget.

BackgroundImage: Filename of the background image. The image should have 24 bit color depth. PNG file format recommended. (Note: seamless backgrounds can easily be made with GIMP: filters -> map -> make seamless). Use empty string to disable background image: BackgroundImage =
BackgroundMode: Display mode of the background image. Possible values are: tile, stretch, tile3h, tile3v, tile9
TextAlign: Possible values: LEFT, CENTER, RIGHT
FontColor: Specifies the font color. Order of colors: RGB. Examples: 0xff0000 is pure red; 0 is black
FontName: Don't use this entry unless you know exactly what you are doing. And in that case you wouldn't need this documentation :-)
FontAlpha: 0 = invisible, 255 = fully visible
FontSize: The size of the fonts
BackgroundColor: Specifies the background color, syntax just like FontColor. Is only evaluated if backgroundImage is empty ("backgroundimage = ")
Transparency: Specifies the transparency of the whole widget. 0 = opaque / 255 = fully transparent (this is opposite from FontAlpha!)

Widget Types

Image

FileName: The filename of the image. See BackgroundImage
Mode: See BackgroundMode

StaticText

Displays text which is defined right in the .ascgui file.

Text: The text of the label
Style: The given Paragui-Style will be used for the widget. This overrides all user specified parameters like background color or font size. Style is NOT derived to child widgets.

TextOutput

Displays text which will be provided by ASC. This widget is only useful together with appropriate program code inside ASC.

Name: A name for identifying the widget from the program code to write. All Names must be unique in each panel.
Style: The given Paragui-Style will be used for the widget. This overrides all user specified parameters like background color or font size. Style is NOT derived to child widgets.

BarGraph

Similar to an Area, but its fill ranges from 0% to 100% from left to right. This widget is only useful together with appropriate program code inside ASC.

Name: A name for identifying the widget from the program code to write. All Names must be unique in each panel.
Direction: Possible values: left2right, right2left, top2buttom, buttom2top. Default is left2right.

You can define different colors for different ranges:

           colors= 3
           color0 {
             color = 0x009c00
             fraction = 1
           } color0
           color1 {
             color = 0xfff000
             fraction = 0.3
           } color1
           color2 {
             color = 0xd6000f
             fraction = 0.1
           } color2

SpecialDisplay

This widget is only useful together with appropriate program code inside ASC. It is used to display non-standard things like the small map or the wind direction arrow.

Name: A name for identifying the widget from the program code to write. All Names must be unique in each panel.

Area

Displays rectangular border in 3D style

in: true / false ; determines whether the 3D effect is embossed (area lower than surroundings) or elevated (area higher than surroundings)

ListBox

Displays box where the user can select items from a list. The items can not be specified in the .ascgui file, but can only be provided programmatically by ASC

SpecialInput

This widget is only useful together with appropriate program code inside ASC. A SpecialInput widget is used to start actions when the user clicks on it. Since this widget itself is invisible, it must be used together with some visible widget.

Name: A name for identifying the widget from the program code to write. All Names must be unique in each panel.

Dummy

This widget does nothing and is used to structure other widgets. Example (also demonstrates unnamed widgets by specifying "widgetNum = 3" instead of "childWidgets = Name1 Name2 Name3"):

   widget0 {
      x = 10
      y = 10
      width = 20
      height = 44
      type = Dummy      FontColor = 0xffffff
      textalign = CENTER
      FontSize = 7
   
      widgetNum = 3
      widget0 {
	 x = 0
	 y = 0
         height = 15
	 type = TextOutput
	 name = WeaponPunch0
      } widget0
      widget1 {
	 x = 0
	 y = 15
         height = 15
	 type = TextOutput
	 name = WeaponPunch1
      } widget1
      widget2 {
	 x = 0
	 y = 30
         height = 15
	 type = TextOutput
	 name = WeaponPunch2
      } widget2
      
   } widget0

By using the Dummy widget, you can group the 3 TextOutput widgets. You can now change their font settings with a single entry. And since the coordinate are relative, you can move the whole column around and change their width by just changing the coordinates of the dummy widget.

MultiLineText

Displays a bigger amount of text. If the text doesn't fit into the widgets, a vertical scrollbar will be displayed for scrolling the text.

Name: A name for identifying the widget from the program code to write. All Names must be unique in each panel.
Style: The given Paragui-Style will be used for the widget. This overrides all user specified parameters like background color or font size. Style is NOT derived to child widgets.

ScrollArea

Represents a area in which other widgets can be placed. If the widget coordinates don't fit into ScrollArea, ScrollBars are displayed for scrolling in ScrollArea.

Button

A simple button which can be pushed

Text: The text on the Button

RadioButton

A RadioButton which can be selected or not. All RadioButtons of a parent widget act as a RadioButton group, so that only one of the RadioButtons can be selected at one. If you want more than one RadioButton group, put them into different dummy widgets.

Text: The text at the RadioButton

CheckBox

A simple checkbox.

Text: The text on the Button

LineEdit

A single-line text input field

Text: The default text (optional)

Slider

A simple button which can be pushed

Orientation: Possible values: "vertical", "horizontal"

Plain

A simple, uniformly colored area

General Advice

Do NOT include text in any pictures, rather use the StaticText widget for displaying text. This allows for a future translation of ASC into other languages
Try to keep the graphics atomic. For example don't make an image of a whole dialog that already has the location of text entry fields. That would make later enhancements (for example adding a new text output field) or adjustments of the dialogs very difficult. Rather use a generic backgroud texture and position the individual elements on it inside the ASCGUI text file

Last change: Mon, 2009-06-01 10:44

search knowledgebase
browse knowledgebase