Added documentation

author: Ian C <ianc@noddybox.co.uk> 2005-09-18 19:19:36 +0000
committer: Ian C <ianc@noddybox.co.uk> 2005-09-18 19:19:36 +0000
commit: f8de91ae41929286b1cf43c72093e5c996b1f949 (patch)
tree: f9ccb2fa8461c2941e6d60187ae8952e9ee30f12 /simplegui.mod
parent: f79195715c66530b0bda50242380812c5e670c00 (diff)
2 files changed, 316 insertions, 16 deletions
diff --git a/simplegui.mod/doc/commands.html b/simplegui.mod/doc/commands.html
new file mode 100644
index 0000000..c66334a
--- /dev/null
+++ b/simplegui.mod/doc/commands.html
@@ -0,0 +1,109 @@
+<html>
+<head>
+<title>BlitzMax Module Reference</title>
+<link rel="stylesheet" type="text/css" href="../../../../doc/bmxstyle.css">
+</head>
+<body>
+<h1>Function Reference</h1>
+<p><div id=GUINotify class=ref>
+<div class=rootdoc><font class=token>Function GUINotify( s:String )</font> Displays a notification alert with the supplied string.</div><div class=indent></div><br></div><br>
+<p><div id=GUIYesNo class=ref>
+<div class=rootdoc><font class=token>Function GUIYesNo:Int( s:String )</font> Displays a yes/no alert with the supplied string.</div><div class=indent><p><b>Returns:</b> True if Yes selected, otherwise False.</div><br></div><br>
+<p><div id=GUIMenu class=ref>
+<div class=rootdoc><font class=token>Function GUIMenu( title:String, options:String[],x,y )</font> Displays a pop-up menu.</div><div class=indent><p><b>Returns:</b> The index of the selected option, -1 for none.<p><b>title</b> is the menu title, <b>options</b> the options to display and <b>x</b> and <b>y</b> specify its position,.</div><br></div><br>
+<h1>Type Reference</h1>
+<p><div id=TGUIFont class=ref>
+<div class=rootdoc><font class=token>Type TGUIFont</font> Defines the <b>TBitmapFont</b> to be used by the GUI.</div><div class=indent></div><br><p><div id=font>
+<div class=rootdoc><font class=token>Global font:TBitmapFont</font> The font to use.</div><div class=indent></div><br></div><br>
+</div><br>
+<p><div id=TWidget class=ref>
+<div class=rootdoc><font class=token>Type TWidget Abstract</font> The base widget type.</div><div class=indent></div><br><p><div id=enabled>
+<div class=rootdoc><font class=token>Field enabled:Int</font> If true the widget is displayed and can be used.</div><div class=indent></div><br></div><br>
+<p><div id=text>
+<div class=rootdoc><font class=token>Field text:String</font> The text displayed in the widget.</div><div class=indent></div><br></div><br>
+<p><div id=x>
+<div class=rootdoc><font class=token>Field x:Int</font> The X co-ordinate of the widget.</div><div class=indent></div><br></div><br>
+<p><div id=y>
+<div class=rootdoc><font class=token>Field y:Int</font> The Y co-ordinate of the widget.</div><div class=indent></div><br></div><br>
+<p><div id=w>
+<div class=rootdoc><font class=token>Field w:Int</font> The width of the widget.</div><div class=indent></div><br></div><br>
+<p><div id=h>
+<div class=rootdoc><font class=token>Field h:Int</font> The height of the widget.</div><div class=indent></div><br></div><br>
+<p><div id=callback>
+<div class=rootdoc><font class=token>Field callback(w:TWidget)</font> Callback to call when clicked.</div><div class=indent></div><br></div><br>
+<p><div id=mouse_over>
+<div class=rootdoc><font class=token>Field mouse_over:Int</font> True if the mouse is over this widget, False otherwise.</div><div class=indent></div><br></div><br>
+<p><div id=owner>
+<div class=rootdoc><font class=token>Field owner:TGUIHandler</font> The <b>TGUIHandler</b> that owns this widget.</div><div class=indent></div><br></div><br>
+<p><div id=HandleKey>
+<div class=rootdoc><font class=token>Method HandleKey( k:Int )</font> Override this accept keypresses</div><div class=indent></div><br></div><br>
+<p><div id=MouseEnter>
+<div class=rootdoc><font class=token>Method MouseEnter()</font> Override this for when the mouse enters.  Call this parent version to handle <b>mouse_over</b> too.</div><div class=indent></div><br></div><br>
+<p><div id=MouseLeave>
+<div class=rootdoc><font class=token>Method MouseLeave()</font> Override this for when the mouse leaves.  Call this parent version to handle <b>mouse_over</b> too.</div><div class=indent></div><br></div><br>
+<p><div id=HandleClick>
+<div class=rootdoc><font class=token>Method HandleClick()</font> Override to handle a mouse button press.</div><div class=indent></div><br></div><br>
+<p><div id=Draw>
+<div class=rootdoc><font class=token>Method Draw()</font> Must be provided by a widget to draw itself.</div><div class=indent></div><br></div><br>
+<p><div id=DrawBox>
+<div class=rootdoc><font class=token>Function DrawBox( x:Int, y:Int, w:Int, h:Int )</font> Helper to draw a wireframe rectangle.</div><div class=indent></div><br></div><br>
+<p><div id=Draw3DBox>
+<div class=rootdoc><font class=token>Function Draw3DBox( x:Int, y:Int, w:Int, h:Int, invert:Int, size:Int=2 )</font> Helper to draw a 3D rectangle.</div><div class=indent></div><br></div><br>
+</div><br>
+<p><div id=TLabel class=ref>
+<div class=rootdoc><font class=token>Type TLabel Extends TWidget</font> The label widget (simply displays the supplied string)</div><div class=indent></div><br><p><div id=Create>
+<div class=rootdoc><font class=token>Function Create:TLabel( gui:TGUIHandler,x:Int, y:Int, text:String )</font> Create a TLabel widget.</div><div class=indent><p><b>Returns:</b> The created widget.<p><b>gui</b> is the <b>TGUIHandler</b> object managing this wiget. <b>x</b> and <b>y</b> are its position and <b>text</b> is the text to display in the label.</div><br></div><br>
+</div><br>
+<p><div id=TText class=ref>
+<div class=rootdoc><font class=token>Type TText Extends TWidget</font> The text entry widget</div><div class=indent></div><br><p><div id=Create>
+<div class=rootdoc><font class=token>Function Create:TText( gui:TGUIHandler,x:Int, y:Int, text:String, maxlen:Int, callback(w:TWidget)=Null )</font> Create a TText widget.</div><div class=indent><p><b>Returns:</b> The created widget.<p><b>gui</b> is the <b>TGUIHandler</b> object managing this wiget. <b>x</b> and <b>y</b> are its position and <b>text</b> is the initial text in the widget.
+<b>maxlen</b> is the maximum number of characters allowed.  <b>callback</b> is called when RETURN is pressed in the text field.</div><br></div><br>
+</div><br>
+<p><div id=TCheckbox class=ref>
+<div class=rootdoc><font class=token>Type TCheckbox Extends TWidget</font> The checkbox widget</div><div class=indent></div><br><p><div id=checked>
+<div class=rootdoc><font class=token>Field checked:Int</font> True if the box is checked, False otherwise.</div><div class=indent></div><br></div><br>
+<p><div id=Create>
+<div class=rootdoc><font class=token>Function Create:TCheckbox( gui:TGUIHandler, x:Int, y:Int, text:String, callback(w:TWidget)=Null )</font> Create a TCheckox widget.</div><div class=indent><p><b>Returns:</b> The created widget.<p><b>gui</b> is the <b>TGUIHandler</b> object managing this wiget. <b>x</b> and <b>y</b> are its position and <b>text</b> is the text to display by the checkbox.
+<b>callback</b> is called when the checkbox is toggled.</div><br></div><br>
+</div><br>
+<p><div id=TButton class=ref>
+<div class=rootdoc><font class=token>Type TButton Extends TWidget</font> The button widget</div><div class=indent></div><br><p><div id=Create>
+<div class=rootdoc><font class=token>Function Create:TButton( gui:TGUIHandler, x:Int, y:Int, w:Int, h:Int, text:String, callback(w:TWidget) )</font> Create a TButton widget.</div><div class=indent><p><b>Returns:</b> The created widget.<p><b>gui</b> is the <b>TGUIHandler</b> object managing this wiget. <b>x</b>, <b>y</b>, <b>w</b> and <b>h</b> are its position and size, and <b>text</b> is the text to display in the button.
+<b>callback</b> is called when the button is pressed.</div><br></div><br>
+</div><br>
+<p><div id=TButtonList class=ref>
+<div class=rootdoc><font class=token>Type TButtonList Extends TWidget</font> A drop down list type widget</div><div class=indent></div><br><p><div id=selected>
+<div class=rootdoc><font class=token>Field selected:Int</font> The selected item.</div><div class=indent></div><br></div><br>
+<p><div id=Create>
+<div class=rootdoc><font class=token>Function Create:TButtonList( gui:TGUIHandler, x:Int, y:Int, options:String[], selected:Int, callback(w:TWidget) )</font> Create a TButtonList widget.</div><div class=indent><p><b>Returns:</b> The created widget.<p><b>gui</b> is the <b>TGUIHandler</b> object managing this wiget. <b>x</b> and <b>y</b> are its position. <b>options</b> are the options for the list and
+<b>selected</b> is the currently selected item. <b>callback</b> is called when the selection changes.</div><br></div><br>
+</div><br>
+<p><div id=TGUIHandler class=ref>
+<div class=rootdoc><font class=token>Type TGUIHandler</font> Handles the GUI.</div><div class=indent></div><br><p><div id=Register>
+<div class=rootdoc><font class=token>Method Register( w:TWidget )</font> Register a widget.</div><div class=indent><p>Widgets call this themselves.</div><br></div><br>
+<p><div id=Clear>
+<div class=rootdoc><font class=token>Method Clear()</font> Remove all widgets.</div><div class=indent></div><br></div><br>
+<p><div id=SetFocus>
+<div class=rootdoc><font class=token>Method SetFocus( w:TWidget )</font> Sets the keyboard focus to the supplied widget.  Pass null for no focus.</div><div class=indent></div><br></div><br>
+<p><div id=GetFocus>
+<div class=rootdoc><font class=token>Method GetFocus:TWidget()</font> Gets the keyboard focus.</div><div class=indent><p><b>Returns:</b> The currently focused TWidget, or null for no focus.</div><br></div><br>
+<p><div id=Clicked>
+<div class=rootdoc><font class=token>Method Clicked:TWidget()</font> Gets the last clicked widget.</div><div class=indent><p><b>Returns:</b> The last clicked TWidget.  Null is returned if this is called again before another widget is clicked.</div><br></div><br>
+<p><div id=EventLoop>
+<div class=rootdoc><font class=token>Method EventLoop()</font> Perform the event loop and pass any necessary events.</div><div class=indent><p>KeyHit(KEY_MOUSELEFT) and GetChar() are used to consume events for the interface.</div><br></div><br>
+<p><div id=Create>
+<div class=rootdoc><font class=token>Function Create:TGUIHandler()</font> Create a GUI Handler.</div><div class=indent><p><b>Returns:</b> The GUI Hanbler.</div><br></div><br>
+</div><br>
+<h1>Module Information</h1>
+<table>
+<tr><td><b>Framework</b></td>
+<td> (Very) Simple GUI</td></tr>
+<tr><td><b>Copyright</b></td>
+<td> Public Domain</td></tr>
+<tr><td><b>Author</b></td>
+<td> Ian Cowburn</td></tr>
+<tr><td><b>Version</b></td>
+<td> $Revision$</td></tr>
+</table>
+</body>
+</html>
diff --git a/simplegui.mod/simplegui.bmx b/simplegui.mod/simplegui.bmx
index 712c61f..bcabdb0 100644
--- a/simplegui.mod/simplegui.bmx
+++ b/simplegui.mod/simplegui.bmx
@@ -1,3 +1,6 @@
+Rem
+bbdoc: noddybox.simplegui
+EndRem
 Module noddybox.simplegui
 
 ModuleInfo "Framework: (Very) Simple GUI"
