BRL.MaxGUI: Functions Modinfo Source  

MaxGUI

The MaxGUI module contains commands to create and control user interfaces for developing applications in BlitzMax.
Users should be familiar with the WaitEvent command and BlitzMax events which provide the basic communication mechanism between user interface and program when developing MaxGUI applications.

Gadgets

MaxGUI provides numerous types of gadgets that can be created and arranged for the purposes of providing a user interface to BlitzMax applications.

The position of gadgets in relation to their group (parent) gadget can be controlled with the SetGadgetShape command and monitored with the GadgetX, GadgetY, GadgetWidth and GadgetHeight commands. Gadgets that can act as group gadgets such as Windows, Tabbers and Panels have an inner region that contains their children with an area that can be found with the ClientWidth and ClientHeight functions.

Gadget's can be made to automatically reposition themselves when their group gadget changes size with the SetGadgetLayout command.

A gadget's group (parent) gadget can be found with the GadgetGroup command. A gadget can be shown with ShowGadget, hidden with HideGadget, it's visibility found with the GadgetHidden function and removed completely from the system with the FreeGadget command.

EnableGadget, DisableGadget and GadgetDisabled control and return if a gadget is currently enabled. ActivateGadget will set a particular gadget as active so that it is highlighted and receives any keyboard events while ActiveGadget returns which gadget if any is currently active.

SetGadgetText, SetGadgetFont, SetGadgetColor and SetGadgetTextColor control the appearance of many of the BlitzMAX gadgets' appearance.

Windows


A Window is used to contain a collection of gadgets that make up the user interface of an application. The CreateWindow command creates a Window of a specified size that can then be used as the Group parameter for the other gadget creation commands.

The WindowMenu command returns a handle that can be used as the parent parameter of the CreateMenu command to add menus to a Window. UpdateWindowMenu should be called after adding menus to a Window for the changes to take effect.

A window can be activated (made the currently selected window on the Desktop) with the ActivateWindow command. The text displayed in a Window's optional Statusbar can be modified by the SetStatusText command.

If a Window is resizable (created with the WINDOW_RESIZABLE style) it's minimum size can be restrained with the SetMinWindowSize and it can be minimized, maximized and restored with the MinimizeWindow, MaximizeWindow and RestoreWindow commands. The minimized and maximized state of a Window can be detected with the WindowMinimized and WindowMaximized commands.

Menus


The CreateMenu command is used to create menu items. Menus can be attached to a Window's menu bar by parenting them to a WindowMenu or can popup at the current mouse location by using the PopupWindowMenu command.

FreeMenu removes a menu from it's parent, SetMenuText modifies a Menu's text label, CheckMenu adds a check to a Menu item and UncheckMenu removes a check from a menu item. EnableMenu allows a Menu item to be selected while DisableMenu will "gray out" a Menu item. MenuText returns a Menu's current text label, while MenuChecked and MenuEnabled return the state of the specified Menu.

Buttons


The CreateButton command is used to add buttons to an applicaion's user interface. Buttons can be normal push buttons that emit an event when pushed or can be created with the BUTTON_CHECKBOX or BUTTON_RADIO styles in which case they can be selected or deselected by the user or programatically with the SetButtonState command. Their current state can be found with the help of the ButtonState command.

Panels


The CreatePanel command is used to to create a Panel gadget. Panels can be used to group other gadget's together and can optionally have a background color or image using the SetPanelColor or SetPanelPixmap commands. Buttons can feature a border and may generate mouse events with the optional PANEL_BORDER and PANEL_ACTIVE styles.

TextFields


A TextField allows the users to enter a single line of text. The CreateTextField command creates a TextField at the specified location, an optional TEXTFIELD_PASSWORD style can be used to create a password style entry field (input is hidden with asterisk chracters). The TextFieldText command can be used to retrieve the current contents of the TextField gadget.

TextAreas


TextAreas can disply and optionally allow editting of multiple lines of text. The CreateTextArea command creates a TextArea with optional TEXTAREA_WORDWRAP and TEXTAREA_READONLY styles, SetTextAreaText inserts or overwrites text in a TextArea while AddTextAreaText appends text to the end of a TextArea gadget.

TextAreaText returns either a portion or the entire contents of a a TextArea while TextAreaLen returns either the number of characters or lines currently contained in a TextArea.

The cursor position and characters or lines currently selected can be found with the TextAreaCursor and TextAreaSelLen commands and controlled with the SelectTextAreaText command.

SetTextAreaTabs controls the tab size of a TextArea gadget while SetTextAreaFont and SetTextAreaColor affect the font and color of the text displayed in a TextArea. LockTextArea and UnlockTextArea lock and unlock a TextArea gadget for improved performance when formatting a TextArea's contents with the FormatTextArea command.

TextAreaChar finds the character position of a given line in a TextArea gadget while the line of a given character position in a TextArea gadget can be found with the TextAreaLine command.

ComboBoxes


ComboBoxes provide a dropdown list of options to the user with an optional style that allows the user to enter their own text in a similar manner to the TextField gadget. CreateComboBox creates a ComboBox and the standard list based gadget commands ClearGadgetItems, AddGadgetItem, ModifyGadgetItem, RemoveGadgetItem, SelectGadgetItem, SelectedGadgetItem, CountGadgetItems and GadgetItemText can be used to manage the items contained by the ComboBox gadget.

ListBoxes


ListBoxes are similiar to ComboBoxes but features a scrolling list rather than a drop down selection mechanism, The CreateListBox command is used to create a ListBox gadget while the standard list based gadget commands listed in the previous ComboBox section are used to manage the contents of the ListBox gadget.

ToolBars


ToolBars feature a list of icons and optional Tips that popup when the user holds the mouse over an icon. The CreateToolBar command creates a toolbar from a specified image file containing a strip of icons.

EnableToolBarItem and DisableToolBarItem control the behavior of individual items while SetToolBarTips assigns a list of meaningful strings to the toolbar items.

Tabbers


The CreateTabber command creates a Tab control gadget commonly used to group gadgets into a collection of pages. The standard list based gadget commands ClearGadgetItems, AddGadgetItem, ModifyGadgetItem, RemoveGadgetItem, SelectGadgetItem, SelectedGadgetItem, CountGadgetItems and GadgetItemText can be used to manage the items contained in a Tabber gadget.

TreeViews


A TreeView is used to display hierarchical data where items are contained in nodes that can be children of other nodes. The CreateTreeView command creates a new TreeView gadget that provides a TreeViewRoot used to create a tree of nodes.

AddTreeViewNode, InsertTreeViewNode, ModifyTreeViewNode, ExpandTreeViewNode, CollapseTreeViewNode and FreeTreeViewNode provide commands to control the the contents of a TreeView.

SelectedTreeViewNode and SelectTreeViewNode return and set respectively the currently highlighted node in a TreeView while CountTreeViewNodes returns the number of nodes contained in a single TreeViewNode.

HtmlViews


An HTMLView is a gadget containing a complete web browser display. The CreateHTMLView command creates an HTMLView gadget while HtmlViewGo, HtmlViewBack and ViewForward control the page being displayed.

HtmlViewStatus, HtmlViewCurrentURL and HtmlViewEventURL provide extended information about the state of an HTMLView gadget while HtmlViewRun allows scripts to be run (on some platforms).

Labels

Labels are read-only regions of text on a user inteface that do not have a background and are created with the CreateLabel command.

Sliders


Sliders allow the user to control a numerical value by dragging a control inside a container. CreateSlider can create both a ScrollBar type slider where the size of the knob represents the portion of the document being viewed and TrackBar style sliders (SLIDER_TRACKBAR style) where the knob is a fixed size and SetSliderRange controls the minimum and maximum values allowed by the control.

SetSliderValue and SliderValue set and get the position of the knob in a Slider control.

ProgressBars


CreateProgBar creates a progress bar gadget commonly used to display the progress state of an operation. The UpdateProgBar command is used to update the progress bar with a value between 0.0 and 1.0 representing how complete the current processing operation is.

Desktop

A gadget representing the user's desktop is returned by the Desktop command.

Functions

Function ActivateGadget( gadget:TGadget )
DescriptionRequest keyboard focus for gadget.

Function ActivateWindow( window:TGadget )
DescriptionActivate a window gadget.

Function ActiveGadget:TGadget()
ReturnsThe gadget if any that currently has the keyboard focus.
DescriptionReturn the currently active Gadget.

