To control the placement of text, a compound string can contain <tab> characters. To interpret those characters on display, a widget will refer to the rendition in effect for that compound string, where it will find a list of tab stops.
A tab stop is encoded in an XmTab data type, and a XmTabList is an array of one or more XmTabs. A tab stop contains a tab value, the units of the value (such as inches, centimeters, pixels), the offset model, and the alignment model. The offset model dictates whether the tab measurement is absolute, measured from the left margin of the compound string display (or the right margin if the layout direction is right-to-left), or relative, measured from the previous tab stop. The tab stop information also contains information about the alignment of the text and the tab stop. A user could choose to align the tab stop with the beginning, center, or end of the text appearing at the stop. However, the alignment model is included only for future use, and the only alignment model supported by Motif will align the beginning of the following text with the tab stop.
Note that only the tab list associated with the first text component on any displayed line is used. If a rendition contains a NULL tab list, the default tab list is used. This consists of ten tabs, each of eight font units (XmFONT_UNIT).
The following functions are used to create a single tab stop.
Use the XmTabCreate convenience function to create a tab stop from a tab value, the tab units, and the offset model. To specify the offset model, there are the defined constants XmABSOLUTE and XmRELATIVE. Note that the tab value must be a positive number, and that, if a tab stop would cause a text component to overwrite the previous component, the x position of the component will be moved (the tab is ignored) to follow the first component. There is also an input argument to XmTabCreate to define the alignment of the text relative to the tab stop. Presently, XmALIGNMENT_BEGINNING is the only valid value.
Tab stops may be measured in any of the following units:
Font units are calculated from the dimensions of the font used. Horizontal font units (used in horizontal tabs) are calculated as follows:
The XmTabGetValues function separates a tab stop into its constituent parts, as outlined above, and the XmTabSetValue function is used to change only the value field, or the actual measurement of an existing tab stop. XmTabSetValue has no effect on the units, the offset model, or the alignment of a tab stop.
Motif provides convenience functions to create tab lists in an application.
The XmTabListInsertTabs function adds one or more XmTabs to an already existing XmTabList. Use it with an empty input tab list to create a tab list.
The XmStringTableProposeTablist function takes an XmStringTable structure containing tabbed compound strings and, using its rendition information and input about the desired padding between columns, returns a proposed tab list. This tab list is defined so that, if used to render the strings in the table, it would cause the strings to line up in columns with no overlap and with the specified amount of padding between the widest item in each column and the start of the next column. Each tab in the tab list would have the same unit type, offset model, and alignment type, specified on input.
Tab stops and tab lists may also be specified in a resource file. To create a tab stop in a resource file, use the following syntax:
resource_spec: tab [, tab ]*
The resource value string consists of one or more tabs separated by commas. Each tab identifies the value of the tab, the unit type, and whether the offset is relative or absolute. The tab stop specification uses the following syntax:
tab = [ + ] float [ units ]
The tab contains a decimal number and an indication of the units to be used. If no units are specified, the default unit is pixels. The presence or absence of a sign indicates, respectively, a relative offset or an absolute offset model. A relative tab stop is measured from the previous tab stop in the list, while an absolute tab stop is measured from the left margin (or the right margin if the layout direction is right-to-left).
For example, the following line of a resource file sets a tab list for a rendition (rend1) in a render table (render_table) used by a widget called List. It specifies a tab list consisting of a 1-inch absolute tab followed by a 1-inch relative tab (equivalent to a 2-inch absolute tab, unless and until a third tab is inserted between the two):
*List.render_table.rend1.tabList: 1in, +1in
The recognized units and their abbreviations include:
See section 9.3.1 for more information about font units.
These are the functions provided to maintain and modify a tab list:
To remove tabs from a list, a program may use either XmTabListRemoveTabs, XmTabListCopy, or XmTabListReplacePositions. The first of these actually deletes the indicated XmTab entries from the list. The second and third functions create a new XmTabList using a subset of the original list. For XmTabListCopy, the subset must be in order in the original list, while XmTabListReplacePositions can pick an assortment of tab stops out of the old list to put in the new one.
The XmTabListGetTab function returns a copy of the tab stop at the indicated position in the list, and XmTabListTabCount simply returns the number of tab stops in a given tab list.
The functions that create tabs and tab lists allocate memory in which to put them. When an application is finished with the tabs, it should use XmTabFree and XmTabListFree to free that memory for other uses.