@@ -12,38 +15,92 @@ Import brl.Max2D
 Import brl.Basic
 Import noddybox.bitmapfont
 
+Rem
+bbdoc: Defines the @TBitmapFont to be used by the GUI.
+EndRem
 Type TGUIFont
+	Rem
+	bbdoc: The font to use.
+	EndRem
 	Global font:TBitmapFont
 End Type
 
+Rem
+bbdoc: The base widget type.
+EndRem
 Type TWidget Abstract
 
+	Rem
+	bbdoc: If true the widget is displayed and can be used.
+	EndRem
 	Field	enabled:Int
+	Rem
+	bbdoc: The text displayed in the widget.
+	EndRem
 	Field	text:String
+	Rem
+	bbdoc: The X co-ordinate of the widget.
+	EndRem
 	Field	x:Int
+	Rem
+	bbdoc: The Y co-ordinate of the widget.
+	EndRem
 	Field	y:Int
+	Rem
+	bbdoc: The width of the widget.
+	EndRem
 	Field	w:Int
+	Rem
+	bbdoc: The height of the widget.
+	EndRem
 	Field	h:Int
-	Field	owner:TGUIHandler
+	Rem
+	bbdoc: Callback to call when clicked.
+	EndRem
 	Field	callback(w:TWidget)
