Form

Form module presents alternative way of creating AHK windows.  It can be used alone or as a part of the Forms framework.  Some of the main differences between normal GUI creation and the way it is done using the module are:

  • Bigger cohesion - one function call can set most of the creation features for any control thus making changes, maintenance and bug testing much easier.
  • Custom controls without any syntax differences.  The end effect is the same as if you were using integrated AHK control.
  • Control extensions provide way to implement any behavior that you may want for control.
  • Provides elements for standardization of Gui/control creation process, option specification and module design.
Summary
FormForm module presents alternative way of creating AHK windows.
AddAdd control to the parent.
AutoSizeResize the window so all controls fit.
DestroyDestroy the form.
DefaultSet form as default one.
HideHide the form.
GetNextPosObtain the position of next control.
NewCreates new form.
ParseForm options parser.
ShowShow form.
SetSet Form options.
FormStorage.
About

Add

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

Add control to the parent.

Parameters

HParentHandle of the parent.  This can be top level window or container control.
CtrlControl name or handle.  All AHK controls are supported by default.  Custom controls must be included if needed.  See below for details.
TxtText of the new control (optional).
OptSpace separated list of control options (optional).
E1..E7Control extensions (optional).  Extension function must exist in the script in order to use it.  Option string may preceed extension name in the RegEx manner.  See below for details.

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.

AutoSize

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.

HwndHandle of the parent.
DeltaDot delimited string of DeltaW & DeltaH.  Delta is added to the calculated window size.  Both arguments are optional.

Dependencies

Win 1.22

Destroy

Form_Destroy(HForm = "")

Destroy the form.

Default

Form_Default(HForm)

Set form as default one.

Remarks

Hide

Form_Hide(HForm)

Hide the form.

GetNextPos

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

Obtain the position of next control.

Parameters

HFormHandle of the form.
OptionsForm control options.  Optional.
x, yReference to output variables.  Optional.

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.

New

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

Creates new form.

Parameters

OptionsForm options.  Any AHK Gui option can be set plus custom options listed bellow.

Custom Options

a#Alpha, procentage.
c#Gui color.  Hexadecimal or integer value.
e#How Escape key works.  “e1” will hide the form.  “e2” will destroy the form.  “e3” will exit the app.  Operation can happen only if form is the active window.  This option can not be used together with FormN_Escape routine.
m#Margin, decimal number in the form X.Y .
FontGui font (style, face).
NameName of the form, by default FormN where N is the number of the forms created.
TTransparent window.

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

Parse

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.

OString with Form options.
pQQuery parameter.  It is a space separated list of option names you want to extract from the options string.  See bellow for details of extraction.
o1..o10Variables to receive requested options.  Their number should match the number of variables you want to extract from the option string plus 1 more if you want to get non-consumed options.

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)
nameGet the option by the name (style, font).  In option string, option must be followed by assignment char (= by default).
NGet option by its position in the options string, (1 3).
str*Get option that has str prefix (HWND*).
str#Get option that holds the number and have str prefix (x# y# h#).
str?Boolean option, output is true if str exists in the option string or false otherwise (red?).

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).

sCSet separator char to C (default is space)
aCSet assignment char to C (default is =)
qCSet quote char to C (default is ‘)
eCSet escape char to C (default is `)
cNSet case sensitivity to number N (default is 0 = off)

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.

Show

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

Show form.

Parameters

HFormHandle of the form.  Defaults to first form created.
OptionsAny option that can be specified in Gui, Show.
TitleTitle of the window.  By default Label name.

Returns

Set

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

Set Form options.

Parameters

hFormHandle of the form.
OptionsForm options.  See New for details.
nInternally used.

Form

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

Storage.

Parameters

varVariable name to retrieve.  To get up several variables at once (up to 6), omit this parameter.
valueOptional variable value to set.  If var is empty value contains list of vars to retrieve with optional prefix
o1 .. o6If present, reference to variables to receive values.

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.

About

Form_Add(HParent,  
Ctrl,  
Txt = "",
Opt = "",
E1 = "",
E2 = "",
E3 = "",
E4 = "",
E5 = "",
E6 = "",
E7 = "")
Add control to the parent.
Form_AutoSize(Hwnd,  
Delta = "")
Resize the window so all controls fit.
Form_Destroy(HForm = "")
Destroy the form.
Form_Default(HForm)
Set form as default one.
Form_Hide(HForm)
Hide the form.
Form_GetNextPos( HForm,  
 Options = "",
ByRef x = "",
ByRef y = "")
Obtain the position of next control.
Form_New(Options = "",
E1 = "",
E2 = "",
E3 = "",
E4 = "",
E5 = "")
Creates new form.
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.
Form_Show(HForm = "",
Options = "",
Title = "")
Show form.
Form_Set(HForm,  
Options = "",
n = "")
Set Form options.
Form( Var = "",
 Value = "~`a ",
ByRef o1 = "",
ByRef o2 = "",
ByRef o3 = "",
ByRef o4 = "",
ByRef o5 = "",
ByRef o6 = "")
Storage.
Control container.
Set of window functions.
Close