GreatSex SEXML 1.0 Specification

Introduction

GreatSex is the SEXML file-format for specifying the widget layout in the Rococo GUI system. It's name was taken from the letters of Gui-retained S-Expression. Unfortunately, despite its name, it is unlikely to solve the world's demographic collapse problem - but it may make user-interfaces easier to author.

Familiarity with the SEXML specification is required. Widgets exist in a tree, with a root widget that has no parent. The root is always a Frame widget. Frame widgets have two sub-widgets, a toolbar, which is usually collapsed, but can be used to create a regular OS style UI toolbar for fullscreen mode, and a client-area where children widgets are placed. In GreatSex SEXML, top-level Widget directives append new children to the frame's client-area. The client-area matches the area of the frame less the area of the toolbar. So without a toolbar, the default for GreatSEX SEXML, client-area spans the entire frame.

Every widget has a number of colours used in its rendering (see the Colour Table at the bottom of this document), and if they are not explicitly defined, then the rendering algorithm will search ancestors for a definition, so this means you can set such colours in a parent widget, and have all the children use the scheme. If no widget explicitly defines a particular colour, then the rendering algorithm will look at the frame's scheme, which is set with the top-level Scheme directives. The particular scheme that will be that which matches the control state of the UI. The control state consists of 3 flags - Hovered, Focused and Pressed. Hovered means the UI cursor is within the bounds of the widget, while Focused means the keyboard sends default input to the widget and Pressed means the the widget is in some pressed state, such as with a button.

Top Level Directives

• Insert

  - analagous to a #include directive in C and C++.

  • Name-Value Attributes

    • Path - the string argument gives the ping path to another SEXML script, the expression tree of such is inserted into the SEXML expression tree at the corresponding point of definition of the Insert statement.

      Example: (Path "!tests/greatsex.scheme.sexml")

• Zoom

  - there may be a number of competing zoom directives. The directive which defines the highest minimum resolution defines GUI zoom levels

  • Name-Value Attributes

    • MinWidth - integer argument that defines the minimum horizontal pixel resolution for the zoom directive to apply.

    • MinHeight - integer argument that defines the minimum vertical pixel resolution for the zoom directive to apply.

  • Type-Name-Value Attributes

    • #List Levels ... - with a floating point list that gives legal zoom scales. Range is 1.0 to 100.0. Values must increase left to right.

      Example: ([] Levels 1.0 1.1 1.2 1.3 1.4 1.5 1.6 1.7 1.8 1.9 2.0 2.1 2.2 2.3 2.4 2.5)

• Scheme

  - defines a colour scheme that applies for a set of user-input states on a hierarchy of GUI widget panels

  • Optional Subdirectives

    • ApplyTo

      • Type-Name-Value Attributes

        • #List RenderStates ... - combination of boolean flags represented by strings 'pressed', 'focused', 'hovered'. If none apply use 'default' The combination determine whether the scheme applies for a given focus and cursor state.

          Example: (ApplyTo ([] RenderStates pressed focused))

    • {colour-name} - where {colour-name} is any of the text items in the AttributeName coloum of the colour table below in this HTML

      • Name-Value Attributes

        • Red - integer between 0 and 255, giving the red intensity of the colour

        • Green - integer between 0 and 255, giving the green intensity of the colour

        • Blue - integer between 0 and 255, giving the blue intensity of the colour

        • Alpha - integer between 0 and 255, giving the alpha intensity of the colour

• Colour

  - defines a colour, keyed by its Id mandatory attribute

  • Attributes

    • Id [name] - mandatory attribute - the string argument gives the unique name of the colour. Some widget directives can take such a name as a string attribute to determine which colours apply

    • #List Unform.RGBA [red] [green] [blue] [alpha] - optional attribute - arguments are 4 integers ranging 0-255, red, green, blue and alpha that apply for all GUI states. Note that if present, then subdirective Spec is superfluous

  • Optional Subdirectives

    • Spec - defines what colour applies and under what circumstances

      • Mandatory Name-Value Attributes

        • Red - integer between 0 and 255, giving the red intensity of the colour

        • Green - integer between 0 and 255, giving the green intensity of the colour

        • Blue - integer between 0 and 255, giving the blue intensity of the colour

        • Alpha - integer between 0 and 255, giving the alpha intensity of the colour

      • Mandatory Type-Name-Value Attributes

        • #List For ... - combination of boolean flags 'pressed', 'focused' and 'hovered' with 'default' meaning no flags

          ([] For pressed focused))