Function AddGadgetItem(gadget:TGadget,text$,flags=0,icon=-1,tip$="",extra:Object=Null)
DescriptionAdd an item to a list based gadget.
InformationAn item can be added the ComboBox, ListBox, Tabber and ToolBar list based gadgets.

It's text parameter is used as it's label.
The flags parameter can be a combination of the following values:

ConstantMeaning
GADGETITEM_NORMALA plain gadget item.
GADGETITEM_DEFAULTThe item defaults to a selected state.
GADGETITEM_TOGGLESThe item alternates between selected states when pressed.
The tip$ parameter attaches an optional tooltip to the item.
The optional icon parameter specifies an icon from the gadget's IconStrip (see SetGadgetIconStrip).
The extra parameter is supplied in the EventExtra field of any Event generated by the Item.

SeeAlso: InsertGadgetItem, CreateComboBox, CreateListBox, CreateTabber and CreateToolBar.


Function AddTextAreaText( textarea:TGadget,text$ )
DescriptionAppend text to the contents of a TextArea gadget.

Function AddTreeViewNode:TGadget( text$,node:TGadget,icon=-1 )
DescriptionAdd a node to a TreeView gadget.

Function ButtonState( button:TGadget )
DescriptionDetect a Button gadget's state.

Function CanvasGraphics:TGraphics(gadget:TGadget)
DescriptionRetrieve a Canvas gadget's Graphics context.
InformationThe RedrawGadget example shows an alternative method for drawing to Canvas gadgets utilizing the EVENT_GADGETPAINT event.

See Also: CreateCanvas.


Function CheckMenu( menu:TGadget )
DescriptionSet a menu's checked state.

Function ClearGadgetItems(gadget:TGadget)
DescriptionRemove all items added to a list based gadget.

Function ClientHeight( gadget:TGadget )
ReturnsHeight of the client area of the specified group gadget.
DescriptionClient height of gadget.

Function ClientWidth( gadget:TGadget )
ReturnsWidth of the client area of the specified group gadget.
DescriptionClient width of gadget.

Function CollapseTreeViewNode( node:TGadget )
DescriptionCollapse a Node in a TreeView gadget.

Function CountGadgetItems( gadget:TGadget )
DescriptionGet the number of items in a list based gadget.

Function CountTreeViewNodes( node:TGadget )
DescriptionGet the number of children of a Node gadget.

Function CreateButton:TGadget(label$,x,y,w,h,group:TGadget,style=BUTTON_PUSH)
DescriptionCreate a Button gadget.
InformationA Button generates an EVENT_GADGETACTION Event whenever it is pushed.

A button can be created with ONE of the following styles:
ConstantMeaning
BUTTON_PUSHStandard push button
BUTTON_CHECKBOXA check box button that displays a tick when it's state is TRUE.
BUTTON_RADIOA radio button is accompanied by a small circular indicator, filled when it's state is TRUE.
BUTTON_OKStandard push button that is also activated when the user presses the RETURN key
BUTTON_CANCELStandard push button that is also activated when the user presses the ESCAPE key

See Also: SetGadgetText, SetButtonState and ButtonState.

Example
' createbutton.bmx

Strict 

Local window:TGadget
Local button:TGadget[5]

window=CreateWindow("MaxGui Buttons",40,40,240,300,Null,WINDOW_TITLEBAR)
button[0]=CreateButton("Push Button",10,10,140,24,window,BUTTON_PUSH)
button[1]=CreateButton("Checkbox Button",10,34,140,24,window,BUTTON_CHECKBOX)
button[2]=CreateButton("Radio Button",10,58,140,24,window,BUTTON_RADIO)
button[3]=CreateButton("OK",10,82,70,24,window,BUTTON_OK)
button[4]=CreateButton("Cancel",84,82,70,24,window,BUTTON_CANCEL)

While True
	WaitEvent 
	Select EventID()
		Case EVENT_WINDOWCLOSE
			End
		Case EVENT_GADGETACTION
			Print "EVENT_GADGETACTION"
	End Select
Wend

Function CreateCanvas:TGadget(x,y,w,h,group:TGadget,style=0)
DescriptionCreate a Canvas gadget.
InformationA Canvas provides a Graphics interface for realtime drawing purposes.

Once a Canvas is created, the CanvasGraphics() Function can be used with the SetGraphics command to direct Max2D drawing commands to be drawn directly on the Canvas.

An EVENT_GADGETPAINT event is generated whenever the gadget must be redrawn by either the system (for instance when it is first shown) or due to the RedrawGadget command.

An EVENT_GADGETPAINT handler should always call SetGraphics with the canvas's Max2D graphics context to ensure the viewport and similar properties are in their correct state.

When a Canvas is active using either the ActivateGadget command or clicking on the Canvas when the application is running, the following event's will also be sent from the Canvas:
EVENT_MOUSEDOWNMouse button pressed. Event data contains mouse button code
EVENT_MOUSEUPMouse button released. Event data contains mouse button code
EVENT_MOUSEMOVEMouse moved. Event x and y contain mouse coordinates
EVENT_MOUSEWHEELMouse wheel spun. Event data contains delta clicks
EVENT_MOUSEENTERMouse entered gadget area
EVENT_MOUSELEAVEMouse left gadget area
EVENT_KEYDOWNKey pressed. Event data contains keycode
EVENT_KEYUPKey released. Event data contains keycode
EVENT_KEYCHARKey character. Event data contains unicode value

See Also: ActivateGadget, RedrawGadget, CanvasGraphics.

Example
' createcanvas.bmx

Strict 

Global GAME_WIDTH=320
Global GAME_HEIGHT=240

' create a centered window with client size GAME_WIDTH,GAME_HEIGHT

Local wx=(ClientWidth(Desktop())-GAME_WIDTH)/2
Local wy=(ClientHeight(Desktop())-GAME_HEIGHT)/2

Local window:TGadget=CreateWindow("My Canvas",wx,wy,GAME_WIDTH,GAME_HEIGHT,Null,WINDOW_TITLEBAR|WINDOW_CLIENTCOORDS)

' create a canvas for our game

Local canvas:TGadget=CreateCanvas(0,0,320,240,window)

' create an update timer

CreateTimer 60

While WaitEvent()
	Select EventID()
		Case EVENT_TIMERTICK
			RedrawGadget canvas

		Case EVENT_GADGETPAINT
			SetGraphics CanvasGraphics(canvas)
			SetOrigin 160,120
			SetLineWidth 5
			Cls
			Local t=MilliSecs()
			DrawLine 0,0,120*Cos(t),120*Sin(t)
			DrawLine 0,0,80*Cos(t/60),80*Sin(t/60)
			Flip

		Case EVENT_MOUSEMOVE
			Print "MOVE!"

		Case EVENT_WINDOWCLOSE
			FreeGadget canvas
			End

		Case EVENT_APPTERMINATE
			End
	End Select
Wend

Function CreateComboBox:TGadget(x,y,w,h,group:TGadget,style=0)
DescriptionCreate a ComboBox gadget.
InformationA ComboBox gadget provides a dropdown list of items to the user.
An EVENT_GADGETACTION is generated when the user selects an item.

The optional COMBOBOX_EDITABLE style allows the ComboBox to also behave similary to a TextField gadget with the user able to enter a line of text with the keyboard in addition to selecting from the items contained in the list.

See Also: AddGadgetItem, ClearGadgetItems, ModifyGadgetItem, SelectGadgetItem, RemoveGadgetItem and SelectedGadgetItem.

Example
' createcombobox.bmx

Strict 

Local window:TGadget
Local combobox:TGadget

window=CreateWindow("My Window",30,20,200,200)

combobox=CreateComboBox(4,4,120,22,window)
AddGadgetItem combobox,"Short"
AddGadgetItem combobox,"Medium"
AddGadgetItem combobox,"Fat",True
AddGadgetItem combobox,"Humungous"

While WaitEvent()
	Select EventID()
		Case EVENT_GADGETACTION
			Print "eventdata="+EventData()
		Case EVENT_WINDOWCLOSE
			End
	End Select
Wend

Function CreateHTMLView:TGadget(x,y,w,h,group:TGadget,style=0)
DescriptionCreate an HTMLView gadget.
InformationThe HTMLView is a complete web browser object inside a MaxGUI gadget. The HTML page displayed is controlled with the HTMLViewGo command or from the user navigating from within the currently viewed page.