+	Rem
+	bbdoc: True if the mouse is over this widget, False otherwise.
+	EndRem
 	Field	mouse_over:Int
-	
+	Rem
+	bbdoc: The @TGUIHandler that owns this widget.
+	EndRem
+	Field	owner:TGUIHandler
+
+	Rem
+	bbdoc: Override this accept keypresses
+	EndRem	
 	Method HandleKey(k:Int)
 	End Method
 	
+	Rem
+	bbdoc: Override this for when the mouse enters.  Call this parent version to handle @mouse_over too.
+	EndRem
 	Method MouseEnter()
 		mouse_over=True
 	End Method
 
+	Rem
+	bbdoc: Override this for when the mouse leaves.  Call this parent version to handle @mouse_over too.
+	EndRem
 	Method MouseLeave()
 		mouse_over=False
 	End Method
 
+	Rem
+	bbdoc: Override to handle a mouse button press.
+	EndRem
 	Method HandleClick()
 	End Method
 	
+	Rem
+	bbdoc: Must be provided by a widget to draw itself.
+	EndRem
 	Method Draw() Abstract
 	
+	Rem
+	bbdoc: Helper to draw a wireframe rectangle.
+	EndRem
 	Function DrawBox(x:Int, y:Int, w:Int, h:Int)
 		DrawLine(x,y,x+w-1,y)
 		DrawLine(x+w-1,y,x+w-1,y+h-1)
