forked from ericoporto/ImGi
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.BBCode
255 lines (182 loc) · 13.7 KB
/
README.BBCode
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
[size=14pt][b]ImGi[/b][/size] [color=gray][b] version 0.4.2 [/b][/color]
[url=https://ci.appveyor.com/project/ericoporto/imgi][img]https://ci.appveyor.com/api/projects/status/tq90vg1if9bvdyie?svg=true[/img][/url]
[url=https://github.com/ericoporto/ImGi/releases/download/0.4.2/imgi.scm]Get Latest Release [b]imgi.scm[/b][/url] | [url=https://github.com/ericoporto/ImGi]GitHub Repo[/url] | [url=https://github.com/ericoporto/ImGi/releases/download/0.4.2/imgi_demo_windows.zip]Demo Windows[/url] | [url=https://github.com/ericoporto/ImGi/releases/download/0.4.2/imgi_demo_linux.tar.gz]Demo Linux[/url] | [url=https://github.com/ericoporto/ImGi/archive/0.4.2.zip] Download project .zip [/url]
AGS Script Module for Immediate Gui, uses script Overlays to render the interface.
[color=red][glow=white,2,300][b]This is beta quality[/b][/glow][/color], I predict Overlays will enter into fashion in one of the next seasons so this module is being written for when the time comes. 8-)
[img]https://raw.githubusercontent.com/ericoporto/ImGi/main/docs/images/screenshot.gif[/img]
[size=14pt][b]Usage[/b][/size]
[spoiler]
[code=ags]function repeatedly_execute() // In Room Script, use room_RepExec()
{
ImGi.Begin();
if(ImGi.BeginWindow("Hello World", 32, 32, 130, 60, eImGi_Opt_AlignCenter | eImGi_Opt_NoClose))
{
// makes following rows to have two columns of width 60 and 70, and let height be default
ImGi.LayoutRow2(60, 70);
ImGi.Label("A Label:");
if(ImGi.Button("A Button!"))
{
player.Say("You clicked the button!");
}
ImGi.EndWindow();
}
ImGi.End();
}[/code][/spoiler]
[size=14pt][b]Script API[/b][/size]
[spoiler]
ImGi entire API uses static functions and attributes
[size=12pt][b]Basic[/b][/size]
[b][tt]ImGi.Begin[/tt][/b]
[code=ags]void ImGi.Begin()[/code]
Call only once per frame and make sure to call End() after.
[b][tt]ImGi.End[/tt][/b]
[code=ags]void ImGi.End()[/code]
Call only once per frame, after Begin() is called.
[hr]
[size=12pt][b]Layout System[/b][/size]
ImGi uses a row based layout system. Each row can have a number of columns (up to 16 columns), each with it's own width, and also a height.
Controls then will be placed in this cell. If you don't change how rows are, it's assumed to keep same LayoutRow.
If you don't specify a height, it will use your style size and padding. Places elements relative to the bottom. Controls may make height bigger than what you set.
If your column width is 0, it will your style size and padding. A negative width will try to place that element at that distance relative from the rights.
Some special Controls can force the width of it's specific column, ignoring the positive values you set, this can be useful if you don't know before hand their sizes.
[b][tt]ImGi.LayoutRow1[/tt][/b]
[b][tt]ImGi.LayoutRow2[/tt][/b]
[b][tt]ImGi.LayoutRow3[/tt][/b]
[b][tt]ImGi.LayoutRow4[/tt][/b]
[code=ags]void ImGi.LayoutRow1(int width, int height = 0)
void ImGi.LayoutRow2(int w1, int w2, int height = 0)
void ImGi.LayoutRow3(int w1, int w2, int w3, int height = 0)
void ImGi.LayoutRow4(int w1, int w2, int w3, int w4, int height = 0)[/code]
Functions to configure the next LayoutRow to use, from a single column (LayoutRow1) up to four columns (LayoutRow4). Use these if you know you want either of these number of columns.
You can optionally specify a height.
[b][tt]ImGi.LayoutRow[/tt][/b]
[code=ags]void ImGi.LayoutRow(int count, int widths[], int height = 0)[/code]
Pass an array of widths with count elements to configure the columns in a row. You can optionally specify a height.
This is useful if you are reading an array of things or have 5 or more columns in your layout. The maximum number of widths is 16.
[code=ags]int row[];
row = new int[2];
row[0] = 60; // set a predefined column width size per element in row
row[1] = 70; // this is the width of other column
ImGi.LayoutRow(2 /*n columns*/, row); // rows after this line have such column config[/code]
[b][tt]ImGi.LayoutBeginColumn[/tt][/b]
[b][tt]ImGi.LayoutEndColumn[/tt][/b]
[code=ags]void ImGi.LayoutBeginColumn()
void ImGi.LayoutEndColumn()[/code]
Allows subdividing a cell in a row in more rows and columns. You start the column with ImGi.LayoutBeginColumn(), and it's void, so ALWAYS call LayoutEndColumn() after (you don't check it's return value because it's void!).
[hr]
[size=12pt][b]Window[/b][/size]
A window can be created by a [tt]BeginWindow[/tt] and if this is successful (returns any non false value), it has to call [tt]EndWindow[/tt] to specify where it logically ends.
All controls must exist within a window. An example of normal usage is below:
[code=ags]if(ImGi.BeginWindow("My First Window!", 32, 32, 130, 60))
{
ImGi.Text("Hi!"); // your controls are here ...
ImGi.EndWindow();
}[/code]
[b][tt]ImGi.BeginWindow[/tt][/b]
[code=ags]ImGi_Res ImGi.BeginWindow(String title, int x, int y, int width, int height, ImGi_Opt opt = 0)[/code]
Creates a window, make sure to call a matching EndWindow() if this method return is not false.
[b][tt]ImGi.EndWindow[/tt][/b]
[code=ags]void ImGi.EndWindow()[/code]
Has to be called each time a BeginWindow is successful once all elements inside the window are listed
[b][tt]ImGi.OpenWindow[/tt][/b]
[code=ags]void ImGi.OpenWindow(String title)[/code]
If a window of matching title is closed, it opens again.
[b][tt]ImGi.Close[/tt][/b]
[code=ags]void ImGi.Close()[/code]
Closes what is the current scope (Window, Popup, ...). Don't call it outside of a Window, a Popup, ...
[b][tt]ImGi.BeginPopup[/tt][/b]
[b][tt]ImGi.EndPopup[/tt][/b]
[b][tt]ImGi.OpenPopup[/tt][/b]
[code=ags]ImGi_Res ImGi.BeginPopup(String title)
void ImGi.EndPopup()
void OpenPopup(String name)[/code]
Popups are like windows, but you can't move or resize them, and they have no headers. They open where the mouse is when calling OpenPopup by default.
Popups open on top of everything, and they close if you click outside of them. Clicks outside of the popup that hit no window will be forwarded to the rest of your game to handle.
[b][tt]ImGi.BeginPanel[/tt][/b]
[b][tt]ImGi.EndPanel[/tt][/b]
[code=ags]ImGi_Res ImGi.BeginPanel(String name, ImGi_Opt opt = 0)
void ImGi.EndPanel()[/code]
If you need a scrollable area inside a window that is not the window itself, you can use panels! A panel has to be inside of a window, it will use the LayoutRow cell size for it's size. If it returns successful, you have to call EndPanel() after.
[code=ags]if(ImGi.BeginPanel("Pan")){
ImGi.Text("Hi panel!"); // your controls are here ...
ImGi.EndPanel();
}[/code]
[hr]
[size=12pt][b]Controls[/b][/size]
Controls are things you can place inside a window. Controls cannot exist outside of windows.
Every controls takes a string as label, this string can't be empty and can't match the label of other control. The exception is if the control can take an icon or graphic, then if you pass null as the string and the control has an icon, it will use the icon if possible. Each window or similar will be a new scope, used to compose this identification, so two different windows can have controls with matching labels.
ImGi comes with a limited number of icons, whenever you can provide an icon as a parameter, you can alternatively pass a sprite number, and in this case it will use that sprite instead of the icon. The default icons use negative numbers, so they don't conflict with your sprite ID.
[b][tt]ImGi.Empty[/tt][/b]
[code=ags]void ImGi.Empty()[/code]
This control does nothing and is invisible. Use it when you don't want to place anything in cell to advance the layout.
[b][tt]ImGi.Label[/tt][/b]
[code=ags]void ImGi.Label(String label)[/code]
[img]https://raw.githubusercontent.com/ericoporto/ImGi/main/docs/images/ctrl_label.gif[/img]
This control is a Label containing the specified text. It has no interaction.
[b][tt]ImGi.Text[/tt][/b]
[code=ags]void ImGi.Text(String text)[/code]
[img]https://raw.githubusercontent.com/ericoporto/ImGi/main/docs/images/ctrl_text.gif[/img]
This control is a Multiline Label for visualization only. It has no interaction.
[b][tt]ImGi.TextBox[/tt][/b]
[code=ags]String ImGi.TextBox(String label, String buf, int bufsz, ImGi_Result* res = 0, ImGi_Opt opt = 0)[/code]
This control is an editable TextBox. Click on it to give focus and enter the text input with the keyboard. Enter exits focus.
The character limit is defined in [color=grey][b][tt]bufsz[/tt][/b][/color]. This function will return the [color=grey][b][tt]buf[/tt][/b][/color] String modified, just assign it to the same String so it's content can be updated.
[b][tt]ImGi.Button[/tt][/b]
[code=ags]ImGi_Res ImGi.Button(String label, ImGi_Icon icon = 0, ImGi_Opt opt = eImGi_Opt_AlignCenter)[/code]
[img]https://raw.githubusercontent.com/ericoporto/ImGi/main/docs/images/ctrl_button.gif[/img]
This control is a Button. When clicked, it will return a value different than false.
[b][tt]ImGi.ButtonImage[/tt][/b]
[code=ags]ImGi_Res ImGi.ButtonImage(String label, int graphic_normal, int graphic_over, int graphic_pressed, ImGi_Opt opt = 0)[/code]
Pass a sprite for the Button normal state, one for when mouse is over, and a graphic for when it's clicked. You can set label null if it's the only button in the window with same graphics.
[b][tt]ImGi.CheckBox[/tt][/b]
[code=ags]ImGi_Res ImGi.CheckBox(String label, CheckBoxState* chkst, ImGi_Icon icon = eImGi_Icon_Check)[/code]
[img]https://raw.githubusercontent.com/ericoporto/ImGi/main/docs/images/ctrl_checkbox.gif[/img]
This control is a CheckBox. It doesn't store state, so make sure to pass it's state. You optionally pass a different icon to it.
[b][tt]ImGi.Number[/tt][/b]
[b][tt]ImGi.NumberI[/tt][/b]
[code=ags]ImGi_Res ImGi.Number(String label, ImGi_Real* value, float step = 0, String format = 0, ImGi_Opt opt = 0)
ImGi_Res ImGi.NumberI(String label, ImGi_Int* value, int step = 0, String format = 0, ImGi_Opt opt = 0)[/code]
[img]https://raw.githubusercontent.com/ericoporto/ImGi/main/docs/images/ctrl_number.gif[/img]
This control shows a Number, set step to allow quick mouse drag adjustments. Holding shift and clicking it allows entering input with the keyboard.
You can pass a format string similar to the one used with String.Format to specify how the number should be rendered. It's a float, so make sure to use either [tt]"%f"[/tt] or [tt]"%g"[/tt].
NumberI is the same control but for integer ([tt]int[/tt]) numbers, it's not the same control just wrapped, so it's format string default is [tt]"%d"[/tt].
[b][tt]ImGi.Slider[/tt][/b]
[b][tt]ImGi.SliderI[/tt][/b]
[code=ags]ImGi_Res ImGi.Slider(String label, ImGi_Real* value, float low, float high, float step = 0, String format = 0, ImGi_Opt opt = 0)
ImGi_Res ImGi.SliderI(String label, ImGi_Int* value, int low, int high, int step = 0, String format = 0, ImGi_Opt opt = 0)[/code]
[img]https://raw.githubusercontent.com/ericoporto/ImGi/main/docs/images/ctrl_slider.gif[/img]
This control is a Slider. You can adjust it manually with the mouse or you can hold shift and click to specify a value with the keyboard.
You can pass a format string similar to the one used with String.Format to specify how the number should be rendered. It's a float, so make sure to use either [tt]"%f"[/tt] or [tt]"%g"[/tt].
SliderI is the same control but for integer ([tt]int[/tt]) numbers, it's not the same control just wrapped, so it's format string default is [tt]"%d"[/tt].
[hr]
[size=12pt][b]Options[/b][/size]
Some controls and other elements can take options. Below is the list of available options. If you wish to pass two or more options, you can combine them with the bitfield or operator |
[code=ags]ImGi.Button("centered text and non-interactive",0, eImGi_Opt_AlignCenter | eImGi_Opt_NoInteract)[/code]
[table]
[tr][td][tt]eImGi_Opt_AlignCenter[/tt][/td][td]The header of a window or the control will have text aligned to center.[/td][/tr]
[tr][td][tt]eImGi_Opt_AlignRight[/tt][/td][td]The header of a window or the control will have text aligned to right.[/td][/tr]
[tr][td][tt]eImGi_Opt_NoInteract[/tt][/td][td]Disables interaction with the control.[/td][/tr]
[tr][td][tt]eImGi_Opt_NoFrame[/tt][/td][td]If the control or window has any frame, it's not drawn.[/td][/tr]
[tr][td][tt]eImGi_Opt_NoResize[/tt][/td][td]You can't resize the window by click-dragging it's bottom right corner.[/td][/tr]
[tr][td][tt]eImGi_Opt_NoScroll[/tt][/td][td]Window has no scrollbars.[/td][/tr]
[tr][td][tt]eImGi_Opt_NoClose[/tt][/td][td]Window has no close button.[/td][/tr]
[tr][td][tt]eImGi_Opt_NoTitle[/tt][/td][td]Window has to title bar.[/td][/tr]
[tr][td][tt]eImGi_Opt_HoldFocus[/tt][/td][td]Controls with this option will require clicking on a different control to remove focus. Default of some controls.[/td][/tr]
[tr][td][tt]eImGi_Opt_AutoSize[/tt][/td][td]Makes the window resize to fit content.[/td][/tr]
[tr][td][tt]eImGi_Opt_PopUp[/tt][/td][td]Closes the container when clicking out of it. This is used by default in Popus.[/td][/tr]
[tr][td][tt]eImGi_Opt_Closed[/tt][/td][td]Makes the container start closed by default.[/td][/tr]
[tr][td][tt]eImGi_Opt_Expanded[/tt][/td][td]These are for tree elements, which are not implemented yet.[/td][/tr]
[/table]
[hr]
[size=12pt][b]Utilities[/b][/size]
[b][tt]ImGi.SetFocusLastControl[/tt][/b]
[code=ags]void ImGi.SetFocusLastControl()[/code]
Places the focus on what is the last control. Some controls behave differently when focused - like Number and TextBox. Focus is only reggarding input, but won't scroll or move things at center.
[hr]
[size=12pt][b]Style and Design customization[/b][/size]
[b][tt]ImGi.Style[/tt][/b]
[code=ags]ImGi_Style* ImGi.Style[/code]
Holds the Current Style for ImGi.
[hr][/spoiler]
[size=14pt][b]License[/b][/size]
This code is licensed with MIT [url=https://github.com/ericoporto/ImGi/blob/main/LICENSE][tt]LICENSE[/tt][/url]. The code on this module is based on rxi's Microui, which is also MIT licensed, referenced in the license, this port though has many changes - lots of new bugs too.