Added extensive documentation of my GUI engine to gui/engine.hpp + various minor fixes
git-svn-id: svn+ssh://svn.code.sf.net/p/supertuxkart/code/main/branches/irrlicht@3386 178a84e3-b1eb-0310-8ba1-8eac791a3b58
This commit is contained in:
auria
parent
57ce9a3879
commit
d6bb49e492
@ -1,3 +1,152 @@
|
||||
/*
|
||||
+---------+
|
||||
+ Widgets +
|
||||
+---------+
|
||||
|
||||
_______________________________________________________
|
||||
Internal constant Name in XML files
|
||||
_______________________________________________________
|
||||
WTYPE_RIBBON "ribbon", "buttonbar", "tabs"
|
||||
appears an horizontal bar containing elements laid in a row, each being and icon and/or a label
|
||||
the "ribbon" subcategory will behave a bit like a radio button group, i.e. one element must selected.
|
||||
events are triggered as soon as a choice is selected (can be simply by hovering).
|
||||
the "buttonbar" subcategory treats children buttons as action buttons, which means they can't have a
|
||||
'selected' state, only focused or not (i.e. there is no selection that remains if you leave this area).
|
||||
events are triggered only on enter/fire.
|
||||
the "tabs" subcategory will show a tab bar. behaviour is same as normal ribbon, only looks are different.
|
||||
Ribbon widgets are of spawn type (<ribbon> ... </ribbon>) and may contain icon-buttons or buttons as children.
|
||||
Property PROP_SQUARE can be set to tell the engine if the ribbon's contents are rectangular or not (this will
|
||||
affect the type of highlighting used)
|
||||
|
||||
WTYPE_SPINNER "spinner"
|
||||
A spinner component (lets you choose numbers). Sprecify PROP_MIN_VALUE and PROP_MAX_VALUE to have control
|
||||
over values (default will be from 0 to 10). You can specify an icon; then, include a sprintf format string
|
||||
like %i in the name, and at runtime the current number will be inserted into the given name to find the
|
||||
right file for each possible value the spinner can take.
|
||||
|
||||
WTYPE_BUTTON "button"
|
||||
A plain text buttons.
|
||||
|
||||
WTYPE_GAUGE "gauge"
|
||||
A control that lets users choose a value between a maximal and a minimal value, with a graphical filling bar.
|
||||
|
||||
WTYPE_ICON_BUTTON "icon-button", "icon"
|
||||
A component with an image, and optional text to go under it. The "icon" variant will have no border and will not
|
||||
be clickable. PROP_ICON is mandatory for this component.
|
||||
|
||||
WTYPE_CHECKBOX "checkbox"
|
||||
A checkbox. Not used at the moment.
|
||||
|
||||
WTYPE_LABEL "label"
|
||||
A plain label. Supports properties PROP_WORD_WRAP and PROP_TEXT_ALIGN.
|
||||
|
||||
WTYPE_SPACER "spacer"
|
||||
Some blank space; not visible on screen.
|
||||
|
||||
WTYPE_DIV "div"
|
||||
A container. Does not do much on itself, but is useful to lay out children automatically. Divs can be nested.
|
||||
Supports property PROP_LAYOUT. Of spawn type (<div>...</div>, place children within)
|
||||
|
||||
WTYPE_RIBBON_GRID "ribbon_grid"
|
||||
Shows a scrollable grid of icons. NOT of spawn type (<ribbon_grid .../>), contents must be programmatically set at runtime.
|
||||
Property PROP_SQUARE can be set to tell the engine if the ribbon's contents are rectangular or not (this will
|
||||
affect the type of highlighting used). Supports an optional label at the bottom if PROP_TEXT is set.
|
||||
PROP_CHILD_WIDTH and PROP_CHILD_HEIGHT are mandatory (so at least aspect ratio of elements that will later be added isk nown)
|
||||
An interesting aspect of PROP_CHILD_WIDTH and PROP_CHILD_HEIGHT is that you can use them to show textures to any aspect ratio
|
||||
you want (so you can e.g. save textures to a power-of-two size like 256x256, but then show it in 4:3 ratio).
|
||||
|
||||
WTYPE_MODEL_VIEW "model"
|
||||
Displays a model. Currently incomplete. Contents must be set programmatically.
|
||||
|
||||
WTYPE_LIST "list"
|
||||
Displays a list. Currently incomplete. Contents must be set programmatically.
|
||||
|
||||
+------------+
|
||||
+ Properties +
|
||||
+------------+
|
||||
|
||||
_______________________________________________________
|
||||
Internal constant Name in XML files
|
||||
_______________________________________________________
|
||||
|
||||
PROP_ID "id"
|
||||
gives a unique internal name to each object using this property. It will be
|
||||
used in events callbacks to determine what action occurred. Can be omitted
|
||||
on components that do not trigger events (e.g. labels)
|
||||
|
||||
PROP_TEXT "text"
|
||||
gives text (a label) to the widget where supported.
|
||||
|
||||
PROP_ICON "icon"
|
||||
give an icon to the widget. Property contents is the path to the file, relative
|
||||
relative to the /data directory of STK.
|
||||
|
||||
PROP_TEXT_ALIGN "text_align"
|
||||
used exclusively by label components. Value can be "right" or "center" (left used if not specified).
|
||||
PROP_WORD_WRAP "word_wrap"
|
||||
used exclusively by label components. Value can be "true" to indicate that long text should spawn on
|
||||
multiple lines.
|
||||
|
||||
PROP_MIN_VALUE "min_value"
|
||||
PROP_MAX_VALUE "max_value"
|
||||
used to specify a minimum and maximum value for numeric widgets (c.f. spinner)
|
||||
|
||||
PROP_X "x"
|
||||
PROP_Y "y"
|
||||
sets the position (location) of a widget, relative to its parent (container <div> or screen if none).
|
||||
A plain number will be interpreted as an aabsolute position in pixels. A '%' sign may be added to the
|
||||
given number to mean that the location is specified in terms of a percentage of parent size (parent size
|
||||
means the parent <div> or the whole screen if none). A negative value can also be passed to start coordinate
|
||||
from right and/or bottom, instead of starting from top-left corner as usual.
|
||||
Note that in many cases, it is not necessary to manually a position. Div layouts will often manage that
|
||||
for you (see PROP_LAYOUT). Other widgets will also automativally manage the position and size of their children,
|
||||
for instance ribbons.
|
||||
|
||||
PROP_WIDTH "width"
|
||||
PROP_HEIGHT "height"
|
||||
give dimensions to the widget. A plain number will be interpreted as an aabsolute position in pixels.
|
||||
A '%' sign may be added to the given number to mean that the size is specified in terms of a percentage
|
||||
of parent size (parent size means the parent <div> or the whole screen if none).
|
||||
Note that in many cases, it is not necessary to manually a size. Div layouts will often manage that
|
||||
for you (see PROP_LAYOUT). In addition, sizes are automatically calculated for widgets made of icons
|
||||
and/or text like labels and plain icons. Other widgets will also automativally manage the position and
|
||||
size of their children, for instance ribbons.
|
||||
|
||||
|
||||
PROP_CHILD_WIDTH "child_width"
|
||||
PROP_CHILD_HEIGHT "child_height"
|
||||
Used exclusively by the ribbon grid widget. See docs for this widget above.
|
||||
|
||||
PROP_GROW_WITH_TEXT "grow_with_text"
|
||||
Reserved, but currently unimplemented and unused.
|
||||
|
||||
PROP_LAYOUT "layout"
|
||||
Valid on 'div' containers. Value can be "horizontal-row" or "vertical-row". This means x and y coordinates
|
||||
of all children will automatically be calculated at runtime, so they are laid in a row. Width and height can
|
||||
be set absolutely as usual, but can also be determined dynamically according to available screen space. Also
|
||||
see PROP_ALIGN and PROP_PROPORTION to known more about controlling layouts. Note that all components within a
|
||||
layed-out div will ignore all x/y coordinates you may give them as parameter.
|
||||
|
||||
PROP_ALIGN "align"
|
||||
For widgets located inside a vertical-row layout div. Value can be "left", "center" or "right". Determines how
|
||||
the x coord of the widget will be determined.
|
||||
|
||||
PROP_PROPORTION "proportion"
|
||||
Helps determining widget size dynamically (according to available screen space) in layed-out divs. In a
|
||||
vertical row layout, proportion sets the height of the item. In an horizontal row, it sets the width of
|
||||
the item. Proportions are always evaluated relative to the proportions of other widgets in the same div.
|
||||
If one div contains 4 widgets, and their proportions are 1-2-1-1, it means the second must take twice as
|
||||
much space as the 3 others. In this case, 10-20-10-10 would do the exact same effect. 1-1-1-1 would mean
|
||||
all take 1/4 of the available space. Note that it is allowed to mix absolute widget sizes and proportions;
|
||||
in this case, widgets with absolute size are evaluated first, and the dynamically-sized ones split the
|
||||
remaining space according to their proportions.
|
||||
|
||||
PROP_SQUARE "square_items"
|
||||
Valid on Ribbons or RibbonGrids. Can be "true" (omitting it means "false"). Indicates whether the contents
|
||||
use rectangular icons (this will affect the type of focus/highlighting used)
|
||||
|
||||
*/
|
||||
|
||||
#ifndef HEADER_ENGINE_HPP
|
||||
#define HEADER_ENGINE_HPP
|
||||
|
||||
|
||||
@ -80,7 +80,11 @@ void Screen::calculateLayout(ptr_vector<Widget>& widgets, Widget* parent)
|
||||
horizontal = true;
|
||||
else if(!strcmp("vertical-row", layout_name.c_str()))
|
||||
horizontal = false;
|
||||
else break;
|
||||
else
|
||||
{
|
||||
std::cerr << "Unknown layout name : " << layout_name.c_str() << std::endl;
|
||||
break;
|
||||
}
|
||||
|
||||
const int w = parent->w, h = parent->h;
|
||||
|
||||
|
||||
@ -168,6 +168,7 @@ void Widget::readCoords(Widget* parent)
|
||||
if(abs_h > -1) this->h = abs_h;
|
||||
else if(percent_h > -1) this->h = parent_h*percent_h/100;
|
||||
}
|
||||
else if(texture_h > -1 && label_h > -1) this->h = texture_h + label_h;
|
||||
else if(texture_h > -1) this->h = texture_h;
|
||||
else if(label_h > -1) this->h = label_h;
|
||||
}
|
||||
@ -777,7 +778,7 @@ void RibbonGridWidget::add()
|
||||
IconButtonWidget* icon = new IconButtonWidget();
|
||||
icon->m_properties[PROP_ICON]="gui/track_random.png";
|
||||
|
||||
// set size to get proper ratio (as most textures are saved sccaled down to 256x256)
|
||||
// set size to get proper ratio (as most textures are saved scaled down to 256x256)
|
||||
icon->m_properties[PROP_WIDTH] = m_properties[PROP_CHILD_WIDTH];
|
||||
icon->m_properties[PROP_HEIGHT]= m_properties[PROP_CHILD_HEIGHT];
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user