Documentation for Win32lib v0.60.6
Table of Contents

Forms

Forms are a combination of a Window and its controls.


Win32lib enables easy ways of creating a form and writing event handlers for it.

  • proc createForm( sequence pFormDefinition )   This creates a Window and its controls.
  • func getFormIds(integer Action)   Returns the most recently created form(s)
  • func loadForms(sequence FileName)   Builds a form definition from a text file.

    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    createForm
    ( sequence pFormDefinition )

    This creates a Window and its controls.

    Category: Forms

    pFormDefinition is a list of Control definitions, the first is assumed to be a Window definition and the rest are the controls that the window is to contain. Each control definition is passed on to newUIObj to create the actual control in the order they are defined in pFormDefinition.

    The elements in pFormDefinition as strings that each define a single control. The string is a comma separated list of parameters in the form KEY=VALUE, but note that some key names can be defaulted if omitted. All the parameters have a keyword name, which is not case sensitive, meaning that "width=200" and "WIDTH=200" are both acceptable. However, certain parameters can have assumed keyword names if not supplied. The first unnamed parameter is assumed to be the "TYPE" parameter, the second unnamed is assumed to be "CAPTION", and so on for "NAME", "LEFT", "TOP", "WIDTH", "HEIGHT", "FLAGS", and "EXFLAGS" parameters, in that order. If there are still unnamed parameters after all the assumed ones have been allocated, an error message is issued.

    Also note that include w32Start.ew is usually used in conjunction with applications that use createForm()

    Example:

          createForm({"Window, Login,height=200,bar=status, left=10, top=Center",
                      "RText,   User Name:, left=10,top=10",
                      "EditText,User Name Text,caption=(), from=UserName" &
                                ", left=(2),top=(-2,,), width=25chars",
                      "RText,   Password:, from=UserName,left=(),top=(15),width=()",
                      "EditText,Password Text,caption=(), from=Password" &
                                ", left=(2),top=(-2,,), width=(),flag=es_password",
                      "DefPushButton,&Submit, right=75, width=70,bottom=5, height=25",
                      "CancelButton,&Cancel,  from=Submit, left=(5),top=()" &
                      ", height=(), width=(), flag=autoclose",
                      "TabOrder=(UserName,PasswordText,Submit)"
                      })
    

    See Also: getFormIds, loadForms


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    getFormIds
    (integer Action)

    Returns the most recently created form(s)

    Returns: SEQUENCE: A list of window ids created by the createForm routine.

    Category: Forms

    If Action = 1 then only the most recent form id is returned, otherwise all the form ids are returned as a list ordered from oldest to most recently created.

    Example:

          sequence fid
          -- Create a form
          createForm( FormDefn )
          -- Get its form (window) id.
          fid = getFormIds(1)
    

    See Also: createForm, loadForms


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    loadForms
    (sequence FileName)

    Builds a form definition from a text file.

    Returns: SEQUENCE: A form definition suitable to give to createForm()

    Category: Forms

    FileName is the pathname of a file that contains form definition statements. These are almost identical to the ones used by newUIObject but there are a few differences to help laying out the text file.

    The form definition file consists of one or more lines of text. Any text following the comment string are stripped off. Initially the comment string is two semi-colons, eg. ";;".
    The lines are grouped into UI Object definitions. Each definition starts in column 1. If you need to extend a definition over multiple lines, offset the second and subsequent lines by at least one space (or tab) character.

    You can change the default comment string by inserting a comment in the form "comment=<xxx>" where "<xxx>" is one or more characters that become the new comment lead-in string from that point onwards.

    Example of a form definition file:

     ;;comment=---
     --- Customer.form
     --- This defines the customer input screen.
    

    Window, Customer Input at={20, 20} bar=status

    Label, Number ------------------ Customer Number at={5,10} EditText left={}, top={0}, width=20ch

    Label, Name ------------------ Customer Name left={}, top={4} EditText left={}, top={0}, width=50char

    Button, Accept left={}, top={10} Button, Cancel left={4}, top={}

    Example for calling loadForm:

          sequence lFormDefn
          lFormDefn = loadForm("customer.form")
          createForm(lFormDefn)
          lFormId = getFormIds(1)
          setText(lFormId[1], sprintf("%s (%d)",{getText(lFormId[1]), lFormId[1]}))
    

    See Also: createForm, getFormIds