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

   1 USING: ui.gadgets help.markup help.syntax generic kernel
   2 classes.tuple quotations ;
   3 IN: ui.gadgets.packs
   4
   5 ARTICLE: "ui-pack-layout" "Pack layouts"
   6 "Pack gadgets layout their children along a single axis."
   7 { $subsection pack }
   8 "Creating empty packs:"
   9 { $subsection <pack> }
  10 { $subsection <pile> }
  11 { $subsection <shelf> }
  12
  13 "For more control, custom layouts can reuse portions of pack layout logic:"
  14 { $subsection pack-pref-dim }
  15 { $subsection pack-layout } ;
  16
  17 HELP: pack
  18 { $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:"
  19 { $list
  20     { $link <pack> }
  21     { $link <pile> }
  22     { $link <shelf> }
  23 }
  24 "Packs have the following slots:"
  25 { $list
  26     { { $snippet "align" } " a rational number between 0 and 1, the alignment of gadgets along the axis perpendicular to the pack's orientation" }
  27     { { $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" }
  28     { { $snippet "gap" } " a pair of integers, the horizontal and vertical gap between children" }
  29 }
  30 "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 } "." } ;
  31
  32 HELP: pack-layout
  33 { $values { "pack" "a new " { $link pack } } { "sizes" "a sequence of pairs of integers" } }
  34 { $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." }
  35 { $notes
  36     "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."
  37 } ;
  38
  39 HELP: <pack>
  40 { $values { "orientation" "an orientation specifier" } { "pack" "a new " { $link pack } } }
  41 { $description "Creates a new pack which lays out children along the given axis. Children are laid out vertically if the orientation is " { $snippet "{ 0 1 }" } " and horizontally if the orientation is " { $snippet "{ 1 0 }" } "." } ;
  42
  43 { <pack> <pile> <shelf> } related-words
  44
  45 HELP: <pile>
  46 { $values { "pack" "a new " { $link pack } } }
  47 { $description "Creates a new " { $link pack } " which lays out its children vertically." } ;
  48
  49 HELP: <shelf>
  50 { $values { "pack" "a new " { $link pack } } }
  51 { $description "Creates a new " { $link pack } " which lays out its children horizontally." } ;
  52
  53 HELP: pack-pref-dim
  54 { $values { "gadget" gadget } { "sizes" "a sequence of pairs of integers" } { "dim" "a pair of integers" } }
  55 { $description "Computes the preferred size of a pack, with each gadget receiving its size from the corresponding index of the " { $snippet "sizes" } " sequence." }
  56 { $notes
  57     "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."
  58 } ;
  59
  60 ABOUT: "ui-pack-layout"