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

hiCreateTabField

hiCreateTabField(
?name s_name
?fields l_fieldEntries
[ ?attachmentList l_fieldAttachments ]
[ ?tabs g_tabs ]
[ ?pageBase g_pageBase ]
[ ?value g_currentValue ]
[ ?defValue g_defaultValue ]
[ ?tabPlacement g_tabPlacement ]
[ ?tabOrderIsAddOrder g_tabOrderIsAddOrder ]
[ ?callback g_callback ]
[ ?pageScroller g_pageScroller ]
[ ?notebookStyle g_notebookStyle ]
[ ?help g_fieldHelp ]
[ ?invisible g_invisible ]
[ ?tabToolTips l_tooltip ]
[ ?tabLabels l_tabLabel ]
[ ?scrollPage l_scrollPage ]
)
=> r_fieldHandle

Description

Creates a tab field, which can have multiple pages. You can change the pages interactively by selecting the tab attached to each page, or programmatically by using the form->field->value property.

Tab fields do not have scroll bars. If you want scroll bars on a tab page, place a scroll region on that page. You can do so only if the fields in the tab field do not have attachments and if the tab field itself is not an attached field, that is, a field attachment is not specified for it when the form is created. For information about scroll regions, see hiCreateScrollRegion.

You can enable or disable (gray out) either a specific page of the tab field or the entire tab field with the enabled property.

To enable or disable the entire field, use the following:

form->tabField->enabled = t | nil

To enable or disable a specific page of the tab field, use the following:

form->tabField->page->enabled = t | nil

The status of the fields within the tab field or tab page does not get updated with these settings. If you query a field within a tab field with form->tabfield->field->enabled, the field reports its own enabled/disabled status, regardless of whether it is in an enabled or disabled tab field.

Also, you cannot enable a field that is within a disabled tab field or disabled tab page. If you specify form->tabField->field->enabled=t, the field does not get enabled until the tab field itself becomes enabled.

A tab field can also have a context menu, that is, a pop-up menu that is displayed when you right-click on the field.

You can create a tooltip for this field; see Creating Tool Tips for Fields.

Arguments

?name s_name

Handle to the tab field within a form. To reference it, use:

formHandle->hiFieldSym

?fields l_fieldEntries

  

A list of 2-D lists. Each 2-D list forms a page of the tab field. The number and order of elements in the l_fieldEntries argument determine the number and order of pages in the tab field. The default value of this argument is nil.

For more information about 2-D lists, see Two Dimensional Form Layout.

You can reference a tab page by its base name (which lets you reference the page by position) or with a combination of the base name and tab label (which lets you reference the page by name). Use the following command:

formHandle->hiFieldSym->tabPage

where tabPage is either pageBaseName# or pageBaseName_tabLabel. (See the g_pageBase argument for more information about the base name and the g_tabs argument for more information about the tab label.)

For example, if you have the following tab field in a form myForm:

hiCreateTabField(?name ’myTabField ... ?tabs list("abc" "def" "ghi")...)

and the default page base name, page, is used, then you can reference the second tab in one of the following ways:

myForm->myTabField->page2
myForm->myTabField->page_def

Referencing the tab page by tab name (the second option listed above) allows you to insert additional tab pages easily without affecting existing code.

Any whitespace in the tabLabel name is converted to underscore and leading or trailing whitespace is removed.

?attachmentList l_fieldAttachments

Determines how each page of the tab field attaches to the tab pane. For more information about field attachments, see Field Attachments.

?tabs g_tabs

List of strings representing the tab labels. nil and "" (empty string) are also legal values. If you specify "", the page has an empty tab. If you specify nil, the page has a tab but whether the page is enabled or disabled depends on the value of the g_pageScroller argument—if g_pageScroller is t, the page is enabled and its tab displays the page number; if g_pageScroller is nil, the page is disabled and its tab is blank.

The default value of this argument is nil.

?pageBase g_pageBase

  

A string or symbol that defines the base name for each page of the tab field. The default base name for each page is "page".