• Font

  - defines a font, keyed by its Id mandatory attribute

  • Mandatory Attributes

    • Id [name] - the string argument gives the unique name of the font. Some widget directives can take such a name as a string attribute to determine which font applies

    • Family [family-name] - the argument is a string that identifies the font-family.

  • Optional Attributes

    • #List Mods ... - list of boolean flags 'Bold' and 'Italic'.

      Example: ([] Mods Bold Italic))

• Frame

  - The frame element navigates up the owner branch until the frame is found and then sets the attributes specified in the sexml

  • Attributes and Subdirectives

    - frames are Widgets, and have the all the base widget attributes and subdirectives. If no Frame element is included in the SEXML then a frame for the GUI still exists, but its attributes are not overriden by the SEXML.

• Frame.ClientArea

  - The frame-client-area element navigates up the owner branch until the frame is found and then sets the attributes of the ClientArea specified in the sexml

  • Attributes and Subdirectives

    - a frame's client area is a Division Widget, and has the all the attributes and subdirectives of such. If no client-area element is included in the SEXML then the client area for the GUI Frame still exists, but its attributes are not overriden by the SEXML.

Widget Directives

Widgets serve as parent containers to child widgets, and thus all widget directives are allowed an arbitrary number of widget directives in their subdirective list, with each such defining a child widget.

Any widget may have any widget type as a child, the exception is the frame widget, which hosts the widget-tree. The frame widget's client area, may have children, but no widget may have a frame as a child. Frames are root widgets only.

All widgets also have an arbirary list of panel and colour attributes. Panel attribute names begin with the subspace 'Panel'. Colour attribute names begin with the subspace 'Colour'.

Colour attributes are all name-value pairs with the second argument being the colour id. The id must match the id of top-level-directive (Colour ...) defined in the SEXML or at an insert point.

A list of all legal 'Colour' names is in the table at the bottom of this HTML document

Widget Factories

A widget directive other than Frame or Frame.ClientArea creates widgets. In addition to the panels and colours every widget can specify, every widget factory has its own custom set of attributes and subdirective types, so, for example, a Slider widget will have attributes and subdirectives that control the mapping between the slider and the underlying property bound to the slider. Here follows a comprehensive set of widget factories and their custom attributes and subdirectives.

• Button

  - Construct a ButtonWidget

  • Attributes

    • Text [text]

      - Prevents image rendering if the [text] string is not blank and specifies that the button renders the text instead

    • Meta [text]

      - Sets the button's metadata string to [text]

    • FitTextH

      - Existential attribute that tells a button to shrink horizontally to fit its text string

    • FitTextV

      - Existential attribute that tells a button to shrink vertically to fit its text string

    • #Vec2i Text.Spacing [dx] [dy]

      - Defines the spacing between the button text and its bounding rectangle. Behaviour depends on text alignment.

    • Text.Alignment [alignment]

      - Defines the text alignment. Must be one of Left|Right|Top|Bottom|TopLeft|TopRight|BottomLeft|BottomRight|Centre]

• Div

  - Construct a DivisionWidget, the tabula rasa of widgets, they exist to layout children and display a backround and little else. They have no unique attributes.

• Label

  - Create a TextWidget. They display a text string. Generally they are not expected to have children.

  • Attributes

    • Text [text]

      - Specifies the [text] to render. It is centred horizontally and vertically.

    • Font [id]

      - Specifies the [id] of the font to render. The font must have been defined by a top-level Font directive

    • FitH [boolValue]

      - Specifies whether to shrink the widget to fit the text horizontally

    • FitV [boolValue]

      - Specifies whether to shrink the widget to fit the text vertically