@@ -51,6 +108,9 @@ Type TWidget Abstract
 		DrawLine(x,y+h-1,x,y)
 	End Function
 
+	Rem
+	bbdoc: Helper to draw a 3D rectangle.
+	EndRem
 	Function Draw3DBox(x:Int, y:Int, w:Int, h:Int, invert:Int, size:Int=2)
 		Local f:Int
 		
@@ -82,7 +142,15 @@ Type TWidget Abstract
 
 End Type
 
+Rem
+bbdoc: The label widget (simply displays the supplied string)
+EndRem
 Type TLabel Extends TWidget
+	Rem
+	bbdoc: Create a TLabel widget.
+	returns: The created widget.
+	about: @gui is the @TGUIHandler object managing this wiget. @x and @y are its position and @text is the text to display in the label.
+	EndRem
 	Function Create:TLabel(gui:TGUIHandler,x:Int, y:Int, text:String)
 		Local o:TLabel=New TLabel
 		o.enabled=True
@@ -101,9 +169,18 @@ Type TLabel Extends TWidget
 
 End Type
 
+Rem
+bbdoc: The text entry widget
+EndRem
 Type TText Extends TWidget
 	Field	maxlen:Int
 	
+	Rem
+	bbdoc: Create a TText widget.
+	returns: The created widget.
+	about: @gui is the @TGUIHandler object managing this wiget. @x and @y are its position and @text is the initial text in the widget.
+	about: @maxlen is the maximum number of characters allowed.  @callback is called when RETURN is pressed in the text field.
+	EndRem
 	Function Create:TText(gui:TGUIHandler,x:Int, y:Int, text:String, maxlen:Int, callback(w:TWidget)=Null)
 		Local o:TText=New TText
 		o.enabled=True