CreateHTMLView supports the following styles:
ConstantMeaning
HTMLVIEW_NOCONTEXTMENUThe view's default context menu is disabled
HTMLVIEW_NONAVIGATEUser navigation is disabled and events generated instead

If the HTMLVIEW_NONAVIGATE style is selected, EVENT_GADGETACTION is generated when the user clicks on a link with EventText containing the requested URL.

EVENT_GADGETDONE events are generated at the completion of a page load.

See Also: HtmlViewGo, HtmlViewBack, HtmlViewForward, HtmlViewStatus and HtmlViewCurrentURL.

Example
' createhtmlview.bmx

Strict 

Local window:TGadget
Local htmlview:TGadget

window=CreateWindow("My Window",30,20,600,440,,15|WINDOW_ACCEPTFILES)

htmlview=CreateHTMLView(0,0,ClientWidth(window),ClientHeight(window),window)
SetGadgetLayout htmlview,1,1,1,1 

HtmlViewGo htmlview,"www.blitzmax.com"

While WaitEvent()
	Print CurrentEvent.ToString()
	Select EventID()
		Case EVENT_WINDOWCLOSE
			End
	End Select
Wend

Function CreateLabel:TGadget(name$,x,y,w,h,group:TGadget,style=LABEL_LEFT)
DescriptionCreate a Label gadget.
InformationA Label gadget is used to place static text or frames in a MaxGUI user interface.

Labels support these optional styles:
ConstantMeaning
LABEL_FRAMEThe label has a simple border.
LABEL_SUNKENFRAMEThe label has a sunken border.
LABEL_SEPARATORThe label is an etched box with no text useful for drawing separators.
LABEL_LEFTThe label's text is left aligned. (*default)
LABEL_CENTERThe label's text is aligned to the center.
LABEL_RIGHTThe label's text is right aligned.

See Also: SetGadgetText, SetGadgetTextColor, SetGadgetFont and SetGadgetColor.

Example
' createlabel.bmx

Strict 

Local window:TGadget

window=CreateWindow("My Window",30,20,320,480)

CreateLabel("A plain label",10,10,280,52,window)
CreateLabel("A label with LABEL_FRAME",10,80,280,60,window,LABEL_FRAME)
CreateLabel("A label with LABEL_SUNKENFRAME",10,150,280,60,window,LABEL_SUNKENFRAME)
CreateLabel("not applicable",10,220,280,54,window,LABEL_SEPARATOR)

While WaitEvent()<>EVENT_WINDOWCLOSE
Wend

Function CreateListBox:TGadget(x,y,w,h,group:TGadget,style=0)
DescriptionCreate a ListBox gadget.
InformationA ListBox gadget displays a scrollable table of items.
An EVENT_GADGETACTION is generated when the user selects an item.

See Also: AddGadgetItem, ClearGadgetItems, ModifyGadgetItem, SelectGadgetItem, RemoveGadgetItem and SelectedGadgetItem.

Example
' createlistbox.bmx

Strict 

Local window:TGadget
Local listbox:TGadget

window=CreateWindow("My Window",30,20,200,200)

Const ETIP$="Great for lovers of rain, mushy peas and stomping beats.~r~nNew line..."

listbox=CreateListBox(4,4,100,80,window)

AddGadgetItem listbox,"German"
AddGadgetItem listbox,"England",False,-1,ETIP
AddGadgetItem listbox,"French",False,-1,"tip - goes here","mystringobject"

SelectGadgetItem listbox,2

While WaitEvent()
	Print CurrentEvent.ToString()
	If EventSource()=listbox
		Print "SelectedGadgetItem()="+SelectedGadgetItem(listbox)
		If EventData()<>SelectedGadgetItem(listbox) Print "error with skidracer"
	EndIf
	Select EventID()
		Case EVENT_WINDOWCLOSE
			End
	End Select
Wend

Function CreateMenu:TGadget( text$,tag,parent:TGadget,hotKey=0,modifier=0 )
DescriptionCreate a menu.
InformationMenu gadgets can be attached to a WindowMenu, other Menu gadgets or used with the PopupWindowMenu command. The tag field should be a unique identifier that will be present in the EventData field of EVENT_MENUACTION events.

Keyboard shortcuts can be associated with a Menu by using the optional hotKey and modifier parameters.

Please refer to the KeyCodes module for valid key and modifier codes. The MODIFIER_COMMAND value should be used instead of MODIFIER_CONTROL with Menu hotkeys for best crossplatform compatability.

See Also: FreeMenu, SetMenuText, CheckMenu, UncheckMenu, EnableMenu, DisableMenu, MenuText, MenuChecked and MenuEnabled.

Example
' createmenu.bmx

Strict 

Local window:TGadget
Local filemenu:TGadget
Local editmenu:TGadget
Local helpmenu:TGadget

Const MENU_NEW=101
Const MENU_OPEN=102
Const MENU_SAVE=103
Const MENU_CLOSE=104
Const MENU_EXIT=105

Const MENU_CUT=106
Const MENU_COPY=107
Const MENU_PASTE=108

Const MENU_ABOUT=109

window=CreateWindow("My Window",40,40,320,240)

filemenu=CreateMenu("&File",0,WindowMenu(window))
CreateMenu"&New",MENU_NEW,filemenu,KEY_N,MODIFIER_COMMAND
CreateMenu"&Open",MENU_OPEN,filemenu,KEY_O,MODIFIER_COMMAND
CreateMenu"&Close",MENU_CLOSE,filemenu,KEY_W,MODIFIER_COMMAND
CreateMenu"",0,filemenu
CreateMenu"&Save",MENU_SAVE,filemenu,KEY_S,MODIFIER_COMMAND
CreateMenu"",0,filemenu
CreateMenu"E&xit",MENU_EXIT,filemenu,KEY_F4,MODIFIER_COMMAND

editmenu=CreateMenu("&Edit",0,WindowMenu(window))
CreateMenu "Cu&t",MENU_CUT,editmenu,KEY_X,MODIFIER_COMMAND
CreateMenu "&Copy",MENU_COPY,editmenu,KEY_C,MODIFIER_COMMAND
CreateMenu "&Paste",MENU_PASTE,editmenu,KEY_V,MODIFIER_COMMAND

helpmenu=CreateMenu("&Help",0,WindowMenu(window))
CreateMenu "&About",MENU_ABOUT,helpmenu

UpdateWindowMenu window

While True
	WaitEvent 
	Select EventID()
		Case EVENT_WINDOWCLOSE
			End
		Case EVENT_MENUACTION
			Select EventData()
				Case MENU_EXIT
					End
				Case MENU_ABOUT
					Notify "Incrediabler~n(C)2005 Incredible Software"
			End Select
	End Select
Wend

Function CreatePanel:TGadget(x,y,w,h,group:TGadget,style=0,title$="")
DescriptionCreate a Panel gadget.
InformationA Panel is a general purpose gadget that can be used to group other gadgets, it has background color and pixmap properties and can optionally produce the following mouse and key events when the PANEL_ACTIVE style is selected:
EVENT_MOUSEDOWNMouse button pressed. Event data contains mouse button code
EVENT_MOUSEUPMouse button released. Event data contains mouse button code
EVENT_MOUSEMOVEMouse moved. Event x and y contain mouse coordinates
EVENT_MOUSEWHEELMouse wheel spun. Event data contains delta clicks
EVENT_MOUSEENTERMouse entered gadget area
EVENT_MOUSELEAVEMouse left gadget area
EVENT_KEYDOWNKey pressed. Event data contains keycode
EVENT_KEYUPKey released. Event data contains keycode
EVENT_KEYCHARKey character. Event data contains unicode value

A panel can feature the following optional styles:
ConstantMeaning
PANEL_BORDERPanel is drawn with a border
PANEL_ACTIVEPanel generates mouse move events
PANEL_GROUPPanel is drawn with a titled etched border

See Also: SetPanelColor and SetPanelPixmap.

Example
' createpanel.bmx

Strict 

Local window:TGadget
Local panel:TGadget
Local panel2:TGadget
Local group:TGadget

window=CreateWindow("My Window",40,40,320,240)

' create a purple panel that occupies entire window client area

