From ef8d622b54f77521f32a2fc6b515964b521da7bc Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Thu, 5 Feb 2009 05:16:22 -0600 Subject: [PATCH] UI documentation and test fixes --- ...gle-docs.factor => rectangles-docs.factor} | 19 ++++++++---- basis/ui/commands/commands-docs.factor | 2 +- basis/ui/gadgets/frames/frames-docs.factor | 31 +++++++++++-------- basis/ui/gadgets/gadgets-docs.factor | 8 ++--- basis/ui/gadgets/grids/grids-docs.factor | 6 ++-- basis/ui/gadgets/packs/packs-docs.factor | 2 +- basis/ui/gadgets/worlds/worlds-docs.factor | 4 +-- basis/ui/gestures/gestures-docs.factor | 2 +- .../ui/tools/inspector/inspector-docs.factor | 4 +-- .../ui/tools/inspector/inspector-tests.factor | 4 +-- 10 files changed, 46 insertions(+), 36 deletions(-) rename basis/math/rectangles/{rectangle-docs.factor => rectangles-docs.factor} (82%) diff --git a/basis/math/rectangles/rectangle-docs.factor b/basis/math/rectangles/rectangles-docs.factor similarity index 82% rename from basis/math/rectangles/rectangle-docs.factor rename to basis/math/rectangles/rectangles-docs.factor index 90c70602bb..1d5c32d7d0 100644 --- a/basis/math/rectangles/rectangle-docs.factor +++ b/basis/math/rectangles/rectangles-docs.factor @@ -38,9 +38,13 @@ HELP: rect-intersect { $values { "rect1" rect } { "rect2" rect } { "newrect" "a new " { $link rect } } } { $description "Computes the intersection of two rectangles." } ; -HELP: intersects? -{ $values { "rect/point" "a " { $link rect } " or a pair of integers" } { "rect" rect } { "?" "a boolean" } } -{ $description "Tests if two rectangles (or a point and a rectangle, respectively) have a non-empty intersection." } ; +HELP: contains-rect? +{ $values { "rect1" rect } { "rect2" rect } { "?" "a boolean" } } +{ $description "Tests if two rectangles have a non-empty intersection." } ; + +HELP: contains-point? +{ $values { "point" "a pair of integers" } { "rect" rect } { "?" "a boolean" } } +{ $description "Tests if a rectangle contains a point." } ; HELP: { $values { "rect" "a new " { $link rect } } } @@ -56,9 +60,12 @@ ARTICLE: "math.rectangles" "Rectangles" { $subsection } { $subsection } { $subsection } -"More utility words for working with rectangles:" -{ $subsection offset-rect } +"Set-theoretic operations on rectangles:" { $subsection rect-intersect } -{ $subsection intersects? } ; +{ $subsection rect-union } +{ $subsection contains-rect? } +{ $subsection contains-point? } +"A utility word:" +{ $subsection offset-rect } ; ABOUT: "math.rectangles" diff --git a/basis/ui/commands/commands-docs.factor b/basis/ui/commands/commands-docs.factor index 78b82a345c..81a4096aab 100644 --- a/basis/ui/commands/commands-docs.factor +++ b/basis/ui/commands/commands-docs.factor @@ -110,7 +110,7 @@ HELP: command-string { $values { "gesture" "a gesture" } { "command" "a command" } { "string" string } } { $description "Outputs a string containing the command name followed by the gesture." } { $examples - { $example + { $unchecked-example "USING: io ui.commands ui.gestures ;" "IN: scratchpad" ": com-my-command ;" diff --git a/basis/ui/gadgets/frames/frames-docs.factor b/basis/ui/gadgets/frames/frames-docs.factor index 36c7feed97..52eef11d1c 100644 --- a/basis/ui/gadgets/frames/frames-docs.factor +++ b/basis/ui/gadgets/frames/frames-docs.factor @@ -1,5 +1,5 @@ USING: help.syntax help.markup ui.gadgets kernel arrays -quotations classes.tuple ui.gadgets.grids ; +quotations classes.tuple ui.gadgets.grids parser ; IN: ui.gadgets.frames ARTICLE: "ui-frame-layout" "Frame layouts" @@ -18,19 +18,24 @@ ARTICLE: "ui-frame-layout" "Frame layouts" { $subsection @bottom-left } { $subsection @bottom-right } ; -: $ui-frame-constant ( element -- ) - drop - { $description "Symbolic constant for a common input to " { $link grid-add } "." } print-element ; +<< -HELP: @center $ui-frame-constant ; -HELP: @left $ui-frame-constant ; -HELP: @right $ui-frame-constant ; -HELP: @top $ui-frame-constant ; -HELP: @bottom $ui-frame-constant ; -HELP: @top-left $ui-frame-constant ; -HELP: @top-right $ui-frame-constant ; -HELP: @bottom-left $ui-frame-constant ; -HELP: @bottom-right $ui-frame-constant ; +: ui-frame-constant + { $values { "value" pair } } parsed + { $description "Symbolic constant for a common input to " { $link grid-add } "." } parsed ; + parsing + +>> + +HELP: @center ui-frame-constant ; +HELP: @left ui-frame-constant ; +HELP: @right ui-frame-constant ; +HELP: @top ui-frame-constant ; +HELP: @bottom ui-frame-constant ; +HELP: @top-left ui-frame-constant ; +HELP: @top-right ui-frame-constant ; +HELP: @bottom-left ui-frame-constant ; +HELP: @bottom-right ui-frame-constant ; HELP: frame { $class-description "A frame is a gadget which lays out its children in a 3x3 grid. If the frame is enlarged past its preferred size, the center gadget fills up available room." diff --git a/basis/ui/gadgets/gadgets-docs.factor b/basis/ui/gadgets/gadgets-docs.factor index 878bcad39e..557c6f812c 100644 --- a/basis/ui/gadgets/gadgets-docs.factor +++ b/basis/ui/gadgets/gadgets-docs.factor @@ -1,6 +1,6 @@ USING: help.markup help.syntax opengl kernel strings classes.tuple classes quotations models math.rectangles -ui.gadgets.private ; +ui.gadgets.private accessors ; IN: ui.gadgets HELP: gadget-child @@ -30,9 +30,9 @@ HELP: user-input* { $contract "Handle free-form textual input while the gadget has keyboard focus." } ; HELP: children-on -{ $values { "rect/point" "a " { $link rect } " or a pair of integers" } { "gadget" gadget } { "seq" "a sequence of gadgets" } } -{ $contract "Outputs a sequence of gadgets which potentially intersect a rectangle or contain a point in the co-ordinate system of the gadget." } -{ $notes "This does not have to be an accurate intersection test, and simply returning " { $snippet "children" } " is a valid implementation. However, an accurate intersection test reduces the amount of work done when drawing this gadget if it is partially clipped and not all children are visible." } ; +{ $values { "rect" rect } { "gadget" gadget } { "seq" "a sequence of gadgets" } } +{ $contract "Outputs a sequence of gadgets which potentially intersect a rectangle in the co-ordinate system of the gadget." } +{ $notes "This does not have to be an accurate intersection test, and simply returning " { $link children>> } " is a valid implementation. However, an accurate intersection test reduces the amount of work done when drawing this gadget if it is partially clipped and not all children are visible." } ; HELP: pick-up { $values { "point" "a pair of integers" } { "gadget" gadget } { "child/f" { $maybe gadget } } } diff --git a/basis/ui/gadgets/grids/grids-docs.factor b/basis/ui/gadgets/grids/grids-docs.factor index c5efe82e8e..2d1af445a3 100644 --- a/basis/ui/gadgets/grids/grids-docs.factor +++ b/basis/ui/gadgets/grids/grids-docs.factor @@ -29,17 +29,17 @@ HELP: { $description "Creates a new " { $link grid } " gadget with the given children." } ; HELP: grid-child -{ $values { "grid" grid } { "i" "non-negative integer" } { "j" "non-negative integer" } { "gadget" gadget } } +{ $values { "grid" grid } { "pair" "a pair with shape " { $snippet "{ i j }" } } { "gadget" gadget } } { $description "Outputs the child gadget at the " { $snippet "i" } "," { $snippet "j" } "th position of the grid." } { $errors "Throws an error if the indices are out of bounds." } ; HELP: grid-add -{ $values { "grid" grid } { "child" gadget } { "i" "non-negative integer" } { "j" "non-negative integer" } } +{ $values { "grid" grid } { "child" gadget } { "pair" "a pair with shape " { $snippet "{ i j }" } } } { $description "Adds a child gadget at the specified location." } { $side-effects "grid" } ; HELP: grid-remove -{ $values { "grid" grid } { "i" "non-negative integer" } { "j" "non-negative integer" } } +{ $values { "grid" grid } { "pair" "a pair with shape " { $snippet "{ i j }" } } } { $description "Removes a child gadget from the specified location." } { $side-effects "grid" } ; diff --git a/basis/ui/gadgets/packs/packs-docs.factor b/basis/ui/gadgets/packs/packs-docs.factor index c9196d1274..c08f2c48f1 100644 --- a/basis/ui/gadgets/packs/packs-docs.factor +++ b/basis/ui/gadgets/packs/packs-docs.factor @@ -51,7 +51,7 @@ HELP: { $description "Creates a new " { $link pack } " which lays out its children horizontally." } ; HELP: pack-pref-dim -{ $values { "gadget" gadget } { "sizes" "a sequence of pairs of integers" } { "dim" "a pair of integers" } } +{ $values { "pack" pack } { "sizes" "a sequence of pairs of integers" } { "dim" "a pair of integers" } } { $description "Computes the preferred size of a pack, with each gadget receiving its size from the corresponding index of the " { $snippet "sizes" } " sequence." } { $notes "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." diff --git a/basis/ui/gadgets/worlds/worlds-docs.factor b/basis/ui/gadgets/worlds/worlds-docs.factor index 72f134c4ee..c948cb73b9 100644 --- a/basis/ui/gadgets/worlds/worlds-docs.factor +++ b/basis/ui/gadgets/worlds/worlds-docs.factor @@ -27,8 +27,8 @@ HELP: flush-gl-context { $description "Ensures all GL rendering calls made to an OpenGL context finish rendering to the screen. This word is called automatically by the UI after drawing a " { $link world } "." } ; HELP: focus-path -{ $values { "world" world } { "seq" "a new sequence" } } -{ $description "If the top-level window containing the world has focus, outputs a sequence of parents of the currently focused gadget, otherwise outputs " { $link f } "." } +{ $values { "gadget" gadget } { "seq" "a new sequence" } } +{ $description "If the gadget has focus, outputs a sequence of parents of the currently focused gadget, otherwise outputs " { $link f } "." } { $notes "This word is used to avoid sending " { $link gain-focus } " gestures to a gadget which requests focus on an unfocused top-level window, so that, for instance, a text editing caret does not appear in this case." } ; HELP: world diff --git a/basis/ui/gestures/gestures-docs.factor b/basis/ui/gestures/gestures-docs.factor index d1fab23f04..6ac7d4bcd5 100644 --- a/basis/ui/gestures/gestures-docs.factor +++ b/basis/ui/gestures/gestures-docs.factor @@ -184,7 +184,7 @@ HELP: gesture>string { $values { "gesture" "a gesture" } { "string/f" { $maybe string } } } { $contract "Creates a human-readable string from a gesture object, returning " { $link f } " if the gesture does not have a human-readable form." } { $examples - { $example "USING: io ui.gestures ;" "T{ key-down f { C+ } \"x\" } gesture>string print" "C+x" } + { $unchecked-example "USING: io ui.gestures ;" "T{ key-down f { C+ } \"x\" } gesture>string print" "C+x" } } ; HELP: left-action diff --git a/basis/ui/tools/inspector/inspector-docs.factor b/basis/ui/tools/inspector/inspector-docs.factor index af20462a09..0b8cb14cdc 100644 --- a/basis/ui/tools/inspector/inspector-docs.factor +++ b/basis/ui/tools/inspector/inspector-docs.factor @@ -8,9 +8,7 @@ $nl "The slot editor's text editing commands are standard; see " { $link "gadgets-editors" } "." $nl "The slot editor has a toolbar containing various commands." -{ $command-map slot-editor "toolbar" } -"The following commands are also available." -{ $command-map source-editor "word" } ; +{ $command-map slot-editor "toolbar" } ; ARTICLE: "ui-inspector" "UI inspector" "The graphical inspector provides functionality similar to the terminal inspector (see " { $link "inspector" } "), adding in-place editing of slot values." diff --git a/basis/ui/tools/inspector/inspector-tests.factor b/basis/ui/tools/inspector/inspector-tests.factor index 07ba5bc5c6..44e20fb0fd 100644 --- a/basis/ui/tools/inspector/inspector-tests.factor +++ b/basis/ui/tools/inspector/inspector-tests.factor @@ -1,6 +1,6 @@ IN: ui.tools.inspector.tests -USING: tools.test ui.tools.inspector math ; +USING: tools.test ui.tools.inspector math models ; \ must-infer -[ ] [ \ + com-edit-slot ] unit-test \ No newline at end of file +[ ] [ \ + com-edit-slot ] unit-test \ No newline at end of file