User:Raiguard/Tutorial:Modding tutorial/GUI/Style guide
THIS PAGE IS A WORK IN PROGRESS
This style guide is designed to give you an overview of the precepts and specific element styles used to create 0.18-esque GUIs. This guide is not to be taken as gospel - the contents are merely suggestions to help you improve your interfaces.
This style guide assumes you know how to create GUIs, assign styles to elements, and edit styles. If you do not know these things, this guide won't be of much use to you.
Window
Windows are created using the default frame style. Because of this, you need not specify a style when creating the element.
For windows that contain multiple sub-windows (e.g. most windows that hold a character inventory) outer_frame
is used as the outer frame and inner_frame_in_outer_frame
is used for each internal window.
Generally there are three kinds of windows:
- Standard windows have a close button in the top-right corner, and are opened/closed manually either by clicking something or using a hotkey.
- Dialog windows have a row of dialog buttons along the bottom, and do not have a close button. These are used when there is a clear hierarchy of actions - you go "back" to the previous action, or you "confirm" the current action. These windows must have a "Back" button in the bottom-left corner, and may have a "Confirm" button in the bottom-right corner. Other buttons on the bottom row are optional and should be used sparingly.
- Compact windows have neither a titlebar nor a dialog row. These are usually mini-GUIs that are opened/closed automatically as a result of some user action. There are no set rules for these kinds of GUIs, it entirely depends on what they're used for.
Titlebar
Draggable vs. non-draggable windows.
Each non-compact window must have a titlebar. All titlebars include a title, and for windows that are meant to be draggable, the titlebar includes a drag handle. Standard windows also include a close button. Other frame action buttons may be added to the left of the close button, but should be used sparingly.
Titlebars are created using a simple horizontal flow with no special edits - the default style is perfect for this case.
- The title text is a
label
using theframe_title
style. Setignored_by_interaction
on this element, so the dragging functionality will work. - The "drag handle" is an
empty-widget
element with thedraggable_space_header
style. You will need to applyhorizontally_stretchable
to the element's style, and set theheight
to24
. If adding a close button or other frame action button, set theright_margin
to4
. This element also requiresignored_by_interaction
to be true, so the dragging functionality will work. - Close buttons, or any other frame action buttons you are adding, are created with
sprite-button
using theframe_action_button
style. The default sprite should be colored (RGB)227,227,227
, and the hovered and clicked sprites should be colored (RGB)29,29,29
. Custom frame action sprites should be 26x26 with a 3px padding around the edges, making for a file size of 32x32. As of the time of writing, the base game does not use mipmaps for these icons, but it would probably be a good idea to add them to your own icons just in case. - When creating draggable windows,
drag_target
should be set on the flow element that comprises the titlebar, not the "drag handle" itself. - If your window is not in
screen
or is otherwise non-draggable, DO NOT add a drag handle. Instead, use anempty-widget
withhorizontally_stretchable
enabled.
Content frame
An example of inside_shallow_frame_with_padding, demonstrating the built-in 12px padding.
Each non-compact window must have at least one "content frame" (the light grey pane seen in the above screenshots). This is where the meat of your interface will go.
Content frames are created using the inside_shallow_frame_with_padding
style. This will give you 12px of padding in the frame. If you need to have zero padding (i.e. for adding a scroll pane or a toolbar), use inside_shallow_frame
instead.
It is good practice to separate different "purposes" in a GUI with different content panes. For example, Recipe Book uses different content panes for search and information:
TODO add image
If you add multiple content panes, add them to a flow element with horizontal_spacing
or vertical_spacing
set to 12
.
Dialog Row
The dialog row is the row of buttons at the bottom of a dialog window. Generally, a window will have one or two of these, but more can be added if necessary.
The game uses a left-to-right methodology for its navigation. Therefore, the leftmost dialog button is the "back" or "cancel" action, while the rightmost is the "confirm" action. Because dialogs have an actual "confirm" action, changes to the content of the dialog should not be saved until the "confirm" button is clicked and the window closed.
TODO list styles
Toolbar
Toolbars are a great place to keep a content pane's "title" as well as tools used in that pane. You can see two examples of toolbars in the Recipe Book screenshot above.
Toolbars are created using the subheader_frame
style. There are a few locations where they are acceptable:
- At the top of an
inside_shallow_frame
(no padding) - At the top of an
inside_deep_frame
(usually above a tabbed pane) - Below the tab row in a tabbed pane. In this case, use a custom style TODO SHOW STYLE