The first page of the tab field is named pageBaseName1, the second page is named pageBaseName2, and so on, up to the last page of the field. If you do not provide a base name, the default names of the pages are page1, page2, page3, and so on.

This argument is necessary if you create a tab field within a tab field as you need to distinguish the pages of one from the other.

?value g_currentValue

  

Initial and current value of the field. Determines which page is displayed when the tab field first appears. The legal values for this argument are 1 to number_of_pages, where 1 indicates the first page. To change the value, use:

form->field->value = x

where x is any number between 1 and number_of_pages.

?defValue g_defaultValue

  

Default value of the field. Determines which page of the tab field is displayed as the default. The legal values for this argument are 1 to number_of_pages, where 1 indicates the first page. To change the value, use:

form->field->defValue = x

where x is any number between 1 and number_of_pages.

?tabPlacement g_tabPlacement

  

Location of the tabs on the field. Specify one of the following:

’top

’bottom

The default value of this argument is ’bottom.

’left and ’right are no longer supported. For any existing ’left or ’right settings, tabs are placed at the top of the field.

?tabOrderIsAddOrder g_tabOrderIsAddOrder

Determines the order in which pages within the tab field are traversed when the Tab key is pressed. If you specify t, the nextField property is automatically set for the fields and the traversal order is the order in which fields are added to the form (that is, the order in which they are listed in the l_fieldEntries list). If you specify nil, the default traversal order is based on the form layout —left-to-right and top-to-bottom— beginning with the field at the top-left corner of the form.

The default value of g_tabOrderIsAddOrder is nil.

The nextField property set on a field (to any non-nil value) overrides the g_tabOrderIsAddOrder value.

?callback g_callback

  

Triggers callback function when the pages are changed. The default value of this argument is an empty string ("").

?pageScroller g_pageScroller

  

Enables a page that has a tab label of niland the page number gets displayed for its tab. If this argument is nil, any page that has a tab label of nil is disabled and displays a blank tab.

The default value of this argument is nil.

?notebookStyle g_notebookStyle

  

This argument is now ignored. The Motif Notebook style is not supported any longer.

?help g_fieldHelp

A string or symbol used to reference help. If not specified, s_name is used. This argument is currently not used.

?invisible g_invisible

  

Controls if you want the field to be invisible or visible. The default value is nil.

You can modify the value of this argument (after the form is created) with the invisible property. For example:

formHandle->fieldSym->invisible = nil

?tabToolTips l_tooltips

A list specifying strings to be used as tab tooltips.

?tabLabels l_tabLabel

A list specifying strings to be used as tab labels. You can specify multiple lines as labels. The label strings can be specified in plain text or rich text. For new line, use <br> for rich text and /n for plain text.

When this option is specified, the value for the ?tab argument is ignored.

Specifies a list of strings as tab labels. Each string can be specified in plain text or in rich text.

The argument supports multiple-line label. For newline, use \n for plain text and <br> for rich text.  

When specified, the option replaces ?tag for tab labels.

?scrollPage l_scrollPage

A list specifying whether scrollbar needs to be enabled for different tabs in a form:

?scrollPage list(t/nil)

The default is t, which means that if you do not specify any value or specify the following, scrollbars are added to all tabs of the form:

?scrollPage list()

The following statement also adds scrollbar to all tabs:

?scrollPage list(t)

You can specify values for only some of the tabs. In this case, all of the next tabs have the same value as the last value defined in the list. For example, consider you have five tabs and you specify:

?scrollPage list(t nil)

It is same as specifying:

?scrollPage list(t nil nil nil nil)

In this example, scrollbars are added only to the first tab.

If you specify the following:

?scrollPage list(t nil t)

It is same as specifying:

?scrollPage list(t nil t t t)

This means that all tabs except the second tab have scrollbars.

Value Returned

r_fieldHandle

Handle to the tab field.

Examples

A form named Tab Field Form with the specified tabs is created. 

