hiCreateLayoutForm

hiCreateLayoutForm( 
s_name 
t_title 
r_layout 
[ ?callback g_callback ]
[ ?mapCB g_mapCallback ]
[ ?help g_help ]
[ ?unmapAfterCB g_unmapAfterCB ] 
[ ?buttonLayout g_buttonLayout ]
[ ?buttonDisabled l_buttonDisabled ]
[ ?formType s_formType ]
[ ?dialogStyle s_dialogStyle ]
[ ?baseName s_baseName ]
[ ?plist g_plist ]
[ ?initialSize l_initialSize ]
[ ?minSize l_minimumSize ] 
[ ?maxSize l_maximumSize ]
[ ?sizePolicy s_sizePolicy ]

) 
=> r_form / nil

Description

Returns the SKILL representation of a layout form with the specified field entries and sets it to the specified name.

Arguments

s_name	The global SKILL symbol used to reference this form.
t_title	Specifies the form title, which is displayed on the top of the form.
r_layout	The main hiLayout of the form.
`?callback` g_callback
	Specifies the SKILL functions (callbacks) that execute after you select Apply, OK, or Cancel in the form. g_callback can be in one of two formats: g_okAction or'`(`g_okAction g_cancelAction`)` g_okAction specifies the SKILL function to be executed when the Apply, OK, Close, or Quit button is pressed in a form; g_cancelAction specifies that the SKILL function to be executed when the Cancel button is pressed. Here, if g_cancelAction is not specified, no callback is called when the form is canceled. Both g_okAction and g_cancelAction can be in one of the following formats: t_callback, s_callback, or u_callback t_callback is the string representation of the SKILL function to be executed. If you specify t_callback, the string is evaluated and the callback function is not passed any argument. s_callback is the symbol of the SKILL function to be called. If you specify s_callback, the callback function is passed and r_form returned from `hiCreateLayoutForm` as its only parameter. u_callback is a callback of the function object type. The callback function is passed and r_form returned from `hiCreateLayoutForm` as its only parameter. After the form is instantiated, you can change the callback with the `hiChangeFormCallback` function.
`?mapCB` g_mapCallback
	Specifies the callback to be invoked when the form is mapped, that is, when `hiDisplayForm` is called for a form that is not currently mapped. Specify one of the following: The name (string), Symbol of the map callback function, The function object.
`?help` g_help	Specify g_help as one of the following: Single string Single symbol List of strings List of symbols that are used to refer a `.tgf` help file. If you do not want to use the default `.tgf` help file mechanism, you can specify your own callback for the Help button. If you specify a single string or symbol, it is used to set the `hiHelpAppName` property on the symbol that represents the form name. If you specify a list of strings or a list of symbols, the first element in the list is used to set the `hiHelpAppName` property and the second element is used to set the `hiHelpSymName` property. If you want to specify only the help symbol, specify a list of two strings or symbols, with `nil` as the first element of the list and the help symbol as the second element. This sets the `hiHelpSymName` property without setting the `hiHelpAppName` property.)
	When a user clicks Help on the form, the `hiHelp` function is called with the following arguments: appId helpTag If the `hiHelpAppName` property has been set, it is used as the appId, otherwise the application ID of the current window is used as the appId. If the `hiHelpSymName` property has been set, it is used as the helpTag, otherwise the form name is used as the helpTag.
	The appId and helpTag determine the name of the tag file that is called (appId`.tgf`) and the help tag in the file that is accessed. You can also use the `hiHelpAppName` and `hiHelpSymName` properties directly to specify the help file and help tag that are used to reference the help.
`?unmapAfterCB` g_unmapAfterCB
	If set to `t`, the form is removed (unmapped) from the screen after the callback is executed. If set to `nil`, the form is removed before the callback is invoked. The default value is `nil`. If you use hiSetCallbackStatus in your callback routine, you must set the value of g_unmapAfterCB to `t` or the callback status is ignored.
