basis/ui/gadgets/packs/packs-docs.factor

   1 USING: ui.gadgets help.markup help.syntax generic kernel
   2 classes.tuple quotations ui.gadgets.packs.private
   3 ui.baseline-alignment ;
   4 IN: ui.gadgets.packs
   5
   6 ARTICLE: "ui-pack-layout" "Pack layouts"
   7 "Pack gadgets layout their children along a single axis."
   8 { $subsections pack }
   9 "Creating empty packs:"
  10 { $subsections
  11     <pack>
  12     <pile>
  13     <shelf>
  14 }
  15
  16 "For more control, custom layouts can reuse portions of pack layout logic:"
  17 { $subsections
  18     pack-pref-dim
  19     pack-layout
  20 } ;
  21
  22 HELP: pack
  23 { $class-description "A gadget which lays out its children along a single axis stored in the " { $snippet "orientation" } " slot. Can be constructed with one of the following words:"
  24 { $list
  25     { $link <pack> }
  26     { $link <pile> }
  27     { $link <shelf> }
  28 }
  29 "Packs have the following slots:"
  30 { $list
  31     { { $snippet "align" } " a rational number between 0 and 1, or " { $link +baseline+ } "; the alignment of gadgets along the axis perpendicular to the pack's orientation" }
  32     { { $snippet "fill" } " a rational number between 0 and 1, where 0 gives each gadget its preferred size and 1 fills the dimension perpendicular to the pack's orientation" }
  33     { { $snippet "gap" } " a pair of integers, the horizontal and vertical gap between children" }
  34 }
  35 "Custom gadgets can inherit from the " { $link pack } " class and implement their own " { $link pref-dim* } " and " { $link layout* } " methods, reusing pack layout logic by calling " { $link pack-pref-dim } " and " { $link pack-layout } "." } ;
  36
  37 HELP: pack-layout
  38 { $values { "pack" "a new " { $link pack } } { "sizes" "a sequence of pairs of integers" } }
  39 { $description "Lays out the pack's children along the " { $snippet "orientation" } " of the pack, with each gadget receiving its size from the corresponding index of the " { $snippet "sizes" } " sequence." }
  40 { $notes
  41     "This word is useful if you are writing your own layout gadget which inherits from " { $link pack } ". This allows you to reuse layout logic while computing gadget sizes using a custom procedure."
  42 } ;
  43
  44 HELP: <pack>
  45 { $values { "orientation" "an orientation specifier" } { "pack" "a new " { $link pack } } }
  46 { $description "Creates a new pack which lays out children with the given orientation, either " { $link horizontal } " or " { $link vertical } "." } ;
  47
  48 { <pack> <pile> <shelf> } related-words
  49
  50 HELP: <pile>
  51 { $values { "pack" "a new " { $link pack } } }
  52 { $description "Creates a new " { $link pack } " which lays out its children vertically." } ;
  53
  54 HELP: <shelf>
  55 { $values { "pack" "a new " { $link pack } } }
  56 { $description "Creates a new " { $link pack } " which lays out its children horizontally." } ;
  57
  58 HELP: pack-pref-dim
  59 { $values { "pack" pack } { "sizes" "a sequence of pairs of integers" } { "dim" "a pair of integers" } }
  60 { $description "Computes the preferred size of a pack, with each gadget receiving its size from the corresponding index of the " { $snippet "sizes" } " sequence." }
  61 { $notes
  62     "This word is useful if you are writing your own layout gadget which inherits from " { $link pack } ". This allows you to reuse layout logic while computing gadget sizes using a custom procedure."
  63 } ;
  64
  65 ABOUT: "ui-pack-layout"