panel=CreatePanel(0,0,ClientWidth(window),ClientHeight(window),window,PANEL_ACTIVE)
SetGadgetLayout panel,1,1,1,1
'SetPanelColor panel,100,0,200

' and a smaller box

panel2=CreatePanel(10,10,100,100,panel,PANEL_ACTIVE|PANEL_BORDER)
panel2.SetColor(160,255,160)

' and a group panel with a child button

group=CreatePanel(120,10,100,100,panel,PANEL_GROUP)
group.settext("My Group")
CreateButton("hello",0,0,64,24,group)


While True
	WaitEvent 
	Print CurrentEvent.ToString()
	Select EventID()
		Case EVENT_WINDOWCLOSE
			End
	End Select
Wend

Function CreateProgBar:TGadget(x,y,w,h,group:TGadget,style=0)
DescriptionCreate a Progress Bar gadget.
Example
' createprogbar.bmx

Strict 

Local window:TGadget=CreateWindow("My Window",50,50,240,100,,WINDOW_TITLEBAR)

Local progbar:TGadget=CreateProgBar(10,10,200,20,window)

CreateLabel "Please Wait",10,40,200,20,window

CreateTimer 10

While WaitEvent()
	Select EventID()
		Case EVENT_WINDOWCLOSE
			End
		Case EVENT_TIMERTICK
			Local t=EventData()
			If t=50 End
			UpdateProgBar progbar,t/50.0
	End Select
Wend

Function CreateSlider:TGadget(x,y,w,h,group:TGadget,style=0)
DescriptionCreate a Slider gadget.
InformationA Slider gadget supports the following styles:
ConstantMeaning
SLIDER_HORIZONTALThe slider is moved left and right
SLIDER_VERTICALUser slider is moved up and down
SLIDER_SCROLLBARThe slider uses a proportional size knob
SLIDER_TRACKBARThe slider uses a fixed size knob
SLIDER_STEPPERThe slider has no knob, just arrow buttons

An EVENT_GADGETACTION is generated with the SliderValue of the Slider gadget in the EventData field whenever a Slider position is modified by the user.

See Also: SetSliderRange, SetSliderValue and SliderValue.

Example
' createslider.bmx

Strict 

Local window:TGadget=CreateWindow("My Window",0,0,240,240,,WINDOW_TITLEBAR)

Local slider:TGadget[3]

' standard vertical and horizontal scroll bars

slider[0]=CreateSlider(10,10,16,100,window,SLIDER_VERTICAL)
slider[1]=CreateSlider(30,10,100,16,window,SLIDER_HORIZONTAL)

' a horizontal trackbar

slider[2]=CreateSlider(30,30,100,24,window,SLIDER_HORIZONTAL|SLIDER_TRACKBAR)

' a row of vertical trackbars

Local trackbar:TGadget[5]

For Local i=0 To 4
	trackbar[i]=CreateSlider(30+i*20,50,16,60,window,SLIDER_VERTICAL|SLIDER_TRACKBAR)
Next

' a single stepper

Local stepper:TGadget
stepper=CreateSlider(10,120,24,24,window,SLIDER_STEPPER)

SetSliderValue stepper,4
Print SliderValue(stepper)

While WaitEvent()
	Print CurrentEvent.ToString()
	Select EventID()
		Case EVENT_WINDOWCLOSE
			End
	End Select
Wend

Function CreateTabber:TGadget(x,y,w,h,group:TGadget,style=0)
DescriptionCreate a Tabber gadget.
InformationA Tabber gadget provides a list of Tabs above a client area typically used for handling multiple documents.

See Also: AddGadgetItem, ClearGadgetItems, ModifyGadgetItem, SelectGadgetItem, RemoveGadgetItem and SelectedGadgetItem.

Example
' createtabber.bmx

Strict 

Local window:TGadget
Local tabber:TGadget
Local document:TGadget[3]
Local currentdocument:TGadget

' CreateDocument creates a hidden panel that fills entire tabber client area 

Function CreateDocument:TGadget(tabber:TGadget)
	Local	panel:TGadget
	panel=CreatePanel(0,0,ClientWidth(tabber),ClientHeight(tabber),tabber)
	SetGadgetLayout panel,1,1,1,1
	HideGadget panel
	Return panel
End Function

' create a default window with a tabber gadget that fills entire client area

window=CreateWindow("My Window",30,20,400,300)

tabber=CreateTabber(0,0,ClientWidth(window),ClientHeight(window),window)
SetGadgetLayout tabber,1,1,1,1 

' add three items and corresponding document panels to the tabber

AddGadgetItem tabber,"Document 0",False,-1,""
AddGadgetItem tabber,"Document 1",False,-1,"Tabber Tip 1"
AddGadgetItem tabber,"Document 2",False,-1,"tips 4 2"

document[0]=CreateDocument(tabber)
document[1]=CreateDocument(tabber)
document[2]=CreateDocument(tabber)

SetPanelColor document[0],255,200,200
SetPanelColor document[1],200,255,200
SetPanelColor document[2],200,200,255

' our documents start off hidden so make first one current and show

currentdocument=document[0]
ShowGadget currentdocument

' standard message loop with special tabber GADGET_ACTION handling

While WaitEvent()
	Select EventID()
		Case EVENT_GADGETACTION
			If EventSource()=tabber
				HideGadget currentdocument
				currentdocument=document[EventData()]
				ShowGadget currentdocument
			EndIf
		Case EVENT_WINDOWCLOSE
			End
	End Select
Wend

Function CreateTextArea:TGadget(x,y,w,h,group:TGadget,style=0)
DescriptionCreate a TextArea gadget.
InformationA TextArea gadget is a multiline text editor with commands that allow control over the contents, style and selection of the text it contains.

A GADGET_ACTION event occurs whenever the user modified a TextArea's text while a GADGET_SELECT event occurs whenever the cursor or selected text region is modified by the user. A GADGET_MENU command occurs if the user clicks the right button of the mouse inside a TextArea gadget.

A TextArea gadget may have the following optional styles:
ConstantMeaning
TEXTAREA_WORDWRAPWORDWRAP mode makes long lines of text flow onto following lines
TEXTAREA_READONLYThe user is unable to modify text in a READONLY TextArea

See Also: SetTextAreaText, AddTextAreaText, TextAreaText, TextAreaLen, LockTextArea, UnlockTextArea, SetTextAreaTabs, SetTextAreaFont, SetTextAreaColor, TextAreaCursor, TextAreaSelLen, FormatTextAreaText, SelectTextAreaText, TextAreaChar and TextAreaLine.

Example
' createtextarea.bmx

Strict 

Local window:TGadget
Local textarea:TGadget

window=CreateWindow("My Window",130,20,200,200,,15|WINDOW_ACCEPTFILES)

textarea=CreateTextArea(0,0,ClientWidth(window),ClientHeight(window)/2,window)
SetGadgetLayout textarea,1,1,1,1
SetGadgetText textarea,"a textarea gadget~none line~nandanother"
ActivateGadget textarea

SelectTextAreaText textarea,1,1,TEXTAREA_LINES

Print TextAreaCursor(textarea,TEXTAREA_LINES) 
Print TextAreaSelLen(textarea,TEXTAREA_LINES) 

While WaitEvent()
	Print CurrentEvent.ToString()+" "+EventSourceHandle()
	Select EventID()
		Case EVENT_WINDOWCLOSE
			End
		Case EVENT_APPTERMINATE
			End
	End Select
Wend

Function CreateTextField:TGadget(x,y,w,h,group:TGadget,style=0)
DescriptionCreate a TextField gadget.
InformationA TextField is a single line text entry gadget. An EVENT_GADGETACTION Event is generated whenever the contained text is modified by the user.

The optional TEXTFIELD_PASSWORD style creates a TextField that displays the user's input as asterisks in order to hide their input from others.

See Also: SetGadgetText and TextFieldText.

Example
' createtextfield.bmx

Strict 

Local window:TGadget
Local textfield:TGadget
Local button:TGadget

window=CreateWindow("My Window",30,20,320,200)

textfield=CreateTextField(4,4,120,22,window)
SetGadgetText( textfield,"A textfield gadget" )

' we need an OK button to catch return key

button=CreateButton("OK",130,4,80,24,window,BUTTON_OK)

ActivateGadget textfield

