UI Standards - Rulesets and Extensions

Overview

Goal

The goal of this section is to provide a common framework for which frame and template assets to use from the CoreRPG ruleset layer in order to provide the best end-user common experience as well as to minimize the work needed to customize ruleset and extension visuals. Going forward, we will be adapting the existing code and working with ruleset and extension developers to move to a common visual framework.

Additionally, all rulesets and themes made by SmiteWorks will be moving to this common framework. In order to maximize our ability to deliver timely products, any assets used by rulesets and extensions that do not adhere to the common framework will not be supported.

Design Notes

When designing templates for this standardization effort, the goal is that templates should be self-contained for defined the anchoring offsets needed to support their frame offsets, and to prevent overlap with other controls. The end result should be that controls should be able to be stacked on top of each other as simple blocks, instead of trying to guess offsets that look good.

Other notes:

  • Lists and formatted text fields should indent extra 10 for scrollbars

  • Top anchor should be named “contentanchor”; and bottom anchor named “bottomanchor”
    (for limited backward compatibility)

  • Provide options primarily for vertical layout (top down, bottom up, fill, split fill)

Ongoing Plans

The initial effort was to focus on getting a lot of the templates in place for this project, as well as standardizing frames at a high level. We will be continuing to migrate different window records within the included and store rulesets to use these standardized templates as much as possible.

The work will be accomplished by tackling windows based on their top-level window frames, with the effort going to standardizing the top-level layout and list item layout.

The following top-level window frame classes have been completed:
tokenbag, utilitybox

The planned order to tackle the remaining window frame classes is:
referencelist, charselect, storybox, imagebox, recordsheet, charsheet, charsheethelper, partysheet, ctbox

Top-Level Windows

Desktop Window Frames

When making desktop-level windows (i.e. panels; those that are pinned on the desktop); these are the frame assets you should use.

Frame Asset Name

Top Level Windows

Frame Asset Name

Top Level Windows

chatbox

Chat Window

shortcuts

Sidebar Background Window

imagepanel

Image Background Window

Floating Window Frames

When making floating windows (i.e. non-panel windows); these are the frame assets you should use.

Frame Asset Name

Top Level Windows

Frame Asset Name

Top Level Windows

Utility

utilitybox

Tools, Settings, Dialogs, Reference Manual, Library

tokenbag

Graphic Selection, Asset Selection

ctbox

Combat Tracker

partysheet

Party Sheet

Lists

charselect

List (Character Records)

referencelist

List (Other Record Types)

Records

charsheet

Record (Characters)

charsheethelper

Record Detail Windows (from any record sheet)

storybox

Record (Story and Notes)

imagebox

Record (Images)

recordsheet

Record (Other Record Types)

Specific Asset Definitions (Per Frame)

NOTE: We have an ongoing project to standardize the layout control naming for top-level windows that is being take in steps

Currently, only the following frames have been updated to the latest layout naming and templates:
utilitybox, tokenbag, referencelist, charselect, recordsheeet, imagebox, storybox

The next step will be migrating ctbox/charsheet/charsheethelper frames to use content layout templates.

For each top-level window frame, certain additional assets should be defined in order to ensure theming goes smoothly, and that changes in the CoreRPG layer do not impact layout of layered rulesets.

When replacing top-level frames in layered rulesets or theme extensions, make sure to update all the associated templates (and other assets) to ensure that content is correctly placed and displayed in the new frames.

Frame Asset Name

Additional Assets To Define

Frame Asset Name

Additional Assets To Define

Panels

chatbox

Templates: resize_chatbox

Templates: anchor_content_chatbox_top, anchor_content_chatbox_bottom

Fonts: emotefont, msgfont, oocfont, systemfont

imagepanel

Templates: anchor_content_imagepanel_top, anchor_content_imagepanel_bottom

Utility

utilitybox

Templates: windowtitlebar_utilitybox, windowmenubar_utilitybox, resize_utilitybox
Templates: anchor_content_utilitybox_top, anchor_content_utilitybox_bottom

tokenbag

Templates: windowtitlebar_tokenbag, windowmenubar_tokenbag, resize_tokenbag

Templates: anchor_content_tokenbag_top, anchor_content_tokenbag_bottom

ctbox

Templates: close_ctbox, help_ctbox, resize_ctbox

Templates: anchor_title_ctbox

Fonts: list-empty-ct, sheetlabel_ct

(Changes Upcoming after March 2024 to match other top-level windows.)

partysheet