@@ -153,9 +230,22 @@ Type TText Extends TWidget
 	End Method
 End Type
 
+Rem
+bbdoc: The checkbox widget
+EndRem
 Type TCheckbox Extends TWidget
+
+	Rem
+	bbdoc: True if the box is checked, False otherwise.
+	EndRem
 	Field	checked:Int
 	
+	Rem
+	bbdoc: Create a TCheckox widget.
+	returns: The created widget.
+	about: @gui is the @TGUIHandler object managing this wiget. @x and @y are its position and @text is the text to display by the checkbox.
+	about: @callback is called when the checkbox is toggled.
+	EndRem
 	Function Create:TCheckbox(gui:TGUIHandler, x:Int, y:Int, text:String, callback(w:TWidget)=Null)
 		Local o:TCheckbox=New TCheckbox
 		o.enabled=True
@@ -195,11 +285,20 @@ Type TCheckbox Extends TWidget
 	End Method
 End Type
 
+Rem
+bbdoc: The button widget
+EndRem
 Type TButton Extends TWidget
 
 	Field ox:Int
 	Field oy:Int
 	
+	Rem
+	bbdoc: Create a TButton widget.
+	returns: The created widget.
+	about: @gui is the @TGUIHandler object managing this wiget. @x, @y, @w and @h are its position and size, and @text is the text to display in the button.
+	about: @callback is called when the button is pressed.
+	EndRem
 	Function Create:TButton(gui:TGUIHandler, x:Int, y:Int, w:Int, h:Int, text:String, callback(w:TWidget))
 		Local o:TButton=New TButton
 		o.enabled=True
@@ -233,6 +332,74 @@ Type TButton Extends TWidget
 	End Method
 End Type
 
+Rem
+bbdoc: A drop down list type widget
+EndRem
+Type TButtonList Extends TWidget
+
+	Field options:String[]
+	
+	Rem
+	bbdoc: The selected item.
+	EndRem
+	Field selected:Int
+	
+	Rem
+	bbdoc: Create a TButtonList widget.
+	returns: The created widget.
+	about: @gui is the @TGUIHandler object managing this wiget. @x and @y are its position. @options are the options for the list and
+	about: @selected is the currently selected item. @callback is called when the selection changes.
+	EndRem
+	Function Create:TButtonList(gui:TGUIHandler, x:Int, y:Int, options:String[], selected:Int, callback(w:TWidget))
+		Local o:TButtonList=New TButtonList
+		Local maxw:Int=0
+		o.enabled=True
+		o.x=x
+		o.y=y
+		o.options=options
+		o.selected=selected
+		o.text=options[selected]
+		
+		For Local s:String=EachIn options
+			maxw=Max(maxw,TGUIFont.font.TextWidth(s))
+		Next
+		
+		o.w=maxw+TGUIFont.font.MaxHeight()+4
+		o.h=TGUIFont.font.MaxHeight()+2
+		o.callback=callback
+		gui.Register(o)
+		Return o
+	End Function
+	
+	Method HandleClick()
+		Local sel:Int=GUIMenu("Select value",options,x,y)
+		
+		If sel<>-1
+			selected=sel
+			text=options[selected]
+			If callback<>Null
+				callback(Self)
+			EndIf
+		EndIf
+	End Method
+
+	Method Draw()
+		If (mouse_over)
+			SetColor(128,128,128)
+		Else
+			SetColor(64,64,64)
+		EndIf
+
+		DrawRect(x,y,w,h)
+		Draw3DBox(x+2,y+2,h-4,h-4,False,1)
+
+		TGUIFont.font.Draw(text,x+TGUIFont.font.MaxHeight()+3,y+1)
+	End Method
+End Type
+
+Rem
+bbdoc: Handles the GUI.
+EndRem
 Type TGUIHandler
 
 	' These are private