• Portrait

  - Typically defined as the first and only child of the Frame's child area, draws a background portrait that preserve's the texture's aspect ratio.

  • Attributes

    • Image [pingPath]

      - Specifies the [pingPath] of the image to render. It is centred horizontally and vertically and anything outside the render area is drawn using the Colour.Portrait.Band for the panel

• HintBox

  - Creates a box that receives notification when the keyboard focus changes to render a string from the focus widget panel's hint property

  • Attributes

    • #Vec2i Text.Spacing [dx] [dy]

      - Defines the spacing between the hint text and its bounding rectangle. Behaviour depends on text alignment.

    • Text.Alignment [alignment]

      - Defines the text alignment. Must be one of Left|Right|Top|Bottom|TopLeft|TopRight|BottomLeft|BottomRight|Centre]

    • Test.Font [id]

      - Defines the id of the font, which must have been defined in a top-level Font directive.

• GradientFill

  • Attributes

    • TopLeft [colourId]

      - Defines the top left colour of the gradient zone. The colour must have been defined in a top-level Colour directive

    • TopRight [colourId]

      - Defines the top right colour of the gradient zone. The colour must have been defined in a top-level Colour directive

    • BottomLeft [colourId]

      - Defines the bottom left colour of the gradient zone. The colour must have been defined in a top-level Colour directive

    • BottomRight [colourId]

      - Defines the bottom right colour of the gradient zone. The colour must have been defined in a top-level Colour directive

    • Fill [fillType]

      - Defines the gradient fill type. Must be one of Banner|Smooth|Solid|Default.

      • Default|Solid fill uses the top left colour for the entire fill.
      • Banner creates a horizontally symmetrical fill.
      • Smooth renders two triangles, split from top left to bottom right, using all four colour definitions.

    • FitV FirstChild

      - Shrinks the gradient fill to match the height of the first child

• RadioButtons

  - defines a group of buttons in which activation of any one button deactivates the other. Keyboard and gamepad navigation between buttons is automatically handled.

  • Attributes

    • #List Group ...

      - Specifies a list of button panel descriptions that identify which buttons are part of the radio collection. See Panel.Description

    • Navigate [direction]

      - Specifies whether up-down or left-right gui events change the radio focus. [direction] must be one of H|V|Horizontal|Vertical.
      H|Horizontal => left-right, V|Vertical => up-down

    • Default [description]

      - Specifies the button by description that is considered the default button

  • Subdirectives

    • Tab

      - specifies that a radio button toggles a widget panel's collapsed state, so that only one tab is visible at a time

      Attributes

      • For [meta]

        - Specifies the Meta string of the radio-button that controls toggling of the target widget

      • Toggles [description]

        - Specifies the Panel.Description of the target widget panel, the collapse state of which is to be toggled by the associated button

• VerticalList

  - defines a top-down layout widget. Tab events automatically advance through the children. If the end of the children is reached tab returns focus to the top child if Panel.TabsCycle is defined. This widget factory has no unique attributes or subdirectives.

• Viewport

  - defines a vertically scrolling region and renders a vertical scroll bar if needs be.

  • Attributes

    • Viewport.RectStyle.Scrollable [style]

      - Specifies the viewport panel rectangle style when a scroller in visible. [style] can be one of SHARP|ROUNDED|BLUR

    • Viewport.Rectstyle.NotScrollable [style]

      - Specifies the viewport panel rectangle style when a scroller in hidden. [style] can be one of SHARP|ROUNDED|BLUR

    • Viewport.SyncDomainToChildren

      - An existential attribute, when present sets the scroller domain height to the sum of the heights of the client area children.

    Subdirectives

    • Viewport.ClientArea

      - Provides configuration for the viewport's client area panel attributes. It has no unique attributes nor subdirectives.

    • Viewport.Offset

      - Provides configuration for the viewport's offset area panel attributes. It has no unique attributes nor subdirectives..

