1 Overview
- 1.1 Goal
- 1.2 Design Notes
- 1.3 Ongoing Plans
2 Top-Level Windows
3 Content UI and Layout
- 3.1 Individual Field UI
- 3.2 Vertical Content Layout
- 3.3 List Item Content Layout

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.

For width, in order to work the best with all the standard fonts defined with themes, all fields should use a height of 20 as the basic field/line height.

For framing, 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.