Programming Guide

sm_sb_insert

Inserts a status bar section 

int sm_sb_insert(int sectno, int type, int length);

sectno
The index, in the array of sections, of the section to be added.

type
The type of the new section, one of the following constants: 
SBS_TEXT
SBS_SEPARATOR
SBS_SYSTEM_TIME
SBS_ELAPSED_TIME
SBS_OVERLAY
SBS_CAPS
SBS_NUM
SBS_SCROLL

length
The length of the section to be added.

Returns

Description

This function inserts a new section on the status bar. When the status bar is initially created it contains a single section of type SBS_MSGLINE. This initial section is the one written to by the various Panther functions that send messages to the status line. The initial SBS_MSGLINE section occupies the 0 position in the array of status bar sections. Newly added sections must be placed to the right of the initial section, hence the value of the first argument to sm_sb_insert cannot be 0. If you supply a negative value to the first parameter, the newly added section will be the rightmost, no matter how many sections already exist.

The newly added section must be one of several pre-defined types, as specified by the second argument to sm_sb_insert. You cannot add a second section of type SBS_MSGLINE. Hence, the valid values for the second argument are as follows:

SBS_TEXT
This type of section is used to display text. Text is written to such a section using the funtion sm_sb_settext.

SBS_SEPARATOR
This type of section is used to mark a boundary between two other sections. In character mode, it is equivalent to SBS_TEXT, and you can write whatever character you wish to it, to mark the section boundary. In a GUI SBS_SEPARATOR sections aren't displayed in a recessed style.

SBS_SYSTEM_TIME
This type of section displays the system time. The format for the time displayed is set by the function sm_sb_format. The default format shows the time in a 12-hour clock, with an AM/PM indicator.

SBS_ELAPSED_TIME
This type of section displays the time elapsed since the section was created. The format for the time displayed is set by the function sm_sb_format. The default format shows the time in the form '00:00:00'.

SBS_OVERLAY
This type of section displays the state of Panther's insert/overstrike mode. The length parameter is ignored if this is the type specified. In character mode the length defaults to 3, and will either display 'OVR' or be blank. In a GUI the 'OVR' indicator may be grayed out rather than blanked.

SBS_CAPS
This type of section displays the CAPS LOCK state of the keyboard. The length parameter is ignored if this is the type specified. This type is not supported in character mode.

SBS_NUM
This type of section displays the NUM LOCK state of the keyboard. The length parameter is ignored if this is the type specified. This type is not supported in character mode.

SBS_SCROLL
This type of section displays the SCROLL LOCK state of the keyboard. The length parameter is ignored if this is the type specified. This type is not supported in character mode.

Other than for SBS_TEXT and SBS_SEPARATOR, you can have only one section of each type on the status bar. Calls to sm_sb_insert that specify a type that already exists on the status bar will have no effect. You can insert any number of SBS_TEXT or SBS_SEPARATOR sections.

The length parameter is the length, in characters, of the section to be added. The length specified should be greater than or equal to the length of any text that might be placed in that section. This parameter is ignored for some section types, as noted above.

Note that the length of the status bar as a whole remains constant, and that the message line section initially occupies all of it. In Motif, the message line section is always 255 characters long, so any sections placed after it will appear displaced by 255 character positions. As a result, in Motif sections added to the status bar will probably not be visible unless the window containing the status bar is very wide. To compensate for this you can, in Motif, add a trailing SBS_SEPARATOR section that's wide enough to force the section to the right of the message line section to become visible.

Since in the GUIs the screen space allocated to status line sections is font-dependent, you may need to experiment with different lengths to get the status line sections to appear the way you want them.

See Also

sm_sb_delete, sm_sb_format, sm_sb_gettext, sm_sb_settext