Form

Form_Add( HParent,    Ctrl,    Txt  =  "", Opt  =  "", E1  =  "", E2  =  "", E3  =  "", E4  =  "", E5  =  "", E6  =  "", E7  =  "" )

Add control to the parent.

Parameters

Adding Controls

Form can make any internal AHK control and any custom control.  Making internal control is similar to using native command Gui, Add :

Gui, Add,          CtrlName,  Options, Text
Form_Add(hParent, "CtrlName", "Text", "Options")

To make custom control, you must include appropriate module.  If the module contains Add2Form function you can create it the same way as internal control, by specifying its textual name in Ctrl parameter.  Otherwise, after creating the control the way described in the module documentation and obtaining its handle, you can specify the handle as Ctrl parameter.  In that case Txt and Opt parameters are ignored but extensions will still work.

Implementing Add2Form function is the best way to use custom control as it makes you forget about difference between custom and integrated controls.  The following is implementation of Add2Form for Panel control.

Panel_Add2Form(hParent, Txt, Opt){
    static parse = "Form_Parse"
    %parse%(Opt, "x# y# w# h# style", x, y, w, h, style)
    hCtrl := Panel_Add(hParent, x, y, w, h, style, Txt)
    return hCtrl
}

;with above in place you can use:
hPanel := Form_Add(hForm, "Panel", "Panel1", "w100 h200 style=hidden")

When executing Add function, Form will check if there is Panel_add2Form function and if that’s true, it will call it with adequate parameters.  If not, function will return the error message.

Controls can use Form_Parse function to extract individual options from the Opt string.  It should be called using dynamic function calls so that control can work even when included in scripts that don’t use Form module (without it, compiler would generate missing include error).

Using Extensions

Extension is any AHK function that accepts handle of the control as its first parameter.  It can have any number of of additional parameters.  You can quickly write new extension when you need it and it will instantly become available, or you can include 3thd party extensions.  Extensions are used similarly to AHK commands - you specify extension name followed by a space (not comma !) and list of its parameters between commas.

hButton :=  Form_Add(hForm1, "Button", "Cancel", "gOnButton", "Align F, 250", "Attach p r", "Tooltip I pwn")

In this example Add function has 3 extensions: Align with 2 parameters and Attach & Tooltip with 1 parameter.  The above code is equivalent to:

hButton :=  Form_Add(hForm1, "Button", "Cancel", "gOnButton")   ;make button without extensions:
Align(hButton, "F", 250), Attach(hButton, "p r"), Ext_Tooltip(hButton, "I pwn")

Notice that Tooltip extension uses “Ext_” prefix.  Add function will first check for the function name that matches extension name and if doesn’t exist, it will try with “Ext_” prefix.

The order of extensions may be important.  In above case Attach extension will not produce intented results if control doesn’t have dimensions already set, so Align extension is placed before it (in this case, the same could be achieved without Align extension by specifying x..w options).  Tooltip extension, however, doesn’t depend on anything so it can be put anywhere in extension list.

You can customize parameter extraction with 2 chars that can optionally preceed the extension name.  For instance “Font s18, Courier New” will use Font extension with 2 parameters “s18” and “ Courier New”.  Since Font extension accepts comma in input this is wrong interpretation.  To specify that sentence containing comma is part of the argument itself, set “*|)Font s18, Courier New”.  First parameter sets the mode.  * is normal mode, “!” is trimmed mode.  Second option sets separator char, by default comma.  In this case its changed to | so Font extension will be called with single argument “s18, Courier New”.

Returns

Control’s handle if successful.  0 or error mesage if control can’t be created.  Error message on invalid usage.

Form_AutoSize( Hwnd,    Delta  =  "" )

Resize the window so all controls fit.

Remarks

This function works similar to Gui, Show, AutoSize.  The difference is that it works on Panel also and takes into account custom controls.

Dependencies

Win 1.22

Form_Destroy( HForm  =  "" )

Destroy the form.

Form_Default( HForm )

Set form as default one.

Remarks

Form_Hide( HForm )

Hide the form.