`?buttonLayout` g_buttonLayout
	Specifies the buttons that appear at the bottom of the form. g_buttonLayout can be in one of the following formats: s_buttonLayout Displays a predefined set of buttons, followed by the Help button. You can select from a list of button layouts. '(s_buttonLayout (s_customButtonText s_customButtonCB) ...) Displays a predefined set of buttons, followed by your custom buttons and the Help button. Custom buttons are specified as button text/button callback pairs.
	`’`(`’`Empty (s_customButtonText s_customButtonCB) ...) Displays only custom buttons, followed by the Help button. Specify either OK, Close, or Quit as one of the button names in your list of custom buttons so the form can be closed. You can use `hiFormClose()` as the callback for these buttons. ’`Empty` Does not display any buttons in the form. The form can be closed either through the window manager or by calling `hiFormDone()`.
	s_buttonLayout specifies a predefined set of buttons. The Help button is automatically added with each of these combinations. Select one of the following button layouts: For non-options forms: `’OKCancel ’OKCancelDef ’OKCancelLast ’OKCancelDefLast ’OKCancelApply ’ApplyCancel ’ApplyCancelDef ’ApplyCancelLast ’ApplyCancelDefLast ’Close/’Quit ’OKCancelDefApply` (default) You can use the Quit button instead of the Close button with the same behavior. For options forms: `’HideCancel ’HideCancelDef ’HideCancelLast ’HideCancelDefLast`(default) `’ApplyHideCancel ’ApplyHideCancelDef ’ApplyHideCancelLast ’ApplyHideCancelDefLast`
	where, `OK` denotes the OK button (`hiFormDone` is called when this button is pressed, and `hiFormDone` calls the g_okAction callback); `Apply` denotes the Apply button (`hiFormApply` is called when this button is pressed, and `hiFormApply` calls the g_okAction callback);
	`Cancel` denotes the Cancel button (`hiFormCancel` is called when this button is pressed, and `hiFormCancel` calls the g_cancelAction callback); `Close` denotes the Close or Quit button (`hiFormClose` is called when this button is pressed, and `hiFormClose` calls the g_okAction callback. The Close and Quit buttons are similar to the OK button; `hiFormClose` is an alias for `hiFormDone`); `Last` denotes the Last button; `Def` denotes the Defaults button; `Hide` denotes the Hide button. If there is no Cancel button on a form but there is a Close or Quit button, when you close the form from the window manager or by typing `hiFormCancel` in the CIW, `hiFormDone` is called. For custom buttons, s_buttonLayout or ’Empty should be listed consisting of button text/button callback pairs: `’(`s_customButtonText s_customButtonCB`)` s_customButtonText is the symbol whose printname is the button text. For example, to have a button "Press Me", s_customButtonText would be specified as `’Press\ Me`. You can use `concat("`string`")` to get the symbol of a string. s_customButtonCB is the callback for the button and can be specified as a symbol or string. If it is a symbol, the callback function is passed and r_form returned from `hiCreateAppForm` as its only argument. If it is a string, the unchanged string is passed to SKILL to interpret.
	Press Enter to perform the same action as the first button of the form button list. This is usually `hiFormDone()` for non-options forms and `hiToggleEnterForm()` for options forms. If you specify your own button list, you need to be aware that the action of <Enter> is changed. For example, if your button list is `’ApplyCancelDef`, the action of <Enter> in a type-in field performs the `hiFormApply()` action. Use `formDefaultAction` to specify the buttonText of a button to link to the `Enter` Key.
`?buttonDisabled` l_buttonDisabled
	List of buttons that are disabled when the form appears. You can change this value with the `hiSetFormButtonEnabled` function.
`?formType` s_formType
	Possible choices include `’nonoptions` (default), or `’options`. Options forms must be modeless.
`?dialogStyle` s_dialogStyle
	One of the following symbols, which determines the blocking behavior of the form: `’modal`Blocks access to the application while it is displayed. You must dismiss the form in order to continue using the application. (Access to window manager commands or other applications is not blocked.)
	`’modeless`Does not block access to the application. You can continue using the application without having to close the form. The default value of this argument is `’modeless`.
`?baseName` s_baseName
	A string or symbol that defines the base name of the form.
g_plist	Indicates whether or not this is a "property list" form.
`?initialSize` l_initialSize
	A list of width and height values. The form is sized to the specified width and height, or to the size needed to accommodate all the fields, whichever is less.
`?minSize` l_minimumSize
	The minimum size of the form, specified as a list of width and height or width`:`height values. The minimum size excludes the window manager’s title and border. The default minimum width is a few pixels wider than the width of the button banner and the default minimum height is a few pixels more than the height of the button banner. To change the minimum size, use the `hiSetFormMinMaxSize` function.
`?maxSize` l_maximumSize
	The maximum size of the form, specified as a list of width and height or width`:`height. The maximum size excludes the window manager’s title and border. The default maximum size is the size of the screen. To change the maximum size, use the `hiSetFormMinMaxSize` function.
`?sizePolicy s_sizePolicy`
	Controls how the forms can be resized. It includes the following options: `'expanding`: Allows resizing of form layout in both the directions. `'horizontalExpanding`: Allows horizontal resizing of the form layout. `'verticalExpanding`: Allows vertical resizing of the form layout. `'fixed`: Resizing is not allowed. Default value: `'expanding` It includes only the interactive resizing of the form. The `sizePolicy` cannot be changed once the form is instantiated or displayed.

Values Returned

r_form	Returns the handle of the form. the SKILL representation of a layout form
`nil`	The handle of the form is not returned.

Additional Information

When creating a hiLayout form, instead of a list of fields, a single layout container is passed to hiCreateLayoutForm. The layouts themselves contain the details of the fields within. A specified layout have a name, which must be unique within the form, tab page or scroll region. Each layout contains not only a list of fields, but options relevant to the layout type for describing spacer items or stretch items and how alignment works within the layout. Fields can be added and deleted to layouts similar to 1D and 2D forms, but specifying coordinates are not necessary.

The fields within a layout can be accessed without using the layout container. For example, a field myField within a layout myLayout on a form myForm can be accessed using:

myForm->myField->value

which makes it simpler to convert existing code using a 2D form to use hiLayout containers. Instead, the code does not need to be updated to reflect any new containers which have been inserted. Alternatively, you can use myForm->myLayout->myField->value.

The only field type not supported in an hiLayout form is a frame field. This is replaced by the ?frame argument for each layout creation function.

Cadence User Interface SKILL Reference
Product Version IC23.1, September 2023