CycField = hiCreateCyclicField(
    ?name       'CycField
    ?prompt     "Cyclic"
    ?choices    list( "hello" "bonjour" "guten tag" "buenos tardes" )
    ?value      "hello"
)
StringField = hiCreateStringField(
    ?name       'StringField
    ?prompt     "String"
    ?format     "%s"
    ?defValue   "String"
    ?value      "valString"
)
FrameField = hiCreateFrameField(
    ?name    'FrameField
    ?labelText    "Frame"
)
ListBField = hiCreateListBoxField(
    ?name    'ListBField
    ?prompt    "List Box"
    ?choices    list( "bowling" "volleyball" "softball" "baseball"
        "duckpins" "basketball" "tennis" "football" )
    ?value    list( 1 3 4 "football" )
    ?numRows    3
    ?multipleSelect t
    ?keepHistory t
)
MlTextField = hiCreateMLTextField(
    ?name    'MlTextField
    ?prompt    "ML Text"
    ?value    "The quick brown fox jumped\nover the lazy yellow dog."
    ?defValue    "The quick brown fox jumped\nover the lazy yellow dog."
    ?enableWordWrap t
)
IntField = hiCreateIntField(
    ?name    'IntField
    ?prompt    "Integer"
    ?value    4192
    ?defValue    4192
)
ListField = hiCreateListField(
    ?name    'ListField
    ?prompt    "List"
    ?value    list( 1 2 "three" "four" 4.999764 )
    ?defValue    list( 1 2 "three" "four" 4.999764 )
)
PointField = hiCreatePointField(
    ?name    'PointField
    ?prompt    "Point"
    ?value    124:255
    ?defValue    124:255
)
BboxField = hiCreateBBoxField(
    ?name    'BboxField
    ?prompt    "BBox"
    ?value    list( 12:25 233:165 )
    ?defValue    list( 12:25 233:165 )
)
TabField = hiCreateTabField(
    ?name    'TabField
    ?pageScroller nil
    ?fields    list(
      list(
   list( FrameField 5:17 235:52 15 )
   list( CycField 10:33 130:30 55 )
   list( StringField 5:70 230:10 55 )
      )
      list(
   list( ListBField 5:10 230:80 55 )
   list( MlTextField 5:90 250:80 55 )
   list( IntField 5:170 230:10 55 )
      )
      list(
   list( ListField 5:10 230:10 55 )
   list( PointField 5:40 230:10 55 )
   list( BboxField 5:70 230:10 55 )
      )
  )
    ?tabPlacement 'top
    ?callback    'SampleTabFieldCB
    ?tabs    list( "Fred" "Wilma" "Barney" )
)
procedure( SampleTabFieldCB( )
    let(((MyForm hiGetCurrentForm()))
 MyForm->TabField->defValue = MyForm->tabField->value
 printf("tab field value = %L\n", MyForm->tabField->value)
    )
)
TabFieldForm = hiCreateAppForm(
  ?name  'TabFieldForm
  ?formTitle "Tab Field Form"
  ?fields  list( list( TabField 10:10 300:235 ))
  ?buttonLayout 'OKCancelApply
  ?formType 'nonOptions
  ?unmapAfterCB t
  ?initialSize t
             )
hiDisplayForm(TabFieldForm)

A form named 2D Form is created. Each tab in the form has tooltips added using the ?tabToolTips argument. The form has multiple tabs and each tab has a tooltip. The example also shows how to add different types of labels using the ?tabLabels argument.