While WaitEvent()
	Select EventID()
	Case EVENT_GADGETACTION
		Select EventSource()
			Case textfield
				Print "textfield updated"
			Case button
				Print "return key / OK button pressed"
		End Select
	Case EVENT_WINDOWCLOSE
		End
	End Select
Wend

Function CreateToolBar:TGadget(source:Object,x,y,w,h,group:TGadget,style=0)
DescriptionCreate a ToolBar gadget.
InformationA ToolBar is created from a source pixmap that contains a row of equally shaped images. Any images in the row left blank are treated as ToolBar separators.

The source parameter can either be a TPixmap or a URL to an image file from which CreateToolBar loads a pixmap.

An EVENT_GADGETACTION is generated with the index of the ToolBar button in the EventData field.

See Also: AddGadgetItem, EnableGadgetItem, DisableGadgetItem and SetToolBarTips.

Example
' createtoolbar.bmx

Strict 

Local window:TGadget=CreateWindow("My Window",50,50,480,240)

Local toolbar:TGadget=CreateToolBar("toolbar.bmp",0,0,0,0,window)

SetToolBarTips toolbar,["New","Open","Save~nmy soul"] 

AddGadgetItem toolbar,"hello",GADGETITEM_TOGGLE,2,"This item is a quick test of GADGETITEM_TOGGLE"

DisableGadgetItem toolbar,2

While WaitEvent()
	Select EventID()
		Case EVENT_GADGETACTION
			If EventSource()=toolbar 
				Print "ToolBar GadgetAction~nEventData()="+EventData()
			EndIf
		Case EVENT_WINDOWCLOSE
			End
	End Select
Wend

Function CreateTreeView:TGadget(x,y,w,h,group:TGadget,style=0)
DescriptionCreate a TreeView gadget.
InformationA TreeView provides a view of an expandable list of nodes populated with the AddTreeViewNode command. TreeView nodes can themselves contain nodes providing a flexible method of displaying a hierachy of information.

EVENT_GADGETSELECT events occur when the user clicks on a node, EVENT_GADGETACTION when the user double clicks and, EVENT_GADGETMENU when the user right clicks.

EVENT_GADGETOPEN and EVENT_GADGETCLOSE are generated when the user expands and collapses nodes.

Each event will have the containing TreeView gadget as the EventSource and the actual node gadget in the EventExtra field of the Event.

See Also: AddTreeViewNode, InsertTreeViewNode, ModifyTreeViewNode, TreeViewRoot, SelectedTreeViewNode and CountTreeViewNodes, SelectTreeeViewNode, ExpandTreeViewNode, CollapseTreeViewNode and FreeTreeViewNode.

Example
' createtreeview.bmx

Strict 

Local window:TGadget=CreateWindow("My Window",50,50,240,240)
Local treeview:TGadget=CreateTreeView(0,0,200,200,window)

SetGadgetLayout treeview,2,2,2,2

Local root:TGadget=TreeViewRoot(treeview)

Local help:TGadget=AddTreeViewNode("Help",root)
AddTreeViewNode "topic 1",help
AddTreeViewNode "topic 2",help
AddTreeViewNode "topic 3",help

Local projects:TGadget=AddTreeViewNode("Projects",root)
AddTreeViewNode "project 1",projects
AddTreeViewNode("project 2",projects)
AddTreeViewNode("project 3 is a big waste of time",projects)

While WaitEvent()
	Print CurrentEvent.ToString()
	Select EventID()
		Case EVENT_WINDOWCLOSE
			End
	End Select
Wend

Function CreateWindow:TGadget(name$,x,y,w,h,group:TGadget=Null,style=15)
DescriptionCreate a Window gadget.
InformationA Window is the primary gadget of MaxGui. Windows should be used as the primary group gadgets in MaxGui applications to contain the gadgets that make up the program's user interface.

A Window produces the following events:
EVENT_WINDOWMOVEWindow has been moved
EVENT_WINDOWSIZEWindow has been resized
EVENT_WINDOWCLOSEWindow close icon clicked
EVENT_WINDOWACTIVATEWindow activated
EVENT_WINDOWACCEPTDrag and Drop operation was attempted

The following style flags are supported when creating a Window, the default window style is WINDOW_TITLEBAR | WINDOW_RESIZABLE | WINDOW_MENU | WINDOW_STATUS.
ConstantMeaning
WINDOW_TITLEBARThe Window has a titlebar that displays it's name
WINDOW_RESIZABLEThe Window can be resized by the user
WINDOW_MENUThe Window has a menubar
WINDOW_STATUSThe Window has a statusbar
WINDOW_TOOLThe Window is rendered on some platforms with a reduced titlebar
WINDOW_CLIENTCOORDSThe dimensions specified relate to the client area not the window frame
WINDOW_HIDDENThe Window is created in a hidden state
WINDOW_ACCEPTFILESEnable drag and drop operations

SeeAlso: WindowMenu, UpdateWindowMenu, PopupWindowMenu, ActivateWindow, SetStatusText, SetMinWindowSize, MinimizeWindow, maximizeWindow, RestoreWindow, WindowMinimized and WindowMaximized.

Example
' createwindow.bmx

Strict 

Local window:TGadget

window=CreateWindow("My Window",40,40,320,240)

While True
	WaitEvent 
	Print CurrentEvent.ToString()
	Select EventID()
		Case EVENT_WINDOWCLOSE
			End
	End Select
Wend

Function DeselectGadgetItem(gadget:TGadget,index)
DescriptionDeselect an item in a list based gadget.

Function Desktop:TGadget()
DescriptionReturn a gadget representing the system's desktop.

Function DisableGadget( gadget:TGadget )
DescriptionDisable a gadget blocking user interaction.

Function DisableGadgetItem( gadget:TGadget,index )
DescriptionDisable a particular item in a list based gadget.

Function DisableMenu( menu:TGadget )
DescriptionDisable a menu so it can not be selected.

Function EnableGadget( gadget:TGadget )
DescriptionEnable a gadget allowing user interaction.

Function EnableGadgetItem( gadget:TGadget,index )
DescriptionEnable a particular item in a list based gadget.

Function EnableMenu( menu:TGadget )
DescriptionEnable a menu for selection.

Function ExpandTreeViewNode( node:TGadget )
DescriptionExpand a Node in a TreeView gadget.

Function FontName$(font:TGuiFont)
ReturnsThe name of the font.
DescriptionFont name.

Function FontSize(font:TGuiFont)
ReturnsThe size of the font.
DescriptionFont size.

Function FontStyle(font:TGuiFont)
ReturnsThe style of the font.
DescriptionFont style.

Function FormatTextAreaText( textarea:TGadget,r,g,b,flags,pos=0,length=TEXTAREA_ALL,units=TEXTAREA_CHARS )
DescriptionFormat the color and style of some text in a TextArea gadget.
InformationThe r,g,b parameters represent the red, green and blue components (0..255) which when combined represent the new text color for the the sepecified region of characters.

The flags parameter can be a combination of the following values:
ConstantMeaning
TEXTFORMAT_BOLDBold
TEXTFORMAT_ITALICItalic
TEXTFORMAT_UNDERLINEUnderline
TEXTFORMAT_STRIKETHROUGHStrikeThrough

Depending on the value of the units parameter the position and length parameters specify the character position and number of characters or the starting line and the number of lines that FormatTextAreaText will modify.

See Also: LockTextArea and CreateTextArea.


Function FreeGadget( gadget:TGadget )
DescriptionRemove gadget and free it's resources.

Function FreeMenu( menu:TGadget )
DescriptionRemove a menu.

Function FreeTreeViewNode( node:TGadget )
DescriptionRemove a Node from a TreeView gadget.

Function GadgetCopy( gadget:TGadget )
DescriptionPerform Copy operation on gadget.

Function GadgetCut( gadget:TGadget )
DescriptionPerform Cut operation on gadget.

Function GadgetDisabled( gadget:TGadget )
ReturnsTrue if the gadget is disabled.
DescriptionGet a gadget's enabled status.

Function GadgetGroup:TGadget( gadget:TGadget )
ReturnsThe parent or group gadget.
DescriptionGet Gadget's group.

Function GadgetHeight( gadget:TGadget )
ReturnsThe current height in pixels of a gadget.
DescriptionGadget height.

Function GadgetHidden( gadget:TGadget )
ReturnsTrue if the gadget is hidden.
DescriptionGet a gadget's visible status.

