Difference between revisions of "IS BTN"
m (→Introduction) |
m |
||
| (One intermediate revision by the same user not shown) | |||
| Line 123: | Line 123: | ||
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. | 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. | ||
| + | |||
| + | [[Category:InSim packets]] | ||
Latest revision as of 00:55, 2 December 2023
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.