Templates: windowtitlebar_partysheet, windowmenubar_partysheet, resize_partysheet

Templates: anchor_content_partysheet_top, anchor_content_partysheet_bottom

Templates: tabs_partysheet

Lists

referencelist

Templates: close_referencelist, help_referencelist, resize_referencelist

Templates: anchor_content_referencelist_top, anchor_content_referencelist_bottom

Fonts: reference-header

charselect

Templates: windowtitlebar_charselect, windowmenubar_charselect, resize_charselect

Templates: anchor_content_charselect_top, anchor_content_charselect_bottom

Records

recordsheet

Templates: windowmenubar_recordsheet, resize_recordsheet

Templates: anchor_content_recordsheet_top, anchor_content_recordsheet_bottom

Templates: tabs_recordsheet

Fonts: recordsheet_header

charsheet

Templates: close_charsheet, resize_charsheet

Templates: tabs_charsheet

Templates: anchor_title_charsheet

(Changes Upcoming after March 2024 to match other top-level windows.)

charsheethelper

Templates: close_charsheethelper, resize_charsheethelper

Templates: anchor_title_charsheethelper

(Changes Upcoming after March 2024 to match other top-level windows.)

imagebox

Templates: windowmenubar_imagebox, resize_imagebox

Templates: anchor_content_imagebox_top, anchor_content_imagebox_bottom

Fonts: imagebox_header

storybox

Templates: windowmenubar_storybox, resize_storybox

Templates: anchor_content_storybox_top, anchor_content_storybox_bottom

Fonts: storybox_header

 

 

Auxiliary Asset Definitions (Per Frame)

Each top-level window frame may have additional assets defined to assist in presentation or layout in addition to the base frame. If any of the auxiliary assets are replaced, certain additional assets should be defined in order to ensure theming goes smoothly, and that changes in the CoreRPG layer do not impact layout of layered rulesets.

Top-Level Window

Auxiliary Asset Frame Name

Additional Assets To Define

Top-Level Window

Auxiliary Asset Frame Name

Additional Assets To Define

(Any)

buttonup

Frames: buttondown, buttondisabled

Fonts: button-white

Script: Add ColorManager.setButtonIconColor(“XXXXXX”), where “XXXXXX” matches button-white coloring

(Any)

headerref

Fonts: reference-groupdesc

chatbox

chatframe_chat

Fonts: chatfont, chatnpcfont, chatgmfont

chatbox

chatframe_record_share

Fonts: chat_record_share

chatbox

chatframe_story

Fonts: narratorfont

chatbox

chatframe_whisper

Fonts: whisperfont

tokenbag

tokenbagasset

Fonts: assetview_empty, tokenbagasset_grid, tokenbagasset_list

Icons: tokenbag

Top Level Layout Template Usage

For each of the top-level and panel window frames, there are a number of standard templates that should be used in order to ensure that content is displayed within the correct space with window frame assets using different sizes for borders, edges, gutters, shadows, etc. See the table above for which templates are relevant to each frame. See that CoreRPG ruleset in the common/template_windows.xml file for the templates of CoreRPG provided top-level and panel window frames.

Template Name

Notes

Template Name

Notes

windowtitlebar_framename

Location of window title bar (if defined for window type)

windowmenubar_framename

Location of window top menu buttons (upper left and upper right)

anchor_content_framename_top

Top/left/right edges of content area;
Used for relative anchoring

anchor_content_framename_bottom

Bottom edge of content area;
Requires top anchor;
Used for relative anchoring

resize_framename

Location of window resize graphic (lower-right);
Just a graphic; window resizing still requires frame asset insideoffset tag to be set to matching offsets.

tabs_framename

(For all rulesets: recordsheet, charsheet, partysheet)
(For some rulesets: npcsheet)
Location of right-hand side tabs for multi-tabbed sheets

Retired Window Frames

Historically, several other top-level frames were used sporadically across different rulesets, and have been retired in order to standardize the top-level frames. The following top-level frames have been retired, and will not be supported in official themes and rulesets in the future.

Retired Frame Asset Name

Replace With

Retired Frame Asset Name

Replace With

calendar

utilitybox

utilitybox2

utilitybox

utilitybox3

utilitybox

npcsheet

recordsheet

referencepage

recordsheet

Content UI and Layout

Individual Field UI

NOTE: Avoid the temptation to override the default field frame offsets and offset anchors, as these may be adjusted by themes directly.

In general, fields that are editable should use these basic guidelines for frame asset usage:

Frame Asset Name

Notes

Frame Asset Name

