snapshot save

README.md

@@ -136,8 +136,8 @@ In your .vimrc, add self as shown below:
 
       ....
 
-      let g:vim_addon_manager.plugin_sources['self'] = {'type': 'git', 'url': 'git://github.com/megaannum/self.git'}
-      let g:vim_addon_manager.plugin_sources['forms'] = {'type': 'git', 'url': 'git://github.com/megaannum/forms.git'}
+      let g:vim_addon_manager.plugin_sources['self'] = {'type': 'git', 'url': 'git://github.com/megaannum/self'}
+      let g:vim_addon_manager.plugin_sources['forms'] = {'type': 'git', 'url': 'git://github.com/megaannum/forms'}
 
 
       let plugins = [
@@ -265,6 +265,10 @@ No testing has been done on the Windows GVim configure. Feedback is welcome.
 
 [Vim location](http://www.vim.org/scripts/script.php?script_id=4150)
 
+## Tutorial
+
+There is a Forms tutorial which can be accessed at [Forms tutorial](https://github.com/megaannum/forms/blob/master/tutorial/forms/Tutorial.md).
+
 ## Acknowledgements and thanks
 
 - Marc Weber: provided initial release feedback identifying Vim 7.3 bug and

autoload/forms/tutorial/do_nothing_form.vim

@@ -0,0 +1,17 @@
+
+"---------------------------------------------------------------------------
+" forms#tutorial#do_nothing_form#Make() 
+"   A Form that does nothing: no display, no event handling
+"
+"  parameters: None
+"---------------------------------------------------------------------------
+function! forms#tutorial#do_nothing_form#Make() 
+    let body = forms#newNullGlyph({})
+
+    let form = forms#newForm({'body': body})
+    function! form.purpose() dict
+      return "This is Help associated with the Null Glyph Tutorial Form."
+    endfunction
+
+    call form.run()
+endfunction

autoload/forms/tutorial/editor_slider.vim

@@ -0,0 +1,73 @@
+
+"---------------------------------------------------------------------------
+" forms#tutorial#editor_slider#Make() 
+"   Create a FixedLengthField editor and Slider and wire them together
+"     using Actions.
+"
+"  parameters: None
+"---------------------------------------------------------------------------
+function! forms#tutorial#editor_slider#Make()
+
+    function! SliderActionFunc(...) dict
+      " convert the slider Number value to String
+      let value = "".a:1
+      " set the editor's text with that value
+      call self.editor.setText(value)
+    endfunction
+
+    function! EditorActionFunc(...) dict
+      " convert editor String value to Number
+      let value = a:1 + 0
+      " attempt to set the slider's value
+      try
+        call self.hslider.setRangeValue(value)
+      catch /.*/
+        " handle error here: editor value out of range
+      endtry
+    endfunction
+
+    let slideraction = forms#newAction({'execute': function("SliderActionFunc")})
+    let editoraction = forms#newAction({'execute': function("EditorActionFunc")})
+    let attrs = {
+              \ 'size' : 32,
+              \ 'tag' : 'hslider',
+              \ 'resolution' : 4,
+              \ 'on_move_action' : slideraction,
+              \ 'range' : [0,255]
+              \ }
+    let hslider = forms#newHSlider(attrs)
+
+    let editor = forms#newFixedLengthField({
+                                    \ 'size': 3,
+                                    \ 'tag' : 'editor',
+                                    \ 'on_selection_action' : editoraction,
+                                    \ 'init_text': '0'})
+
+    let slideraction.editor = editor
+    let editoraction.hslider = hslider
+
+    let labeleditor = forms#newLabel({'text': 'Editor'})
+    let hpolyeditor = forms#newHPoly({'children': [
+                            \ labeleditor,
+                            \ editor
+                            \ ], 
+                            \ 'mode': 'light'})
+
+    let labelslider = forms#newLabel({'text': 'Slider'})
+    let hpolyslider = forms#newHPoly({'children': [
+                            \ labelslider,
+                            \ hslider
+                            \ ], 
+                            \ 'mode': 'light'})
+
+    let vpoly = forms#newVPoly({'children': [
+                            \ hpolyeditor,
+                            \ hpolyslider
+                            \ ],
+                            \ 'alignment': 'C',
+                            \ 'mode': 'double'})
+
+    let form = forms#newForm({'body': vpoly })
+    call form.run()
+
+endfunction

autoload/forms/tutorial/label.vim

