diff --git a/basis/help/cookbook/cookbook.factor b/basis/help/cookbook/cookbook.factor index 6e27bd9256..711712a4bc 100644 --- a/basis/help/cookbook/cookbook.factor +++ b/basis/help/cookbook/cookbook.factor @@ -325,6 +325,15 @@ ARTICLE: "cookbook-pitfalls" "Pitfalls to avoid" { "If " { $link run-file } " throws a stack depth assertion, it means that the top-level form in the file left behind values on the stack. The stack depth is compared before and after loading a source file, since this type of situation is almost always an error. If you have a legitimate need to load a source file which returns data in some manner, define a word in the source file which produces this data on the stack and call the word after loading the file." } } ; +ARTICLE: "cookbook-images" "Image file cookbook" +"Factor has the ability to save the entire state of the system into an " { $emphasis "image file" } "." +$nl +"You can save a custom image if you find yourself loading the same libraries in every Factor session; some libraries take a little while to compile, so saving an image with those libraries loaded can save you a lot of time." +$nl +"For example, to save an image with the web framework loaded," +{ $code "USE: furnace" "save" } +"See " { $link "images" } " for details." ; + ARTICLE: "cookbook-next" "Next steps" "Once you have read through " { $link "first-program" } " and " { $link "cookbook" } ", the best way to keep learning Factor is to start looking at some simple example programs. Here are a few particularly nice vocabularies which should keep you busy for a little while:" { $list @@ -349,6 +358,7 @@ ARTICLE: "cookbook" "Factor cookbook" { $subsection "cookbook-application" } { $subsection "cookbook-scripts" } { $subsection "cookbook-compiler" } +{ $subsection "cookbook-images" } { $subsection "cookbook-philosophy" } { $subsection "cookbook-pitfalls" } { $subsection "cookbook-next" } ; diff --git a/basis/tools/vocabs/browser/browser-docs.factor b/basis/tools/vocabs/browser/browser-docs.factor index 6c5fb596e8..508b4a3493 100644 --- a/basis/tools/vocabs/browser/browser-docs.factor +++ b/basis/tools/vocabs/browser/browser-docs.factor @@ -11,3 +11,7 @@ ARTICLE: "vocab-index" "Vocabulary index" { $subsection "vocab-tags" } { $subsection "vocab-authors" } { $describe-vocab "" } ; + +HELP: words. +{ $values { "vocab" "a vocabulary name" } } +{ $description "Printings a listing of all the words in a vocabulary, categorized by type." } ; diff --git a/basis/ui/gadgets/worlds/worlds-docs.factor b/basis/ui/gadgets/worlds/worlds-docs.factor index 9dd152885e..35781fa568 100644 --- a/basis/ui/gadgets/worlds/worlds-docs.factor +++ b/basis/ui/gadgets/worlds/worlds-docs.factor @@ -53,3 +53,20 @@ HELP: draw-world { $values { "world" world } } { $description "Redraws a world." } { $notes "This word should only be called by the UI backend. To force a gadget to redraw from user code, call " { $link relayout-1 } "." } ; + +HELP: find-gl-context +{ $values { "gadget" gadget } } +{ $description "Makes the OpenGL context of the gadget's containing native window the current OpenGL context." } +{ $notes "This word should be called from " { $link graft* } " and " { $link ungraft* } " methods which need to allocate and deallocate OpenGL resources, such as textures, display lists, and so on." } ; + +ARTICLE: "ui-paint-custom" "Implementing custom drawing logic" +"The UI uses OpenGL to render gadgets. Custom rendering logic can be plugged in with the " { $link "ui-pen-protocol" } ", or by implementing a generic word:" +{ $subsection draw-gadget* } +"Custom drawing code has access to the full OpenGL API in the " { $vocab-link "opengl" } " vocabulary." +$nl +"Gadgets which need to allocate and deallocate OpenGL resources such as textures, display lists, and so on, should perform the allocation in the " { $link graft* } " method, and the deallocation in the " { $link ungraft* } " method. Since those words are not necessarily called with the gadget's OpenGL context active, a utility word can be used to find and make the correct OpenGL context current:" +{ $subsection find-gl-context } +"OpenGL state must not be altered as a result of drawing a gadget, so any flags which were enabled should be disabled, and vice versa." +{ $subsection "ui-paint-coord" } +{ $subsection "gl-utilities" } +{ $subsection "text-rendering" } ; diff --git a/basis/ui/gestures/gestures-docs.factor b/basis/ui/gestures/gestures-docs.factor index 1e472e921f..602d3fd425 100644 --- a/basis/ui/gestures/gestures-docs.factor +++ b/basis/ui/gestures/gestures-docs.factor @@ -191,6 +191,43 @@ HELP: gesture>string { $example "USING: io ui.gestures ;" "T{ key-down f { C+ } \"x\" } gesture>string print" "C+x" } } ; +HELP: left-action +{ $class-description "Gesture sent when the user performs a multi-touch three-finger swipe left." } ; + +HELP: right-action +{ $class-description "Gesture sent when the user performs a multi-touch three-finger swipe right." } ; + +HELP: up-action +{ $class-description "Gesture sent when the user performs a multi-touch three-finger swipe up." } ; + +HELP: down-action +{ $class-description "Gesture sent when the user performs a multi-touch three-finger swipe down." } ; + +HELP: zoom-in-action +{ $class-description "Gesture sent when the user performs a multi-touch two-finger pinch in." } ; + +HELP: zoom-out-action +{ $class-description "Gesture sent when the user performs a multi-touch two-finger pinch out." } ; + +ARTICLE: "gesture-differences" "Gesture handling differences between platforms" +"On Mac OS X, the modifier keys map as follows:" +{ $table + { { $link S+ } "Shift" } + { { $link A+ } "Command (Apple)" } + { { $link C+ } "Control" } + { { $link M+ } "Option" } +} +"On Windows and X11:" +{ $table + { { $link S+ } "Shift" } + { { $link A+ } "Alt" } + { { $link C+ } "Control" } + { { $link M+ } "Windows key" } +} +"On Windows, " { $link key-up } " gestures are not reported for all keyboard events." +$nl +{ $link "multitouch-gestures" } " are only supported on Mac OS X." ; + ARTICLE: "ui-gestures" "UI gestures" "User actions such as keyboard input and mouse button clicks deliver " { $emphasis "gestures" } " to gadgets. If the direct receiver of the gesture does not handle it, the gesture is passed on to the receiver's parent, and this way it travels up the gadget hierarchy. Gestures which are not handled at some point are ignored." $nl @@ -207,6 +244,9 @@ $nl { $subsection "ui-user-input" } "Mouse input:" { $subsection "mouse-gestures" } +{ $subsection "multitouch-gestures" } +"Guidelines for cross-platform applications:" +{ $subsection "gesture-differences" } "Abstractions built on top of gestures:" { $subsection "ui-commands" } { $subsection "ui-operations" } ; @@ -301,6 +341,18 @@ $nl "Global variable set when a mouse scroll wheel gesture is sent:" { $subsection scroll-direction } ; +ARTICLE: "multitouch-gestures" "Multi-touch gestures" +"Multi-touch gestures are only supported on Mac OS X with newer MacBook and MacBook Pro models." +$nl +"Three-finger swipe:" +{ $subsection left-action } +{ $subsection right-action } +{ $subsection up-action } +{ $subsection down-action } +"Two-finger pinch:" +{ $subsection zoom-in-action } +{ $subsection zoom-out-action } ; + ARTICLE: "action-gestures" "Action gestures" "Action gestures exist to keep keyboard shortcuts for common clipboard operations consistent." { $subsection cut-action } diff --git a/basis/ui/render/render-docs.factor b/basis/ui/render/render-docs.factor index 294ee1c63d..7f88a904ec 100644 --- a/basis/ui/render/render-docs.factor +++ b/basis/ui/render/render-docs.factor @@ -1,5 +1,6 @@ USING: ui.gadgets ui.gestures help.markup help.syntax -kernel classes strings opengl.gl models math.geometry.rect ; +kernel classes strings opengl opengl.gl models +math.geometry.rect ; IN: ui.render HELP: gadget @@ -128,21 +129,11 @@ $nl { $subsection draw-string } { $subsection draw-text } ; -ARTICLE: "ui-paint-custom" "Implementing custom drawing logic" -"The UI uses OpenGL to render gadgets. Custom rendering logic can be plugged in with the " { $link "ui-pen-protocol" } ", or by implementing a generic word:" -{ $subsection draw-gadget* } -"Custom drawing code has access to the full OpenGL API in the " { $vocab-link "opengl" } " vocabulary." -$nl +ARTICLE: "ui-paint-coord" "The UI co-ordinate system" "The UI uses a co-ordinate system where the y axis is oriented down. The OpenGL " { $link GL_MODELVIEW } " matrix is not saved or restored when rendering a gadget. Instead, the origin of the gadget relative to the OpenGL context is stored in a variable:" { $subsection origin } -"Custom drawing implementations can translate co-ordinates manually, or save and restore the " { $link GL_MODELVIEW } " matrix." +"Custom drawing implementations can translate co-ordinates manually, or save and restore the " { $link GL_MODELVIEW } " matrix using a word such as " { $link with-translation } "." $nl -"OpenGL state must not be altered as a result of drawing a gadget, so any flags which were enabled should be disabled, and vice versa." -$nl -"Gadgets must not draw outside of their bounding box, however clipping is not enforced by default, for performance reasons. This can be changed by setting the " { $snippet "clipped?" } " slot to " { $link t } " in the gadget's constructor." -$nl -"Saving the " { $link GL_MODELVIEW } " matrix and enabling/disabling flags can be done in a clean way using the combinators documented in the following section." -{ $subsection "gl-utilities" } -{ $subsection "text-rendering" } ; +"Gadgets must not draw outside of their bounding box, however clipping is not enforced by default, for performance reasons. This can be changed by setting the " { $slot "clipped?" } " slot to " { $link t } " in the gadget's constructor." ; ABOUT: "ui-paint-custom" diff --git a/basis/ui/tools/tools-docs.factor b/basis/ui/tools/tools-docs.factor index 6368737460..8e1cc8d8f0 100644 --- a/basis/ui/tools/tools-docs.factor +++ b/basis/ui/tools/tools-docs.factor @@ -76,17 +76,6 @@ $nl ; -ARTICLE: "ui-tool-tutorial" "UI tool tutorial" -"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 " { $operation edit } " in the listener, which displays a gadget where you can type part of a loaded file's name, and then press " { $snippet "RET" } " 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 " { $operation walk } " 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 menu." } - { "After fixing the problem in the source editor, you right click on the word in the stepper and invoke " { $strong "Reload" } " from the menu." } -} ; - ARTICLE: "ui-completion-words" "Word completion popup" "Clicking a word in the word completion popup displays the word definition in the " { $link "ui-browser" } ". Pressing " { $snippet "RET" } " with a word selected inserts the word name in the listener, along with a " { $link POSTPONE: USE: } " declaration (if necessary)." { $operations \ $operations } ; @@ -110,18 +99,16 @@ $nl { $subsection "ui-completion-sources" } ; ARTICLE: "ui-workspace-keys" "UI keyboard shortcuts" +"See " { $link "gesture-differences" } " to find out how your platform's modifier keys map to modifiers in the Factor UI." { $command-map workspace "tool-switching" } { $command-map workspace "scrolling" } { $command-map workspace "workflow" } -{ $command-map workspace "multi-touch" } -{ $heading "Implementation" } -"Workspaces are instances of " { $link workspace } "." ; +{ $command-map workspace "multi-touch" } ; ARTICLE: "ui-tools" "UI developer tools" "The Factor development environment can seem rather different from what you are used to, because it is very simple and powerful.." $nl "To take full advantage of the UI, you should be using a supported text editor. See " { $link "editor" } "." -{ $subsection "ui-tool-tutorial" } { $subsection "ui-workspace-keys" } { $subsection "ui-presentations" } { $subsection "ui-completion" } diff --git a/basis/ui/ui-docs.factor b/basis/ui/ui-docs.factor index 978bd24055..de2df4ee6e 100644 --- a/basis/ui/ui-docs.factor +++ b/basis/ui/ui-docs.factor @@ -1,6 +1,6 @@ USING: help.markup help.syntax strings quotations debugger io.styles namespaces ui.backend ui.gadgets ui.gadgets.worlds -ui.gadgets.tracks ui.gadgets.packs ui.gadgets.grids math.geometry.rect ; +ui.gadgets.tracks ui.gadgets.packs ui.gadgets.grids math.geometry.rect colors ; IN: ui HELP: windows @@ -47,18 +47,19 @@ HELP: (open-window) { $description "Opens a native window containing the given world. This grafts the world by calling " { $link graft } ". Each world can only be displayed in one top-level window at a time." } { $notes "This word should not be called directly by user code. Instead, use " { $link open-window } "." } ; +HELP: raise-window +{ $values { "gadget" gadget } } +{ $description "Makes the native window containing the given gadget the front-most window." } ; + +HELP: with-ui +{ $values { "quot" quotation } } +{ $description "Calls the quotation, starting the UI first if necessary." } +{ $notes "This combinator should be used in the " { $link POSTPONE: MAIN: } " word of a vocabulary, in order for the vocabulary to work when run from the UI listener (" { $snippet "\"my-app\" run" } " and the command line (" { $snippet "./factor -run=my-app" } ")." } +{ $examples "The " { $vocab-link "hello-ui" } " vocabulary implements a simple UI application which uses this combinator." } ; + ARTICLE: "ui-glossary" "UI glossary" { $table - { "color specifier" - { "an array of four elements, all numbers between 0 and 1:" - { $list - "red" - "green" - "blue" - "alpha - 0 is completely transparent, 1 is completely opaque" - } - } - } + { "color" { "an instance of " { $link color } } } { "dimension" "a pair of integers denoting pixel size on screen" } { "font specifier" { "an array of three elements:" @@ -129,9 +130,7 @@ ARTICLE: "ui-backend" "Developing UI backends" "UI backends may implement the " { $link "clipboard-protocol" } "." ; ARTICLE: "ui-backend-init" "UI initialization and the event loop" -"An UI backend is required to define a word to start the UI:" -{ $subsection ui } -"This word should contain backend initialization, together with some boilerplate:" +"An UI backend is required to define a method on the " { $link ui } " word. This word should contain backend initialization, together with some boilerplate:" { $code "IN: shells" "" @@ -163,10 +162,6 @@ ARTICLE: "ui-backend-windows" "UI backend window management" "If the user clicks the window's close box, you must call the following word:" { $subsection close-window } ; -HELP: raise-window -{ $values { "gadget" gadget } } -{ $description "Makes the native window containing the given gadget the front-most window." } ; - ARTICLE: "ui-layouts" "Gadget hierarchy and layouts" "A layout gadget is a gadget whose sole purpose is to contain other gadgets. Layout gadgets position and resize children according to a certain policy, taking the preferred size of the children into account. Gadget hierarchies are constructed by building up nested layouts." { $subsection "ui-layout-basics" } @@ -240,7 +235,23 @@ $nl { $subsection "clipboard-protocol" } { $see-also "ui-layout-impl" } ; +ARTICLE: "starting-ui" "Starting the UI" +"The UI starts automatically where possible:" +{ $list + { "On Windows, the UI starts when the Factor executable is run." } + { "On X11, the UI starts if the " { $snippet "DISPLAY" } " environment variable is set." } + { "On Mac OS X, the UI starts if the " { $snippet "Factor.app" } " application bundle is run." } +} +"In all cases, passing the " { $snippet "-run=listener" } " command line switch starts the terminal listener instead. The UI can be started from the terminal listener using a word:" +{ $subsection ui } +"To run the terminal listener and the UI simultaneously, start the UI in a new thread:" +{ $code "USING: threads ui ;" "[ ui ] in-thread" } +"The main word of a vocabulary implementing a UI application should use a combinator to ensure that the application works when run from the command line as well as in the UI listener:" +{ $subsection with-ui } ; + ARTICLE: "ui" "UI framework" +"The " { $vocab-link "ui" } " vocabulary hierarchy implements the Factor UI framework. The implementation relies on a small amount of platform-specific code to open windows and receive keyboard and mouse events; UI gadgets are rendered using OpenGL." +{ $subsection "starting-ui" } { $subsection "ui-glossary" } { $subsection "building-ui" } { $subsection "new-gadgets" }