diff --git a/src/gui/engine.hpp b/src/gui/engine.hpp index efa4d3cdc..2e2f52247 100644 --- a/src/gui/engine.hpp +++ b/src/gui/engine.hpp @@ -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 ( ... ) 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 (
...
, place children within) + +WTYPE_RIBBON_GRID "ribbon_grid" +Shows a scrollable grid of icons. NOT of spawn type (), 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
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
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
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 diff --git a/src/gui/screen.cpp b/src/gui/screen.cpp index 76e5056f5..437b192b9 100644 --- a/src/gui/screen.cpp +++ b/src/gui/screen.cpp @@ -80,7 +80,11 @@ void Screen::calculateLayout(ptr_vector& 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; diff --git a/src/gui/widget.cpp b/src/gui/widget.cpp index 38799d213..8ac60bb55 100644 --- a/src/gui/widget.cpp +++ b/src/gui/widget.cpp @@ -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];