MegaGlest Forum
Archives (read only) => Glest Advanced Engine => General discussion => Topic started by: Omega on 14 June 2011, 14:24:11
-
The title explains it pretty well. Obviously, the widgets is a huge deal, and could give a lot of customability to modders who wish to invest the time to create a custom GUI for their mod. However, documentation for it is, well, non-existent. I would make it myself, but even I do not begin to know how it would be done.
An explanation of how it works and what most of the options do would be greatly appreciated, even if just a small description (which may be expanded through further testing, etc)...
-
A bit rough, and possibly with an error or two, but here's a start,
=Setup functions=
==addColour(name, colourString);==
Add a named colour. The name should be unique and the colourString is a hexadecimal
representation of the colour (0xRRGGBBAA, or #RRGGBBAA, or RRGGBBAAh).
==loadTexture(name, path, mipmap);==
Load a named texture. The name should be unique and path is the complete path to the
desired image file from the 'root' glest directory. An optioinal boolean 'mipmap'
tells the engine whether to generate mipmaps for the texture or not, if omitted the
defualt value is true, and this is generally appropriate, textures with 'fine detail'
(such as those used for borders) being the exception to the general rule.
==setOverlayTexture(type, texName);==
The three texture overlays used on auto-command toggles are set via this function,
it should be called three times with type 'tick', 'cross', & 'question'. The texName
parameter is a previously loaded texture.
==loadFont(name, path, size);==
Load a named font. The name should be unique and path is the complete path to the
desired font file from the 'root' glest directory. The size parameter sets the size
in points. NOTE: size will not be exactly respected, and is scaled based on the
window size/resolution the user is playing the game with.
==setDefaultFont(type, fontName);==
Set default and fallback fonts, should be called four times, with types 'menu', 'game',
'title' & 'version'. The menu and game fonts are fallbacks for text styles that are
missing fonts, while title and version are used only for the 'advanced engine' and
version labels on the root menu.
=Style definitions=
WidgetType = {
Default = { --[[ Style definition for default state ]] },
States = {
Disabled = { --[[ style definition (or 'overrides') for disabled state ]] },
Hover = { --[[ style definition (or 'overrides') for hover state ]] },
Focus = { --[[ style definition (or 'overrides') for focus state ]] },
Selected = { --[[ style definition (or 'overrides') for selected state ]] },
},
}
The default state determines a widgets 'normal' look, the tables within the States table
determine their appearance in various behavioural states, any individual style elements
that are not specified in a special state are copied from the default state.
A style definition consists of a table each for borders, background, highlight, text and
overlay.
==Borders==
Type: A border style must contain a Type field, which must be one of 'none', 'invisible',
'raise', 'embed', 'solid', 'custom-sides', 'custom-corners' or 'texture'.
Sizes: If the Type is anything other than 'none', then a sizes table should be included,
if not type texture it should contain four integers for the left, top, right & bottom
border respectively, for type texture it should contain two integers for the side and corner
size.
Colours: A table of one to four named colours, used where type is solid (single colour), raise
or embed (two colours, light and dark respectively), custom-sides or custom-corners (four
colours, [left, top, right, bottom or top-left, top-right, bottom-right, bottom-left). Not
used for types none, invisible or texture.
Texture: A named texture, used only for type texture.
==Background==
Type: A background style must contain a type, which should be 'none', 'colour', 'custom-colours'
or 'texture'.
InsideBorders: boolean value indicating whether the background should be rendered only within
the widgets borders, or over the entire widget's size.
Colours: A table of one or four named colours, used where type is colour (single entry) or
custom-colours (four values: top-left, top-right, bottom-right, bottom-left).
Texture: named texture to use if type is texture.
==Highlight==
Type: Style type, one of 'none', 'oscillate' or 'fixed'.
Colour: a named colour for the highlight.
==Text==
Font: A named font that this widget should use for any text.
Colour: A named colour to render the font in.
Shadow: boolean value indicating whether text should be shadowed.
ShadowColour: a named colour the shadow should be rendered with.
==Overlay==
Texture: a named texture identifying the overlat image.
InsideBorders: boolean value indicating whether the overlay should be rendered only within
the widgets borders, or over the entire widget's size.
=Widget Types=
The folloeing is a list of tables the engine looks for to style certain widgets,
StaticWidget
Button
CheckBox.Checked
CheckBox.UnChecked
TextBox
ListItem
ListBox
DropList
ScrollBar
ScrollBarButtonUp
ScrollBarButtonDown
ScrollBarButtonLeft
ScrollBarButtonRight
ScrollBarVerticalShaft
ScrollBarVerticalThumb
ScrollBarHorizontalShaft
ScrollBarHorizontalThumb
Slider
SliderVerticalShaft
SliderVerticalThumb
SliderHorizontalShaft
SliderHorizontalThumb
TitleBar
TitleBarCloseButton
TitleBarRollUpButton
TitleBarRollDownButton
TitleBarExpandButton
TitleBarShrinkButton
MessageBox
GameWidgetFrame
ToolTip
ToolTip.Header
ToolTip.Main
ToolTip.Item
ToolTip.RequirementMet
ToolTip.RequirementNotMet
ColourPicker
ColourButton
TickerTape
InfoWidget
Logger
Logger.Header
Logger.LogLine
CodeView
CodeEdit
ResourceBar
MiniMap
Display
Console
GameStats
-
Wow, thanks silnarm. I added that to the wiki for now (with improved formatting and some typo fixes). Just one question, it says the colors can be written as:
(0xRRGGBBAA, or #RRGGBBAA, or RRGGBBAAh).
The last one has a rather out of place looking "h" at the end. Just checking whether this is supposed to be there or if it's a typo.
At any rate, it's on the wiki at: https://docs.megaglest.org/GAE/Widgets
We can expand on it later, now that it's at a publicly editable location, where everyone can edit without even making an account [Wiki advertising goes here].
-
Just one question, it says the colors can be written as:
(0xRRGGBBAA, or #RRGGBBAA, or RRGGBBAAh).
The last one has a rather out of place looking "h" at the end. Just checking whether this is supposed to be there or if it's a typo.
That's just one of numerous semi-standard ways to write a hexadecimal number, I chose to support as many common ones as I could think of ;)
We can expand on it later, now that it's at a publicly editable location, where everyone can edit without even making an account [Wiki advertising goes here].
Thanks for getting that up, I'll certainly look to add to it myself as time permits, but in the meantime if anyone else is playing around with widget.cfg, please feel free to help out!
PS: I see we have a page for translations now too, Thanks!
-
Good work Silnarm/Omega :thumbup: I've been wanting to play with the widgets more since my initial experimenting. I'll see what I can do with this extra info ;)
Also someone needs to make a standalone installer for GAE 0.4 for people who don't compile. I'm currently still using the 0.4 beta snapshot which is bolted to an old install thru the addons folder :confused: and is really buggy. The wierdest bug is that tilesets only load the first model in each set and align them all in the same way, kinda annoying as I'm trying to design a new tileset atm :O
-
Also someone needs to make a standalone installer for GAE 0.4 for people who don't compile. I'm currently still using the 0.4 beta snapshot which is bolted to an old install thru the addons folder :confused: and is really buggy. The wierdest bug is that tilesets only load the first model in each set and align them all in the same way, kinda annoying as I'm trying to design a new tileset atm :O
Ooops, don't know how I missed that.. Fixed. and a 0.4-beta2 with installer is on the way.
-
Is there any documentation for the widget layout code? I made a bit of a mess of the options tabbing using trial and error.
-
Is there any documentation for the widget layout code? I made a bit of a mess of the options tabbing using trial and error.
I have been meaning too, honest! :angel:
Looks like you did a pretty good job anyway, the buttons didn't have anchors set (see commit 6bdde7749) which was causing them to wander off when the frame was moved.
I found most of the errors I made were due do not setting SizeHints or Anchors, or setting them incorrectly.
Will get a overview on using CellStrips together, but I have mate visiting until Sunday... so I'll probably mostly have an xbox controller in my hands for the next couple of days ;), hopefully get it done on Sunday.