listField = hiCreateListField(
    ?name       'listField
    ?prompt     "List"
    ?value      list( 1 2 "three" "four" 4.999764 )
    ?defValue   list( 1 2 "three" "four" 4.999764 )
    ;?editable   nil
)
pointField = hiCreatePointField(
    ?name       'pointField
    ?prompt     "Point"
    ?value      124:255
    ?defValue   124:255
    ?editable   nil
    ?invisible  nil
)
bboxField = hiCreateBBoxField(
    ?name       'bboxField
    ?prompt     "BBox"
    ?value      list( 12:25 233:165 )
    ?defValue   list( 12:25 233:165 )
    ?editable   nil
)
ptListField = hiCreatePointListField(
    ?name       'ptListField
    ?prompt     "Point List"
    ?value      list( 50:50 60:60 45:95 95:45 50:60 60:50 )
    ?defValue   list( 50:50 60:60 45:95 95:45 50:60 60:50 )
    ?editable   nil
)
tabField1 = hiCreateTabField(
    ?name       'tabField1
    ?fields     list(
                    list(
                        list( pointField 5:15 230:10 55 )
                        ;list( bboxField 5:45 230:10 55 )
                        ;list( ptListField 5:75 230:10 55 )
                    )
                    list(
                        list( pointField 5:15 230:10 55 )
                        list( bboxField 5:45 230:10 55 )
                        ;list( ptListField 5:75 230:10 55 )
                    )
                    list(
                        list( pointField 5:15 230:10 55 )
                        list( bboxField 5:45 230:10 55 )
                        list( ptListField 5:75 230:10 55 )
                    )
                )
    ?tabPlacement 'top
    ?tabs       list( "Tab1" "Tab2" "Tab3")
    ;?tabLabels list( "&Line 1\nLine 2" "&Short\nVery Long Long" "Very Long Long\nShort")
    ?tabLabels list( "&Line 1\nLine 2" "<b>Short<br>&Very Long Long</b>" "<h2><b><font color='green'>+&Big+</font></b>")
    ?tabToolTips list("tooltip 1" "tooltip 2" "tooltip 3")
)
tabField2 = hiCreateTabField(
    ?name       'tabField2
    ?fields     list(
                    list(
                        list( pointField 5:15 230:10 55 )
                        ;list( bboxField 5:45 230:10 55 )
                        ;list( ptListField 5:75 230:10 55 )
                    )
                    list(
                        ;list( pointField 5:15 230:10 55 )
                        list( bboxField 5:45 230:10 55 )
                        ;list( ptListField 5:75 230:10 55 )
                    )
                    list(
                        ;list( pointField 5:15 230:10 55 )
                        ;list( bboxField 5:45 230:10 55 )
                        list( ptListField 5:75 230:10 55 )
                    )
                )
    ;?tabPlacement 'bottom
    ?tabPlacement 'top
    ?tabs       list( "Tab1" "Tab2" "&Tab3")
    ?tabLabels list( "&One Line" "&Short\nVery  Long Long" "<b><font color='red'>&Red Tab</font></b>")
    ?tabToolTips list("tooltip a" "tooltip b" "tooltip c")
)
tabField3 = hiCreateTabField(
    ?name       'tabField3
    ?fields     list(
                    list(
                        list( pointField 5:15 230:10 55 )
                        ;list( bboxField 5:45 230:10 55 )
                        list( ptListField 5:75 230:10 55 )
                    )
                    list(
                        list( pointField 5:15 230:10 55 )
                        list( bboxField 5:45 230:10 55 )
                        ;list( ptListField 5:75 230:10 55 )
                    )
                    list(
                        ;list( pointField 5:15 230:10 55 )
                        list( bboxField 5:45 230:10 55 )
                        list( ptListField 5:75 230:10 55 )
                    )
                )
    ?tabPlacement 'top
    ?tabs       list( "Tab&1" "Tab&2" "Tab&3")
    ?tabToolTips list("tooltip x" "tooltip y" "tooltip z")
)
my2DFields = list(
                list( tabField1 15:15  300:150 15 )
                list( tabField2 15:175 300:150 15 )
                list( tabField3 15:340 300:150 15 )
   )
my2DForm = hiCreateAppForm(
                ?name           'my2DForm
                ?formTitle      "2D Form"
                ?fields         my2DFields
                ?buttonLayout   'Close
                ?formType       'nonOptions
                ?unmapAfterCB   t
                ?dontBlock      t
                ?initialSize    1000:800
                ;?maxSize        2000:2100
                ?minSize        330:300
                ?fieldFocus     'allFields
             )
my2DForm->tabField3->hiToolTip = "Body 3 ToolTip"
my2DForm->tabField2->hiToolTip = "Body 2 ToolTip"
my2DForm->tabField1->hiToolTip = "Body 1 ToolTip"
hiDisplayForm my2DForm

Related Topics

Form and Field Functions


Return to top
 ⠀
X