• ControlPrompt

  - defines a widget that displays control prompts, either for Keyboard or an XBOX controller. The device responsible for input just before a render cycle determines which icon set is used.

  • Attributes

    • Font [id]

      - Specifies the font by id for rendering text prompts. The id must match a font that has been defined by a top-level Font directive.

    • AlignRight

      - An existential attribute: if present, aligns the control prompts on the right hand side of the widget panel.

    Subdirectives

    • DefIcon

      - defines an icon for a particular device and control

      Attributes

      • Icon [iconId]

        - gives a unique name to the icon. For use in the Prompt subdirective (see below)

      • For [controlType]

        - One of Keyboard|XBOX. For keyboard, a mouse or keyboard event will activate this icon. For XBOX, then XBOX game controllers will activate the icon.

      • Path [pingPath]

        - Ping path to the image file for the icon

      • VPadding [vPadding]

        - vertical padding above and below image

    • Prompt

      - specifies which icon to use and the associated text. The order of prompt directives determines the order of icons in the control prompt

      Attributes

      • Icon [iconId]

        - gives a unique name to the icon. Must match one of the icon ids defined in the DefIcon's Icon subdirective (see above)

      • Text [text]

        - gives a text message to display to the left of the icon

• Toolbar

  - creates a widget with a layout optimized for displaying button image controls.

  - experimental: there is a hidden toolbar in the root frame widget that is normally invisible for most GUI applications. While the toobar widget has been proven to work, its usefulness in the context of a SEXML specified context is questionable - a division widget may be more flexible and serve much the same purpose.

  • Attributes

    • Content.Padding.Cell [padding]

      - [padding] integer specifies the space between child widgets

    • Content.Padding.Border [padding]

      - [padding] integer specifies the space between the border of the toolbar and the contentss

    • ChildrenContent.Alignment [alignment]

      - where [alignment] is one of top|right|bottom|hcentre|vcentre

• GameOptions

  - This is the most complex of the widget directives and has its own Game Options Web Page.

Panel Attributes

Attribute Format	Definition and Commentary
#Vec2i Panel.Offset [dx] [dy]	The delta offset [dx,dy] from the parent's top left position to the panel's top left position
#Vec2i Panel.Span [dx] [dy]	The constant span [dx,dy] of the widget panel
Panel.FixedWidth [width]	[width] is an integer. If it ends with a % sign, specifies with as the fraction of the parent's x-span, otherwise specifies widget co-ordinate x-span
Panel.FixedHeight [height]	[height] is an integer. If it ends with a % sign, specifies with as the fraction of the parent's y-span, otherwise specifies widget co-ordinate y-span
Panel.Description [text]	At a minimum provides a debugging string for the widget, but also gives a key for navigation and other logic to identify a purpose for the widget
Panel.TabsCycle [boolValue]	Pass true for [boolValue] to mark a panel to cycle tabs endlessly
#Reci Panel.Padding [left] [top] [right] [bottom]	Set's the panel's padding on all four of its bounds. If any end with % symbol, the value specifies the faction of the parent's span across the appropriate axis. See ExpandH and ExpandV.
Panel.Layout [layout]	Where layout is one of LeftToRight|RightToLeft|TopToBottom|BottomToTop|None. This determines the direction across which child widgets are laid out. 'None' is used when children geometries are micromanaged elsewhere
Panel.ExpandH	An existential attribute that specifies that a widget to expand horizontally to match its parent geometry, and then shrink according to the Padding for the panel. See Panel.Padding
Panel.ExpandV	An existential attribute that specifies that a widget to expand vertically to match its parent geometry, and then shrink according to the Padding for the panel. See Panel.Padding.
#Recti Panel.ChildPadding [top] [left] [right] [bottom]	Behaviour dependendent on the layout algorithm - but specifies gaps between children when laid out by their parent
#List Panel.Fit ...	Arguments can be any of H|Horizontal|V|Vertical. Prescence of H|Horizontal specifies a widget shrinks to fit its children horizontally; ditto - V|Vertical specifies vertically.
Panel.RectStyle [style]	Where style is one of SHARP|ROUNDED|BLUR. Specifies the rectangle perimeter used to render the widget background. See Panel.CornerRadius
Panel.CornerRadius	In the case of a ROUNDED rectangle style, specifies the radius of the corner arcs. Typically 1-10. See Panel.RectStyle
Panel.AcceptFocus	An existential attribute that marks a panel as having the potential for keyboard focus
#List Panel.Navigate ...	The items form a string list of Panel.Description text that is used to define a tabbed navigation sequence for the panel. The argument order specifies the navigation order.
Panel.Hint [hint]	Specifies the [hint] that is registered when keyboard focus applies to the panel. The [hint] may appear in a hint widget.
Panel.Collapsed	An existential attribute that marks a panel as being collapsed - invisible, disabled and taking up no span. All descendants are also invisible, disabled and take no span.
Panel.NavLeft [desc]	Specifies the panel description for the panel that takes the next focus when a left action is taken (gamepad or cursor left). See Panel.Description
Panel.NavRight	Specifies the panel description for the panel that takes the next focus when a right action is taken (gamepad or cursor right). See Panel.Description
Panel.NavUp	Specifies the panel description for the panel that takes the next focus when an up action is taken (gamepad or cursor up). See Panel.Description
Panel.NavDown	Specifies the panel description for the panel that takes the next focus when an up action is taken (gamepad or cursor down). See Panel.Description
Panel.OcclusionSurface [boolValue]	The boolean value true|false determines whether a panel should be painted over with an occlusion surface in the rendering of an occluding GUI object (such as a popup menu). This creates a visual cue for the modality of a popup.