Notes

fielddark

Editable fields

fieldlight

Read-only (static) fields

fieldfocus

Use in keyedit control frame definition to indicate keyboard focus;
Or drophilight control frame definition to indicate accepted drop type.

In order for users to recognize standard behavior of fields within the user interface, it is recommended to use the built in templates for field definitions for the different field types:

Template

Field Type

Editable

DB Linked?

Template

Field Type

Editable

DB Linked?

basicdice

dice

Yes

Yes

basicft

formatted text

Yes

Yes

linkfield

link

Yes

Yes

linkcontrol

link

Yes

No

linkcontrol_record (standard record self-link)

link

No

No

linkcontrol_static

link

No

No

basicnumber

number

Yes

Yes

basicnumberc

number

Yes

No

number_static

number

No

Yes

numberc_static

number

No

No

label

string

No

No

basicstring

string

Yes

Yes

basicstringc

string

Yes

No

string_static

string

No

Yes

stringc_static

string

No

No

stringu (underlined)

string

Yes

Yes

stringcu (underlined)

string

Yes

No

Vertical Content Layout

NOTE: This is an ongoing project.

Currently, only tool and asset windows have been migrated. Additional templates will be forthcoming to support data record windows fully.

Another common layout need is to create a vertical layout of window controls within a given window. In order to support this usage, we have added a number of templates to support that use case.

First, start by specifying the following templates:

Template

Notes

Template

Notes

anchor_content_top

Anchoring control for top of child window containing fields.

anchor_content_bottom

Anchoring control for bottom of child window containing fields;
(Only use for fixed height windows; not scrollable windows);
(Required to use any bottom or fill templates below)

anchor_content_groupbox_top

Anchoring control for top of child window containing fields and using the groupbox frame.

anchor_content_groupbox_bottom

Anchoring control for bottom of child window containing fields and using the groupbox frame;
(Only use for fixed height windows; not scrollable windows);
(Required to use any bottom or fill templates below)

Some helper templates to assist in layout are specified here:

Template

Control Type

Editable

DB Linked?

Template

Control Type

Editable

DB Linked?

line_content_top
line_content_bottom

genericcontrol

-

-

spacer_content_top
spacer_content_bottom
(default height = 5)

genericcontrol

-

-

area_content_top
area_content_bottom
area_content (fill)
area_content_left (fill; left half)
area_content_right (fill; right half)

genericcontrol

-

-

area_content_framed_groupbox_top
area_content_framed_groupbox_bottom
area_content_framed_groupbox (fill)

genericcontrol

-

-

sub_content_top
sub_content_bottom
sub_content_buttons_bottom (height = 30)
sub_content (fill)
sub_content_left (fill; left half)
sub_content_right (fill; right half)
sub_content_scroll (fill; with room for scrollbar)

subwindow

-

-

sub_content_hidden_top
sub_content_hidden_bottom
sub_content_hidden (fill)

subwindow

-

-

sub_content_framed_groupbox_top
sub_content_framed_groupbox_bottom
sub_content_buttons_groupbox_bottom (height = 30)
sub_content_framed_groupbox (fill)
sub_content_framed_groupbox_left (fill; left half)
sub_content_framed_groupbox_right (fill; right half)

subwindow

-

-

sub_content_framed_groupbox_hidden_bottom
sub_content_framed_groupbox_hidden (fill)

subwindow

-

-

sub_content_paging
(used with lists set up for ListManager paging)

(special)

 

 

For lists, you can specify either a straight list or a labeled list. Labels are defined after the list is defined. The following templates can be used:

Template

Control Type

Editable

DB Linked?

Template

Control Type

Editable

DB Linked?

list_content_top
list_content_bottom
list_content (fill)
list_content_alternating_top (row shading)
list_content_alternating (fill; row shading)

windowlist

-

-

list_content_noscroll_top
list_content_noscroll_alternating_top (row shading)

windowlist

-

-

list_content_labeled_top
list_content_labeled (fill)
list_content_labeled_alternating_top (row shading)
list_content_labeled_alternating_filtered (row shading; filter)

windowlist

-

-

list_content_framed_groupbox_top
list_content_framed_groupbox_bottom
list_content_framed_groupbox (fill)
list_content_framed_groupbox_alternating (fill; row shading)
list_content_framed_groupbox_alternating_filtered (fill; row shading; filter)
list_content_framed_groupbox_left (fill; left half)
list_content_framed_groupbox_right (fill; right half)

windowlist

-

-

label_list_content_framed_headersimple

