# C

`(cancelButton)`
  A cancel button. Uses the +Force and +Close prefix classes. See also +Force, +Close, +Button, gui.

`(change Msg Env Exe Exe)`
  Workhorse function for '+UndoButton' and '+RedoButton'. When called in some button action, or as a side-effect in a '+Chg' function or similar, it maintains an undo- and a redo-stack for the current form. It takes:
  - A message to be displayed as a tooltip in the undo- and redo-button, to inform the user what is being un- or redone in case that button should be pressed.
  - An environment of variable bindings, to be pushed onto - and popped from - the stacks, and to be used during the un-/redo operations.
  - A single 'exe' for *un-doing* in that environment.
  - And one or several 'exe's (i.e. a 'prg') for *doing* in that environment.
  Example:

         (gui '(+UndoButton))
         (gui '(+RedoButton))
         ...
         (gui '(+Button) "Do something"
            '(change "Some change action"
                (env 'New (makeNewValue)  'Old (getCurrentValue))  # Build environment
                (restoreValue Old)                                 # Undo-expression
                (doSomething New) ) )                              # Do-expression

  When this button is pressed, 'doSomething' is executed with the results of (makeNewValue) and (getCurrentValue). The tooltip of the undo-button will show "Undo: 'Some change action'". The redo-stack is cleared and the redo-button is disabled.

  If now the undo-button is pressed, 'undoSomething' is executed with the saved results of (foo) and (bar). It should perform the opposite action of 'doSomething', effectively undoing the operation. The tooltip of the redo-button will now show "Redo: 'Some change action'", and the tooltip of the undo-button will show a possible previous undoable operation. Pressing the redo-button will *do* the operation again, and so on.

  See also +UndoButton, +RedoButton.

`(choButton 'Exe)`
  A button used to select or create an object of the same type as the one currently displayed. See also +Rid, +Tip, +Button, gui.

`(chart @)`
  Returns the chart where the current field is, or any value accessible from that chart by applying the 'get' algorithm.

          (chart) # chart
          (chart 'data 1) # The first line (list) of the chart's data.

`+Chg`
  A prefix taking a function argument, which is called when the user changes the value of a field. That function receives the modified value, and may modify it again or perform side-effects with it like setting other fields (accessible with 'field').

`+ChoButton`
  A class corresponding to `(choButton 'Exe)`. `+ChoButton` is quite a general class. It can be used to select, or even do, anything. See also choButton, +Tiny, +Tip, +Button.

`+Choice`
  Subclass of `+ChoButton`. Opens a `dialog` that allows the user to choose anything from a list, which is dynamically generated from the 'Exe' argument. See also +ChoButton, dialog.

`(cho)`
  `cho` is a function that returns the number 16 if the `diaform` is used as a normal form (i.e. not as a dialog) or 8 if used in another context. It is typically used to show a different number of rows in a chart when the same chart is used as a dialog compared to when it is used on it's own. The following code fragment comes from the demo app included in the PicoLisp distribution, in gui.l. Here we can see `cho` being used to determine how many rows of data should be created, as well as making sure scrolling the data goes along with the number of rows.

       . .
           (do (cho)
              (<row> (alternating)
                 (gui 1 '(+DstButton) Dst) (gui 2 '(+NumField)) (gui 3 '(+ObjView
                 +TextField) '(: nm)) (gui 4 '(+TextField)) (gui 5 '(+MailField)) (gui
                 6 '(+TextField)) (gui 7 '(+TextField)) (gui 8 '(+TelField)) (gui 9
                 '(+TelField)) ) ) )
        (<spread>
           (scroll (cho)) . .

  See also diaform.

`(choTtl Ttl X . @)`
  `choTtl` is a utility function typically used to set the title of a chart in a search dialog. The function combines a transient symbol, a text string, with the number of objects of a given type in the database. Here is an example from the demo app included in the PicoLisp distribution, in gui.l.

          (choTtl ,"Customers/Suppliers" 'nr '+CuSu)

  This example specifies an index, "...'nr '+CuSu)", and counts the number of `+CuSu` objects in that index. The result is combined with "Customers/Suppliers", setting the title of the data chart to, for example, "3 Customers/Suppliers". It is also possible to specify only the class, "... '+CuSu)". In that case the total number of entities of that class is used, regardless of any index.

`(choDlg Dst Ttl Rel [Hook] [((+XyzField) ..) Exe Able])`
  `choDlg`, "choose dialog" creates a dialog that lets the user select or create an object, to be either jumped to (when called as a form), or taken into the destination field (when called as a dialog, see +DstButton). The following example comes from the demo app included with the PicoLisp distribution, in cusu.l. This file implements a form that handles objects of a class called `+CuSu`, "CustomerSupplier". `+CuSu` is connected to another class, `+Sal`, "Salutation". Using a `choDlg` in cusu.l allows a user to add or change the salutation belonging to the current object from the same GUI page used to edit other properties.

       ,"Salutation" (choDlg 0 ,"Salutations" '(nm +Sal))

  This code creates a `choDlg` that presents objects of the class `+Sal` using a `diaform`. Selecting an object in the choose dialog will close the dialog and adopts the selected value as the new salutation. See also diaform.

`+Close`
  A button prefix class which closes the current form if it is a dialog. See also dialog, diaForm.

`+Clr0`
  Prefix for a numeric field which maps zero to/from NIL.

`+Click`
  Class that can be used together with `+Auto` to automatically click a button after a certain amount of time has passed. Strictly speaking, `+Click` is not limited to `+Auto` buttons, but that is the most common usage.

          (gui '(+Click +Auto +Button) 420 'This 1000 '(pop
          *Throbber)
             '(with (: home)
                (for Col (: grid)
                   (for This Col
                      (let N # Count neighbors
                         (cnt
                            '((Dir) (get (Dir This) 'life)) (quote
                               west east south north ((X) (south (west X))) ((X)
                               (north (west X))) ((X) (south (east X))) ((X) (north
                               (east X))) ) )
                         (=: next # Next generation
                            (if (: life)
                               (>= 3 N 2) (= N 3) ) ) ) ) )
                (for Col (: grid) # Update
                   (for This Col
                      (=: life (: next)) ) ) ) )

  See also +Auto, +Button.

`+Chk`
  Prefix class used to implement on-the-fly field validation. For example, the following code uses `+Chk` in combination with the built-in validation from `+NumField` to only accept numbers not bigger than 9.

          (app)

          (action
             (html 0 "+Chk" "@lib.css" NIL
                (form NIL
                   (gui '(+Chk +NumField)
                      '(or
                         (extra)
                         (and (> (val> This) 9) "Number too big") )
                      12 )
                   (gui '(+JS +Button) "Print"
                      '(msg (val> (field -1))) ) ) ) )

`+Chart`
  Charts are an important part of the GUI framework. The basic idea is to provide a separation between the way two-dimensional data (i.e. a tabular data, a list of lists) is presented in the gui and the way it is stored internally. Charts make it possible to display the data in rows and columns, scroll the data and connect it to gui components. The first argument to a `+Chart` is a number:

          (gui (+Chart) 2)
          (<table> NIL NIL '((NIL "Text") (NIL "Number"))
             (do 1
                (<row> NIL
                  (gui 1 '(+TextField) 20)
                  (gui 2 '(+NumField) 10) ) ) )

  This number tells the chart how many columns of data to expect. As can be seen in the code snippet above, the number '2' matches the number of gui components in the table. To make it possible for a `+Chart` to display data in a representation that is different from how the date is stored, you may pass two functions to a `+Chart`. The functions in question are a 'put' and a 'get' function, and they are responsible for 'translating' the data format between the gui and the internal representation. The first function is a 'put'- function that puts data into the GUI components from the internal representation and the second one is a 'get'- function gets data from the GUI components into the internal representation.

          (gui '(+E/R +Chart) '(bin : home obj) 3
             '((This) (list (: nm)))                    # 'Put'- function
             '((L D)                                    # 'Get'- function
                (and D (put!> D 'nm (car L)))
                D ) )
          (<table> NIL "Binaries" '((NIL "Name"))
             (do 6
                (<row> NIL
                   (gui 1 '(+Able +TextField) '(curr) 30)
                   (gui 2 '(+DelRowButton))
                   (gui 3 '(+BubbleButton)) ) ) )

  All GUI components that follow a chart and that have a number as their first argument go into that chart. Typically, the components are arranged in a `<table>` but this is not a requirement. Any suitable layout works just as well. See also charts, +Chart1, +QueryChart and gui.

`+Chart1`
  +Chart1 is a shortcut to +Chart, with the 'put'-function predefined to 'list' and the 'get'- function predefined to 'car'. This way, +Chart1 can directly map a one-dimensional list to a table.

          (gui '(+Var +Chart1) (: mup -3) 3)
          (<table> 'chart NIL '((NIL "Media"))
             (do 3
                (<row> (alternating)
                   (gui 1 '(+ObjView +TextField) '(: nm)) # Binary name
                   (gui 2 '(+DelRowButton)) (gui 3 '(+BubbleButton)) ) )
             (<row> NIL (scroll 3 T)) )

  The example above comes from the code running the PicoLisp wiki, in gui.l. In this code, a `+Chart1` handles the data provided by `(: mup -3)` and the chart expects 3 columns. 'mup' is setup a little earlier in the code:

          (=: mup
               (list
                  (and (: obj mup) (in (blob @ 'txt) (till NIL T))) # txt
                  NIL # sum
                  NIL # min
                  (: obj mup bin) ) )

  'mup' is a list here, and `(: mup -3)` picks `(: obj mup bin)` from there. 'list' is applied as the 'put'- function, resulting in a list containing what is stored in the 'bin' property of the markup contained in the current object. In the table displaying the data, a combination of +ObjView and +TextField is used to create a link to the object: `(gui 1 '(+ObjView +TextField) '(: nm))` See also +Chart, charts.

`+Checkbox`
  A checkbox component, example:

          ,"Hotel?" (gui '(+E/R +Checkbox) '(htl : home obj))

  `+Checkbox` maps to a bool (T or NIL). In the example above, the 'htl' property of the current object will contain T or NIL, depending on whether the checkbox in the gui has been ticked or not. See also gui, +field and input fields.

`+ClassField`
  A `+ClassField` is used to display and change the class of an object .

          (gui '(+ClassField) '(: home obj) '(("Male" +Man) ("Female" +Woman)))

  The example above displays and changes a person's sex from male to female and vice versa. See also +Map, +TextField.

`cloneButton`
  This function creates a button used to clone, make a copy of the object in the current form. To customise the copy the form object, or it's class, may override the `clone>`- method (inherited from `+Entity`). See also +Rid, +Able, +Tip and +Button.

`(closeButton Lbl 'Exe)`
  A close button. 'Exe' runs when the button is pressed and 'Lbl' is the button label. See also +Rid, +Close, +Button, gui.

`+ClrButton`
  Clears all input fields. See also resetButton, +JS, +Tip and +Button.

`+Cue`
  Prefix class used to initialize fields with a help text, hint, about what is supposed to be entered in the field. Displays the argument value within angular brackets if the current value of the field is NIL. Example:

         (gui '(+Cue +TextField) "Please enter some text here" 30)

  Causes an empty field to display "<Please enter some text here>".

`(curr @)`
  Returns the data in the current row of the current chart, optionally applying the 'get' algorithm to any following arguments.

          ...
          (<table> 'chart NIL
             '((NIL ,"File") (NIL ,"Delete")) (do 2
                (<row> NIL
                   (gui 1 '(+DocObj +TextField) (curr)) # (gui 2 '(+DelRowButton)) ) )
                   )
          ...