Colour Attribute Names & Commentary

Attribute Name	EGRSchemeColourSurface	Comment
Colour.Background	BACKGROUND	Background for the root frame widget and viewport widget
Colour.Button	BUTTON	Background colour for buttons and slider bulbs
Colour.Button.Edge.Top.Left	BUTTON_EDGE_TOP_LEFT	Edge colour for left and top of button rectangles
Colour.Button.Edge.Bottom.Right	BUTTON_EDGE_BOTTOM_RIGHT	Edge colour for right and buttom of button rectangles
Colour.Button.Image.Fog	BUTTON_IMAGE_FOG	For buttons with images, this is the translucent overlay colour
Colour.Button.Shadow	BUTTON_SHADOW	Provides the shadow colour behind button text
Colour.Button.Text	BUTTON_TEXT	Provides the colour of button text
Colour.Menu.Button	MENU_BUTTON	In a menu item, determines the background colour
Colour.Menu.Button.Edge.Top.Left	MENU_BUTTON_EDGE_TOP_LEFT	Edge colour for left and top of menu item rectangles
Colour.Menu.Button.Edge.Bottom.Right	MENU_BUTTON_EDGE_BOTTOM_RIGHT	Edge colour for right and bottom of menu item rectangles
Colour.Container.Background	CONTAINER_BACKGROUND	Background colour of control-prompts, divisions, hintboxes, radio-button groups, toolbars and vertical lists
Colour.Container.Top.Left	CONTAINER_TOP_LEFT	Top-left edge colour of control-prompts, game option controls, property editors, divisions, hintboxes, labels, radio-button groups, viewports, toolbars and vertical lists
Colour.Container.Bottom.Right	CONTAINER_BOTTOM_RIGHT	Bottom-right edge colour of control-prompts, game option controls, property editors, divisions, hintboxes, labels, radio-button groups, viewports, toolbars and vertical lists
Colour.Scroller.Button.Background	SCROLLER_BUTTON_BACKGROUND	Background colour of vertical scroller buttons
Colour.Scroller.Button.Top.Left	SCROLLER_BUTTON_TOP_LEFT	Top-left edge colour of vertical scroller buttons
Colour.Scroller.Button.Bottom.Right	SCROLLER_BUTTON_BOTTOM_RIGHT	Bottom-right edge colour of vertical scroller buttons
Colour.Scroller.Bar.Background	SCROLLER_BAR_BACKGROUND	Background colour of scroller bars
Colour.Scroller.Bar.Top.Left	SCROLLER_BAR_TOP_LEFT	Top-left edge colour of vertical scroller bar
Colour.Scroller.Bar.Bottom.Right	SCROLLER_BAR_BOTTOM_RIGHT	Bottom-right edge colour of vertical scroller bar
Colour.Scroller.Slider.Background	SCROLLER_SLIDER_BACKGROUND	Background colour of scroller slider
Colour.Scroller.Slider.Top.Left"	SCROLLER_SLIDER_TOP_LEFT	Top-left edge colour of vertical scroller slider
Colour.Scroller.Slider.Bottom.Right	SCROLLER_SLIDER_BOTTOM_RIGHT	Bottom-right edge colour of vertical scroller slider
Colour.Editor	EDITOR	Background colour of an editor widget in edit mode
Colour.Text	TEXT	Text colour for an editor in edit mode, a label, a game option control title, or property editor name-value widgets
Colour.Focus	FOCUS_RECTANGLE	Comment
Colour.EditText	FOCUS_RECTANGLE	Focus widget highlight colour
Colour.Label	LABEL_BACKGROUND	Background colour for editor widgets in read-only mode, labels, game option titles, and property editor titles
Colour.Label.Shadow	LABEL_SHADOW	Text shadow colour for labels
Colour.Splitter.Background	SPLITTER_BACKGROUND	Background colour for splitter widget
Colour.Splitter.Edge	SPLITTER_EDGE	Edge colour for splitter widget
Colour.Carousel.Text	CAROUSEL_TEXT	Text colour for carousel when not disabled
Colour.Carousel.Background	CAROUSEL_BACKGROUND	Background colour for carousel when not disabled
Colour.Carousel.Top.Left	CAROUSEL_TOP_LEFT	Top-left edge colour of carousel control
Colour.Carousel.Bottom.Right	CAROUSEL_BOTTOM_RIGHT	Bottom-right edge colour of carousel control
Colour.GameOption.Background	GAME_OPTION_BACKGROUND	Background colour for game option container if not disabled
Colour.GameOption.Disabled.Background	GAME_OPTION_DISABLED_BACKGROUND	Background colour for game option container if disabled
Colour.GameOption.Disabled.Text	GAME_OPTION_DISABLED_TEXT	Text colour for disabled option
Colour.GameOption.Top.Left	GAME_OPTION_TOP_LEFT	Top-left edge colour of game option container
Colour.GameOption.Bottom.Right	GAME_OPTION_BOTTOM_RIGHT	Bottom-right edge colour of game option container
Colour.GameOption.ChildSpacer	GAME_OPTION_CHILD_SPACER	Colour of the line below a game option
Colour.Carousel.DropDown	CAROUSEL_DROP_DOWN_BACKGROUND	Scrollable menu background colour for a carousel drop-down
Colour.Carousel.DropDown.Text	CAROUSEL_DROP_DOWN_TEXT	Scrollable menu text colour for a carousel drop-down
Colour.Portrait.Band	PORTRAIT_BAND_COLOUR	The colour of the bands that appear to the sides of the portrait widget when the aspect ratio of the panel does not match the image
Colour.Slider.Guage	SLIDER_GUAGE	Game option scalar background colour for slider guage
Colour.Slider	SLIDER_BACKGROUND	Slider background colour
Colour.Slider.Slot	SLIDER_SLOT_BACKGROUND	Slider slot background colour
Colour.Slider.Slot.Edge.1	SLIDER_SLOT_EDGE_1	1st edge colour for the slider slot. Results depends on the slider rendering algorithm
Colour.Slider.Slot.Edge.2	SLIDER_SLOT_EDGE_2	2nd edge colour for the slider slot. Results depends on the slider rendering algorithm
Colour.Occlusion.Surface	OCCLUSION_SURFACE	The colour a scrollable menu uses to mask off the background panels