Function GadgetItemExtra:Object( gadget:TGadget,index )
DescriptionGet the extra data of a given item in a list based gadget.

Function GadgetItemFlags( gadget:TGadget,index )
DescriptionGet the flags parameter of a given item in a list based gadget.

Function GadgetItemIcon( gadget:TGadget,index )
DescriptionGet the icon of a given item in a list based gadget.

Function GadgetItemText$( gadget:TGadget,index )
DescriptionGet the text of a given item in a list based gadget.

Function GadgetPaste( gadget:TGadget )
DescriptionPerform Paste operation on gadget.

Function GadgetPrint( gadget:TGadget )
DescriptionPerform Print operation on gadget.

Function GadgetText$( gadget:TGadget )
DescriptionReturns a Gadget's text.
InformationFor a Window gadget, GadgetText returns the title of the Window.

For the Label, Button, TextField and TextArea gadgets, the contents of the gadget are returned with the new Text.


Function GadgetWidth( gadget:TGadget )
ReturnsThe current width in pixels of a gadget.
DescriptionGadget width.

Function GadgetX( gadget:TGadget )
ReturnsThe horizontal position of a gadget relative to it's group.
DescriptionHorizontal position of gadget.

Function GadgetY( gadget:TGadget )
ReturnsThe vertical position of a gadget relative to it's group.
DescriptionVertical position of gadget.

Function HideGadget( gadget:TGadget )
DescriptionHide gadget from view.

Function HtmlViewBack( view:TGadget )
DescriptionGo back a page in an HTMLView gadget.

Function HtmlViewCurrentURL$( view:TGadget )
DescriptionGet the current page location of an HTMLView gadget.

Function HtmlViewForward( view:TGadget )
DescriptionGo forward a page in an HTMLView gadget.

Function HtmlViewGo( view:TGadget,url$ )
DescriptionSet the location URL of an HTMLView gadget.

Function HtmlViewRun$( view:TGadget,script$ )
DescriptionRun a script in an HTMLView gadget.

Function HtmlViewStatus( view:TGadget )
DescriptionGet the status of an HTMLView gadget.

Function InsertGadgetItem(gadget:TGadget,index,text$,flags=0,icon=-1,tip$="",extra:Object=Null)
DescriptionInserts an item in a list based gadget at the specified index.
InformationAn item can be inserted in a ComboBox, ListBox, Tabber and ToolBar list based gadgets.

See AddGadgetItem for a description of the parameters.

SeeAlso: AddGadgetItem, CreateComboBox, CreateListBox, CreateTabber and CreateToolBar.


Function InsertTreeViewNode:TGadget( index,text$,node:TGadget,icon=-1 )
DescriptionInsert a node at a given index in a TreeView gadget.

Function LoadGuiFont:TGuiFont( name$,height,bold=False,italic=False,underline=False)
ReturnsA TGuiFont object, or null if a suitable matching font was not found on the system.
DescriptionLoad a system font by name.
InformationLoads a system font by name and returns and object that can be used with the SetGadgetFont command.

Function LoadIconStrip:TIconStrip(source:Object)
DescriptionCreates an icon strip from an image file.
InformationAn icon strip is a series of small images that can be attached to items within container gadgets.
Icons must be square, and arranged in a single horizontal strip across the source image.
The number of icons in an iconstrip is determined by dividing the image width by its height. For example, an iconstrip 64 wide by 8 high is assumed to contain 64/8=8 icons.
Icon strips can be attached to container gadgets using SetGadgetIconStrip.
Prompts the user for a font and returns a font handle, Or 0 If no font was selected.

See Also: SetGadgetIconStrip.


Function LockTextArea( textarea:TGadget )
DescriptionLock a TextArea gadget for improved performance when formatting.

Function MaximizeWindow( window:TGadget )
DescriptionMaximize a window gadget.




Function MinimizeWindow( window:TGadget )
DescriptionSet a window gadget's maximum size.

Function ModifyGadgetItem( gadget:TGadget,index,text$,flags=0,icon=-1,tip$="",extra:Object=Null )
DescriptionModify the contents of an item to a list based gadget.
InformationSee AddGadgetItem for a description of the parameters.

SeeAlso: CreateComboBox, CreateListBox and CreateTabber.


Function ModifyTreeViewNode( node:TGadget,text$,icon=-1 )
DescriptionModify a node.

Function PopupWindowMenu( window:TGadget,menu:TGadget )
DescriptionDisplay a popup menu.
InformationA drop down menu is displayed on the Screen below the user's current mouse position.

See Also: CreateMenu.

Example
Strict

Local menu:TGadget
Local window:TGadget
Local panel:TGadget

menu=CreateMenu("popup",0,Null)
CreateMenu("Load",101,menu)
CreateMenu("Save",102,menu)

window=CreateWindow("Test PopupWindowMenu",20,20,200,200)

' create a panel to capture some mouse events

panel=CreatePanel(0,0,ClientWidth(window),ClientHeight(window),window,PANEL_ACTIVE)

While True
	WaitEvent
	Select EventID()
		Case EVENT_MOUSEDOWN
			If EventData()=2 PopupWindowMenu window,menu
		Case EVENT_WINDOWCLOSE
			End
		Case EVENT_MENUACTION
			Print "EVENT_MENUACTION: eventdata()="+EventData()
	End Select
Wend

Function QueryGadget(gadget:TGadget,queryid)
DescriptionReturn internal gadget properties.
InformationDependent on the Operating System and type of Gadget, QueryGadget can be used to retrieve system handles useful for programming platform specific functions that extend the functionality of a TGadget.
ConstantMeaning
QUERY_HWNDA TWin32Gadget's HWND handle
QUERY_HWND_CLIENTA TWin32Gadget's client HWND handle
QUERY_NSVIEWA TCocoaGadget's NSVIEW handle
QUERY_NSVIEW_CLIENTA TCocoaGadget's client NSVIEW handle
QUERY_FLWIDGETA TFLTKGadget's FL_WIDGET handle
QUERY_FLWIDGET_CLIENTA TFLTKGadget's client FL_WIDGET handle

Function RedrawGadget( gadget:TGadget )
DescriptionRedraws a gadget.
InformationThe RedrawGadget command causes the gadget to be redrawn by the underlying Operating System and is not guaranteed to happen immediately.

In the case of a Canvas gadget an EVENT_GADGETPAINT command is generated when the Operating System begins the actual redraw, the following example illustrates how to manage this feature:

Example
' redrawgadget.bmx

Strict

Type TApplet 

	Method OnEvent(Event:TEvent) Abstract

	Method New()
		AddHook EmitEventHook,eventhook,Self
	End Method

	Function eventhook:Object(id,data:Object,context:Object)
		Local	event:TEvent
		Local	app:TApplet
		event=TEvent(data)
		app=TApplet(context)
		app.OnEvent event	
	End Function

End Type

Type TSpinningApplet Extends TApplet

	Field	window:TGadget
	Field	canvas:TGadget
	Field	timer:TTimer
	Field	image:TImage
	
	Method Draw()
		SetGraphics CanvasGraphics(canvas)
		SetViewport 0,0,GraphicsWidth(),GraphicsHeight()
		SetBlend ALPHABLEND
		SetRotation MilliSecs()*.1
		SetClsColor 255,0,0
		Cls
		DrawImage image,GraphicsWidth()/2,GraphicsHeight()/2
		Flip
	End Method
	
	Method OnEvent(Event:TEvent)
		Select event.id
		Case EVENT_WINDOWCLOSE
			End
		Case EVENT_TIMERTICK
			RedrawGadget canvas
		Case EVENT_GADGETPAINT
			draw
		End Select
	End Method
	
	Method Create:TSpinningApplet(name$)
		Local	a:TApplet
		Local	w,h
		image=LoadImage("fltkwindow.png")
		window=CreateWindow(name,20,20,512,512)
		w=ClientWidth(window)
		h=ClientHeight(window)
		canvas=CreateCanvas(0,0,w,h,window)
		canvas.SetLayout 1,1,1,1
		timer=CreateTimer(100)
		Return Self		
	End Method
	
End Type

AutoMidHandle True

Local	spinner:TSpinningApplet

spinner=New TSpinningApplet.Create("Spinning Applet")

While True
	WaitEvent
Wend

Function RemoveGadgetItem( gadget:TGadget,index )
DescriptionRemove an item from a list based gadget.

