From 192a8fc6407256d4beb6256d70ab0778468a773e Mon Sep 17 00:00:00 2001 From: slava Date: Mon, 9 Oct 2006 18:51:09 +0000 Subject: [PATCH] Documentation updates, help link operations fix, list mouse gestures --- TODO.FACTOR.txt | 4 -- doc/handbook/handbook.facts | 5 ++- doc/handbook/ui/tools.facts | 58 ++++++++++++++++++++++--- library/syntax/parser.factor | 2 +- library/ui/gadgets/lists.factor | 14 +++++- library/ui/gadgets/presentations.factor | 2 +- library/ui/tools/help.factor | 10 ----- library/ui/tools/listener.factor | 10 ++++- library/ui/tools/operations.factor | 10 +++++ 9 files changed, 86 insertions(+), 29 deletions(-) diff --git a/TODO.FACTOR.txt b/TODO.FACTOR.txt index 5da07cd681..371a8a3f20 100644 --- a/TODO.FACTOR.txt +++ b/TODO.FACTOR.txt @@ -1,10 +1,6 @@ - auto-invoke code gc - fix alien-callback/SEH bug on win32 -- list mouse gestures - maybe simplify list into displaying list a sequence of strings -- nested presentation mouse over is not right -- ui quick start doc -- document the UI workspace entirely! - x11: scroll up/down wiggles caret - slider needs to be modelized - some way of intercepting all gestures diff --git a/doc/handbook/handbook.facts b/doc/handbook/handbook.facts index fe728891d4..c116f1e56f 100644 --- a/doc/handbook/handbook.facts +++ b/doc/handbook/handbook.facts @@ -10,11 +10,12 @@ ARTICLE: "handbook" "Factor documentation" { "The basic unit of code, corresponding to a \"function\" in other languages, is called a " { $emphasis "word" } " in Factor." } { "Word take inputs from the stack, and leave output values on the stack. This is documented in a " { $emphasis "stack effect declaration" } ", for example " { $snippet "( x y -- z )" } " denotes that a word takes two inputs, with " { $snippet "y" } " at the top of the stack, and returns one output. See " { $link "effect-declaration" } " for details." } { "You can load source files with " { $link run-file } ":" - { $code "\"examples/lcd.factor\" run-file" } } - { { "You can load " { $snippet "contrib/" } " modules with " { $link require } ":" } + { $code "\"hello-world.factor\" run-file" } } + { { "You can load modules from " { $snippet "contrib/" } " and " { $snippet "examples/" } " with " { $link require } ":" } { $code "\"contrib/httpd\" require" } } { { $link .s } " prints the contents of the stack." } { { $link . } " prints the object at the top of the stack." } + { "If you are reading this from the Factor UI, take a look at " { $link "ui-tools" } "." } } { $heading "Cookbook" } { $subsection "cookbook-syntax" } diff --git a/doc/handbook/ui/tools.facts b/doc/handbook/ui/tools.facts index c76c2a0c30..e055225e13 100644 --- a/doc/handbook/ui/tools.facts +++ b/doc/handbook/ui/tools.facts @@ -1,11 +1,29 @@ USING: gadgets gadgets-listener gadgets-browser gadgets-help -gadgets-walker gadgets-dataflow gadgets-workspace help -gadgets-panes gadgets-text listener ; +gadgets-presentations gadgets-walker gadgets-dataflow +gadgets-workspace help gadgets-panes gadgets-text listener +definitions prettyprint io parser ; + +ARTICLE: "ui-presentations" "Presentations in the UI" +"A " { $emphasis "presentation" } " is a graphical view of an object which is directly linked to the object in some way. The help article links you see in the documentation browser are presentations; and if you " { $link see } " a word in the UI listener, all words in the definition will themselves be presentations." +$terpri +"When you move the mouse over a presentation, it is highlighted with a rectangular border and a short summary of the object being presented is shown in the status bar (the summary is produced using the " { $link summary } " word)." +$terpri +"Clicking a presentation with the left mouse button invokes a default operation, which usually views the object in some way. For example, clicking a presentation of a word jumps to the word definition in the " { $link "ui-browser" } "." +$terpri +"Clicking and holding the right mouse button on a presentation displays a popup menu listing available operations." +$terpri +"Presentation gadgets can be constructed directly using the " { $link } " word, and they can also be written to " { $link pane } " gadgets using the " { $link write-object } " word." ; ARTICLE: "ui-listener" "UI listener" -"The graphical listener is based around the terminal listener (" { $link "listener" } ") and adds an input history and clickable output presentations (" { $link "styles" } ")." +"The graphical listener is based around the terminal listener (" { $link "listener" } ") and adds the following features:" +{ $list + "Input history" + "Completion" + { "Clickable presentations (see " { $link "ui-presentations" } ")" } +} +"The below completion commands display a gadget at the bottom of the listener, known as the mini-buffer. Typing more text narrows down the list of available items. The " { $snippet "UP" } " and " { $snippet "DOWN" } " arrow keys shift the selection between listed items, and the " { $snippet "RETURN" } " key invokes a default operation for the selected item." { $commands listener-gadget } -"The word commands appearing in the below list operate on the token at the caret position in the input area. The quotation commands operate on the entire contents of the input area. The walker and dataflow tools are invoked using these commands." +"The below word commands operate on the token at the caret position in the input area. The quotation commands operate on the entire contents of the input area." { $commands interactor } "Listeners are instances of " { $link listener-gadget } ". The listener consists of an output area (instance of " { $link pane } "), an input area (instance of " { $link interactor } "), and a stack display kept up to date using a " { $link listener-hook } "." ; @@ -34,12 +52,38 @@ $terpri { $commands dataflow-gadget } "Dataflow viewers are instances of " { $link dataflow-gadget } "." ; -ARTICLE: "ui-tools" "Development tools in the UI" -"UI development tools are integrated into a single-window " { $emphasis "workspace" } ". Multiple workspaces can be open at once, and keyboard commands are provided for switching between tools." +ARTICLE: "ui-cocoa" "Functionality specific to Mac OS X" +"On Mac OS X, the Factor UI offers additional features which integrate with this operating system." +$terpri +"First, a standard Mac-style menu bar is provided, which offers the bare minimum of what you would expect from a Mac OS X application." +$terpri +"Dropping a source file onto the Factor icon in the dock runs the source file in the listener." +$terpri +"If you install " { $strong "Factor.app" } " in your " { $strong "Applications" } " folder, then other applications will be able to call Factor via the System Services feature. For example, you can select some text in " { $strong "TextEdit.app" } ", then invoke the " { $strong "TextEdit->Services->Factor->Evaluate Selection" } " menu item, which will replace the selected text with the result of evaluating it in Factor." + +; + +ARTICLE: "ui-tools" "UI development tools" +"The Factor development environment can seem rather different from what you are used to, however it is very simple and powerful." +$terpri +"To take full advantage of the UI, you should be using a supported text editor, and load the correct editor integration module. See " { $link edit } "." +$terpri +"The following is an example of a typical session with the UI which should give you a taste of its power:" +{ $list + { "You decide to refactor some code, and move a few words from a source file you have already loaded, into a new source file." } + { "You press " { $snippet "C+e" } " in the listener, which displays a gadget where you can type part of a loaded file's name, and then press " { $snippet "RETURN" } " when the correct completion is highlighted. This opens the file in your editor." } + { "You refactor your words, move them to a new source file, and load the new file using " { $link run-file } "." } + { "Interactively testing the new code reveals a problem with one particular code snippet, so you enter it in the listener's input area, and press " { $snippet "C+A+w" } " to invoke the single stepper." } + { "Single stepping through the code makes the problem obvious, so you right-click on a presentation of the broken word in the stepper, and choose " { $strong "Edit" } " from the resulting popup menu." } + { "After fixing the problem in the source editor, you right click on the word in the stepper and invoke " { $strong "Reload" } "." } +} +"All development tools are integrated into a single-window " { $emphasis "workspace" } ". Multiple workspaces can be open at once, and keyboard commands are provided for switching between tools." { $commands workspace } "Workspaces are instances of " { $link workspace-window } "." +{ $subsection "ui-presentations" } { $subsection "ui-listener" } { $subsection "ui-browser" } { $subsection "ui-help" } { $subsection "ui-walker" } -{ $subsection "ui-dataflow" } ; +{ $subsection "ui-dataflow" } +{ $subsection "ui-cocoa" } ; diff --git a/library/syntax/parser.factor b/library/syntax/parser.factor index d8b09309d2..2342963736 100644 --- a/library/syntax/parser.factor +++ b/library/syntax/parser.factor @@ -107,7 +107,7 @@ TUPLE: bad-escape ; global [ { "scratchpad" "syntax" "arrays" "compiler" "definitions" - "errors" "generic" "hashtables" "inference" + "errors" "generic" "hashtables" "help" "inference" "io" "kernel" "listener" "math" "memory" "modules" "namespaces" "parser" "prettyprint" "sequences" "shells" "strings" "styles" "test" diff --git a/library/ui/gadgets/lists.factor b/library/ui/gadgets/lists.factor index 9e8ae8149c..f1ac40ed76 100644 --- a/library/ui/gadgets/lists.factor +++ b/library/ui/gadgets/lists.factor @@ -2,7 +2,7 @@ ! See http://factorcode.org/license.txt for BSD license. IN: gadgets-lists USING: gadgets gadgets-scrolling kernel sequences models opengl -math ; +math namespaces ; TUPLE: list index presenter action color ; @@ -69,8 +69,18 @@ M: list focusable-child* drop t ; dup list-value over list-action call ] unless drop ; +: click-list ( list -- ) + hand-gadget get [ gadget-parent list? ] find-parent + dup [ + over gadget-children index dup -1 = + [ 2drop ] [ swap select-index ] if + ] [ + 2drop + ] if ; + list H{ - { T{ button-down } [ request-focus ] } + { T{ button-down } [ dup request-focus click-list ] } + { T{ drag } [ click-list ] } { T{ key-down f f "UP" } [ select-prev ] } { T{ key-down f f "DOWN" } [ select-next ] } { T{ key-down f f "RETURN" } [ call-action ] } diff --git a/library/ui/gadgets/presentations.factor b/library/ui/gadgets/presentations.factor index 071866af7a..1351162a9c 100644 --- a/library/ui/gadgets/presentations.factor +++ b/library/ui/gadgets/presentations.factor @@ -56,7 +56,7 @@ presentation H{ { T{ button-up } [ [ invoke-presentation ] if-clicked ] } { T{ button-down f f 3 } [ [ operations-menu ] if-clicked ] } { T{ mouse-leave } [ dup hide-mouse-help button-update ] } - { T{ mouse-enter } [ dup show-mouse-help button-update ] } + { T{ motion } [ dup show-mouse-help button-update ] } } set-gestures ! Presentation help bar diff --git a/library/ui/tools/help.factor b/library/ui/tools/help.factor index d7ee783473..b417e716a8 100644 --- a/library/ui/tools/help.factor +++ b/library/ui/tools/help.factor @@ -46,13 +46,3 @@ M: help-gadget tool-help drop "ui-help" ; : help-action ( help-gadget -- link ) help-gadget-history model-value >link ; - -help-gadget "Toolbar" { - { "Back" T{ key-down f { C+ } "b" } [ help-gadget-history go-back ] } - { "Forward" T{ key-down f { C+ } "f" } [ help-gadget-history go-forward ] } - { "Home" T{ key-down f { C+ } "h" } [ go-home ] } -} -link class-operations [ help-action ] modify-operations -[ command-name "Follow" = not ] subset -append -define-commands diff --git a/library/ui/tools/listener.factor b/library/ui/tools/listener.factor index 2d71076346..ac195ed4e5 100644 --- a/library/ui/tools/listener.factor +++ b/library/ui/tools/listener.factor @@ -6,7 +6,7 @@ gadgets-panes gadgets-scrolling gadgets-text gadgets-lists gadgets-search gadgets-theme gadgets-tracks gadgets-workspace generic hashtables tools io kernel listener math models namespaces parser prettyprint sequences shells strings styles -threads words definitions ; +threads words definitions help ; TUPLE: listener-gadget input output stack minibuffer ; @@ -29,10 +29,16 @@ TUPLE: listener-gadget input output stack minibuffer ; : init-listener ( listener -- ) f swap set-listener-gadget-stack ; +: welcome. ( -- ) + "If this is your first time with Factor, please read " print + "ui-tools" ($link) ", and especially " write + "ui-listener" ($link) "." print terpri ; + : listener-thread ( listener -- ) dup listener-stream [ [ ui-listener-hook ] curry listener-hook set find-messages batch-errors set + welcome. tty ] with-stream* ; @@ -163,7 +169,7 @@ listener-gadget "Toolbar" { { "Send EOF" T{ key-down f { C+ } "d" } [ listener-eof ] } } define-commands -listener-gadget "Listener commands" { +listener-gadget "Completion commands" { { "Complete word" T{ key-down f f "TAB" } diff --git a/library/ui/tools/operations.factor b/library/ui/tools/operations.factor index f4e51ebaad..65b1c6fd70 100644 --- a/library/ui/tools/operations.factor +++ b/library/ui/tools/operations.factor @@ -209,3 +209,13 @@ interactor "Quotation commands" quotation class-operations [ quot-action ] modify-listener-operations define-commands + +help-gadget "Toolbar" { + { "Back" T{ key-down f { C+ } "b" } [ help-gadget-history go-back ] } + { "Forward" T{ key-down f { C+ } "f" } [ help-gadget-history go-forward ] } + { "Home" T{ key-down f { C+ } "h" } [ go-home ] } +} +link class-operations [ help-action ] modify-operations +[ command-name "Follow" = not ] subset +append +define-commands -- 2.34.1