string

No

No

anchor_list_content_label_left / anchor_list_content_label_right

-

-

-

label_list_content_left
label_list_content_centered_left
label_list_content_number_left
label_list_content_string_left
label_list_content_string_noframe_left
label_list_content_right
label_list_content_centered_right
label_list_content_number_right
label_list_content_string_right
label_list_content_string_noframe_right
label_list_content_button_right
label_list_content_button_iedit_right
label_list_content_button_iadd_right
label_list_content (fill)
label_list_content_noframe (fill)

string

No

No

spacer_list_content_label_left
spacer_list_content_link_label_left
spacer_list_content_token_label_left
spacer_list_content_label_right
spacer_list_content_link_label_right
spacer_list_content_button_label_right
spacer_list_content_idelete_label_right (hidden when not in edit mode)

genericcontrol

-

-

For large blocks of text, you can optionally specify a header template followed by the field template you want:

Template

Control Type

Editable

DB Linked?

Template

Control Type

Editable

DB Linked?

header_content_framed_groupbox
header_content_framed_headersimple
header_content_framed_rowshade
header_content_framed_headerref
header_content_framed_metalplate
header_content_framed_metalplate_with_icon_top

string

No

No

string_content_top
string_content_noframe_top
string_content_noframe (fill)

string

Yes

Yes

string_content_noframe_static_top

string

No

Yes

stringc_content_top
stringc_content (fill)

string

Yes

No

stringc_content_noframe_static_top
stringc_content_noframe_static_bottom

string

No

No

stringc_content_framed_groupbox_top
stringc_content_framed_groupbox (fill)

string

Yes

No

For labeled field rows, specify the label template followed by the field template you want:

Template

Control Type

Editable

DB Linked?

Template

Control Type

Editable

DB Linked?

label_content_column

string

No

No

string_content_column
string_content_columnh
string_content_column_single (single line)

string

Yes

Yes

stringc_content_column
stringc_content_column_single (single line)

string

Yes

No

stringc_content_column_noframe_static

string

No

No

ft_content_column
ft_content_columnh
ft_content_column_full
ft_content_columnh_full

formattedtext

Yes

Yes

number_content_column
number_content_column_right

number

Yes

Yes

button_checkbox_content_column

button (number)

Yes

Yes

button_stringcycler_content_column
combobox_content_column

special (string)

Yes

Yes

area_content_column
(Used to define reserve a certain height within labeled field row sections for custom control layouts)

-

-

-

List Item Content Layout

One common layout need is to create simple single line list item child windows. In order to support this usage, we have added a number of templates to support that use case.

First, start by specifying the following templates:

Template

Notes

Template

Notes

anchor_listitem_left
anchor_listitem_left_sm

Anchoring control for left edge. Regular and small denote padding values of 5 or 2.

anchor_listitem_right
anchor_listitem_right_sm

Anchoring control for right edge. Regular and small match left anchor padding.

Then, specify any left or right anchored fields:

Template

Field Type

Editable

DB Linked?

Default Width

Template

Field Type

Editable

DB Linked?

Default Width

spacer_listitem_left
spacer_listitem_right

none

No

No

0

button_listitem_delete (self-delete; right)

none

Yes

No

20

button_listitem_left
button_listitem_right

number

Yes

Yes

20

buttonc_listitem_left
buttonc_listitem_right

number

Yes

No

20

link_listitem_left
link_listitem_right

link

No

Yes

20

linkc_listitem_left (self-reference)
linkc_listitem_right (self-reference)

link

No

No

20

number_listitem_left
number_listitem_right

number

Yes

Yes

40

number_listitem_left_static
number_listitem_right_static

number

No

Yes

40

label_listitem_left
label_listitem_right

string

No

No

80

string_listitem_left
string_listitem_right

string

Yes

Yes

80

string_listitem_left_static
string_listitem_right_static
stringc_listitem_left_noframe_static
stringc_listitem_right_noframe_static
stringc_listitem_left_noframe_static_wrapped
stringc_listitem_right_noframe_static_wrapped

string

No

Yes

80

Finally, specify the center field that fills the remaining space (usually the name field).

Template

Field Type

Editable

DB Linked?

Template

Field Type

Editable

DB Linked?

string_listitem_center
string_listitem_center_text (underlined)

string

Yes

Yes

string_listitem_center_static
string_listitem_center_noframe_static
string_listitem_center_noframe_static_linked (click to open link)

string

No

Yes

stringc_listitem_center_noframe_static

string

No

No