Form_GetNextPos(   HForm,      Options  =  "", ByRef  x  =  "", ByRef  y  =  "" )

Obtain the position of next control.

Parameters

Returns

”x” x “ y” y

Remarks

This is very slow function.  It is created just because there might be a need for it in some scenarios.  It creates dummy control with given options, take its x & y coordinates and then deletes it.

Form_New( Options  =  "", E1  =  "", E2  =  "", E3  =  "", E4  =  "", E5  =  "" )

Creates new form.

Parameters

Custom Options

Returns

Form handle.

Remarks

Label is not optional.  Module will set it even if you don’t specify it.  By default, label is set as “FormN” where N is the Gui number.  That means that GuiXXXXX labels can’t be used, but FormN_XXXXX instead.  Single label shouldn’t be used with more then 1 form.

You can reference the form in other functions in several ways: its GUI number, its HWND or its Label.  To obtain Gui number use Form_GetNum function with label or hwnd argument.

If you are adding control to the panel, Margin

Form_Parse(   O,      pQ,    ByRef  o1  =  "", ByRef  o2  =  "", ByRef  o3  =  "", ByRef  o4  =  "", ByRef  o5  =  "", ByRef  o6  =  "", ByRef  o7  =  "", ByRef  o8  =  "", ByRef  o9  =  "", ByRef  o10  =  "", ByRef  o11  =  "", ByRef  o12  =  "", ByRef  o13  =  "", ByRef  o14  =  "", ByRef  o15  =  "" )

Form options parser.

Query

Query is space separated list of variables you want to extract with optional settings prefix . The query syntax is:

Query :: [Settings)][Name=]Value {Query}
Settings :: sC|aC|qC|eC|c01{Settings}
Value   :: SentenceWithoutSpace | 'Sentence With Space'

Examples

options =  x20 y40 w0 h0 red HWNDvar gLabel
options =  w800 h600 style='Resize ToolWindow' font='s12 bold, Courier New' 'show' dummy=dummy=5

Extracting

To extract variables from the option string you first use query parameter to specify how to do extraction then you supply variables to hold the results:

Parse(O, "x# y# h# red? HWND* style font 1 3", x, y, h, bRed, HWND, style, font, p1, p3)

Settings

You can change separator(s), assignment(a), escape(e) and quote(q) character and case sensitivity (c) using syntax similar to RegExMatch.  Option value follows the option name without any separator character.

Parse("x25|y27|Style:FLAT TOOLTIP", "s|a:c1)x# y# style", x, y, style)

In above example, | is used as separator, : is used as assignment char and case sensitivity is turned on (style wont be found as it starts with S in options string).

Remarks

Currently you can extract maximum 10 options at a time, but this restriction can be removed for up to 29 options.  You can specify one more reference variable in addition to those you want to extract to get all extra options in the option string.

Returns

Number of options in the string.

Form_Show( HForm  =  "", Options  =  "", Title  =  "" )

Show form.

Parameters

Returns

Form_Set( HForm,    Options  =  "", n  =  "" )

Set Form options.

Parameters

Form(   Var  =  "",   Value  =  "~`a ", ByRef  o1  =  "", ByRef  o2  =  "", ByRef  o3  =  "", ByRef  o4  =  "", ByRef  o5  =  "", ByRef  o6  =  "" )

Storage.

Parameters

Returns

• if value is omitted, function returns the current value of var
• if value is set, function sets the var to value and returns previous value of the var
• if var is empty, function accepts list of variables in value and returns values of those variables in o1 .. o5

Remarks

Form extensions can use this function to keep its internal data.  This avoid the need to polute global variable space.  In order to support working with or without forms, you can use dynamic function calls to invoke this function.

Examples

Form(x)                             ; returns value of x or value of x from v.ahk inside scripts dir.
Form(x, v)                          ; set value of x to v and return previous value.
Form("", "x y z", x, y, z)          ; get values of x, y and z into x, y and z.
Form("", "prefix_)x y z", x, y, z)  ; get values of prefix_x, prefix_y and prefix_z into x, y and z.