Function RequestColor(r,g,b)
ReturnsTrue if a color is selected, False if if the requester was cancelled.
DescriptionPrompts the user for a color.
InformationThe parameters red,green,blue are the initial color to display in the requester, with components in the range 0 To 255.
After a color is selected, use the RequestedRed, RequestedGreen And RequestedBlue functions to determine the color selected by the user.
Example
' requestcolor.bmx

Strict 

Local window:TGadget
Local panel:TGadget
Local red,green,blue

window=CreateWindow("RequestColor",40,40,320,240)
panel=CreatePanel(20,20,32,32,window,PANEL_ACTIVE|PANEL_BORDER)

While True
	WaitEvent 
	Select EventID()
		Case EVENT_WINDOWCLOSE
			End
		Case EVENT_MOUSEDOWN
			If RequestColor(red,green,blue)
				red=RequestedRed()
				green=RequestedGreen()
				blue=RequestedBlue()
				SetPanelColor panel,red,green,blue
			EndIf				
	End Select
Wend

Function RequestedBlue()
DescriptionGet Blue component of requested color.
InformationSee RequestColor for more information.

Function RequestedGreen()
DescriptionGet Green component of requested color.
InformationSee RequestColor for more information.

Function RequestedRed()
DescriptionGet Red component of requested color.
InformationSee RequestColor for more information.

Function RequestFont:TGuiFont(font:TGuiFont=Null)
ReturnsA TGuiFont object, or null if no font was selected.
DescriptionPrompts the user to select a system font.
InformationPrompts the user for a font and returns an object that can be used with the SetGadgetFont command.
Example
' requestfont.bmx

Strict 

Local window:TGadget
Local button:TGadget
Local label:TGadget
Local font:TGuiFont

window=CreateWindow("RequestFont",30,20,200,250)
label=CreateLabel("font example",4,4,192,132,window)
button=CreateButton("Select Font",4,140,100,20,window)

While WaitEvent()
	Select EventID()
		Case EVENT_WINDOWCLOSE
			End
		Case EVENT_GADGETACTION
			font=RequestFont(font)
			If font
				SetGadgetFont label,font
				SetGadgetText label,FontName(font)+":"+FontSize(font)
			EndIf
	End Select
Wend

Function RestoreWindow( window:TGadget )
DescriptionRestore a window gadget from a minimize or maximized state.

Function SelectedGadgetItem(gadget:TGadget)
DescriptionGet the first selected item in a list based gadget.

Function SelectedGadgetItems[](gadget:TGadget)
DescriptionGet selected items in a list based gadget.

Function SelectedTreeViewNode:TGadget( treeview:TGadget )
DescriptionGet the selected node of a TreeView gadget.

Function SelectGadgetItem(gadget:TGadget,index)
DescriptionSelect an item in a list based gadget.

Function SelectTextAreaText( textarea:TGadget,pos=0,length=TEXTAREA_ALL,units=TEXTAREA_CHARS )
DescriptionSelect a range of text in a TextArea gadget.
InformationDepending on the value of the units the position and length parameters specify the character position and number of characters or the starting line and the number of lines that SelextTextAreaText will highlight.

See Also: TextAreaCursor, TextAreaSelLen and CreateTextArea.


Function SelectTreeViewNode( node:TGadget )
DescriptionSelect a Node.

Function SetButtonState( button:TGadget,checked )
DescriptionSet a Button gadget's state.

