Two Dimensional Form Layout
The two-dimensional layout of form fields may be obtained by specifying 2D attributes. The specification of these attributes is optional. A form or menu is 2D if attributes are specified for each field description when creating a form or two-dimensional menu. They are not specified when creating fields themselves. If you specify 2D attributes for one field, you must specify them for all fields. If 2D attributes are not specified, form fields are sequentially laid out in a one-dimensional column.
Through two-dimensional attributes, you are given the flexibility of exact placement of fields. No geometry management is provided, and the fields appear as specified. 2D fields may therefore be specified in any order. Since field coordinates are implicitly obeyed, it is possible to place fields on top of others. Keep this in mind while specifying field locations.
2D attributes are specified in pixel values. The attributes for each field may vary, depending upon how much flexibility you are given. The minimal set of required attributes includes x, y, width, and height. The attributes x and y are coordinates of the upper-left corner of the field, relative to the upper-left (0,0) corner of the form (below the form banner) or menu. The attributes width and height specify the width and height of the field. An additional, optional attribute lets you specify the prompt box width or title height. These attributes are described in more detail below.
2D attributes are specified at the time the form or menu is created. The attributes should be appended to a list, where the first item of the list is the form field. For example, a 2D field attribute is specified in the following list:
list(r_fieldDescriptionx_xpos:x_yposx_width:x_height[x_promptBoxWidthOrTitleHeight] )
|
Field description returned from one of the field creation routines. |
|
|
Upper-left x coordinate in pixels of the field relative to the upper-left corner of the form. |
|
|
Upper-left y coordinate in pixels of the field relative to the upper-left corner of the form. |
|
|
For fields that have a prompt and that are laid out horizontally, such as a string field or spin box field, this attribute is the width of the prompt box in pixels. For fields that have a top-down layout, such as the report field and the scroll region field, this attribute is the height of the title box in pixels (the title is displayed at the top of the title box). |
|
|
Use this attribute only if the prompt or title is not |
|
|
The value of this attribute should be less than the total width of the field (specified by x_width) or less than the total height of the field (specified by x_height), as applicable, and it cannot be a negative number. |
|
|
This attribute should not be used for those fields that have no prompts, such as |
|
|
This attribute is optional for fields created with hiCreateBooleanButton. If you do not specify it, the right edge of the toggle button appears at the right edge of the field — x_xpos |
|
|
For certain 2D attributes, you may specify a constant which takes on a value determined by the size of the form. For this purpose, |
|
|
Used to indicate that the height of this field should span the height of the form. This value is computed at the time the form is created. |
|
|
Used to indicate that the width of this field should span the width of the form. This value is computed at the time the form is created. |
|
Field Attachments
Use field attachments if you want the fields in a two-dimensional form or scroll region to be automatically resized when the form is resized. One-dimensional forms do not support field attachments.
Field attachments are used in conjunction with two-dimensional attributes; they determine how the two-dimensional attributes of a field are used to position that field in the form. Like two-dimensional attributes, field attachments need to be specified when you create a form.
If you want to use field attachments, you must do the following when you create a form:
- Specify the initial size of the form by providing a list of width and height for the g_initialSize argument.
- Specify two-dimensional attributes for each field entry in the l_fieldEntries argument.
- Provide field attachments for each field listed in l_fieldEntries.
You specify field attachments by using the ?attachmentList l_fieldAttachments argument in the function hiCreateAppForm. This argument takes a list of attachments, which are applied to the corresponding fields in the l_fieldEntries argument. Each attachment is a bitwise OR of a list of constants. Each constant is the attachment specification for a side of the field—left, right, top, or bottom.
You can specify either positional attachments or percentage attachments for the sides of a field.
If you want the left and top edges of a field to be at a fixed distance from the upper left corner of the form, but the width and height to grow as a percentage of the size of the form, use the following field attachments for the field:
hicTopPositionSet | hicLeftPositionSet | hicRightPercentSet | hicBottomPercentSet
The following routine creates a one-dimensional form containing a button field and a cyclic field:
hiCreateAppForm( ?name 'myForm
?formTitle "formName"
?fields list( buttonField cyclicField )
?callback "doneCallback()"
?help "formHelp" )
The following routine creates a two-dimensional form containing a field and a cyclic field:
hiCreateAppForm( ?name 'myForm
?formTitle "formName"
?fields list(
list( buttonField x:y width:height )
list( cyclicField x2:y2 width2:height2
promptWidth ))
?callback "doneCallback()"
?help "formHelp" )
The following routine creates a two-dimensional form with field attachments:
hiCreateAppForm( ?name 'myForm
?formTitle "formName"
?fields list(
list( buttonField x:y width:height )
list( cyclicField x2:y2 width2:height2 promptWidth)
)
?attachmentList list( hicTopPositionSet|hicLeftPositionSet|
hicRightPercentSet|hicBottomPercentSet nil)
?initialSize list( width height)
?callback "doneCallback()"
?help "formHelp" )
The following routine creates a 2D menu:
hiCreate2DMenu( 'myMenu
"menuName"
list( list( buttonField x:y width:height )
list( labelField x2:y2 width2:height2 ))
"menuHelp" )
In the above examples, buttonField is the value returned from hiCreateButton, cyclicField is the value returned from hiCreateCyclicField, and labelField is the value returned from hiCreateLabel. The creation of these fields is shown below.
Specifying fields for 2D menus is the same as that for 2D forms, but only button and label fields created with hiCreateButton and hiCreateLabel are accepted. 2D menus are displayed in the same way as popup menus, with hiDisplayMenu.
buttonField = hiCreateButton( ?name 'someButton
?buttonText "More Options"
?callback "printf(\"pressed\")" )
cyclicField = hiCreateCyclicField( ? name 'cyclic
?prompt "Cycle through:"
?value "a"
?choices '("a" "b" "c" ) )
labelField = hiCreatelabel( ?name 'myLabel
?labelText "I’m a label"
?justification 'center )
To query the extent of the button field, call hiGetFieldInfo and look at the contents of extentList. For example:
extentList = hiGetFieldInfo( myForm 'cyclic )
where extentList would be of the form
(( x2 y2 ) ( width2 height2 ) promptWidth )
Positional Attachments
If you specify a positional attachment for a side of the field, that side is placed at a fixed offset from the same side of the form. When the form is resized, that side of the field maintains the fixed distance from the same edge of the form. The form width and height are obtained from the g_initialSize argument of the hiCreateAppForm function.
Positional attachments are applied to the two-dimensional attributes of a field in the following way:
where x, y, width, and height are obtained from the two-dimensional attributes of the field, which are specified in the l_fieldEntries argument of hiCreateAppForm.
If you do not specify an attachment for either the left or right side (or both), the field width remains constant. If you do not specify an attachment for the top or bottom side (or both), the field height remains constant.
If you specify both positional and percentage attachments for a side, the positional attachment takes precedence.
Percentage Attachments
If you specify a percentage attachment for a side, that side is initially placed the same way as with a positional attachment; however, when the form is resized, that side maintains the same percentage placement within the form. For example, if you specify hicRightPercentSet, and the x location of the field is 10, the width of the field is 90, and the width of the form (as specified by g_initialSize) is 200, then the right side of the field is initially placed at 100 and when the form is resized the right side of the field always be kept halfway between the left and right sides of the form, that is, at the 50% position.
Percentage attachments are applied to the two-dimensional attributes of a field in the following way:
where x, y, width and height are obtained from the two-dimensional attributes of the field (specified in the l_fieldEntries argument of hiCreateAppForm), and formWidth and formHeight are obtained from the g_initialSize argument of hiCreateAppForm.
If you do not specify an attachment for either the left or right side (or both), the field width remains constant. If you do not specify an attachment for the top or bottom side (or both), the field height remains constant.
If you specify both positional and percentage attachments for a side, the positional attachment takes precedence.
Related Topics
Return to top