1. Jason McKesson
  2. LuaTools

Commits

Jason McKesson  committed 5c56e85

LuaGUI: Added AUI layers, and proper documentation for them.

  • Participants
  • Parent commits 476c1c1
  • Branches default

Comments (0)

Files changed (3)

File Docs/LuaGUI.xml

View file
  • Ignore whitespace
                 on the state of the application data.</para>
             <para>A panel is a more general-purpose container. Panels and toolbars can contain the
                 exact same elements. The difference between the lies in how the user can interact
-                with the two kinds of frame containers, and how they are laid out within the main
+                with the two kinds of frame containers and how they are laid out within the main
                 frame window.</para>
             <para>The frame containers are all attached to a specific side of the main window. This
                 side is noted by the <literal>direction</literal> attribute. This can be
                 <quote><literal>right</literal>,</quote>
                 <quote><literal>top</literal>,</quote> or
                 <quote><literal>bottom</literal>.</quote></para>
-            <para>These containers can be given a row number. If the row number for containers that
-                are on the same side match up, then the containers are stacked top-to-bottom for
-                containers on the left or right side and left-to-right for containers on the top and
-                bottom. They are stacked in the order they appear in the document. The row is
-                specified by the <literal>row</literal> attribute, and it can be any number 0 or
-                greater. Higher rows will be more towards the center than lower rows. If the
-                attribute is not specified, it defaults to 0.</para>
-            <para>When panels and toolbars are attached to the same side of a window, toolbars
-                always take precedence, regardless of order. Toolbars will be assigned first,
-                according to their rows. Then panels will be assigned according to their rows. Thus,
-                toolbars are always farther away from the center than panels. Toolbar rows and panel
-                rows are different; you cannot put a toolbar in a panel row or vice-versa. If you
-                use the same row number for a toolbar and a panel on the same side, the two will
-                still be beside each other.</para>
             <para>One frame container can be designated the center pane; this can only be given to a
                     <classname>panel</classname> container. This panel will have all of the room
                 that is left after all of the non-center containers are given their sizes. The
                 of the side of the window, and attach them to a different side. A panel can even be
                 made a free-standing window. Toolbars also have a tearaway strip that allows you to
                 move them.</para>
+            <para>The wxWidgets AUI manager gives unique names to all of the frame containers. LuaGUI
+                will set this name to be the value of <literal>title</literal> if that has been set.
+                If it has not, then the value of the panel's <literal>id</literal> will be the name.
+                Otherwise, an arbitrary name based on the order of creation will be assigned. These
+                names can be used to identify panels and toolbars, so that you can redisplay them if
+                the user hides them.</para>
             <para>If you want to position panels or toolbars, you may use the
                     <literal>gripper</literal> attribute. This attribute defaults to
                         <quote><literal>true</literal></quote>; if it is
                     use wxLua APIs to prevent it from happening or restore the toolbar when it
                     does.</para>
             </note>
+            <formalpara>
+                <title>Frame Container Spacing</title>
+                <para>Frame containers attached to the side of a window will take up variable space
+                    either horizontally or vertically (controlled by a bar the user can resize), but
+                    the space they take up in the other direction is fixed based on the space
+                    available. So frame containers attached to the top or bottom will be resizable
+                    vertically, and containers attached to the left or right will be resizable
+                    horizontally.</para>
+            </formalpara>
+            <para>How much space is taken in the fixed direction depends on the arrangement of other
+                frame containers. After all, if you have a container docked on the left and a
+                container on the bottom, which one owns the overlap area at the bottom left? If two
+                containers are attached to the same direction, which one goes on top? Or does one go
+                on top at all?</para>
+            <para>There are two attributes that control these values: <literal>layer</literal> and
+                    <literal>row</literal>. The <literal>layer</literal> attribute decides which
+                container gets priority in space conflicts. Layer 0 represents the closest region to
+                the center, so higher values will get space first. So if you are attaching
+                containers to the left and bottom, if you want the left container to span the whole
+                top-to-bottom area, then you give it a higher layer than the one on the bottom. The
+                    <literal>layer</literal> value cannot be less than 0.</para>
+            <para>If the <literal>layer</literal> is not specified, then a layer will be assigned
+                arbitrarily. If two frame containers have the same layer, but are attached to
+                different sides, the way conflicts are resolved is likewise arbitrary.</para>
+            <para>It is possible for two frame containers to have the same layer and be attached to
+                the same side. In this case, this states that you want the containers to take up the
+                same space. The two (or more) will be stacked top-to-bottom or left-to-right.</para>
+            <para>The <literal>row</literal> attribute determines the ordering of stacked frame
+                containers. Row 0 represents the left or top-most area. Row 1 is the next one to the
+                right or below. If the attribute is not specified, then the order will be
+                arbitrarily assigned.</para>
             <para>Another important difference between panels and toolbars is that panels are
                 resizeable. Two panels adjacent to each other will have a resizing bar between them.
                 This is true for the center panel as well. Because of this, panels only need one
-                size specified: the size in the dimension that they expand on. The other size is
-                automatic; panels are stretched to fill the available space. Toolbars have an innate
-                size that must be specified. And no matter where the toolbar is placed, it will be
-                of that size. Any empty space will be the window's background color.</para>
+                size specified: the size in the dimension that they expand on (though the other
+                dimension will be used if you tear the window away). The other size is automatic;
+                panels are stretched to fill the available space. Toolbars have an innate size that
+                must be specified. And no matter where the toolbar is placed, it will be of that
+                size. Any empty space will be the window's background color.</para>
             <para>Panels can have a maximize button. This button causes the panel to take up all of
                 the available area, including the center pane (but not covering any toolbars). To
                 allow a panel to have this button, use the <literal>maximizebutton</literal>

File Docs/luagui.rnc

View file
  • Ignore whitespace
         lg.aui.title.attribute?,
         (lg.aui.direction.attribute | lg.aui.centerpane.attribute),
         lg.aui.row.attribute?,
+        lg.aui.layer.attribute?,
         lg.aui.maximizebutton.attribute?,
         lg.aui.floatable.attribute?,
         lg.aui.resizable.attribute?
     lg.aui.toolbar.attlist =
         lg.aui.direction.attribute,
         lg.aui.row.attribute?,
+        lg.aui.layer.attribute?,
         lg.aui.resizable.attribute?
 
     lg.std.window.attlist =
         attribute direction { "right" | "left" | "top" | "bottom" }
     
     lg.aui.row.attribute =
-        ## ... I don't know.
+        ## Specifies the order for panes attached to the same layer.
         attribute row { xsd:nonNegativeInteger }
     
+    lg.aui.layer.attribute =
+        ## Determines how close the attached pane is to the center.
+        attribute layer { xsd:nonNegativeInteger }
+    
     lg.aui.centerpane.attribute =
         ## Puts this container in the center of the window. Only one container can have this,
         ## and it cannot be used with "direction".

File Tools/LuaGUI.lua

View file
  • Ignore whitespace
 	bHasProp, prop = currNode:GetPropVal("row");
 	if(bHasProp) then info:Row(tonumber(prop)) end;
 	
+	bHasProp, prop = currNode:GetPropVal("layer");
+	if(bHasProp) then info:Layer(tonumber(prop)) end;
+	
 	if(GetNodeBoolProp(currNode, "centerpane", false)) then info:CenterPane() end;
 	if(GetNodeBoolProp(currNode, "maximizebutton", false)) then info:MaximizeButton() end;