From: adam Date: Tue, 30 Mar 2004 23:15:12 +0000 (+0000) Subject: reference updates, including diagrams X-Git-Url: http://git.megacz.com/?p=org.ibex.core.git;a=commitdiff_plain;h=332129d6e1b9d55064d5edd9554bcf0fd0054a6f reference updates, including diagrams darcs-hash:20040330231512-5007d-015a0b17990c27e93e20e57b6712e401217b8474.gz --- diff --git a/Makefile b/Makefile index 993e66e..d09fcb1 100644 --- a/Makefile +++ b/Makefile @@ -379,8 +379,9 @@ propose-patch: commit: propose-patch darcs push --and-apply xwt@xwt.org:/var/www/org/ibex/core/ -reference: build/class/org/ibex/util/XML.class build/class/org/ibex/util/Doc.class doc/reference.xml - cd doc; java -cp ../build/class org.ibex.util.Doc < reference.xml > reference.tex - cd doc; pdflatex reference.tex - open doc/reference.pdf +doc/%.pdf: build/class/org/ibex/util/XML.class build/class/org/ibex/util/Doc.class doc/%.xml + cd $(@D); java -cp ../../build/class org.ibex.util.Doc slides < `basename $*`.xml > `basename $*`.tex + cd $(@D); pdflatex `basename $*`.tex + open doc/$*.pdf + diff --git a/doc/ibex-doc.xml b/doc/ibex-doc.xml new file mode 100644 index 0000000..05e49d9 --- /dev/null +++ b/doc/ibex-doc.xml @@ -0,0 +1,204 @@ + + +
+ +
+ + Foo. + +
+ +
+ + + + IbexDoc targets four primary documentation tasks: + + + + Books, Manuals and references + + Articles + + Literate Programming (documentation embedded in source code) + + Presentation Slides + + Web pages, including WikiWebs + + + + + + The goal of separating markup from content has been + around for a long time in the document world. For some reason it + never succeeded. The problem is that: + + + The purpose of content is to convey semantic meaning. + + Some markup and formatting carries semantic meaning. + + + For example, consider italicization. Adding or removing + italicization can actually affect the meaning of a piece of text. + Therefor italicization (or rather "emphasis") is part of the + content of a document. + + IbexDoc recognizes this and does not attempt to use XML for + anything that might carry semantic meaning. Effectively, you can + remove all XML tags from an IbexDoc file without altering the + meaning of the text (although it might be rather hard to discern + the meaning with all the text jumbled together!) + +
+
+
+ + + (title subtitle logo license options(toc,index) logo) + + + + (email, name) + + + + changes + + + + (contains sections, must appear once at EOF) + + + + (title) + + + + .. + + + + .. + + + + (a different kind of list?) + + + + .. + + + + .. + + + + .. + + + + .. + + + + .. + + + + .. + + + + .. + + + + .. + + + + .. + + +
+ +
+ + 
+
+     **italics**
+     __boldface__
+     ||typewriter||
+
+     blank lines become paragraph breaks
+
+     # 1
+        # 1.1
+           # 1.1.1
+
+     - 
+        -
+           -
+
+     \\     -   backslash
+     \0x??  -   unicode
+     \amp
+     \lt
+     \gt
+     \quot
+     \apos
+
+
+ +
+ +
+ + tables + + plugins (charts, graphs, diagrams) + + wiki-style links + + slides + + slide breaks + + overlays + + 2-column + + different diagram layouts + + color + + persistent outline + + watermark/logo + + + + + 
+
+          /** */
+          ///      
+          ///<
+          @param
+          @throws
+          @see
+          @link, autolinking (wiki-style?) of other classes/modules
+          @return
+          @deprecated
+          @since
+          @author?
+          package-level overview (but it's lame to put it in a separate file)
+          inheritance
+
+
+
+ + \ No newline at end of file diff --git a/doc/reference/alignmentpoint.pdf b/doc/reference/alignmentpoint.pdf new file mode 100644 index 0000000..82b5cd4 Binary files /dev/null and b/doc/reference/alignmentpoint.pdf differ diff --git a/doc/reference/grid.pdf b/doc/reference/grid.pdf new file mode 100644 index 0000000..219d379 Binary files /dev/null and b/doc/reference/grid.pdf differ diff --git a/doc/reference/layout.pdf b/doc/reference/layout.pdf new file mode 100644 index 0000000..853b40d Binary files /dev/null and b/doc/reference/layout.pdf differ diff --git a/doc/reference/lifecycle.pdf b/doc/reference/lifecycle.pdf new file mode 100644 index 0000000..940e482 Binary files /dev/null and b/doc/reference/lifecycle.pdf differ diff --git a/doc/reference/offscreen.pdf b/doc/reference/offscreen.pdf new file mode 100644 index 0000000..769be64 Binary files /dev/null and b/doc/reference/offscreen.pdf differ diff --git a/doc/reference/pdftricks.sty b/doc/reference/pdftricks.sty new file mode 100644 index 0000000..68ae554 --- /dev/null +++ b/doc/reference/pdftricks.sty @@ -0,0 +1,363 @@ +% +% pdftricks.sty +% +% Copyright (c) 2001, Radhakrishnan CV +% Rajagopal CV +% http://www.river-valley.com +% +% River Valley Technologies, Software Technology Park, +% Trivandrum, India 695034 +% +% Tel: +91 471 33 7501/7502 +% +% Antoine Chambert-Loir +% +% http://www.math.polytechnique.fr/~chambert +% +% Ecole polytechnique, Palaiseau Cedex, France +% +% +% This program is free software; you can redistribute it and/or +% modify it under the terms of the GNU General Public License +% as published by the Free Software Foundation; either version 2 +% of the License, or (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program (gpl.txt); if not, write to the Free +% Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, +% MA 02111-1307, USA. +% +% $Id: pdftricks.sty,v 1.15 2001/09/30 11:21:23 cvr Exp $ +% +\NeedsTeXFormat{LaTeX2e} +\def\Fileversion$#1: #2 ${\gdef\fileversion{#2}} +\def\Filedate$#1: #2 #3 ${\gdef\filedate{#2}} +\Fileversion$Revision: 1.15 $ +\Filedate$Date: 2001/09/30 11:21:23 $ +\ProvidesPackage{pdftricks} + [\filedate\space\fileversion\space psTricks support in PDF (CVRACL)] +\PackageWarningNoLine{pdftricks} + {****************************************\MessageBreak + Package pdftricks v,\fileversion\space loaded\MessageBreak + [psTricks support in PDF (CVR, ACL)]\MessageBreak + ****************************************} +\RequirePackage{graphicx,color} +\newif\if@debug\@debugfalse +\newif\ifPDFTshell +\newif\ifPDFTnopdf +\newif\ifnoprocess \noprocessfalse +\newif\ifmiktex \miktexfalse +\DeclareOption{debug}{\@debugtrue} +\DeclareOption{noshell}{\PDFTshellfalse} +\DeclareOption{shell}{\PDFTshelltrue} +\DeclareOption{miktex}{\global\miktextrue} +\ExecuteOptions{shell} +\ProcessOptions\relax +\ifPDFTshell +% we must set it to false if \write18 doesn't work. +% Hack given by Thierry Bouche (Thanks !) +\def\tmpfile{/tmp/w18-test-\the\year\the\month\the\day\the\time} +\ifmiktex% + \immediate\write18{rem >"\tmpfile"}%%%%%% LDL-2 +\else + \immediate\write18{touch \tmpfile} %%%%%% LDL-1 +\fi +\ifmiktex + \IfFileExists{\tmpfile.}{\PDFTshelltrue}{\PDFTshellfalse} %%%%%% LDL-4 +\else + \IfFileExists{\tmpfile}{\PDFTshelltrue}{\PDFTshellfalse} %%%%%% LDL-3 +\fi +\fi +\ifPDFTshell + \PackageWarningNoLine{pdftricks} + {****************************************\MessageBreak + Using \csname write\endcsname18 capability \MessageBreak + for producing PDF-figures. \MessageBreak + ****************************************} +\else + \PackageWarningNoLine{pdftricks} + {****************************************\MessageBreak + No \csname write\endcsname18 capability.\MessageBreak + You'll have to run a script by yourself!\MessageBreak + ****************************************} +\fi + +% warning! the definition of FIGURES if pst2pdf must be set accordingly !! +\def\PDFTfigname{\jobname-fig\thepsfig} +\def\PDFTWarning#1#2{\if@debug\PackageWarning{#1}{#2}\fi} +\def\PDFTWarningNoLine#1#2{\if@debug\PackageWarningNoLine{#1}{#2}\fi} +\def\makeinnocent#1{\catcode`#1=12 } +\def\csarg#1#2{\expandafter#1\csname#2\endcsname} +\def\latexname{lplain}\def\latexename{LaTeX2e} +\newwrite\PDFStream + +\long\def\ProcessStream#1% start it all of + {\begingroup% + \def\CurrentStream{#1}% + \let\do\makeinnocent \dospecials + \makeinnocent\^^L% and whatever other special cases + \endlinechar`\^^M \catcode`\^^M=12 \xStream} +{\catcode`\^^M=12 \endlinechar=-1 % + \gdef\xStream#1^^M{% + \expandafter\ProcessStreamLine} + \gdef\ProcessStreamLine#1^^M{\def\test{#1} + \csarg\ifx{End\CurrentStream Test}\test + \edef\next{\noexpand\EndOfStream{\CurrentStream}}% + \else \ThisStream{#1}\let\next\ProcessStreamLine + \fi \next} +} +\long\def\streaminfo{\string\end{document}} +\def\CSstringmeaning#1{\expandafter\CSgobblearrow\meaning#1} +\def\CSstringcsnoescape#1{\expandafter\CSgobbleescape\string#1} +{\escapechar-1 +\expandafter\expandafter\expandafter\gdef + \expandafter\expandafter\expandafter\CSgobblearrow + \expandafter\string\csname macro:->\endcsname{} +} +\def\CSgobbleescape#1{\ifnum`\\=`#1 \else #1\fi} +\def\WriteStreamLine#1{\def\CStmp{#1}% + \immediate\write\PDFStream{\CSstringmeaning\CStmp}} + +\def\AfterIncludedStream + {\immediate\closeout\PDFStream %changed on 2001/1/20 + \relax + }% +\def\BeforeIncludedStream + {\stepcounter{psfig}\xdef\PDFCutFile{\PDFTfigname.tex}% + \message{Opening PDFStream=\PDFCutFile}% + \immediate\openout\PDFStream=\PDFCutFile + \immediate\write\PDFStream{\string\documentclass{article}} + \immediate\write\PDFStream{\string\input\space tmp.inputs} + \immediate\write\PDFStream{\string\pagestyle{empty}} + \immediate\write\PDFStream{\string\usepackage{amssymb,amsbsy}} + \immediate\write\PDFStream{\string\begin{document}} + \let\ThisStream\WriteStreamLine} +\long\def\specialstream #1#2#3{% + \message{Special stream '#1'}% + \csarg\def{After#1Stream}{#2\AfterIncludedStream#3}% + \csarg\def{#1}{\BeforeIncludedStream\relax + \ProcessStream{#1}}% + \PDFEndDef{#1}} +\def\EndOfStream#1{\endgroup\end{#1}% + \csname After#1Stream\endcsname} +\def\PDFEndDef#1{{\escapechar=-1\relax + \csarg\xdef{End#1Test}{\string\\end\string\{#1\string\}}% + }} +%% +%% The real meat of psfile manipulation starts here. +%% +%% +\AtEndDocument{\endPShook% + \ifPDFTnopdf + \PackageWarningNoLine{pdftricks} + {******************************************\MessageBreak + Some PDF files of images were not found.\MessageBreak + Run the script `pst2pdf' before the next\MessageBreak + run of pdfLaTeX\MessageBreak + ******************************************} + \fi +} +\gdef\endPShook{} +\def\noprocess{\global\noprocesstrue + \PackageWarning{pdftricks} + {******************************************\MessageBreak + Figure Number: \PDFTfigname\space is not processed \MessageBreak + ******************************************\MessageBreak} +} +\specialstream{pdfpic}{% + \immediate\write\PDFStream{\streaminfo}} + {\psgraphicsinclude\global\noprocessfalse} +\newcounter{psfig} +\newif\if@pdfGINwidth +\newif\if@pdfGINheight +\newif\if@pdfGINscale +\long\gdef\psgraphicsinclude{% + \@ifundefined{Fig\thepsfig} + {\PDFTWarningNoLine{pdftricks} + {******************************************\MessageBreak + ************ Processing Fig: \thepsfig\space**********\MessageBreak + ******************************************} + } + {\noprocess} + \ifPDFTshell\ifnoprocess\relax\else + \IfFileExists{\PDFTfigname.tex}{% + \immediate\write18{latex -interaction=batchmode \PDFTfigname} + \PDFTWarningNoLine{pdftricks} + {******************************************\MessageBreak + \PDFTfigname.tex converted to \PDFTfigname.dvi\MessageBreak + ******************************************} + }{} + \IfFileExists{\PDFTfigname.dvi}{% + \immediate\write18{dvips -o \PDFTfigname.ps \PDFTfigname} + \immediate\write18{ps2eps -f \PDFTfigname.ps} + \PDFTWarningNoLine{pdftricks} + {******************************************\MessageBreak + \PDFTfigname.eps generated\MessageBreak + ******************************************} + }{} + \IfFileExists{\PDFTfigname.eps}{% + \immediate\write18{epstopdf \PDFTfigname.eps} + \PDFTWarningNoLine{pdftricks} + {******************************************\MessageBreak + \PDFTfigname.eps converted to \PDFTfigname.pdf\MessageBreak + ******************************************} + }{} + \ifmiktex% + \immediate\write18{del \PDFTfigname.aux \PDFTfigname.dvi \PDFTfigname.log \PDFTfigname.eps} %%%%%% LDL-6 + \else + \immediate\write18{rm \PDFTfigname.aux \PDFTfigname.dvi \PDFTfigname.log \PDFTfigname.eps} %%%%%% LDL-5 + \fi\fi + \fi + \IfFileExists{\PDFTfigname.pdf}% + {\begin{center} + \bgroup\fboxsep\@PDFboxsep\fboxrule\@PDFboxrule% + \color{\@PDFgraphiccolor}% + \fcolorbox{\@PDFgraphiclinecolor}{\@PDFgraphicbackground}% + {\if@pdfGINwidth% + \includegraphics[width=\@PDFgraphicwidth]{\PDFTfigname}\else% + \if@pdfGINheight% + \includegraphics[height=\@PDFgraphicheight]{\PDFTfigname}\else% + \if@pdfGINscale% + \includegraphics[scale=\@PDFgraphicscale]{\PDFTfigname}\else% + \includegraphics{\PDFTfigname}\fi\fi\fi% + }\egroup\end{center}% + \global\@pdfGINwidthfalse\let\@PDFgraphicwidth\relax + \global\@pdfGINheightfalse\let\@PDFgraphicheight\relax + \global\@pdfGINscalefalse\let\@PDFgraphicscale\relax + }{\PDFTnopdftrue} + \gdef\@PDFgraphiclinecolor{white} + \gdef\@PDFgraphicbackground{white} + \gdef\@PDFboxsep{0pt} + \gdef\@PDFboxrule{0pt} +} +\definecolor{gray30}{gray}{.70} +\definecolor{gray10}{gray}{.90} +\RequirePackage{keyval} +\def\configure[#1][#2]{\setkeys{#1}{#2} + \PDFTWarning{pdftricks}{Reconfigured #1 parameter(s)\MessageBreak #2\MessageBreak} + } +\define@key{pdfgraphic}{width} {\gdef\@PDFgraphicwidth{#1}\global\@pdfGINwidthtrue} +\define@key{pdfgraphic}{height} {\gdef\@PDFgraphicheight{#1}\global\@pdfGINheighttrue} +\define@key{pdfgraphic}{scale} {\gdef\@PDFgraphicscale{#1}\global\@pdfGINscaletrue} +\define@key{pdfgraphic}{color} {\gdef\@PDFgraphiccolor{#1}} +\define@key{pdfgraphic}{linecolor} {\gdef\@PDFgraphiclinecolor{#1}} +\define@key{pdfgraphic}{background}{\gdef\@PDFgraphicbackground{#1}} +\define@key{pdfgraphic}{linewidth} {\gdef\@PDFboxrule{#1}} +\define@key{pdfgraphic}{rulesep} {\gdef\@PDFboxsep{#1}} +\gdef\@PDFgraphiccolor{black} +\gdef\@PDFgraphiclinecolor{white} +\gdef\@PDFgraphicbackground{white} +\gdef\@PDFboxrule{0pt} +\gdef\@PDFboxsep{0pt} +%% +%% Tweak to grab all the packages used in the master doc. +%% This forces you to load pdftricks as the first package. +%% +\newenvironment{psinputs}{\begingroup + \newwrite\CVinputs + \immediate\openout\CVinputs=tmp.inputs + \def\usepackage{\@ifnextchar[\@CVUsepackage\@@CVUsepackage} + \def\@CVUsepackage[##1]##2{\immediate\write\CVinputs% + {\string\usepackage[##1]{##2}}} + \def\@@CVUsepackage##1{\immediate\write\CVinputs% + {\string\usepackage{##1}}} + } + {\endgroup\immediate\closeout\CVinputs} +%% +%% Arrays to keep the fig numbers +%% +\newcounter{arraylength}% +\newcounter{ArrayIndex}% +\newcounter{zeroCtr}% +\newcounter{recordCtr} +\setcounter{recordCtr}{1} +\newcounter{Ctr} +\def\DeclareArray#1{\Array{#1}[0]{}}% +% +\def\Array#1[#2]#3{% + \expandafter\gdef\csname #1#2\endcsname{#3}% + \expandafter\gdef\csname #1\endcsname[##1]{\csname #1##1\endcsname}}% +% +\def\getArraylength#1{\setcounter{arraylength}{0}% + \loop\expandafter\ifx\csname #1\thearraylength\endcsname\relax% + \else\stepcounter{arraylength}\repeat}% +% +\def\addToArray#1#2{\setcounter{arraylength}{0}% + \loop\expandafter\ifx\csname #1\thearraylength\endcsname\relax% + \else\stepcounter{arraylength}\repeat% + \Array{#1}[\thearraylength]{#2}}% +% +\def\clearArray#1{\getArraylength{#1}% + \loop\ifnum\c@arraylength >0% + \global\expandafter\let\csname #1\thearraylength\endcsname\relax% + \addtocounter{arraylength}{-1}\repeat}% +% +\long\def\ArrayIterator#1#2{% + \setcounter{ArrayIndex}{1}\getArraylength{#1}% + \setcounter{zeroCtr}{\c@arraylength}% + \loop\ifnum\c@ArrayIndex<\c@zeroCtr{#2}% + \stepcounter{ArrayIndex}\repeat% +}% +\def\@nnil{\@nil} +\def\@empty{} +\def\@cvrstop#1\@@#2{} +%% +%% Equivalent of \@tfor and \@for where any delimiter can be +%% provided instead of LaTeX's default comma character +%% +\long\def\cvr@delimfor#1#2#3{\DeclareArray{#1}\clearArray{#1}% + \long\def\@icvrloop##1#2##2\@@##3{\def##3{##1}\ifx ##3\@nnil% + \expandafter\@cvrstop \else\addToArray{#1}{##1}% + \relax\expandafter\@icvrloop\fi##2\@@##3}% + \long\def\@cvrloop##1#2##2#2##3\@@##4{\addToArray{#1}{##1}% + \def##4{##1}\ifx ##4\@nnil \else% + \def##4{##2}\def\y@y{##2}\ifx\y@y\@nnil\else% + \addToArray{#1}{##2}\fi\ifx ##4\@nnil \else% + \@icvrloop ##3\@@##4\fi\fi}% + \expandafter\def\expandafter\@fortmp\expandafter{#3}% + \ifx\@fortmp\@empty \else% + \expandafter\@cvrloop#3#2\@nil#2\@nil\@@\@ee@\fi}% +% +% Dont look into the following code. It is harmful +% for your eyes and brain as well. +% +\newcounter{f@irstCtr} +\newcounter{s@econdCtr} +\long\gdef\NoProcess[#1]{% + \long\def\@i@@noprocess##1,##2\@@##3{\def##3{##1}\ifx ##3\@nnil% + \expandafter\@cvrstop \else + \expandafter\hyphencheck##1-@-*[*] + \relax\expandafter\@i@@noprocess\fi##2\@@##3}% + \long\def\@@@noprocess##1,##2,##3\@@##4{ + \expandafter\hyphencheck##1-@-*[*] + \def##4{##1}\ifx ##4\@nnil \else% + \def##4{##2}\def\y@y{##2}\ifx\y@y\@nnil\else% + \expandafter\hyphencheck##2-@-*[*] + \fi\ifx ##4\@nnil \else% + \@i@@noprocess ##3\@@##4\fi\fi}% + \expandafter\def\expandafter\@fortmp\expandafter{#1}% + \ifx\@fortmp\@empty \else% + \expandafter\@@@noprocess#1,\@nil,\@nil\@@\@ee@\fi}% +\def\d@d#1[*]{} +\def\hyphencheck#1-#2-#3{\def\r@r{@}\def\s@s{*}\edef\c@c{#3} + \ifx\c@c\r@r + \setcounter{f@irstCtr}{#1} + \setcounter{s@econdCtr}{#2} + \stepcounter{s@econdCtr} + \loop\ifnum\thes@econdCtr > \thef@irstCtr% + \expandafter\edef\csname Fig\thef@irstCtr\endcsname{TRUE} + \stepcounter{f@irstCtr} + \repeat% + \else\ifx\c@c\s@s% + \expandafter\edef\csname Fig#1\endcsname{TRUE} + \fi\fi\d@d} + +%% +%% +%% End of file `pdftricks.sty' +%% diff --git a/doc/reference.xml b/doc/reference/reference.xml similarity index 66% rename from doc/reference.xml rename to doc/reference/reference.xml index 15b8da4..4850109 100644 --- a/doc/reference.xml +++ b/doc/reference/reference.xml @@ -1,8 +1,8 @@ -
- +
+ If you are reading the html version of this document and are thinking of printing it out, you might be interested in the nicely @@ -23,14 +23,7 @@ aspect of the environment that the Ibex Core provides to client applications, from the bottom up. If you want to be an Ibex expert, this is the right document to read. It is assumed that you are already - familiar with XML and with either JavaScript or ECMAscript. If - you are not familiar with ECMAscript, some reference materials are - provided in - - The wildebeest sequence (how the Ibex Core gets onto the - client's computer, and how it knows where to download the initial - .ibex from) is not described in this document, since it - will be different for every platform that Ibex is ported to. + familiar with XML and with either JavaScript or ECMAscript. If you need to use or rely on some behavior you notice in the Ibex Core, but which is not clearly defined here, please post to Ibex itself; the native code (or Java bytecode) that runs on - the client. This term does not include the wildebeest + the client. This term does not include the Wildebeest or the UI - a set of files (mostly XML, JavaScript, and PNG images) - bundled up in a zip archive, ending with the "..ibex" + A set of files (mostly XML, JavaScript, and PNG images) + bundled up in a zip archive, ending with the ".ibex" extension. Together, these files specify the appearance and - behavior of the application's user interface. Sometimes - we'll refer to this as the ".ibex" to be clear that we're - talking about the actual zip archive, rather than its visual - appearance when rendered on the screen. + behavior of the application's user interface. + We will use the term "the server" to refer to any other @@ -58,11 +49,11 @@ to. Note that it is possible for the client and server to be the same machine. - - this is a very small piece of code that is downloaded the + + This is a very small piece of code that is downloaded the first time a client uses Ibex. It downloads the Ibex core, verifies its signature, and launches it with the appropriate - parameters indicating where to find the initial UI. The + parameters indicating where to find the initial UI. Wildebeest works differently on every platform, and is outside the scope of this document. @@ -85,492 +76,572 @@ We will use the terms JavaScript and ECMAScript interchangeably in this document. The Ibex interpreter is not completely ECMA-compliant, however (see for details). -
-
- -
- - Each top-level window in an Ibex UI is called a - surface. There are two kinds of surfaces: frames, - which usually have a platform-specific titlebar and border, and - windows, which never have any additional platform-specific - decorations. - - Whenever we refer to the size or position of a surface, we are - referring to the size or position of the UI-accessible portion of the - surface; this does not include any platform-specific decorations. This - means that if you set the position of a frame to (0,0), the - platform-specific titlebar will actually be off the screen on most - platforms (it will be above and to the left of the top-left corner of - the screen). - - Surfaces are not actual JavaScript objects; you cannot obtain a - reference to a surface. However, each surface is uniquely identified - by its root box, described in the next section. - -
+ appendix="ECMAscript compliance"/> for details). + -
+
- A box is the fundamental unit from which all Ibex user - interfaces are built. Boxes can contain other boxes (known as - children). Each Surface has a single box associated with it - called the root box; the root box and its children (and its - children's children, and so on) form the surface's box tree. - - There are three ways to think of a box: as a rendered visualization on - the screen (the "Visual Representation"), as a JavaScript object (the - "Object Representation"), and as an XML tag (the "XML - Representation"). - - FIXME: diagram here - - All three representations are equally valid, and being able to figure - out what an action in one representation would mean in terms of the other - two representations is crucial to a solid understanding of Ibex. - -
+
+ + + + A user typically begins an Ibex session by clicking on a link to + an Ibex application. This link serves the {\tt launch.html} file + to the user's browser, which in turn downloads the appropriate + {\it Wildebeest} -- currently either an ActiveX Control + (Win32/MSIE), XPInstaller (Mozilla), or Signed Applet (all + others). + + The Wildebeest downloads the appropriate core for the user's + machine and verifies its digital signature. It then launches the + core, which downloads the UI (an .ibex archive), loads it, + applies the main.t template (found in the archive), and + renders it onto the screen, running any associated JavaScript + code. + + The user interacts with the application by clicking and moving the + mouse, and by pressing keys on the keyboard. These actions trigger + fragments of JavaScript code which are designated to handle events. + This JavaScript code can then relay important information back to the + server using XML-RPC or SOAP, or it can modify the structure and + properties of the user interface to change its appearance, thereby + giving feedback to the user. + + The Ibex core quits when the last remaining surface has been destroyed. - Each box is a full-fledged ECMAscript object, and can store key-value - pairs as properties. Some of these keys have special meaning, which - will be explained later. Each box's numeric properties hold its - child boxes. -
-
- Each box occupies a rectangular region on the surface. The visual - appearance of a surface is created by rendering each box in its tree. - Unless the clip attribute is false, each box will - clip its childrens' visual representations to its own, so that the - children appear "confined to" the parent. Children are rendered after - their parents so they appear "on top of" their parents (they obscure - them). - - Each box has two major visual components, each with subcomponents: - - FIXME: diagram - +
+ + + Each top-level window in an Ibex UI is called a + surface. There are two kinds of surfaces: frames, + which usually have a platform-specific titlebar and border, and + windows, which never have any additional platform-specific + decorations. + + Whenever we refer to the size or position + of a surface, we are referring to the size or position of the + UI-accessible portion of the surface; this does not include any + platform-specific decorations. This means that if you set the + position of a frame to (0,0), the platform-specific titlebar will + actually be off the screen on most platforms (it will be above and + to the left of the top-left corner of the screen). + + Surfaces are not actual JavaScript objects; you cannot obtain a + reference to a surface. However, each surface is uniquely identified + by its root box, described in the next section. + +
+ +
+ + A box is the fundamental unit from which all Ibex user + interfaces are built. Boxes can contain other boxes (referred to as + its children). Each surface has a single box associated with + it called the root box; the root box and its children (and + its children's children, and so on) form the surface's box + tree. + + There are three ways to think of a box: - A path, which consists of zero or more lines and - curves. The path may be filled with a color, gradient, or - texture, and may be stroked with a line of a given thickness - and color. If the path is not specified, it defaults to the - perimiter of the box. - - - The path has an associated strokecolor, which is a - color - - The path has an associated strokewidth, which is a - number specifying the width of the stroke. - - The path also has a fill, which is either a color, gradient, or - texture - - A single line of text, which can be rendered in - different fonts, colors, and sizes. - - - The text has an associated font, which currently can be - any font supported by the library. - - The text also has an associated fontsize - - The text is drawn in an associated textcolor - + + As a rendered visualization on the screen (the "Visual Representation") + + As a JavaScript object (the "Object Representation") + + As as an XML tag (the "XML Template Representation"). + - These eight components plus the size of a box fully specify its - appearance. Every single box you see in Ibex is drawn only on the - basis of these components and its size. - + + + All three representations are equally valid, and being able to + figure out what an action in one representation would mean in terms + of the other two representations is crucial to a solid understanding + of Ibex. +
+
+ +
+ + A template (discussed in the next section) is an XML file which acts + as a blueprint for constructing a tree of boxes. We call this + construction process applying, since unlike + instantiation in object-oriented programming systems, you + always apply a template to a pre-existing box, and you can apply + multiple templates to the same box. + + Each XML tag corresponds to a single box, or to another template + which will be applied to that box. For example, a scrollbar + template, when applied, will construct a tree of boxes which has the + visual appearance and behavior of a scrollbar. + + Although it is useful to think of the XML tags as being boxes, keep + in mind that the XML representation is only a blueprint for + constructing a tree of JavaScript objects. Once the template has + been instantiated, the XML is effectively "thrown away", and + JavaScript code is free to alter the boxes. Once the process of + applying a template is complete, Ibex completely forgets the fact + that it has applied a particular template to a particular box. One + consequence of this approach is that if you think of templates as + classes, then Ibex has no equivalent for Java's instanceof + operator. + + Each template is an XML document whose root element is + <ibex>. Here is a sample template file: -
+ 
+  
 
-    A template (discussed in the next section) is an XML file which acts
-    as a blueprint for constructing a tree of boxes.  We call this
-    construction process applying, since unlike
-    instantiation, you always apply a template to a pre-existing
-    box, and you can apply multiple templates to the same box.  Each XML
-    tag corresponds to a single box, or to another template which will be
-    applied to that box.  For example, a scrollbar template, when
-    applied, will construct a tree of boxes which has the visual
-    appearance and behavior of a scrollbar.
-    
-    Although it is useful to think of the XML tags as being boxes, keep in
-    mind that the XML representation is only a blueprint for constructing
-    a tree of JavaScript objects.  Once the template has been
-    instantiated, the XML is effectively "thrown away", and JavaScript code is
-    free to alter the boxes.
-    
-
-
+ + This is a cool widget. + -
+ // this code is executed only once + static = { instances : [] }; - Each template is an XML document whose root element - is <ibex>. Any text content of the root element is - ignored, and may safely be used for comments. The root element may - have any of the following elements as children, each of which may - appear no more than once, and which must appear in this order: - - Here is a sample Ibex file: - - 
-  
-      This is a sample Ibex file. Text up here is ignored.
-      Copyright (C) 2004 Mustapha Mond.
-      
-          // code here will be executed only once
-      
-      
+          
+
- - - The following description of the box application is extremely detailed - and precise; it is intended for UI designers who need to know the - exact order in which each event happens. FIXME: - easier description. While this whole process sounds very - complex, it actually works pretty intuitively. The description below - is given in great detail since most applications will wind up being - unintentionally dependent on subtle features of this process. - However, most of the time you can just pretend that the XML tags and - the boxes are the same thing. - - To apply an XML tag X to a box B, perform the following - operations, in this order: - - + The following two namespaces are predefined and need not be declared + using xmlns: - Allocate a fresh scope s whose parent scope is - b. - - Process each child element or text segment of X in the - order they appear in the document: For each text - segment t: + + http://xmlns.ibex.org/meta - - Treat t a JavaScript script, and execute it - with s as the root scope. - + This will be referred to as the "meta namespace" in the + remainder of this document. + - For each child element x of - x: + + http://xmlns.ibex.org/ui - - Create a new box b. - - If the name of tag x is not "box" (in the - default XML namespace), prepend the tag's namespace - identifier uri (if any) to the name of the tag, and use - the result as a key to retrieve a property from the root - stream (defined later). Interpret the resulting stream as - a template and apply that template to b. - - (recursively) apply x to b. - - If x has an id attribute, declare a variable - in s whose name is the value of the id - attribute, prefixed with the $ character, and whose - value is b - - Copy any $-variables created during the application - of x into scope s. - - Append b as the last child of b. - - - Apply any attributes on x to b, except for - id. Since XML specifies that the order of attributes - cannot be significant, Ibex processes attributes in - alphabetical order by attribute name. For example, if - x has the attribute foo="bar", then the - equivalent of the statement B.foo="bar"; will be - performed, with the following exceptions: + This will be referred to as the "ui namespace" in the + remainder of this document. + - - If the value portion of the attribute is the string - "true", put the boolean true. If the - value is "false", put the boolean false. - - If the value is a valid ECMAscript number, put it as a - number (instead of a string). - - If the value begins with a dollar sign ($), - retrieve the value of the corresponding variable in - s and use that value instead. - - If the value begins with a dot (.), prepend the - attributes' namespace identifier uri (if any) and - interpret the remainder as a property to be retrieved from - the root stream (defined later). - - + Additionally, the default namespace for the document will be set to + the template's package FIXME. - The last two steps are referred to as the initialization of the - node. There are two important aspects of this ordering to be aware of: - - - - A given box will be fully initialized before its parent is - given a reference to that box. This way, parents can be - certain that they will never wind up accessing a box when it - is in a partially-initialized state. - - Attributes are applied after scripts are run so that - the attributes will trigger any traps (defined later) - placed by the script. - - - -
- -
- - A user begins by specifying the URL of an Ibex application run. - Usually this is done by visiting a web page which uses the - wildebeest to install the core if it is not already on the user's - machine, but you can also supply the URL on the command line. - - The Ibex Core downloads the .ibex for the application, loads it, applies - the main.ibex template and renders it onto the screen, running - any associated ECMAscript code. - - The user interacts with the application by clicking and moving the - mouse, and by pressing keys on the keyboard. These actions trigger - fragments of JavaScript code which are designated to handle events. - This JavaScript code can then relay important information back to the - server using XML-RPC or SOAP, or it can modify the structure and - properties of the user interface to change its appearance, thereby - giving feedback to the user. - - - DIAGRAM: graphic here showing the circular feedback cycle. - - - The Ibex core quits when the last remaining surface has been destroyed. - -
+
- -
+ If the root <ibex> element contains any non-whitespace + text content, this text is interpreted as JavaScript code and is + executed the first time the template is referenced. This code is + executed in a fresh scope containing two predefined properties: + + + The Ibex Object (described in ) + + + + A reference to this template's static object, which is + initially null. The static object can be accessed (read + and written) from both static scripts as well as instance + scripts in a particular template. FIXME + - The size and position of every other box is determined - by its properties, its childrens' sizes, and its parent's size and position. - Box layout and rendering happens in four phases: packing, - constraining, placing, and rendering. The Core is careful to only - perform a phase on a box if the box has changed in a way that - invalidates the work done the last time that phase was performed. - The - packing and constraining phases are performed in a single traversal of - the tree (packing is preorder, constraining is postorder), and the - placing and rendering phases are performed in a second traversal of - the tree (first placing, then rendering, both preorder). - - For brevity, the rest of this chapter deals only with width and - columns. Height and rows is treated identically and independently. - Also, it is important to note that the term minimum width is - not the same thing as the property minwidth, although they - are closely related. - -
- - When the user resizes a window, Ibex changes the root box's - maxwidth and maxheight to match the size chosen by - the user and then determines the root box's size using the same sizing - rules it uses for other boxes. - - Ibex will always attempt to prevent the - user from making the surface smaller than the root box's - minwidth and minheight. If the hshrink or - vshrink flag is set, Ibex will try to prevent the user from - resizing the surface at all. However, not all platforms give Ibex - enough control to do this. -
+ +
-
- - When talking about positioning, we will often refer to the - alignment point. - - - - If the align property is "center", then the - alignment point is the center of the box. - - If the align property is "topleft", - "bottomleft", "topright", or - "bottomright", then the alignment point is - corresponding corner of the box. - - If the align property is "top", - "bottom", "right", or "left", then - the alignment point is middle of the corresponding edge of the - box. - + Any immediate children of the root element which are in the + meta namespace are treated as metadata and are exempted from + the rest of the template application process. Currently only one + type of metadata element is defined: + + + <meta:doc>: structured documentation for the + template. - FIXME: diagram - - When positioning a child box, the alignment point is determined by the - parent's align property. When positioning a visual - element (a texture, path, or text string) within a box, the alignment - point is determined by the box's own align property. - - A simple way to think about this is that whenever there are two boxes - involved in the decision, you should use the parent's alignment point. - -
- -
- - of cells is created within the parent. If the parent's - cols property is set to 0, the cell grid has an infinite - number of columns. Either cols or rows must be - zero, but not both. - - If a child's visible property is false, it does - not occupy any cells (and is not rendered). Otherwise, each child - occupies a rectangular set of cells child.colspan cells - wide and child.rowspan cells high. - - The Core iterates over the cells in the grid in the following - order: if rows is 0, the Core iterates across each column - before proceeding to the next row; otherwise rows come before - columns. At each cell, the Core attempts to place the first - remaining unplaced child's top-left corner in that cell (with - the child occupying some set of cells extending down and to the - right of that cell). If the parent has a fixed number of columns - and the child's colspan exceeds that limit, the child is - placed in column zero regardless, but only occupies the available - set of cells (it does not "hang off the end" of the box). - - - - 
-    
-        
-        
-        
-        
-        
-    
-
- - Notes on the layout example: - - +
- Box '3' doesn't fit in the gap after '2', nor in the gaps either - side of '2' on the next row, hence it is pushed onto the 3rd row. +
- Box '4' would fit in the gaps around '2', but must be placed - after it's preceeding box, '3'. + All remaining children of the root element are treated as elements + to be applied to the box, in the order in which they appear + in the file using the following procedure. + + + + + + ... FIXME + + During a box initialization, script-private references to a + box's descendants with id attributes are placed on the + box. These references allow scripts on that box to easily refer + to descendant nodes created by the template in which the script + appears. For example, these two blocks of code have exactly the + same effect: + + 
+                                 
+                           
+          $foo.color = "red";             var $foo = this[0];
+                                          $foo.color = "red";
+                                
+
+ + + + To apply an XML tag x to a box b, perform the following + operations, in this order: + + + + Allocate a fresh scope s whose parent scope is + b. + + Process each child element or text segment of x + in the order they appear in the document: + + + + Treat each text segment t as JavaScript code + and execute it with s as the root scope. + + For each child element x' of x: + + + Create a new box b'. + + If the name of tag x' is not + "box" in the ui namespace, prepend the + tag's namespace identifier uri (if any) to the name of + the tag, and use the result as a key to retrieve a + property from the root stream (defined later). + Interpret the resulting stream as a template and apply + that template to b'. + + (recursively) apply x' to b'. + + If x' has an id attribute, declare a variable + in s whose name is the value of the id + attribute, prefixed with the $ character, and whose + value is b' + + Copy any $-variables created during the application + of x' into scope s. + + Append b' as the last child of b. + + + + Apply any attributes on x to b, except for + id. Since XML specifies that the order of attributes + cannot be significant, Ibex processes attributes in + alphabetical order by attribute name. For example, if + x has the attribute foo="bar", then the + equivalent of the statement B.foo="bar"; will be + performed, with the following exceptions: + + + If the value portion of the attribute is the string + "true", put the boolean true. If the + value is "false", put the boolean false. + + If the value is a valid ECMAscript number, put it as a + number (instead of a string). + + If the value begins with a dollar sign ($), + retrieve the value of the corresponding variable in + s and use that value instead. + + If the value begins with a dot (.), prepend the + attributes' namespace identifier uri (if any) and + interpret the remainder as a property to be retrieved from + the root stream (defined later). + + + + + + The last two steps are referred to as the initialization of the + node. There are two important aspects of this ordering to be aware of: + + + + A given box will be fully initialized before its parent is + given a reference to that box. This way, parents can be + certain that they will never wind up accessing a box when it + is in a partially-initialized state. + + Attributes are applied after scripts are run so that + the attributes will trigger any traps (defined later) + placed by the script. + + - +
-
- -
- - - - Each box's minimum width is computed recursively as the - maximum of: - - - Its minwidth - - The width of the box's text (after applying the - box's transform). - - The width of the box's path (after applying the box's - transform) if the box is packed. - - The width of the bounding box enclosing the box's cells. - - - The minimum width of each cell is computed as the minimum - width of the box occupying it divided by the box's - colspan. - - If a box's hshrink property is set to - true, the box's maximum width is the same as its - minimum width; otherwise it is the box's - maxwidth. - - The maximum width of each cell is the maxwidth of - the box occupying it divided by the box's - colspan. - - - -
- -
- - - - Each column's actual width is set to the maximum - minimum width of all the cells in that column. - NOTE: although a column or row can be sized smaller - than its "minimum width" or larger than its "maximum width", a - box will never be smaller than its minwidth or - larger than its maxwidth. - - Each column's maximum width is the largest maximum width of - the cells in that column, but no smaller than the column's - minimum width. - - The slack is the difference between the parent's width - and the sum of its columns' actual width. The slack is - divided equally among the columns. Any column which has - exceeded its maximum width is set to its maximum width, and - the difference is returned to the slack. This process is - repeated until the slack is zero or all columns are at their - maximum width. - - Next, the rows and columns are positioned within the parent - box. The rows and columns are transformed according to the - parent's transform property, and the bounding box of - the resulting cells are placed such that the cells' alignment - point coincides with the parent's alignment point (both - alignment points are determined by the parent's align - property). FIXME: diagram - - Packed boxes: Each packed box's actual position - and size is then set to the aggregation of the actual sizes of - the cells it spans. If this size exceeds the box's maximum - width, the box is sized to its maximum width and centered - horizontally within the space occupied by its cells. - - Non-packed boxes: each non-packed box is transformed - according to the parent's transform property and then - positioned so that its alignment point is (child.x, - child.y) pixels from the parent's alignment point (both - alignment points are determined by the parent's align - property). - - +
-
+ +
+
+ + Each box occupies a rectangular region on the surface. The visual + appearance of a surface is created by rendering each box in its tree. + Unless the clip attribute is false, each box will + clip its childrens' visual representations to its own, so that the + children appear "confined to" the parent. Children are rendered after + their parents so they appear "on top of" their parents. + + Each box has two major visual components, each with subcomponents: + + FIXME: diagram + + + + A box's path consists of zero or more lines and curves. + The path may be filled with a color, gradient, or texture, and + may be stroked with a line of a given thickness and color. If + the path is not specified, it defaults to the perimiter of the + box. [Note: Vector Graphics support (including the ability + to set the path property to anything other than the + default) is currently not implemented]. + + A path also has: + + + an associated strokecolor, which is a color + + an associated strokewidth, which is a number + specifying the width of the stroke. [Note: Vector + Graphics support (including the strokewidth + property) is currently not implemented] + + a fill, which is either a color, gradient, or + texture + + + + + + Each box also has a single line of text, whose + appearance is determined by its: + + + associated font, which can be any font supported by + the + library. + + an associated fontsize in pixels + + an associated textcolor + + + + These eight components plus the size of a box fully specify its + appearance. Every single box you see in Ibex is drawn only on the + basis of these components and its size. +
+ +
+ + The size and position of every box is determined by its + properties, its childrens' sizes, and its parent's size and + position. Box layout and rendering happens in four phases: + packing, constraining, placing, and + rendering. The Core is careful to only perform a phase on + a box if the box has changed in a way that invalidates the work + done the last time that phase was performed. The packing and + constraining phases are performed in a single traversal of the + tree (packing is preorder, constraining is postorder), and the + placing and rendering phases are performed in a second traversal + of the tree (first placing, then rendering, both preorder). + + For brevity, the rest of this chapter deals only with width and + columns. Height and rows is treated identically and independently. + Also, it is important to note that the term minimum width is + not the same thing as the property minwidth, although they + are closely related. + + + + When the user resizes a window, Ibex changes the root box's + maxwidth and maxheight to match the size chosen by + the user and then determines the root box's size using the same sizing + rules it uses for other boxes. + + Ibex will always attempt to prevent the + user from making the surface smaller than the root box's + minwidth and minheight. If the hshrink or + vshrink flag is set, Ibex will try to prevent the user from + resizing the surface at all. However, not all platforms give Ibex + enough control to do this. + + + + + When talking about positioning, we will often refer to the + alignment point. + + If the align property is "center", then the + alignment point is the center of the box. + + If the align property is "topleft", + "bottomleft", "topright", or + "bottomright", then the alignment point is + corresponding corner of the box. + + If the align property is "top", + "bottom", "right", or "left", then + the alignment point is middle of the corresponding edge of the + box. + + When positioning a child box, the alignment point is determined by + the parent's align property. When rendering a + visual element (a texture, path, or text string) within a box, the + alignment point is determined by the box's own align + property. + + A simple way to think about this is that whenever there are two boxes + involved in the decision, you should use the parent's alignment point. + +
+ + A grid of cells is created within the parent. If the + parent's cols property is set to 0, the cell grid has an + infinite number of columns. Either cols or rows + must be zero, but not both. + + If a child's visible property is false, it does + not occupy any cells (and is not rendered). Otherwise, each child + occupies a rectangular set of cells child.colspan cells + wide and child.rowspan cells high. + + The Core iterates over the cells in the grid in the following + order: if rows is 0, the Core iterates across each column + before proceeding to the next row; otherwise rows come before + columns. At each cell, the Core attempts to place the first + remaining unplaced child's top-left corner in that cell + (with the child occupying some set of cells extending down and + to the right of that cell). If the parent has a fixed number of + columns and the child's colspan exceeds that limit, the + child is placed in column zero regardless, but only occupies the + available set of cells (it does not "hang off the end" of the + box). + + 
+      
+          
+          
+          
+          
+          
+      
+
+
+
+
+ +
+ +
+ + Each box's minimum width is computed recursively as the + maximum of: + + + Its minwidth + + The width of the box's text (after applying the + box's transform) [Note: Vector Graphics support + (including the transform property) is currently not + implemented]. + + The width of the box's path (after applying the box's + transform) if the box is packed. + + The width of the bounding box enclosing the box's cells. + + + The minimum width of each cell is computed as the minimum + width of the box occupying it divided by the box's + colspan. + + If a box's hshrink property is set to + true, the box's maximum width is the same as its + minimum width; otherwise it is the box's + maxwidth. + + The maximum width of each cell is the maxwidth of + the box occupying it divided by the box's + colspan. +
+ +
+ + Each column's actual width is set to the maximum + minimum width of all the cells in that column. + NOTE: although a column or row can be sized smaller + than its "minimum width" or larger than its "maximum width", a + box will never be smaller than its minwidth or + larger than its maxwidth. + + Each column's maximum width is the largest maximum width of + the cells in that column, but no smaller than the column's + minimum width. + + A value k is chosen such that when each column's width + is set to min(maximum width, max(minimum width, k)), + the sum of all the column widths equals the parent's width. + If no such value exists, positive or negative infinity is used + (whichever is appropriate). Each column is then set to the + width dictated by k. + + Next, the rows and columns are positioned within the parent + box. The rows and columns are transformed according to the + parent's transform property [Note: Vector Graphics + support (including the transform property) is currently + not implemented]., and the bounding box of the resulting + cells are placed such that the cells' alignment point + coincides with the parent's alignment point (both alignment + points are determined by the parent's align property). + + + + Packed boxes: Each packed box's actual position + and size is then set to the aggregation of the actual sizes of + the cells it spans. If this size exceeds the box's maximum + width, the box is sized to its maximum width and centered + horizontally within the space occupied by its cells. + + Non-packed boxes: each non-packed box is transformed + according to the parent's transform property and then + positioned so that its alignment point is (child.x, + child.y) pixels from the parent's alignment point (both + alignment points are determined by the parent's align + property). + +
+
+
Boxes are rendered in a depth-first, pre-order traversal. Note that @@ -580,7 +651,9 @@ If the box's transform property is non-null, the coordinate space is transformed accordingly for the rest of - this phase and for the rendering of all children. + this phase and for the rendering of all children. [Note: + Vector Graphics support (including the transform + property) is currently not implemented]. If the box is packed and has a non-null path, the path is translated such that the alignment point of the path's @@ -601,7 +674,7 @@ alignment points are determined by the box's align property). - The box's children are rendered (pre-prder traversal). + The box's children are rendered (pre-order traversal). @@ -612,6 +685,11 @@
+ Each box is a full-fledged ECMAscript object, and can store + key-value pairs as properties. Some of these keys have special + meaning, which will be explained later. Each box's numeric + properties hold its child boxes. +
Every box has several special properties which control how it is @@ -620,15 +698,19 @@ put will be ignored. + If the value is a 5-character hex string (#RGB), 7-character hex string (#RRGGBB), 9-character hex string (#AARRGGBB), the box's stroke color will be set to that color. - If the value is one of the colors - (the same set of color names supported by SVG), the stroke - color be set to that color. - If the value is null, the stroke color will be set to - clear (#00000000). + + If the value is one of the colors (the same set of color names + supported by SVG), the stroke color be set to that color. + + If the value is null, the stroke color will be set + to clear (#00000000). @@ -654,23 +736,23 @@ The box's text; writing null to this property sets it - to "". + to "". - + + The color in which to render the font; accepts the same values as strokecolor. + + + When an object is written to this property, its stream is read - using the , and the resulting font is used to render the + using the , + and the resulting font is used to render the box's text. The size (in points) to render the text. - - - The color in which to render the font; accepts the same values as strokecolor. -
@@ -682,36 +764,27 @@ its children and the bounding box of its path. - + If the box is a root box, this is the (x/y)-coordinate of the surface; otherwise it is the distance between the parent's alignment point and this box's alignment point. - - The distance between this box's (left/top) edge and the root - box's (left/top) edge. A put to this property has the same - effect as a put to the (x/y) property, - except that it is relative to the root box rather than to this - box's parent. FIXME is this fakeable? How is - distance measured? - - - + The desired minimum width and height. - + The desired maximum width and height. - - When read, this is the (width/height) of this box. Writing to - this property is equivalent to writing to both the - minimum and maximum (width/height). + + When read, this is the current (width/height) of this box. + Writing to this property is equivalent to writing to + both the minimum and maximum (width/height). - + The number of (columns/rows) in which to lay out the children of this box. If set to zero, the number of (columns/rows) is unconstrained. Either rows or cols must be zero. If @@ -721,7 +794,7 @@ rows is set to 0, and vice versa. - + The number of (columns/rows) that this box spans within its parent. @@ -731,48 +804,43 @@ - If set to false, this box will be rendered as if its width and - height were zero. If this is a root box, the associated surface - will be hidden. - When reading from this property, the value - false will be returned if this box or any of its - ancestors is not visible. Thus it is possible to write - true to a box's visible property and then - read back false. + If set to false, this box will be rendered as if its + width and height were zero. If this is a root box, the + associated surface will be hidden. + + When reading from this property, the value false will + be returned if this box or any of its ancestors is not + visible. Thus it is possible to write true to a box's + visible property and then read back false. - The layout strategy for this box. + The layout strategy for this box. If set to true, the + box occupies no cells and is laid out independently of its + siblings.
- During a box initialization, script-private references to a box's - descendants with id attributes are placed on the box. These - references allow scripts on that box to easily refer to descendant - nodes created by the template in which the script appears. For - example, these two blocks of code have exactly the same effect: - - 
-                         
-                   
-        $foo.color = "red";       var $foo = this[0];
-                                  $foo.color = "red";
-                        
-
- - The following special properties control how a box's children are laid - out. If a box has a non-null redirect target, reads and writes to these - properties will be forwarded to the redirect target. - - The redirect attribute is very useful for hiding the - internal structure of a widget, and for allowing widgets to act as - "smart" containers for other widgets. For example, a menu widget might - have an invisible child as its redirect target; this way, when boxes - representing items on the menu are added as children of the menu - widget, they do not appear until the menu is pulled down. + + Writing to this property sets the box's redirect target. This + property cannot be read from, and can only be written to if + the value being written is a descendant of the current + value. + + If a box has a non-null redirect target, reads and writes to + any of the other properties in this section will be forwarded + to the redirect target. + + The redirect attribute is very useful for hiding the + internal structure of a widget, and for allowing widgets to act as + "smart" containers for other widgets. For example, a menu widget might + have an invisible child as its redirect target; this way, when boxes + representing items on the menu are added as children of the menu + widget, they do not appear until the menu is pulled down. + The nth child of box b can be accessed by reading from @@ -800,13 +868,9 @@ The number of children this box has. - - Writing to this property sets the box's redirect - target. This property cannot be read from, and can only be - written to once. - - + + FIXME If this box has a parent, this property returns parent.surface; otherwise it returns null. This property is a simple building block that the widget @@ -820,7 +884,7 @@ The shape that the cursor should take when inside this - box. Valid values are: "default " , "wait", + box. Valid values are: "default" , "wait", "crosshair", "text", "hand", and "move", as well as resizing cursors"east", "west", "north", "south", @@ -834,21 +898,6 @@ "default" cursor will be used. - - The (horizontal/vertical) distance between the mouse cursor and this - box's (left/top) edge. Puts to this property are ignored. This - value will not be updated if the mouse is outside the root - box of the surface and no button was pressed when it left. - - - - True if the mouse is inside the rendered region of this box or - any of its children. This value will be false if the mouse is - inside a portion of this box which is covered up by one of - this box's siblings, or one of its ancestors' descendants. Puts - to this value are ignored. - - Reading from this property will return the parent scope used to execute the block of the template @@ -872,47 +921,16 @@ has no effect. - - - These properties are meant to be trapped on FIXME defined later?. Placing a trap on - childadded/childremoved lets a box receive - notification when a child is added/removed. In either - situation, the child will be passed as an argument to the trap - function after the addition or removal has been - performed. - - Note that if the parent's redirect target is set to another - box, these traps will only be invoked when children are - manipulated by reading and writing to the parent. Reads and - writes directly to the redirect target will not trigger - the traps. - - Note also that these traps are still triggered if a box's - redirect target is null. This is useful for - boxes that need to accept children and then relocate them - elsewhere. + + This property is actually a function; invoking + box.distanceto(otherbox) will return an object with two + properties, x and y, containing the horizontal + and vertical distance between the two boxes (negative if + otherbox is to the left of / above box). This + can be used to determine the relative placement of two boxes + on different branches of the box tree. - -
-
- - The following properties are used to notify a box of changes specific - to that particular box. - - - The value true is written to this property when the mouse enters the box. - - - - The value true is written to this property when the mouse leaves the box. - - - - The value true is put to this property after the size - of this box changes. - -
@@ -953,8 +971,8 @@ When the user attempts to close a surface, the value true will be put to this property. Scripts may trap - this property FIXME defined later? to - prevent the window from closing. Putting the value + this property to prevent the window from closing. Putting the + value true to this property on a root box has the same effect as putting null to the thisbox property. @@ -962,7 +980,7 @@ The surface's icon. This is usually displayed on the titlebar of a - window. The value should be the stream name of a PNG image. Note + window. The value should be an object whose stream is a PNG image. Note that not all platforms support this property. @@ -978,7 +996,7 @@
-
+ Every object has a stream associated with it. A stream is a sequence of bytes that can be read or written to. @@ -990,9 +1008,7 @@ be an .ibex template which, when applied, will fully reconstitute the box's state. -
- -
+ Despite the ubiquity of streams, you cannot actually reference a stream, since it is not an object. Instead, you simply reference the @@ -1006,8 +1022,6 @@ just shorthand for saying to perform those actions on the object the stream belongs to. -
-
You can create a stream from a URL by calling @@ -1053,16 +1067,18 @@
+ FIXME + You can access variables within the static block of a template by appending a double period (..) and the variable name to the stream used to load that template: 
-    
+    
             foo = 12;
     ...
     // elsewhere
-    ibex.log.print(org.ibex.themes.monopoly.scrollbar..foo);   // prints "12"
+    ibex.log.print(org.ibex.themes.linux.scrollbar..foo);  // prints "12"
@@ -1087,18 +1103,18 @@ You can read a UTF-8 encoded string from a stream like this: 
-    var myString = ibex.stream.fromUTF(ibex.stream.url("utf8:this is a test"));
+    var myString = ibex.stream.fromUTF(ibex.stream.url("utf8:testing..."));
You can also parse XML from a stream using SAX like this: 
     ibex.stream.xml.sax(
-        ibex.stream.url("http://foo.com/foo.xml"),
-            { beginElement : function(tagname, attributeKeyValuePairs) { ... },
-              endElement   : function(tagname) { ... },
-              content      : function(contentString) { ... }
-              whitespace   : function(whitespaceString) { ... }
-            });
+      ibex.stream.url("http://foo.com/foo.xml"),
+        { beginElement : function(tagname, attributeKeyValuePairs) { ... },
+          endElement   : function(tagname) { ... },
+          content      : function(contentString) { ... }
+          whitespace   : function(whitespaceString) { ... }
+        });
@@ -1140,24 +1156,21 @@ - - log the debug message m, optionally dumping object + + log the debug messages m1 through mn. o - - log the informational message m, optionally dumping - object o + + log the info messages m1 through mn. - - log the warning message m, optionally dumping object - o + + log the warning messages m1 through mn. - - log the error message m, optionally dumping object - o + + log the error messages m1 through mn. @@ -1229,10 +1242,6 @@ - - not yet implemented - - return an XML-RPC call object with endpoint URL u @@ -1329,11 +1338,11 @@ that property is written to. 
-    
+    
         foo ++= function(z) {
            ibex.log.info("foo is " + z);
         }
-    
+
If another script were to set the property "foo" @@ -1349,13 +1358,13 @@ is applied to multiple traps. For example: 
-    
+    
         func ++= function(z) {
             ibex.log.info("called trap " + trapname);
         }
         foo ++= func;
         bar ++= func;
-    
+
@@ -1364,27 +1373,27 @@ function you added as a trap: 
-    
+    
         var myfunc = function(z) { /* ... */ }
         // add the trap
         func ++= myfunc;
         // ...
         // remove the trap
         func --= myfunc;
-    
+
- When the property is written to, each of the trap functions placed - on it will be invoked in the opposite order that they were placed on - the box -- the most recently placed trap will execute first. This - last-to-first execution of traps is called cascading. After the - last trap is invoked, the value is stored on the box (remember, boxes - are objects, so they can hold properties just like all other - ECMAscript objects). + When the trapped property is written to, each of the trap + functions placed on it will be invoked in the opposite order that + they were placed on the box -- the most recently placed trap will + execute first. This last-to-first execution of traps is called + cascading. After the last trap is invoked, the value is + stored on the box (remember, boxes are objects, so they can hold + properties just like all other ECMAscript objects).
@@ -1395,12 +1404,12 @@ lower traps), you can use cascade. For example: 
-    
+    
         color ++= function(c) {
             ibex.log.info("refusing to change colors!");
             cascade = "black";
         }
-    
+
This effectively creates a box whose color cannot be changed, and @@ -1409,20 +1418,20 @@ Do not try to do something like this: 
-    
+    
         color ++= function(z) {
             color = "black";      // INFINITE LOOP! BAD!!!
         }
-    
+
To prevent automatic cascading, return true from your function: 
-    
+    
         color ++= function(z) {
             return true;          // the box's color will not change
         }
-    
+
@@ -1434,9 +1443,9 @@ also do not automatically cascade. 
-    
+    
         doublewidth ++= function() { return 2 * width; }
-    
+
If another script attempts to read from the doublewidth @@ -1448,9 +1457,9 @@ You can manually cascade on read traps as well: 
-    
+    
         text ++= function() { return "my text is " + cascade; }
-    
+
Read traps are only rarely needed -- most of the time a write trap @@ -1467,7 +1476,7 @@ Properties"/> except for childadded, childremoved and surface. FIXME: remove? - + If an uncaught exception is thrown from a trap, Ibex will log the exception, but will not propagate it to the code which @@ -1602,14 +1611,14 @@ example prints out "first second third fourth" in that order. 
-    
+    
         _Press1 ++= function(b) { ibex.log.info("first"); }
          Press1 ++= function(b) { ibex.log.info("fourth"); }
-        
+        
           _Press1 ++= function(b) { ibex.log.info("second"); }
            Press1 ++= function(b) { ibex.log.info("third"); }
-        
-    
+        
+
In general, you should use the non-underscore names to respond @@ -1631,17 +1640,42 @@ This will immediately cease the propagation of the event. This is how you would indicate that an event has been "handled". - + - Ibex will trigger the Enter and Leave properties as - it walks down the tree, based on the position of the mouse (or the - faked position if the mouse property has been written to). - However, Enter and Leave are not events since they - do not implicitly cascade up or down the tree. + Ibex uses the following events to notify a box about changes that + only matter to that particular box. These events do not propagate + either up or down the tree. + + + The value true is written to this property when the mouse (enters/leaves) the box. + + + + The value true is put to this property after the size + of this box changes. + + + + When a child is added or removed, that child is written to + this property. The write is always performed after the + addition or removal, so these two cases can be distinguished + by checking indexof(child). + + Note that if the parent's redirect target is set to another + box, this trap will only be invoked when children are + manipulated by reading and writing to the parent. Reads and + writes directly to the redirect target will not trigger + this trap. + + Note also that this traps is still triggered if a box's + redirect target is null. This is useful for + boxes that need to accept children and then relocate them + elsewhere. +
- + Indicates that the use has pressed a mouse button. On platforms with three mouse buttons, the middle button is button 3 -- this ensures that applications written to only @@ -1649,17 +1683,17 @@ platforms. - + Indicates that the use has released a mouse button. - + Indicates that the user has pressed and released the mouse button without moving the mouse much (exactly how much is platform-dependent). - + Indicates that the user has clicked the mouse button twice within a short period of time (exactly how long is platform-dependent). @@ -1670,32 +1704,38 @@ + A string is written to this property when a key is pressed or released If the key was any other key, a multi-character string describing the key will be put. For simplicity, we use the VK_ constants in the . When a + text=" Java 1.1 API java.awt.event.KeyEvent class"/>. When a key is pressed or released, the string put will be the portion of its VK_ constant after the underscore, all in lower case. - If the shift key was depressed immediately before the event - took place, then the string will be capitalized. Special + + + If the shift key was depressed immediately before the + event took place, then the string will be capitalized. Special keynames are also capitalized; shift+home is reported as - "HOME". Symbols are capitalized as they appear on the + "HOME". Symbols are capitalized as they appear on the keyboard; for example, on an American QWERTY keyboard, shift+2 - is reported as "@". If the alt, meta, or command key - was depressed immediately before this key was pressed, then - the string will be prefixed with the string "A-". If - the control key was depressed while this key was pressed, then - the string will be prefixed with the string "C-". If - both alt and control are depressed, the string is prefixed - with "C-A-". Ibex does not distinguish between a key - press resulting from the user physically pushing down a key, - and a 'key press' resulting from the keyboard's typematic - repeat. In the rare case that an application needs to - distinguish between these two events, it should watch for - KeyReleased messages and maintain an internal key-state - vector. + is reported as "@". + + If the alt, meta, or command key was depressed immediately + before this key was pressed, then the string will be prefixed + with the string "A-". If the control key was depressed + while this key was pressed, then the string will be prefixed + with the string "C-". If both alt and control are + depressed, the string is prefixed with "C-A-". + + Ibex does not distinguish between a key press resulting from + the user physically pushing down a key, and a 'key press' + resulting from the keyboard's typematic repeat. In the rare + case that an application needs to distinguish between these + two events, it should watch for KeyReleased messages and + maintain an internal key-state vector. +
@@ -1756,11 +1796,16 @@ Ibex supports HTTP Basic and Digest authentication. To use authentication, pass ibex.net.rpc.xml() a URL in the form - http[s]://user:password@hostname/. Ibex will use Digest - authentication if the server supports it; otherwise it will use - Basic authentication. Please be aware that many XML-RPC server - implementations contain a . + + 
+       http[s]://user:password@hostname/
+
+ + Ibex will use Digest authentication if the server supports it; + otherwise it will use Basic authentication. Please be aware that + many XML-RPC server implementations contain a .
@@ -1950,11 +1995,11 @@ the proper key on the target box. 
-    
+    
         _KeyPressed = function(k) { ibex.log.info("first"); }
          KeyPressed = function(k) { ibex.log.info("sixth"); }
         $recipient.target = $target;
-        
+        
             _KeyPressed = function(k) {
                 ibex.log.info("second");
                 thisbox.target.KeyPressed = k;
@@ -1962,17 +2007,17 @@
                 return true;
             }
              KeyPressed = function(k) { ibex.log.info("fifth"); }
-            
+            
                 _KeyPressed = function(k) {
                    ibex.log.info("this never happens");
                 }
-            
-        
-         
+            
+        
+         
             _KeyPressed = function(k) { ibex.log.info("third"); }
              KeyPressed = function(k) { ibex.log.info("fourth"); }
-        
-    
+        
+
@@ -2123,7 +2168,7 @@ and doing so squanders scarce public IPv4 addresses. As such, the onus is on the administrators of such machines to explicitly block access to clients reporting a User-Agent: header beginning with the - three characters "Ibex". + four characters "IBEX". @@ -2197,7 +2242,7 @@ The token .. is equivalent to [""]. Trapping - + Cloning Extended catch syntax. The following code: @@ -2268,48 +2313,35 @@ - Very early in the loading process, Ibex begins logging messages about - what it is doing. Where this output is logged to differs by platform; - currently it goes to standard output when running inside a JVM, and to - $TMPDIR\ibex-log.txt on Win32 (where $TMPDIR is the - value returned by GetTempPath()). The logs contain a lot of - valuable debugging information and performance hints; if you are - having trouble developing an Ibex application, be sure to check the - logs. - + 
+    Usage: ibex [-lawp] [ url | file | directory ]
+        -l [level]      set logging level to { debug, info (default), warn, error, silent }
+        -l rpc          log all XML-RPC and SOAP conversations
+        -l user@host    email log to user@host
+        -l host:port    emit log to TCP socket
+        -l [file]       write log to a file on disk
+        -a              check assertions
+        -w   reserved for libibex
+        -p              dump profiling information [not yet supported]
+
+ If Ibex encounters a serious problem before it starts logging information, or if it is unable to open the log file, it will abort immediately with a critical abort, which will be displayed on the console for POSIX-native cores and in a dialog box for JVM-based and Win32-native cores. - - You can invoke Ibex directly from the command line during - development. When using a JVM, the invocation format is: - - 
    
-  java -jar path-to-ibex-jar [-sv] source-location [initial-template]
-
- - Where path-to-ibex-jar is the path to ibex.jar, - which can be downloaded . - - On Win32, the invocation format is: - - 
-    ibex.exe [-v] source-location [initial-template]
-
- - The file ibex.exe is placed in Windows' ActiveX cache - directory the first time Ibex is used on the machine. The ActiveX - cache location depends on what version of Windows you are using; - on newer versions of Windows it is C:\WINDOWS\DOWNLOADED - PROGRAM FILES\. You can also extract ibex.exe from - ibex.cab, which is available . + + Note that Microsoft Windows does not provide any mechanism for + redirecting standard input/output of an application which is not + compiled as a "console application". Therefore, Ibex is compiled + as a "console application", and will open a console window when + invoked. To inhibit this console window, provide a logging + destination (file, port, etc). The source-location parameter can be either the path - to an .ibex archive, the http url of an .ibex archive, or the path to a - directory comprising an unpacked .ibex archive. + to an .ibex archive, the http url of an .ibex + archive, or the path to a directory comprising an unpacked + .ibex archive. The initial-template parameter is the stream name of a template to be used as the initial template. If ommitted, it diff --git a/doc/reference/threeviews.pdf b/doc/reference/threeviews.pdf new file mode 100644 index 0000000..0840c40 Binary files /dev/null and b/doc/reference/threeviews.pdf differ