@@ -0,0 +1,18 @@
+
+"---------------------------------------------------------------------------
+" forms#tutorial#label#Make() 
+"   Create a simple Label in a Form.
+"
+"  parameters: None
+"---------------------------------------------------------------------------
+function! forms#tutorial#label#Make()
+  let attrs = {'text': 'My First Label'}
+  let label = forms#newLabel(attrs)
+
+  let form = forms#newForm({'body': label })
+  function! form.purpose() dict
+    return "This is Help associated with the Label Tutorial Form."
+  endfunction
+
+  call form.run()
+endfunction

autoload/forms/tutorial/layout_labels_horizontally.vim

@@ -0,0 +1,34 @@
+
+"---------------------------------------------------------------------------
+" forms#tutorial#layout_labels_horizontally#Make() 
+"   Create a row of 3 Labels in a form.
+"
+"  parameters: None
+"---------------------------------------------------------------------------
+function! forms#tutorial#layout_labels_horizontally#Make()
+    let attrs = {'text': 'Label One'}
+    let labelOne = forms#newLabel(attrs)
+
+    let attrs = {'text': 'Label Two'}
+    let labelTwo = forms#newLabel(attrs)
+
+    let attrs = {'text': 'Label Three'}
+    let labelThree = forms#newLabel(attrs)
+
+    let hspace = forms#newHSpace({'size': 2})
+
+    let hpoly = forms#newHPoly({'children': [
+                            \ labelOne,
+                            \ hspace,
+                            \ labelTwo,
+                            \ hspace,
+                            \ labelThree
+                            \ ]})
+
+    let form = forms#newForm({'body': hpoly })
+    function! form.purpose() dict
+      return "This is Help associated with the\nHorizontal Layout Label Tutorial Form."
+    endfunction
+
+    call form.run()
+endfunction

autoload/forms/tutorial/layout_labels_vertically.vim

@@ -0,0 +1,40 @@
+
+"---------------------------------------------------------------------------
+" forms#tutorial#layout_labels_vertically#Make() 
+"   Create a row of 3 Labels in a form.
+"
+"  parameters: None
+"---------------------------------------------------------------------------
+function! forms#tutorial#layout_labels_vertically#Make()
+    let attrs = {'text': 'Top label is longer that all the reset'}
+    let labelOne = forms#newLabel(attrs)
+
+    let attrs = {'text': 'Middle Label'}
+    let labelTwo = forms#newLabel(attrs)
+
+    let attrs = {'text': 'Bottom Label'}
+    let labelThree = forms#newLabel(attrs)
+
+    let vspace = forms#newVSpace({'size': 1})
+
+    " Make default alignment 'center'
+    " Then override for labelTwo aligning 'L'
+    " and for labelThree aligning 'R'
+    let vpoly = forms#newVPoly({'children': [
+                            \ labelOne,
+                            \ vspace,
+                            \ labelTwo,
+                            \ vspace,
+                            \ labelThree
+                            \ ],
+                            \ 'alignment':'C',
+                            \ 'alignments': [[2,'L'], [4,'R']]
+                              })
+
+    let form = forms#newForm({'body': vpoly })
+    function! form.purpose() dict
+      return "This is Help associated with the\nVertical Layout Label Tutorial Form."
+    endfunction
+
+    call form.run()
+endfunction

autoload/forms/tutorial/results.vim

