IS BTN

Introduction

The BuTtoN packet is sent to LFS to create or update an InSim button. You can display up to 240 buttons simultaneously on the host or guest clients via the ClickID with a value of 0 to 239. You should set the ISF_LOCAL flag (in IS_ISI#Flags) if your program is not a host control system, to make sure your buttons do not conflict with any buttons sent by the host. LFS can display normal buttons in these four screens:

• main entry screen
• race setup screen
• in game
• SHIFT+U mode

The recommended area for most buttons is defined by:

#define IS_X_MIN 0
#define IS_X_MAX 110

#define IS_Y_MIN 30
#define IS_Y_MAX 170

If you draw buttons in this area, the area will be kept clear to avoid overlapping LFS buttons with your InSim program's buttons. Buttons outside that area will not have a space kept clear. You can also make buttons visible in all screens with Inst.

To send a button to LFS, send this variable sized packet:

IS_BTN packet properties

Type	Name	Description
byte	Size	12 + TEXT_SIZE (a multiple of 4)
byte	Type	ISP_BTN
byte	ReqI	non-zero (returned in IS_BTC and IS_BTT packets)
byte	UCID	connection to display the button (0 = local / 255 = all)
byte	ClickID	button ID (0 to 239)
byte	Inst	some extra flags - see below
byte	BStyle	button style flags - see below
byte	TypeIn	max chars to type in - see below
byte	L	left : 0 - 200
byte	T	top : 0 - 200
byte	W	width : 0 - 200
byte	H	height : 0 - 200
char	Text[TEXT_SIZE]	0 to 240 characters of text

Packet Details

Size

The packet size, ranges from 12 to 252 bytes, with 4 byte steps in between.

Type

The packet type from the ISP_ enumeration, always ISP_BTN.

ReqI

Must not be zero, this value is returned to you in IS_BTC and IS_BTT packets.

UCID

Connection to display the button to, 0 for the local client, 255 to all clients.

ClickID

Button ID (0 to 239), this value is returned in IS_BTC and IS_BTT packets.

Inst

Mainly used internally by InSim but also provides some extra user flags

#define INST_ALWAYS_ON	128			// if this bit is set the button is visible in all screens

NOTE : You should not use INST_ALWAYS_ON for most buttons. This is a special flag for buttons that really must be on in all screens (including the garage and options screens). You will probably need to confine these buttons to the top or bottom edge of the screen, to avoid overwriting LFS buttons. Most buttons should be defined without this flag, and positioned in the recommended area so LFS can keep a space clear in the main screens.

BStyle

Defines the button's style and default text colour.

Bit Masks:

#define ISB_C1			1		// you can choose a standard
#define ISB_C2			2		// interface colour using
#define ISB_C4			4		// these 3 lowest bits - see below
#define ISB_CLICK		8		// click this button to send IS_BTC
#define ISB_LIGHT		16		// light button
#define ISB_DARK		32		// dark button
#define ISB_LEFT		64		// align text to left
#define ISB_RIGHT		128		// align text to right

Colors:

// colour 0 : light grey			(not user editable)	#C5C6C6
// colour 1 : title colour			(default:yellow)	#D9FF57
// colour 2 : unselected text			(default:black)		#000000
// colour 3 : selected text			(default:white)		#FFFFFF
// colour 4 : ok				(default:green)		#75B34D
// colour 5 : cancel				(default:red)		#D26220
// colour 6 : text string			(default:pale blue)	#30A6EB
// colour 7 : unavailable			(default:grey)		#72726F

TypeIn

If this is non-zero, the user can click this button to type in text.

The first 7 bits are used to set the maximum number of characters to type in (0 - 95).

The highest bit (128) can be set to initialise dialog with the button's text.

On clicking the button, a text entry dialog will be opened, allowing the specified number of characters to be typed in. The caption on the text entry dialog is optionally customisable using Text in the IS_BTN packet. If the first character of IS_BTN's Text field is zero, LFS will read the caption up to the second zero. The visible button text then follows that second zero.

For example, a Text value of ABC_ (bytes 65-66-67-0, underscore representing 0 in this example) displays "ABC" in the button with no caption for type in. A Text value of _ABC_DEFG___ also displays "ABC" in the button, but additionally shows the caption "DEFG".

L

Left or X Axis can be any value from 0 - 200, but the suggested range is 0 - 110.

T

Left or X Axis can be any value from 0 - 200, but the suggested range is 30 - 170.

W

Width of a button can be any value from 0 - 200, however a value above 110 is considered nonsensical as it might interfere with other LFS buttons.

H

Height of a button can be any value from 0 - 200, however a value above 140 is considered nonsensical as it might interfere with other LFS buttons. Values of 4-20 are the most common for small to large text. Also note that H defines the text's size, but a low W will cause the text to be squished horizontally.

Text

0 to 240 characters of text, padded with zeros to a multiple of 4. Text can be empty.

Notes

If width or height are zero, this would normally be an invalid button. But in that case if there is an existing button with the same ClickID, all the packet contents are ignored except the Text field. This can be useful for updating the text in a button without knowing its position. For example, you might reply to an IS_BTT using an IS_BTN with zero W and H to update the text.