IS BTN

Introduction

The InSim BuTtoN packet. This packet is sent to LFS to make or update a InSim button. It contains various options and flags. You can make up to 240 buttons appear on the host or guests client 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
• game 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.

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

struct IS_BTN // BuTtoN - button header - followed by 0 to 240 characters
{
	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 Detail

Size

The packet size, ranges from 16 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 too, 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

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.

Max chars to type in (0 - 95), the highest bit (128) can be set to initialize 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. A Text value of " AB " would display button text "AB" and no caption, whereas a Text value of " ABC DEFG " would display button text "DEFG" and caption "ABC", where the spaces would be the value of null.

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.

Text

0 to 240 characters of text, it's length must be padded to a modulus of 4.

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.