Function SetGadgetAlpha( gadget:TGadget,alpha# )
DescriptionSet the transparency of a gadget.
InformationAlpha should be in the range 0.0 (invisible) to 1.0 (solid).

Function SetGadgetColor( gadget:TGadget,r,g,b,bg=True )
DescriptionSet Gadget's background color.

Function SetGadgetFilter( gadget:TGadget,callback(event:TEvent,context:Object),context:Object=Null )
DescriptionAttaches an event filter function to a MaxGui Gadget.
InformationThe filter function supplied is called by the Gadget with a TEvent and optional user context object. If the Function returns zero the event is filtered and not processed further by the system whereas a non zero return indicates event processing should proceed as normal.
Currently only EVENT_KEYDOWN, EVENT_KEYCHAR, events produced by TextArea and TextField gadgets can be filtered with the SetGadgetFilter command.
Example
' setgadgetfilter.bmx

Strict 

Local window:TGadget
Global textarea:TGadget

window=CreateWindow("My Window",30,20,320,240)

textarea=CreateTextArea(0,24,ClientWidth(window),ClientHeight(window)-24,window)

SetGadgetLayout textarea,1,1,1,1
SetGadgetText textarea,"A textarea gadget that filters out down arrows~nand tab keys."
ActivateGadget textarea

SetGadgetFilter textarea,filter

Print "KEY_TAB="+KEY_TAB

Function filter(event:TEvent,context:Object)
	Select event.id
		Case EVENT_KEYDOWN
			Print "filtering keydown:"+event.data+","+event.mods
			If event.data=KEY_DOWN Return 0
			If event.data=13 Return 0
		Case EVENT_KEYCHAR
			Print "filtering charkey:"+event.data+","+event.mods
			If event.data=KEY_TAB Return 0
	End Select
	Return 1
End Function

While WaitEvent()
	Select EventID()
		Case EVENT_WINDOWCLOSE
			End
	End Select
Wend

Function SetGadgetFont( gadget:TGadget,font:TGuiFont )
DescriptionSet a gadget's font.
InformationSee LoadGuiFont and RequestFont for creating a TGuiFont for use with the SetGadgetFont command.

Function SetGadgetHotKey( gadget:TGadget,hotkey,modifier )
DescriptionSet hot key for a gadget.

Function SetGadgetIconStrip(gadget:TGadget,iconstrip:TIconStrip)
DescriptionAttaches an icon strip to a container gadget.
InformationOnce attached, icons may be selected when items are added or modified with the AddGadgetItem, InsertGadgetItem and ModifyGadgetItem commands.
This command may only be used with combobox, listbox, tabber and treenode gadgets.

See Also: LoadIconStrip.


Function SetGadgetLayout( gadget:TGadget,Left,Right,Top,Bottom )
DescriptionSet a gadget's layout rules for when it's group is resized.
InformationSetGadgetLayout lets you control the automatic layout of a gadget in the event it's parent is resized.
Each edge of a Gadget has an alignment setting that fixes it in place in the following manner:
EDGE_CENTEREDThe edge of the gadget is kept relative to the center of it's parent.
EDGE_ALIGNEDThe edge of the gadget stays relative to it's parent's corresponding edge.
EDGE_RELATIVEThe edge of the gadget stays relative to both it's parent's edges.
The default is EDGE_CENTERED for all edges.

Function SetGadgetShape( gadget:TGadget,x,y,w,h )
DescriptionSet a gadget's position and size relative to it's group.

Function SetGadgetText( gadget:TGadget,text$ )
DescriptionSet Gadget's text.
InformationFor a Window gadget, SetGadgetText causes the Window to be renamed.

For the Label, Button, TextField and TextArea gadgets, the contents of the gadget are replaced with the new Text.


Function SetGadgetTextColor( gadget:TGadget,r,g,b )
DescriptionSet Gadget's foreground color.
InformationThe red, green and blue components should be in the range 0 To 255.

Function SetHotKeyEvent:THotKey( key,mods,event:TEvent=Null,owner=0 )
DescriptionSet hotkey event.
InformationWhen the specified hotkey combination is selected by the user, the specified event will be emitted using EmitEvent.

If event is null, an event with id equal to EVENT_HOTKEYHIT, data equal to key and mods equal to mods will be emitted.

SetHotKeyEvent will overwrite any existing hotkey event with the same key and mods.
Please refer to the KeyCodes module for valid key and modifier codes.

Function SetMenuText( menu:TGadget,text$ )
DescriptionModify a menu's text.

Function SetMinWindowSize( window:TGadget,w,h )
DescriptionSet a window gadget's minimum size.

Function SetPanelColor( panel:TGadget,r,g,b )
DescriptionSet the color of a Panel.

Function SetPanelPixmap( panel:TGadget,pixmap:TPixmap,flags=PANELPIXMAP_TILE)
DescriptionSet panel's background image to a pixmap.
Information
ConstantMeaning
PANELPIXMAP_TILEThe panel is filled with repeating tiles.
PANELPIXMAP_CENTERThe pixmap is positioned at the center of the Panel.
PANELPIXMAP_FITThe pixmap is scaled to best fit the Panel size.
PANELPIXMAP_STRETCHThe pixmap is stretched to fit the entire Panel.

See Also: CreatePanel and SetPanelColor.


Function SetPointer(shape)
DescriptionSet mouse pointer shape.
InformationThe shape of the system mouse pointer can be one of the following:
ConstantValue
POINTER_DEFAULT0
POINTER_ARROW1
POINTER_IBEAM2
POINTER_WAIT3
POINTER_CROSS4
POINTER_UPARROW5
POINTER_SIZENWSE6
POINTER_SIZENESW7
POINTER_SIZEWE8
POINTER_SIZENS9
POINTER_SIZEALL10
POINTER_NO11
POINTER_HAND12
POINTER_APPSTARTING13
POINTER_HELP14
Example
' setpointer.bmx

Strict 

Local window:TGadget
Local combo:TGadget

window=CreateWindow("SetPointer",40,40,320,240,,WINDOW_TITLEBAR)

CreateLabel "Select a pointer shape:",10,10,200,20,window

combo=CreateComboBox(10,30,200,24,window)
AddGadgetItem combo,"POINTER_DEFAULT"
AddGadgetItem combo,"POINTER_ARROW"
AddGadgetItem combo,"POINTER_IBEAM" 
AddGadgetItem combo,"POINTER_WAIT" 
AddGadgetItem combo,"POINTER_CROSS"
AddGadgetItem combo,"POINTER_UPARROW" 
AddGadgetItem combo,"POINTER_SIZENWSE" 
AddGadgetItem combo,"POINTER_SIZENESW" 
AddGadgetItem combo,"POINTER_SIZEWE" 
AddGadgetItem combo,"POINTER_SIZENS" 
AddGadgetItem combo,"POINTER_SIZEALL" 
AddGadgetItem combo,"POINTER_NO" 
AddGadgetItem combo,"POINTER_HAND"
AddGadgetItem combo,"POINTER_APPSTARTING"
AddGadgetItem combo,"POINTER_HELP"

SelectGadgetItem combo,0

While True
	WaitEvent 
	Select EventID()
		Case EVENT_WINDOWCLOSE
			End
		Case EVENT_GADGETACTION
			SetPointer EventData()
	End Select
Wend

Function SetSliderRange(slider:TGadget,range0,range1)
DescriptionSet the range of a Slider gadget.
InformationFor the default SLIDER_SCROLLBAR style the range0,range1 parameters are treated as a visible / total ratio which dictates both the size of the knob and it's maximum value. The default value is 1,10 which displays a Slider with a knob that occupies 1/10th the area and with a SliderValue range of 0..9.

For the SLIDER_TRACKBAR and SLIDER_STEPPER styles the range0,range1 parameters are treated as the minimum and maximum SliderValue range inclusive.

See Also: CreateSlider, SliderValue and SetSliderValue.


Function SetSliderValue(slider:TGadget,value)
DescriptionSet the position of a Slider gadget.

Function SetStatusText( window:TGadget,text$ )
DescriptionSet the text in a window gadget's status bar.

Function SetTextAreaColor( textarea:TGadget,r,g,b,bg=False )
DescriptionSet the background or foreground colors of a TextArea gadget.

Function SetTextAreaFont( textarea:TGadget,font:TGuiFont )
DescriptionSet the font of a TextArea gadget.

Function SetTextAreaTabs( textarea:TGadget,tabs )
DescriptionSet the tab size of a TextArea gadget.

Function SetTextAreaText( textarea:TGadget,text$,pos=0,length=TEXTAREA_ALL,units=TEXTAREA_CHARS )
DescriptionSet the contents of a TextArea gadget.

Function SetToolBarTips( toolbar:TGadget,tips$[] )
DescriptionAttach a list of tips to a ToolBar gadget.

Function ShowGadget( gadget:TGadget )
DescriptionMake gadget visible.

Function SliderValue(slider:TGadget)
DescriptionGet the position of a Slider gadget.

Function TextAreaChar( textarea:TGadget,line )
DescriptionFind the character position of a given line in a TextArea gadget.

Function TextAreaCursor( textarea:TGadget,units=TEXTAREA_CHARS )
DescriptionFind the position of the cursor in a TextArea gadget.
InformationUse the default TEXTAREA_CHARS units argument to find out which character (column) in the line the cursor is on and use TEXTAREA_LINES to find out which line (row) the cursor is on.

See Also: TextAreaSelLen and CreateTextArea.


Function TextAreaLen( textarea:TGadget,units=TEXTAREA_CHARS )
DescriptionGet the number of characters in a TextArea gadget.

Function TextAreaLine( textarea:TGadget,index )
DescriptionFind the line of a given character position in a TextArea gadget.

Function TextAreaSelLen( textarea:TGadget,units=TEXTAREA_CHARS )
DescriptionFind the size of the selected text in a TextArea gadget.
InformationThe TEXTAREA_CHARS option returns the number of characters currently highlighted by the user where as TEXTAREA_LINES will specify the function returns the number of lines selected.

See Also: TextAreaCursor and CreateTextArea.


Function TextAreaText$( textarea:TGadget,pos=0,length=TEXTAREA_ALL,units=TEXTAREA_CHARS )
DescriptionGet the contents of a TextArea gadget.

Function TextFieldText$( textfield:TGadget )
DescriptionGet the current text in a TextField gadget.

Function ToggleGadgetItem(gadget:TGadget,index)
DescriptionInvert the selected state of an item in a list based gadget.

Function TreeViewRoot:TGadget( treeview:TGadget )
DescriptionGet the root node of a TreeView gadget.

Function UncheckMenu( menu:TGadget )
DescriptionClear a menu's checked state.

Function UnlockTextArea( textarea:TGadget )
DescriptionUnlock a previously locked TextArea gadget.

Function UpdateProgBar(progbar:TGadget,value#)
DescriptionUpdate the display of a ProgressBar gadget.

Function UpdateWindowMenu( window:TGadget )
DescriptionUpdate a window gadget's menu hierachy.

Function WindowMaximized( window:TGadget )
ReturnsTrue if the window is currently maximized, False if not.
DescriptionDetect if a window gadget is maximized.
InformationA maximized window fills the entire desktop. A window may be maximized with the MaximizeWindow command or by the user if CreateWindow was called with the WINDOW_RESIZABLE flag.

Function WindowMenu:TGadget( window:TGadget )
DescriptionGet a window gadget's main menu handle.

Function WindowMinimized( window:TGadget )
ReturnsTrue if the window is currently minimized, False if not.
DescriptionDetect if a window gadget is minimized.

Module Information

Version1.08
AuthorSimon Armstrong, Mark Sibly
LicenseBlitz Shared Source Code
CopyrightBlitz Research Ltd
ModserverBRL
History1.09 Release
HistoryAdded TEXTFORMAT_UNDERLINE and TEXTFORMAT_STRIKETHROUGH constants
HistoryAdded GadgetText function for accessing Gadget.GetText
History1.08 Release
HistoryAdded SetGraphics requirement to CreateCanvas documentation
HistoryReplaced EnableToolBarItem references with Enable/DisableGadgetItem
History1.07 Release
HistoryAdded optional owner window field to THotKey processing
History1.06 Release
HistoryGraphicsFlags removed from CreatePanel, panels now use Graphic's DefaultGraphicsFlags
History1.05 Release
HistoryAdded range checking on gadget item parameters
History1.04 Release
HistoryBumped version to restore missing docs on Apple modserver
History1.03 Release
HistoryFixed some broken examples due to new 1.14 strict rules
HistoryNew common maxgui.h header file for use by native drivers
HistroyDocumented TEXTAREA_ALL, TEXTAREA_CHARS and TEXTAREA_LINES constants
HistroyTreeView now uses EventExtra to specify node involved
History1.02 Release
HistoryRenamed Query() to QueryGadget()
HistoryAdded QUERY_HWND,QUERY_HWND_CLIENT,QUERY_NSVIEW, QUERY_NSVIEW_CLIENT,
HistoryQUERY_FLWIDGET, and QUERY_FLWIDGET_CLIENT constants
HistoryEventSource() fixed for TProxyGadgets
HistoryRemoved SetGadgetTarget, see new Event.AddEventTarget
HistoryRedrawGadget now uses ACTIVATE_REDRAW