steve
/
factor
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Wrote a top-level article documenting UI gadgets

darcs
slava 2006-12-18 06:54:11 +00:00
parent 756cea6164
commit e8e4cb37fb
13 changed files with 235 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
core/bootstrap/boot-stage1.factor
View File

@ -21,6 +21,7 @@ prettyprint sequences vectors words ;
"core/io/buffer" require
"core/ui" require
"core/ui/tools" require
"core/ui/handbook" require
"core/compiler/" architecture get append require
"core/handbook" require

26
core/handbook/cookbook.facts
View File

@ -1,5 +1,29 @@
USING: help io kernel math namespaces parser prettyprint
sequences ;
sequences modules tools ;
ARTICLE: "cookbook" "Factor cookbook"
{ $list
{ "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 "\"my-program.factor\" run-file" } }
{ { "You can load modules from " { $snippet "apps/" } ", " { $snippet "libs/" } " or " { $snippet "demos/" } " with " { $link require } ":" }
{ $code "\"libs/httpd\" require" } }
{ { "Some modules have a defined main entry point, and can be run just like applications in an operating system:" }
{ $code "\"apps/tetris\" run-module" }
}
{ { $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" } "." }
}
{ $subsection "cookbook-syntax" }
{ $subsection "cookbook-colon-defs" }
{ $subsection "cookbook-combinators" }
{ $subsection "cookbook-variables" }
{ $subsection "cookbook-vocabs" }
{ $subsection "cookbook-sources" }
{ $subsection "cookbook-io" }
{ $subsection "cookbook-philosophy" } ;
ARTICLE: "cookbook-syntax" "Basic syntax cookbook"
"The following is a simple snippet of Factor code:"

31
core/handbook/handbook.facts
View File

@ -5,30 +5,8 @@ kernel generic ;
ARTICLE: "handbook" "Factor documentation"
{ $subsection "changes" }
{ $heading "Survival guide" }
{ $list
{ "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 "\"my-program.factor\" run-file" } }
{ { "You can load modules from " { $snippet "apps/" } ", " { $snippet "libs/" } " or " { $snippet "demos/" } " with " { $link require } ":" }
{ $code "\"libs/httpd\" require" } }
{ { "Some modules have a defined main entry point, and can be run just like applications in an operating system:" }
{ $code "\"apps/tetris\" run-module" }
}
{ { $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" }
{ $subsection "cookbook-colon-defs" }
{ $subsection "cookbook-combinators" }
{ $subsection "cookbook-variables" }
{ $subsection "cookbook-vocabs" }
{ $subsection "cookbook-sources" }
{ $subsection "cookbook-io" }
{ $subsection "cookbook-philosophy" }
"If you are new to Factor, please read the cookbook first."
{ $subsection "cookbook" }
{ $heading "Language reference" }
{ $subsection "conventions" }
{ $subsection "syntax" }
@ -50,14 +28,15 @@ ARTICLE: "handbook" "Factor documentation"
{ $subsection "compiler" }
{ $heading "Graphical user interface" }
{ $subsection "ui-tools" }
{ $subsection "gadgets" }
{ $heading "Currently-loaded contributed modules" }
{ $outliner [ modules-help ] }
{ $heading "Index" }
{ $subsection "article-index" }
{ $subsection "primitive-index" }
{ $subsection "error-index" }
{ $subsection "type-index" }
{ $subsection "class-index" } ;
{ $subsection "class-index" }
{ $subsection "primitive-index" } ;
ARTICLE: "article-index" "Article index"
{ $outliner [ articles get hash-keys ] } ;

2
core/handbook/load.factor
View File

@ -22,6 +22,4 @@ PROVIDE: core/handbook
"help.facts"
"tools.facts"
"words.facts"
"ui/tools.facts"
"ui/ui.facts"
} } ;

9
core/ui/gadgets/buttons.facts
View File

@ -5,15 +5,6 @@ generic models ;
HELP: button
{ $class-description "A button is a " { $link gadget } " which responds to mouse clicks by invoking a quotation."
$terpri
"The following words construct buttons:"
{ $list
{ $link <button> }
{ $link <roll-button> }
{ $link <bevel-button> }
{ $link <command-button> }
{ $link <presentation> }
{ $link <repeat-button> }
}
"A button's appearance can vary depending on the state of the mouse button if the " { $link gadget-interior } " or " { $link gadget-boundary } " slots are set to instances of " { $link button-paint } "."
$terpri
"A button can be selected, which is distinct from being pressed. This state is held in the " { $link button-selected? } " slot, and is used by the " { $link <radio-box> } " word to construct a row of buttons for choosing among several alternatives." } ;

2
core/ui/gadgets/outliner.facts
View File

@ -5,7 +5,7 @@ HELP: guide
{ $class-description "A class implementing the " { $link draw-interior } " generic word to draw a single vertical line." } ;
HELP: outliner
{ $class-description "A gadget with an expander arrow which can be clicked to show and hide a child gadget generated by the quotation stored in the " { $link outliner-quot } " slot. Outliners are created by calling " { $link <outliner> } "." }
{ $class-description "An outliner is a " { $link gadget } " with an expander arrow which can be clicked to show and hide a child gadget generated by the quotation stored in the " { $link outliner-quot } " slot. Outliners are created by calling " { $link <outliner> } "." }
{ $see-also <outliner> "presentations" } ;
HELP: <expand-button>

194
core/ui/handbook/gadgets.facts Normal file
View File

@ -0,0 +1,194 @@
USING: gadgets gadgets-labels gadgets-buttons gadgets-sliders
gadgets-panes gadgets-lists gadgets-text gadgets-borders
gadgets-presentations gadgets-scrolling gadgets-outliners help ;
ARTICLE: "gadgets" "UI gadgets"
{ $subsection "gadgets-labels" }
{ $subsection "gadgets-polygons" }
{ $subsection "gadgets-borders" }
{ $subsection "gadgets-buttons" }
{ $subsection "gadgets-sliders" }
{ $subsection "gadgets-scrolling" }
{ $subsection "gadgets-editors" }
{ $subsection "gadgets-panes" }
{ $subsection "gadgets-presentations" }
{ $subsection "gadgets-lists" }
{ $subsection "gadgets-outliners" } ;
ARTICLE: "gadgets-labels" "Label gadgets"
"A label displays a piece of text, either a single line string or an array of line strings."
{ $subsection label }
{ $subsection <label> }
{ $subsection <label-control> }
{ $subsection label-string }
{ $subsection set-label-string } ;
ARTICLE: "gadgets-polygons" "Polygon gadgets"
"A polygon gadget renders a simple shaded polygon."
{ $subsection polygon }
{ $subsection <polygon> }
{ $subsection <polygon-gadget> }
"Some pre-made polygons:"
{ $subsection arrow-up }
{ $subsection arrow-right }
{ $subsection arrow-down }
{ $subsection arrow-left }
{ $subsection close-box } ;
ARTICLE: "gadgets-borders" "Border gadgets"
"Border gadgets add empty space around a child gadget."
{ $subsection border }
{ $subsection <border> }
{ $subsection <default-border> }
"It is also possible to create a labelled border around a child gadget:"
{ $subsection labelled-gadget }
{ $subsection <labelled-gadget> }
"Or a labelled border with a close box:"
{ $subsection closable-gadget }
{ $subsection <closable-gadget> } ;
ARTICLE: "gadgets-buttons" "Button gadgets"
"Buttons respond to mouse clicks by invoking a quotation."
{ $subsection button }
"There are many ways to create a new button:"
{ $subsection <button> }
{ $subsection <roll-button> }
{ $subsection <bevel-button> }
{ $subsection <command-button> }
{ $subsection <repeat-button> }
"A radio box is a row of buttons for choosing amongst several distinct possibilities:"
{ $subsection <radio-box> }
"Button appearance can be customized:"
{ $subsection button-paint } ;
ARTICLE: "gadgets-sliders" "Slider gadgets"
"A slider allows the user to graphically manipulate a value by moving a thumb back and forth."
{ $subsection slider }
{ $subsection <x-slider> }
{ $subsection <y-slider> }
"Changing slider values:"
{ $subsection set-slider }
{ $subsection set-slider-value }
{ $subsection slide-by }
{ $subsection slide-by-line }
{ $subsection slide-by-page } ;
ARTICLE: "gadgets-scrolling" "Scroller gadgets"
"A scroller displays a gadget which is larger than the visible area."
{ $subsection scroller }
{ $subsection <scroller> }
"Getting and setting the scroll position:"
{ $subsection scroller-value }
{ $subsection scroll }
"Writing scrolling-aware gadgets:"
{ $subsection scroll>bottom }
{ $subsection scroll>top }
{ $subsection scroll>rect }
{ $subsection find-scroller } ;
ARTICLE: "gadgets-editors-selection" "The caret and mark"
"If there is no selection, the caret and the mark are at the same location; otherwise the mark delimits the end-point of the selection opposite the caret."
{ $subsection editor-caret }
{ $subsection editor-caret* }
{ $subsection editor-mark }
{ $subsection editor-mark* }
{ $subsection change-caret }
{ $subsection change-caret&mark }
{ $subsection mark>caret }
"Getting and setting the selected text:"
{ $subsection gadget-selection? }
{ $subsection gadget-selection }
{ $subsection user-input* }
"Scrolling to the caret location:"
{ $subsection scroll>caret } ;
ARTICLE: "documents" "Documents"
"The " { $link control-model } " of an " { $link editor } " is a " { $link document } "."
{ $subsection document }
{ $subsection <document> }
"Getting and setting the contents of the entire document:"
{ $subsection doc-string }
{ $subsection set-doc-string }
{ $subsection clear-doc }
"Getting and setting subranges:"
{ $subsection doc-line }
{ $subsection doc-lines }
{ $subsection doc-range }
{ $subsection set-doc-range }
{ $subsection remove-doc-range } ;
ARTICLE: "document-locs-elts" "Locations and elements"
"Locations in the document are represented as a line/column number pair, with both indices being zero-based. There are some words for manipulating locations:"
{ $subsection +col }
{ $subsection +line }
{ $subsection =col }
{ $subsection =line }
"New locations can be created out of existing ones by finding the start or end of a document element nearest to a given location."
{ $subsection prev-elt }
{ $subsection next-elt }
"The different types of document elements correspond to the standard editing taxonomy:"
{ $subsection char-elt }
{ $subsection one-word-elt }
{ $subsection word-elt }
{ $subsection one-line-elt }
{ $subsection line-elt }
{ $subsection doc-elt }
"Miscellaneous words for working with locations:"
{ $subsection lines-equal? }
{ $subsection validate-loc } ;
ARTICLE: "gadgets-editors" "Editor gadgets"
"An editor edits a multi-line passage of text."
{ $heading "General commands" }
{ $commands editor "editing" }
{ $heading "Caret motion commands" }
{ $commands editor "caret" }
{ $heading "Selection commands" }
{ $commands editor "selection" }
{ $heading "Editor words" }
{ $subsection editor }
{ $subsection <editor> }
{ $subsection editor-string }
{ $subsection set-editor-string }
{ $subsection "gadgets-editors-selection" }
{ $subsection "documents" }
{ $subsection "document-locs-elts" } ;
ARTICLE: "gadgets-panes" "Pane gadgets"
"A pane displays formatted text."
{ $subsection pane }
{ $subsection <pane> }
{ $subsection <scrolling-pane> }
{ $subsection <pane-control> }
{ $subsection <labelled-pane> }
"Panes are written to by creating a special output stream:"
{ $subsection pane-stream }
{ $subsection <pane-stream> }
"In addition to the stream output words (" { $link "stream-protocol" } ", pane streams can have gadgets written to them:"
{ $subsection write-gadget }
{ $subsection print-gadget }
{ $subsection gadget. }
"The " { $link gadget. } " word is useful for interactive debugging of gadgets in the listener."
$terpri
"There are a few combinators for working with panes:"
{ $subsection with-pane }
{ $subsection make-pane } ;
ARTICLE: "gadgets-presentations" "Presentation gadgets"
"Outliner gadgets are usually not constructed directly, and instead are written to " { $link "gadgets-panes" } " with formatted stream output words (" { $link "presentations" } ")."
{ $subsection presentation }
{ $subsection <presentation> }
"If you want to display your own windows with mouse-over help for presentations, add this gadget to the window:"
{ $subsection <presentation-help> } ;
ARTICLE: "gadgets-lists" "List gadgets"
"A list displays a list of presentations."
{ $subsection list }
{ $subsection <list> }
{ $subsection list-value } ;
ARTICLE: "gadgets-outliners" "Outliner gadgets"
"Outliner gadgets are usually not constructed directly, and instead are written to " { $link "gadgets-panes" } " with formatted stream output words (" { $link "presentations" } ")."
{ $subsection outliner }
{ $subsection <outliner> }
{ $subsection set-outliner-expanded? } ;

6
core/ui/handbook/load.factor Normal file
View File

@ -0,0 +1,6 @@
PROVIDE: core/ui/handbook
{ +files+ {
"tools.facts"
"gadgets.facts"
"ui.facts"
} } ;

2
core/handbook/ui/tools.facts → core/ui/handbook/tools.facts
View File

@ -33,7 +33,7 @@ ARTICLE: "ui-listener" "UI listener"
"These commands operate on the entire contents of the input area."
{ $commands interactor "quotations" }
{ $heading "Editing commands" }
"The text editing commands are standard and are documented in the " { $link editor } " class."
"The text editing commands are standard; see " { $link "gadgets-editors" } "."
{ $heading "Implementation" }
"Listeners are instances of " { $link listener-gadget } ". The listener consists of an output area (instance of " { $link pane } "), and an input area (instance of " { $link interactor } "), and a stack display kept up to date using a " { $link listener-hook } "." ;

0
core/handbook/ui/ui.facts → core/ui/handbook/ui.facts
View File

6
core/ui/text/document.factor
View File

@ -119,11 +119,9 @@ C: document ( -- document )
: doc-string ( document -- str )
model-value "\n" join ;
: set-doc-lines ( seq document -- )
[ set-model ] keep dup doc-end swap update-locs ;
: set-doc-string ( string document -- )
>r string-lines r> set-doc-lines ;
>r string-lines r> [ set-model ] keep
dup doc-end swap update-locs ;
: clear-doc ( document -- )
"" swap set-doc-string ;

5
core/ui/text/document.facts
View File

@ -79,11 +79,6 @@ HELP: doc-string
{ $values { "document" document } { "string" "a new " { $link string } } }
{ $description "Outputs the contents of the document as a string. Lines are separated by " { $snippet "\\n" } "." } ;
HELP: set-doc-lines
{ $values { "array" "an array of strings" } { "document" document } }
{ $description "Sets the contents of the document to an array of lines." }
{ $side-effects "document" } ;
HELP: set-doc-string
{ $values { "array" "an array of strings" } { "document" document } }
{ $description "Sets the contents of the document to a string, which may use either " { $snippet "\\n" } ", " { $snippet "\\r\\n" } " or " { $snippet "\\r" } " line separators." }

7
core/ui/text/editor.facts
View File

@ -5,13 +5,6 @@ HELP: editor
{ $class-description "An editor is a " { $link control } " for editing a multi-line passage of text stored in a " { $link document } " model. Editors are crated by calling " { $link <editor> } "."
$terpri
"The " { $link interactor } " gadget is built off the " { $link editor } " gadget and is used by the " { $link "ui-listener" } "." }
{ $heading "General commands" }
{ $commands editor "editing" }
{ $heading "Caret motion commands" }
{ $commands editor "caret" }
{ $heading "Selection commands" }
{ $commands editor "selection" }
{ $heading "Slots" }
"Editors have the following slots:"
{ $list
{ { $link editor-font } " - a font specifier." }