HelpSource/Guides/GUI-Layout-Management.schelp

   1 title:: Layout Management
   2 summary:: Using layout classes to manage distribution of child views within parents
   3 categories:: GUI>Layout
   4 related:: Classes/QLayout, Classes/QLineLayout, Classes/QGridLayout
   5
   6 The purpose of layouts is to distribute the amount of space given to the view on which they are installed among the children of that view. Each subclass of QLayout has a specific pattern of space distribution (a line, a 2D grid, etc.). See their documentation for details.
   7
   8 A layout is installed on a view to manage the space the view occupies and distribute it among its child views. These child views can in turn have other layouts installed, managing the space given to them. But a layout can also manage other layouts directly - one layout can directly occupy a place in another layout's distribution pattern. A basic unit on which a layout operates is therefore abstractly called an item and can be a view or another layout.
   9
  10 note::
  11 While layouts can form a hierachy on their own, in terms of view hierarchy all views managed by those layouts are direct children of the view on which the top layout is installed.
  12 ::
  13
  14 The following is an example of a QVLayout, organizing a series of TextFields in a vertical line, and its last item is a QHLayout, organizing a series of Buttons in a horizontal line.
  15
  16 code::
  17 w = Window(bounds:Rect(200,200,200,200)).layout_(
  18         QVLayout(
  19                 TextField(), TextField(), TextField(),
  20                 QHLayout( Button(), Button(), Button() )
  21         )
  22 ).front;
  23 ::
  24
  25
  26 section:: How a layout does its job
  27
  28 A layout does its job by resizing and moving items within its operational space to form its specific distribution pattern, in accord with common sense of what makes the GUI useful and according to items' own size preferences and constraints.
  29
  30 subsection:: Dynamic updating
  31
  32 It works dynamically, meaning that it automatically redistributes the space whenever the amount of it changes (the view on which it is installed or the parent layout is resized), whenever items are added or removed and whenever the size constraints and preferences of items change. The latter may happen for instance when a property of a view that affects its appearance is changed.
  33
  34 subsection:: Automatic distribution policy
  35
  36 Items managed by a layout may be given unequal parts of space, proportional to their type and according to principles of GUI usability. According to their type, views possess intrinsic size constraints (e.g. minimum or maximum width or height) and preferences (whether they want to stay at a preferred size, or prefer to grow in one or another direction, etc.), which will be taken into account at space distribution.
  37
  38 A layout may also affect space distribution up the layout hierarchy - it will define its own constraints and preferences according to its distribution pattern as well as the sum of constraints and preferences of its items. Ultimately, this means that the user's ability to resize a window will be limited by size constraints determined on the basis of window's contents.
  39
  40 For example: in a QHLayout (a layout organizing items in a horizontal line) containing a Button and a TextField, the Button will be given a fixed amount of width according to the text it displays, while the TextField will be given all the width that is left. The other Button in the example code below will occupy all the width of the window, since there is no other item competing for that particular space. Note that both Button and TextField have an instrinsically fixed height and so their height never changes when resizing the window. The size constraints also limit the minimum size that the window can be resized to.
  41
  42 code::
  43 w = Window.new(bounds:Rect(100,100,300,80)).layout_(
  44         QVLayout (
  45                 QHLayout(
  46                         Button().states_([["Super"]]),
  47                         TextField().string_("Collider")
  48                 ),
  49                 Button().states_([["SuperCollider"]])
  50         )
  51 ).front;
  52 ::
  53
  54 section:: User customization
  55
  56 subsection:: Stretch factors
  57
  58 Layouts typically allow the user to override their default distribution policy by assigning stretch factors to items or aspects of the layout's distribution pattern.
  59
  60 code::
  61 w = Window.new(bounds:Rect(100,100,400,80)).layout_(
  62         QHLayout(
  63                 [Button().states_([["Super"]]), stretch:1],
  64                 TextField().string_("Collider")
  65         )
  66 ).front;
  67 ::
  68
  69 subsection:: Size constraints
  70
  71 Intrinsic size constraints of a view may also be overriden by the user by explicitely setting minimum and maximum width or height of the view. If the minimum size is larger than the maximum, the former takes priority.
  72
  73 code::
  74 w = Window.new(bounds:Rect(100,100,300,300)).layout_(
  75         QVLayout(
  76                 TextField().string_("Super").minHeight_(80),
  77                 TextField().string_("Collider").maxWidth_(150)
  78         )
  79 ).front;
  80 ::
  81
  82 subsection:: Alignment
  83
  84 The combination of size constraints and preferences of all items in a layout hierarchy may result in a larger amount of space given to an item than its own constraints allow. In that case the item will only grow up to its maximum allowed size, and its position within its extra available space may be controlled by user by assigning alignment to an item.
  85
  86 code::
  87 w = Window.new.layout_(
  88         QHLayout(
  89                 [Button.new.states_([["Super"]]), align:\bottom],
  90                 TextView(),
  91                 [Button.new.states_([["Collider"]]), align:\top]
  92         )
  93 ).front;
  94 ::
  95
  96
  97 section:: How view and layout hierachies affect each other
  98
  99 A layout starts to operate on the space that a view occupies from the moment it is installed on that view on. However, it will not automatically affect child views that where created before the layout was. For views to be managed by a layout they have to be created as children of a view after the layout has been installed on it, or they have to be explicitely inserted into the layout via layout's constructor or its instance methods for this purpose. These two ways are explained in the next two paragraphs.
 100
 101 When a view is created with another view as parent it will implicitely become subject to the management of the parent's layout - it will be inserted into the layout in some default way. However, layouts like QGridLayout have a complex space distribution pattern and so you will need to use their dedicated methods to specify exactly what place in the layout's distribution pattern a view will occupy, which is explained in the next paragraph.
 102
 103 A view can also be constructed with no parent given; after it is explicitely inserted into a layout via the layout's constructor or an instance method, it will automatically become a child of the view on which the layout is or will be installed. In case the layout occupies place directly in another layout, the view will become a child of the view on wich the topmost layout is installed.