@@ -242,8 +409,10 @@ Type TGUIHandler
 	Field	m_over:TWidget
 	Field	m_clicked:TWidget
 
-	' Creates a new GUI handler
-	'	
+	Rem
+	bbdoc: Create a GUI Handler.
+	returns: The GUI Hanbler.
+	EndRem
 	Function Create:TGUIHandler()
 		Local o:TGUIHandler
 		
@@ -257,41 +426,51 @@ Type TGUIHandler
 		Return o
 	End Function
 	
-	' Register a widget
-	'
+	Rem
+	bbdoc: Register a widget.
+	about: Widgets call this themselves.
+	EndRem
 	Method Register(w:TWidget)
 		m_widgets.AddLast(w)
 		w.owner=Self
 	End Method
 	
-	' Clear widgets
-	'
+	Rem
+	bbdoc: Remove all widgets.
+	EndRem
 	Method Clear()
 		m_widgets.Clear()
 	End Method
 	
-	' Set the keyboard focus (null for none)
-	'
+	Rem
+	bbdoc: Sets the keyboard focus to the supplied widget.  Pass null for no focus.
+	EndRem
 	Method SetFocus(w:TWidget)
 		m_focus=w
 	End Method
 	
-	' Get the keyboard focus (null for none)
-	'
+	Rem
+	bbdoc: Gets the keyboard focus.
+	returns: The currently focused TWidget, or null for no focus.
+	EndRem
 	Method GetFocus:TWidget()
 		Return m_focus
 	End Method
 	
-	' Gets the last clicked widget
-	'
+	Rem
+	bbdoc: Gets the last clicked widget.
+	returns: The last clicked TWidget.  Null is returned if this is called again before another widget is clicked.
+	EndRem
 	Method Clicked:TWidget()
 		Local last:TWidget=m_clicked
 		m_clicked=Null
 		Return last
 	End Method
 	
-	' Perform a loop and any necessary events
-	'
+	Rem
+	bbdoc: Perform the event loop and pass any necessary events.
+	about: KeyHit(KEY_MOUSELEFT) and GetChar() are used to consume events for the interface.
+	EndRem
 	Method EventLoop()
 		Local x:Int=MouseX()
 		Local y:Int=MouseY()
@@ -340,6 +519,9 @@ Type TGUIHandler
 End Type
 
 
+Rem
+bbdoc: Displays a notification alert with the supplied string.
+EndRem
 Function GUINotify(s:String)
 	Local back:TImage=CreateImage(GraphicsWidth(),GraphicsHeight(),1,0)
 	GrabImage(back,0,0)
@@ -368,6 +550,10 @@ Function GUINotify(s:String)
 	Wend
 End Function
 
+Rem
+bbdoc: Displays a yes/no alert with the supplied string.
+returns: True if Yes selected, otherwise False.
+EndRem
 Function GUIYesNo:Int(s:String)
 	Local back:TImage=CreateImage(GraphicsWidth(),GraphicsHeight(),1,0)
 	GrabImage(back,0,0)
@@ -400,6 +586,11 @@ Function GUIYesNo:Int(s:String)
 End Function
 
 
+Rem
+bbdoc: Displays a pop-up menu.
+returns: The index of the selected option, -1 for none.
+about: @title is the menu title, @options the options to display and @x and @y specify its position,.
+EndRem
 Function GUIMenu(title:String, options:String[],x,y)
 	Local f:Int
 	Local back:TImage=CreateImage(GraphicsWidth(),GraphicsHeight(),1,0)
author	Ian C <ianc@noddybox.co.uk>	2005-09-18 19:19:36 +0000
committer	Ian C <ianc@noddybox.co.uk>	2005-09-18 19:19:36 +0000
commit	f8de91ae41929286b1cf43c72093e5c996b1f949 (patch)
tree	f9ccb2fa8461c2941e6d60187ae8952e9ee30f12 /simplegui.mod
parent	f79195715c66530b0bda50242380812c5e670c00 (diff)