Div Text
Div-Text is a string used to specify a rule of layout how child windows are sized/placed within its parent window.
Basic Concept
Attributes of Field
Advanced Fields
A basic concept is field. It represents an area in the window.
Define a field
<>
It represents the whole area of the window.
Define fields
<><>
The two fields represent left area and right area of the window.
Fields can be nested, one outter field and three nested fields
<<><><>>
The three nested fields represent left area, center area and right area of the window.
Root field. There is an implicit root field, all the fields defined by Div-Text are children of root field.
[1, 2, 3]
Define an array that has 1, 2 and 3 three elements.
[1, 2, 3, repeated]
The keyword repeated indicates the array is countless. Its elements are 1,2,3,1,2,3,1,2,3,...
[1, 2, variable, 3]
The keyword variable is a unspecified value, it is interpreted differently by different attributes of the field(arrange, gap, margin). Refer to the attributes for more details.
If a field has a name, the field can be operated. The name is a field's identifier.
<id_you_specify> A named field can be addressed by using following statement.
place.field("id_you_specify");
//or
place["id_you_specify"];Specifies a field that all its nested fields and contents are positioned vertically. If vert is not specified, the nested fields and contents are positioned horizontally. For example.
place plc{fm}; //fm is an instance of nana::form
plc.div("<abc>"); //name abc for the field.
plc["abc"]<<btn0<<btn1<<btn2<<btn3; //These buttons are child widgets of fm.
plc.collocate();
//Replace the line
plc.div("<abc>");
//with
plc.div("<vert abc>");Then, the buttons are positioned vertically.
Specifies the width or height of a field. It depends on the type of its owner field. If the owner field is vertical, the weight indicates the width. If the owner field is horizontal, the weight indicates the height. The weight supports different units type.
<abc><weight=200 def>
If the width of form is 1000px, the field abc is 800px and def is 200px.
<abc><weight=60% def><ghi>
If the width of form is 1000px, the field abc is 200px, def is 600px and ghi is 200px.
Specifies the minimized/maximized weight of a field. When specifies the weight and min/max for a field at same time, the weight attribute only works for initializing the field.
Specifies weight for a group of widgets.
place.div("<abc arrange=[50,100]>");
place["abc"]<<btn0<<btn1;
If the number of widgets in the field is larger than the number of elements in arrange, the extra widgets will be resized by place.
If the variable is given in the arrange's array, it indicates a corresponding widget's weight is not specified, the widget will be resized by place.
place.div("fld arrange=[30,variable,60,repeated]"); //Refer the arrange section for keyword repeated.
std::vector<std::unique_ptr<button>> buttons;
for (int i = 0; i < 6; ++i)
{
buttons.emplace_back(std::make_unique<button>(fm.handle(), std::to_string(i)));
place["fld"] << *buttons.back();
}
place.collocate();
After enlarging, the width of widget 1 and 4 is changed by the place, because their correspending weight in arrange is variable.
Gap is used to specify a space between widgets, in pixels. The value of gap is an array.
place.div("<fld gap=[5,10,20]>");
for (int i = 0; i < 5; ++i)
{
buttons.emplace_back(std::make_unique<button>(fm.handle(), std::to_string(i)));
place["fld"] << *buttons.back();
}
place.collocate();
As you see, there are 3 gaps.
The gap can be assigned with an integral number, the gap interprets the integral number as an repeated array.
<gap=5> is interpreted as <gap=[5,repeated]>
If the element of gap's array is variable, the variable here will be interpreted as zero.
<grid=[3,3] gap=5>
When a field is a grid, the place only employs the first element of gap, other elements are ignored.
Specifies the whitespace at edges of a field. It can have from 1 to 4 values.
<margin=[10,20,30,40]>
top margin = 10, right margin = 20, bottom margin = 30, left margin = 40
<margin=[10,20,30]>
top margin = 10, right margin = 20, bottom margin = 30
<margin=[10,20]>
top and bottom margin = 10, left and right margin = 20
<margin=[10]>
top margin = 10
<margin=20>
top, right, bottom and left margin = 20
The varible in margin is interpreted as zero.
When a field is specified with dock, its child fields are dockable. These child fields called dockable field. A widget that attaches to a dockable field can be docked inside the dock field or floated on the desktop. The dockable field can't have a child field.
Dockpane is a library maintained internal window which attaches to the dockable field, it has a title bar and a close button, it is the parent of user widgets which attaches to dockable field.
//Create a dock field that has one dockable field.
place.div("<dock<dockableA>>");
//Create a dockpane factory that creates a button.
place.dock<button>("dockableA", "f", std::string{"Button"});
//Create a dockpane
place.dock_create("f");
Specifies a field that positions its widgets as a grid. The value of grid is an array with 2 integral numbers.
<grid=[3,2]>
It defines a grid field that has 3 columns and 2 rows.
place.div("<fld grd=[3,3]>");
std::vector<std::unique_ptr<button>> buttons;
for(int i = 0; i < 9; ++i)
{
buttons.emplace_back(std::make_unique<button>(fm.handle(), "Button"));
place["fld"] << *buttons.back();
}
The grid lays the buttons out from left to right, top to bottom.
The grid is like to divide the field into blocks. The collapse can merge the blocks, it has 4 parameters
<grid=[3,2] collapse(0,1,3,1)>
These 4 parameters indicate (left, top, columns, rows), collapse merges 3 blocks in that area.
//Merges the 3 blocks in row 2.
place.div("<fld grid=[3,2] collapse(0,1,3,1)>");
std::vector<std::unique_ptr<button>> buttons;
for(int i = 0; i < 4; ++i)
{
buttons.emplace_back(std::make_unique<button>(fm.handle(), "Button"));
place["fld"] << *buttons.back();
}
A grid can be specified with more than one collapse, but overlapped collapse will be ignored.
<grid=[3,2] collapse(0,1,3,1) collapse(1,1,2,2)>
The second collapse is ignored, because of overlap with the first one.
<a>|<b>
Sets a splitter bar between field a and b. When a number is specified behand |, it stands for an initial weight of right field.
<a>|30<b>
Field b's weight is 30px.
<a>|30%<b>
If the number is a percentage, it indicates the percentage of sum of left and right field. The weight of field b is (weight of a + weight of b) * 30%. Note: the initial weight attribute will be ignored if the weight is specified for right field, for example.
<a>|30%<b weight=20>
The 30% is ignored because of b's weight=20.