AnimateButton
CentreGUI
GetGUIAt
GetGUIObjectAt
GetSliderValue
GetTextBoxText
InputBox
GUIOff
GUIOn
IsGUIOn
ListBoxAdd
ListBoxClear
ListBoxDirList
ListBoxGetItemText
ListBoxGetNumItems
ListBoxGetSelected
ListBoxRemove
ListBoxSaveGameList
ListBoxSetSelected
ListBoxSetTopItem
SetButtonPic
SetButtonText
SetGUIBackgroundPic
SetGUIClickable
SetGUIObjectEnabled
SetGUIObjectPosition
SetGUIObjectSize
SetGUIPosition
SetGUISize
SetGUITransparency
SetGUIZOrder
SetLabelColor
SetLabelFont
SetLabelText
SetSliderValue
SetTextBoxFont
SetTextBoxText
SetTextWindowGUI
AnimateButton(int gui, int object, int view, int loop, int delay, int repeat)Animates a GUI button by playing the specified view loop on it. This could be useful for Sierra-style death animations and other effects.
LOOP from VIEW will be played on button number OBJECT on GUI. The DELAY specifies the speed of the animation - larger numbers are slower. This has the same values you use with the AnimateCharacter and AnimateObject commands.
REPEAT determines whether the animation will loop repeatedly, or just play once and stop with the last frame showing.
You can abort an animation at any time by calling SetButtonPic on the button, or starting a new animation on the same button.
NOTE: This command destroys the button's normal, pushed and mouseover images. If you want to return the button to normal usage after playing an animation, you will have to call SetButtonPic to restore the images.
NOTE: This command does not support flipped view frames. Any frames marked as "Flipped" will in fact be drawn normally when on a button.
Example:
AnimateButton(CONTROLPANEL, 3, 6, 2, 4, 1);will animate button 3 on the CONTROLPANEL GUI, using loop 2 of view 6, with a delay of 4 cycles per frame, and repeat the animation continually.
See Also: SetButtonPic
CentreGUI (int gui)Centres the specified GUI in the middle of the screen. Useful if you've been moving it around with SetGUIPosition and just want to return it to the centre.
Example:
CentreGUI (2);will centre GUI 2 in the middle of the screen.
See Also: SetGUIPosition
GetGUIAt (int x, int y)Checks whether there is currently a GUI at screen co-ordinates (X,Y). If there is, returns its GUI number. If two GUIs overlap, the frontmost one will be returned - this can be changed with the SetGUIZOrder command.
If there is not currently a displayed, clickable GUI at the location, returns -1.
NOTE: This command will not find any GUIs that are set as Non-Clickable (ie. the "Clickable" checkbox not checked).
Example:
if (GetGUIAt(mouse.x,mouse.y) == SETTINGS)
GUIOff(STATUSLINE);
will check if the mouse is over the SETTINGS GUI. If it is it will turn the STATUSLINE GUI off.See Also: GetGUIObjectAt, SetGUIZOrder
GetGUIObjectAt (int x, int y)Checks whether there is a GUI object at screen co-ordinates (X,Y). Returns its object (button) number if there is, or -1 if there is not. You probably want to use this in conjunction with GetGUIAt.
Example:
if (GetGUIObjectAt(mouse.x,mouse.y)!=-1)will check if the cursor is over a GUI button.
See Also: GetGUIAt
GetSliderValue (int gui, int object)Returns the value of slider OBJECT on GUI to your program. You would usually use this command in the interface_click function to find out what value the player has changed the slider to, in order to process their command.
Example:
SetMusicMasterVolume(GetSliderValue(2,5));will set the master music volume to the value of the slider 5 of GUI number 2.
See Also: SetLabelText, SetSliderValue
GetTextBoxText (int gui, int object, string buffer)Retrieves the contents of textbox OBJECT on gui GUI into the BUFFER. This allows you to find out what the player typed in, and to respond appropriately.
Example:
string input;
GetTextBoxText (2,2,input);
Display ("%s",input);
will read what the user typed in textbox 2 of GUI 2 pass it in string input and display it on the screen.See Also: SetTextBoxText, StrCaseComp, StrComp
InputBox (string prompt, string buffer)This function allows your script to read a string typed in by the user. When this function is called it pops up a window asking the user to type in a string, with PROMPT as the text in the window. What they type in will be copied into BUFFER.
Note that this function only allows small strings (about 20 characters) due to the size of the input box it uses.
If you add a '!' character to the start of the prompt, then a Cancel button will be available in the input box. If the player presses this Cancel button (or the ESC key), a blank string is returned.
Example:
string name;
InputBox("!What is your name?", name);
will prompt the user for his name and store it in the string NAME. If the user presses Cancel,
the NAME string will be blank.See Also: StringToInt
GUIOff (int gui_number)Turns GUI number GUI_NUMBER off. It will no longer appear on the screen (or, if it is a pop-up GUI, it cannot be popped up).
Example:
GUIOff(2);will turn GUI 2 off .
NOTE: This function used to be called InterfaceOff but has now been renamed to avoid confusion.
See Also: GUIOn
GUIOn (int gui_number)Turns GUI number GUI_NUMBER on and displays it on the screen. This can be used to display a previously turned off GUI, or to bring up a special interface like an inventory window.
If the specified GUI is a script-only GUI (set to "On script command" in the editor), then the game will be paused while the interface is displayed, and you should use GUIOff as a reaction to a button click on the GUI to remove it.
Example:
GUIOn(2);will turn GUI 2 on.
NOTE: This function used to be called InterfaceOn but has now been renamed to avoid confusion.
See Also: GUIOff, IsGamePaused
IsGUIOn (int gui)Checks whether the specified GUI is currently displayed or not. Returns 1 if it is, 0 if not.
Example:
if (IsGUIOn(4)==0)
GUIOn(4);
will turn on interface 4 if it is off.
ListBoxAdd (int gui, int object, string newitem)Adds NEWITEM to the list box OBJECT on GUI. The item will be appended to the end of the list.
Example:
string input; GetTextBoxText(1,2,input); ListBoxAdd(2,3,input);will take the input from the user and add it to the listbox 3 of GUI 2.
See Also: ListBoxClear, ListBoxDirList, ListBoxRemove
ListBoxClear (int gui, int object)Removes all items from the specified list box.
Example:
ListBoxClear (2,3);will remove all the items from listbox 3 of GUI2
See Also: ListBoxAdd
ListBoxDirList (int gui, int object, string filemask)Fills the list box OBJECT on gui GUI with a list of filenames matching the FILEMASK in the current directory. This could be useful if you have various data files and the player can choose which one to load.
FILEMASK is a standard DOS/Windows search expression such as "*.dat" or "data*.*".
Example:
ListBoxDirList (2,3,"agssave.*");will fill the listbox 3 of GUI 2 with the list of the saved games.
See Also: ListBoxAdd, ListBoxClear, ListBoxSaveGameList
ListBoxGetItemText (int gui, int object, int item, string buffer)Fills BUFFER with the text from list item number ITEM in listbox OBJECT on gui GUI. This is useful for finding out the name of the option the user selected.
Example:
string buffer; ListBoxGetItemText (2,3,ListBoxGetSelected(2,3),buffer);will get the text of the selected item in listbox 3 of GUI 2.
See Also: ListBoxGetSelected
ListBoxGetNumItems (int gui, int object)Returns the number of items in the specified listbox. Valid item indexes range from 0 to (numItems - 1).
Example:
int saves; saves = ListBoxGetNumItems(2,3);will pass the number of saved games to int saves.
See Also: ListBoxGetItemText
ListBoxGetSelected (int gui, int object)Returns the index into the list of the currently selected item. The first item is 0, second is 1, and so on. If no item is selected, returns -1.
Example:
string buffer; ListBoxGetItemText (2,3,ListBoxGetSelected(2,3),buffer);will get the text of the selected item in listbox 3 of GUI 2.
ListBoxRemove (int gui, int object, int item)Removes ITEM from the specified list box. ITEM is the list index of the item to remove, starting with 0 for the top item.
If you want to remove all items from the list, then use ListBoxClear instead.
NOTE: Calling this function causes other items in the list to get re-numbered, so make sure you don't keep around any references from ListBoxGetSelected and related functions while using this command.
Example:
ListBoxAdd (LISTGUI, 3, "First item"); ListBoxAdd (LISTGUI, 3, "Second item"); ListBoxRemove (LISTGUI, 3, 0);the list box will now just contain "Second item".
See Also: ListBoxClear, ListBoxDirList
ListBoxSaveGameList (int gui, int object)Fills the specified listbox with the save game list, sorted correctly with the most recent game at the top of the list.
The global savegameindex array is updated with the actual slot numbers of the entries. So, you could do:
int index = ListBoxGetSelected (GUI_NUMBER, OBJECT_NUMBER); RestoreGameSlot (savegameindex[index]);NOTE: The save game list can only hold 20 save games. If ListBoxGetNumItems returns 20 and you are doing a Save dialog box, you may want to make the user replace an existing file rather than saving a new one.
Example:
ListBoxSaveGameList(2,3);will fill the listbox 3 of GUI 2 with the list of the saved games.
See Also: ListBoxDirList, ListBoxGetSelected, ListBoxGetNumItems
ListBoxSetSelected (int gui, int object, int selection)Changes the currently selected item in the list to SELECTION. Indexes start at 0 for the first item, 1 for the second, and so on. If you specify an item that does not exist (eg. -1), the highlight will be removed.
Example:
ListBoxSetSelected(2,3,0);will automatically select the first item of the lisbox 3 of GUI 2.
ListBoxSetTopItem (int gui, int object, int topitem)Repositions the list box so that TOPITEM is the first item visible. This allows you to manually scroll the list box to any position you like.
Indexes for TOPITEM start from 0 for the first item in the list.
Example:
ListBoxSetTopItem (2,3,0);will automatically scroll listbox 3 of GUI 2 back to the top of the list.
SetButtonPic (int gui, int object, int which, int newslot)Changes a GUI button's graphic to the one you specify. This could be used as an indicator of whether a feature is switched on or off by changing its picture. Sets object number OBJECT on gui GUI to NEWSLOT from the sprite manager.
The WHICH parameter selects which picture to change. It can have these values:
1 normal picture 2 mouse-over picture 3 button pushed pictureNote that you can pass NEWSLOT as -1 to disable the mouse-over and pushed pictures.
Example: if the GUI setup in the editor specifies a pushed-pic, but you want to change the main picture in the game (and so remove the old pushed picture), you can do something like this:
SetButtonPic (2, 3, 1, 100); SetButtonPic (2, 3, 3, -1);which will change button 3 on GUI 2 to have normal picture the one in slot 100 and not have a pushed graphic.
See Also: AnimateButton, SetGUIBackgroundPic, SetButtonText
SetButtonText (int gui, int object, string newtext)Changes the text displayed in the specified button to NEWTEXT. The affected button will be object OBJECT from GUI. You can find out a button's object number by looking at the Properties window of the button.
Example:
SetButtonText(2,3,"Enable jibble");will change button 3 on GUI 2 to read 'Enable jibble'.
See Also: SetButtonPic, SetLabelText
SetGUIBackgroundPic (GUI, int slot)Changes the background image of GUI to SLOT.
You can pass SLOT as 0 to remove the background image from the GUI.
See Also: SetGUIPosition, SetButtonPic
SetGUIClickable(GUI, int clickable)Sets whether the GUI is clickable or not. This allows you to modify the "Clickable" checkbox from the GUI Editor.
If CLICKABLE is 1, then the GUI will respond to mouse clicks as normal.
If CLICKABLE is 0, then this GUI cannot be clicked on by the mouse. This might be useful for a transparent overlay GUI which displays information, and you want the player to be able to click on whatever is underneath.
Example:
SetGUIClickable(STATUSLINE, 0);sets the STATUSLINE GUI to no longer respond to mouse clicks.
See Also: GetGUIAt
SetGUIObjectEnabled(GUI, int object, int enable)Enables or disables a GUI control.
Normally, all your GUI controls (such as buttons, sliders, etc) are enabled at all times except during a cutscene, when they are disabled. This command allows you to explicitly disable a control at your script's discretion.
If you pass ENABLE as 1, the control will be enabled; pass 0 to disable it.
Whether you set it as enabled or not, it will always be disabled during a blocking cutscene, along with all the other controls.
While a control is disabled, it will not respond to mouse clicks. If it is a button, its mouseover and pushed pictures will not be shown. The control will be drawn according to the game "When GUI Disabled" settings, as usual.
Example:
SetGUIObjectEnabled(STATUSLINE, 2, 0);will disable the STATUSLINE GUI's object 2.
See Also: SetGUIObjectPosition, SetGUIObjectSize
SetGUIObjectPosition (GUI, int object, int x, int y)Moves the top-left corner of the object OBJECT on GUI to be at (X,Y). These co-ordinates are relative to the GUI which contains the object.
This allows you to dynamically move GUI objects around on the screen while the game is running, and this may well be useful in conjunction with SetGUISize if you want to create dynamically resizable GUIs.
Example:
SetGUIObjectPosition(STATUSLINE, 1, 40, 10);will move the STATUSLINE GUI object 1 to (40,10) within the GUI.
See Also: SetGUIObjectEnabled, SetGUIPosition, SetGUIObjectSize
SetGUIObjectSize (int gui, int object, int width, int height)Adjusts OBJECT on GUI to have the new size WIDTH x HEIGHT.
This allows you to dynamically resize GUI objects on the screen while the game is running, and this may well be useful in conjunction with SetGUISize and SetGUIObjectPosition if you want to create dynamically resizable GUIs.
Example:
SetGUIObjectSize(INVWINDOW, 3, 100, 80);will resize the INVWINDOW GUI object 3 to 100 x 80 pixels.
See Also: SetGUIObjectPosition, SetGUISize
SetGUIPosition (int gui, int x, int y)Moves the top-left corner of GUI to the new location (X,Y) on the screen. This allows you to dynamically move GUIs around on the screen while the game is running. The co-ordinates are screen co-ordinates, not room co-ordinates, and use the same scale as in the editor.
Example:
SetGUIPosition(2,mouse.x,mouse.y);will move the GUI 2 to the position where the cursor is.
See Also: CentreGUI, SetGUIBackgroundPic, SetGUIObjectPosition, SetGUISize
SetGUISize (int gui, int width, int height)Changes the GUI to have the new size WIDTH x HEIGHT
This could be useful for initially hiding an 'Advanced' part of an options screen and such like.
The size is in the normal 320x200-resolution pixels. Setting the size to 320, 200 will cause the GUI to take up the entire screen.
Example:
SetGUISize (ICONBAR, 160, 100);changes the ICONBAR GUI to be the size of half the screen
See Also: CentreGUI, SetGUIObjectPosition, SetGUIPosition
SetGUITransparency (int gui, int amount)Sets GUI to be AMOUNT % transparent.
Setting AMOUNT to 100 means it is totally invisible, and lower values represent varying levels of transparency. Pass AMOUNT as 0 to stop the GUI being semi-transparent.
NOTE: Transparency currently only works in hi-color games.
NOTE: Having a large transparent GUI can significantly slow down the engine.
Example:
SetGUITransparency(2, 50);will make GUI 2 look semi transparent.
See Also: SetObjectTransparency
SetGUIZOrder(GUI, int z)Changes the z-order of the GUI. This allows you to dynamically change the ordering of GUIs on the screen.
The Z-order setting is an arbitrary number between 0 and 1000. AGS draws the GUIs in order, from the lowest numbered at the back to the highest numbered at the front.
Example:
SetGUIZOrder(STATUSLINE, 0);sets the STATUSLINE GUI to be behind all other GUIs.
See Also: GetGUIAt
SetLabelColor (int gui, int object, int color)Changes the text colour of label OBJECT on gui GUI to COLOR.
Example:
SetLabelColor(4,3,14);will change label 3 on GUI 4 to have yellow text.
See Also: SetLabelFont, SetLabelText
SetLabelFont (int gui, int object, int font)Changes the font used to display label OBJECT on gui GUI to FONT. This is useful if you have a standard SCI font for your English version, but want to change to a TTF font for foreign language versions.
Example:
if (IsTranslationAvailable()) {
SetLabelFont(4,3,2);
}
will change label 3 on GUI 4 to use font 2 if a game translation is in use.See Also: IsTranslationAvailable, SetLabelText, SetTextBoxFont
SetLabelText (int gui, int object, string newtext)Changes the text displayed in the specified label to NEWTEXT. The affected label will be object OBJECT from GUI. You can find out a label's object number by looking at the Properties window of the label.
This command allows you to change the text during the game, for example to create a Lucasarts-style status line.
Example:
string buffer; GetLocationName(mouse.x,mouse.y,buffer); SetLabelText(2,3,buffer);will display the name of the location the cursor is over on label 3 of GUI 2
See Also: SetButtonPic, SetButtonText, SetLabelColor, SetLabelFont
SetSliderValue (int gui, int object, int value)Changes the specified slider (object number OBJECT on GUI) to have the new value VALUE. VALUE must lie between the MIN and MAX settings for the slider, as set up in the GUI editor.
Example:
SetSliderValue(2,3,200);will change the value of the slider 3 of GUI 2 to 200.
See Also: GetSliderValue, SetLabelText
SetTextBoxFont (int gui, int object, int font)Changes the text box OBJECT on gui number GUI to use FONT as its new font. This might be useful if you need a player input text box to use a different font with foreign language translations, for example.
Example:
SetTextBoxFont(INPUTBOX, 3, 1);will change textbox 3 on GUI INPUTBOX to use Font 1.
See Also: SetLabelFont, SetTextBoxText
SetTextBoxText (int gui, int object, string newtext)Changes the text box OBJECT on gui number GUI to contain NEWTEXT. This might be useful to reset the text box to blank after the user has typed something in, or to fill in a default value.
Example:
SetTextBoxText(2,3,"");will clear the textbox 3 of GUI 2.
See Also: GetTextBoxText, SetLabelText, SetTextBoxFont
SetTextWindowGUI (int gui)Changes the GUI used for text windows to the specified GUI. This overrides the "text windows use GUI" setting in the editor.
You can pass -1 as the GUI number to go back to using the default white text box.
Example:
SetTextWindowGUI (4);will change Textwindow GUI 4 to be used for displaying text windows in future.