@@ -0,0 +1,99 @@
+"---------------------------------------------------------------------------
+" forms#tutorial#results#Make() 
+"   Create a simple Label in a Form.
+"
+"  parameters: None
+"---------------------------------------------------------------------------
+function! forms#tutorial#results#Make()
+  let attrs = {'textlines': "Enter Text\nSelect Buttons\nClick Cancel or Submit"}
+  let text = forms#newText(attrs)
+
+  let editor = forms#newFixedLengthField({'tag': 'editor', 'size': 15})
+  let editorbox = forms#newBox({'body': editor, 'mode': 'light_arc'})
+
+
+  let group = forms#newButtonGroup({'member_kind': 'forms#ToggleButton'})
+  let l1 = forms#newLabel({'text': "ONE"})
+  let tb1 = forms#newToggleButton({'tag': 'tbone', 
+                                  \ 'body': l1, 
+                                  \ 'group': group})
+  let b1 = forms#newBox({ 'body': tb1} )
+
+  let l2 = forms#newLabel({'text': "TWO"})
+  let tb2 = forms#newToggleButton({'tag': 'tbtwo', 
+                                  \ 'body': l2, 
+                                  \ 'selected': 1, 
+                                  \ 'group': group})
+  let b2 = forms#newBox({ 'body': tb2} )
+
+  let l3 = forms#newLabel({'text': "THREE"})
+  let tb3 = forms#newToggleButton({'tag': 'tbthree', 
+                                  \ 'body': l3, 
+                                  \ 'group': group})
+  let b3 = forms#newBox({ 'body': tb3} )
+  let hpolytb = forms#newHPoly({ 
+                             \ 'children': [b1, b2, b3], 
+                             \ 'alignment': 'C' })
+
+
+  let group = forms#newButtonGroup({ 'member_kind': 'forms#RadioButton'})
+  let rb1 = forms#newRadioButton({'tag': 'rbone', 
+                                  \ 'group': group})
+  let b1 = forms#newBox({ 'body': rb1 })
+  let rb2 = forms#newRadioButton({'tag': 'rbtwo', 
+                                  \ 'group': group})
+  let b2 = forms#newBox({ 'body': rb2 })
+  let rb3 = forms#newRadioButton({'tag': 'rbthree', 
+                                  \ 'selected': 1, 
+                                  \ 'group': group})
+  let b3 = forms#newBox({ 'body': rb3 })
+  let hpolyrb = forms#newHPoly({ 'children': [b1, b2, b3] })
+
+  let attrs = { 'text': 'Cancel'}
+  let cancellabel = forms#newLabel(attrs)
+  let cancelbutton = forms#newButton({
+                                      \ 'tag': 'cancel',
+                                      \ 'body': cancellabel,
+                                      \ 'action': g:forms#cancelAction})
+  let attrs = { 'text': 'Submit'}
+  let submitlabel = forms#newLabel(attrs)
+  let submitbutton = forms#newButton({
+                                      \ 'tag': 'submit',
+                                      \ 'body': submitlabel,
+                                      \ 'action': g:forms#submitAction})
+
+
+  let hspace = forms#newHSpace({'size': 2})
+  let hpolybuttons = forms#newHPoly({'children': 
+                            \ [cancelbutton, hspace, submitbutton]})
+
+  let vspace = forms#newHSpace({'size': 1})
+  let vpoly = forms#newVPoly({'children': [
+                            \ text, 
+                            \ vspace, 
+                            \ editorbox, 
+                            \ vspace, 
+                            \ hpolytb,
+                            \ vspace, 
+                            \ hpolyrb,
+                            \ vspace, 
+                            \ hpolybuttons
+                            \ ],
+                            \ 'alignments': [[8, 'R']]
+                            \ })
+
+  let border = forms#newBorder({ 'body': vpoly, 'size': 2 })
+  let bg = forms#newBackground({ 'body': border })
+  let form = forms#newForm({'body': bg })
+  function! form.purpose() dict
+    return "This is Help associated with the More Code Structure Tutorial Form."
+  endfunction
+
+  let results = form.run()
+  if type(results) == g:self#DICTIONARY_TYPE
+    echo "" . string(results)
+  endif
+
+endfunction
+
+" call forms#tutorial#results#Make()

autoload/forms/tutorial/selectlist_deck.vim

@@ -0,0 +1,52 @@
+
+"---------------------------------------------------------------------------
+" forms#tutorial#editor_slider#Make() 
+"   Create a SelectList and Deck and wire them together
+"     using an Action so that the SelectList controls which of the Deck's
+"     Cards is showing.
+"
+"  parameters: None
+"---------------------------------------------------------------------------
+function! forms#tutorial#selectlist_deck#Make()
+  let t1 = forms#newText({'textlines': "Card\nOne"})
+  let t2 = forms#newText({'textlines': "Card\nTwo"})
+  let t3 = forms#newText({'textlines': "Card\nThree"})
+  let t4 = forms#newText({'textlines': "Card\nFour"})
+
+  let deck = forms#newDeck({'children': [t1, t2, t3, t4]})
+
+  function! V4Action(...) dict
+    let pos = a:1
+    call self.deck.setCard(pos)
+  endfunction
+  let action = forms#newAction({ 'execute': function("V4Action")})
+  let action['deck'] = deck
+
+  let attrs = { 'mode': 'single',
+              \ 'pos': 0,
+              \ 'choices': [
+              \ ["one", 1],
+              \ ["two", 2],
+              \ ["three", 3],
+              \ ["four", 4]
+              \ ], 'size': 4,
+              \ 'on_selection_action': action
+              \ }
+
+  let slist = forms#newSelectList(attrs)
+  function! slist.purpose() dict
+    return "Select item to change Deck top-of-card."
+  endfunction
+  let b = forms#newBorder({'body': slist, 'char': ' '})
+
+  let hpoly = forms#newHPoly({'children': [b, deck], 
+                              \ 'alignment': 'C' })
+  let bg = forms#newBackground({ 'body': hpoly})
+
+  let form = forms#newForm({'body': bg })
+  function! form.purpose() dict
+    return "This is Help associated with the SelectList/Deck Tutorial Form."
+  endfunction
+
+  call form.run()
+endfunction